From 8905d027eaa4e6a4cc4268007c35a4cc05b1775b Mon Sep 17 00:00:00 2001 From: Andrew Rioux Date: Tue, 21 Oct 2025 07:51:59 -0400 Subject: [PATCH] docs: add more thorough developer documentation --- README.md | 19 +++++++------------ sparse-05/README.md | 21 +++++++++++++++++++-- 2 files changed, 26 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index accc45c..022c63c 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,16 @@ # Sparse: A Rust C2 framework -Developed using libpcap to enable evading local firewalls and with an eye towards hiding itself from inspection +Developed using libpcap to enable evading local firewalls and with an eye towards hiding itself from inspection. Deprecated in favor of sparse-v2 before being completely developed; the most significant tool this repository contributes is `sparse-05`. -## Packages -- [pcap-sys](./pcap-sys/README.org): A Rust wrapper around the libpcap library for Linux -- [nl-sys](./nl-sys/README.org): A Rust wrapper around the netlink (nl) library on Linux -- sparse-protocol: The definition of various protocols, wrappers, and compositions to allow for a flexible working environment +## Significant Packages +- [pcap-sys](./pcap-sys): A Rust wrapper around the libpcap library for Linux +- [nl-sys](./nl-sys): A Rust wrapper around the netlink (nl) library on Linux +- [sparse-05](./sparse-05/README.md): A bind shell utility to create bind shells on target servers and connect to them ## Development -To develop or compile this project, open it in GitHub Codespaces or using Visual Studio Code's Dev Container extension (requires Docker to be installed). -Doing so will create an environment which has all the dependencies necessary in order to build and run the code in a more secure environment. +This environment is designed to be developed in with a Nix developer shell, obtained with `nix develop` -## Proofs of concept - -There are multiple proofs of concept that are made to further develop libraries and further this project as well as provide stepping stones to help educate new contributors, and they are located in [the examples folder](./examples/README.md) - -## Somewhat mature bind shell +## Bind shell The most mature implementation of Sparse would be the Sparse version 0.5 bind shell, which has documentation in [its appropriate folder](./sparse-05/README.md) diff --git a/sparse-05/README.md b/sparse-05/README.md index ce704c7..76ba831 100644 --- a/sparse-05/README.md +++ b/sparse-05/README.md @@ -25,6 +25,12 @@ Sparse 0.5 is a stopgap solution until the C2 framework itself is more mature. I # Obtaining +Sparse 0.5 is immediately ready to build from source if using the [Nix package manager](https://nixos.org/download) [with flakes enabled](https://nixos.wiki/wiki/Flakes) by running `nix build .#sparse-05-client`. + +## FreeBSD support + +Building normally will only produce a client that can generate beacons for Linux and Windows, lacking proper FreeBSD support. To build the client with FreeBSD support, create a FreeBSD build environment by running `vagrant up` and compiling a FreeBSD sparse binary by running `sparse-build` or `sparse-build --release`. With the FreeBSD binary built, copy it from `target/x86_64-unknown-freebsd` to `sparse-05/sparse-05-freebsd-server`, and rebuild using Nix + Currently, there are no prebuilt binaries. However, sparse can easily be built if the [Nix package manager](https://nixos.org/download) is installed. Just clone this repository and run `nix build .#sparse-05-client` and the client will be placed in `result/bin`. # Use @@ -33,12 +39,13 @@ Using sparse centers around the client. The client can generate new servers as w ## Generating a new server -Sparse supports 3 different targets: +Sparse supports 4 different targets: - Linux - Windows - Windows service +- FreeBSD -The basics center around `sparse-05-client generate [-p ] [-t ]`. This generates both a server and the configuration file necessary to connect to the server. The keys and port ensure that the connection is unique, which has the added property that multiple versions of `sparse-05` can be running on a target system with the same port. +The basics center around `sparse-05-client generate [-p ] [-t ]`. This generates both a server and the configuration file necessary to connect to the server. If the port is not specified, it defaults to 54248. @@ -62,6 +69,10 @@ The Windows service has the same requirements, but can be installed with `sc cre As of Jan 25 2023, Windows Defender marks the Windows service binary as malicious +### FreeBSD + +Create a service to run the resulting binary as root + ## Connect After installing and running the server, it is possible to connect using the generated `scon` file and `sparse-05-client` with `sparse-05-client connect .scon :`. @@ -71,3 +82,9 @@ This brings up a shell that can run commands. However, there are special command - `#help`: shows sparse specific help - `#sysinfo`: prints information about the system being connected to - `#upload [local] [remote]`: uploads a file from the local path to the remote path +- `#download [remote] [local]`: downloads a file from the remote path to the local path +- `#edit [remote]`: downloads a file remotely and opens it in `$EDITOR`, and uploads the final version + +## Connection test + +To verify that an installed service is still alive and working, run `sparse-05-client connect-test .scon :`