diff --git a/README.md b/README.md new file mode 100644 index 0000000..8ac74bc --- /dev/null +++ b/README.md @@ -0,0 +1,17 @@ +# Sparse: A Rust C2 framework + +Developed using libpcap to enable evading local firewalls and with an eye towards hiding itself from inspection + +## 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 + +## 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. + +## 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) \ No newline at end of file diff --git a/README.org b/README.org deleted file mode 100644 index 8c87647..0000000 --- a/README.org +++ /dev/null @@ -1,17 +0,0 @@ -#+TITLE: Sparse: A Rust C2 framework - -Developed using libpcap to enable evading local firewalls and with an eye towards hiding itself from inspection - -* Packages -** [[./pcap-sys/README.org][pcap-sys]]: A Rust wrapper around the libpcap library for Linux -** [[./nl-sys/README.org][nl-sys]]: 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 - -* 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. - -* Proofs of concept - -[[./examples/README.org][Check out the examples/proofs of concept used in development]] diff --git a/examples/README.org b/examples/README.md similarity index 64% rename from examples/README.org rename to examples/README.md index 394f272..e068da9 100644 --- a/examples/README.org +++ b/examples/README.md @@ -1,18 +1,18 @@ -#+TITLE: Examples and proofs of concept +# Examples and proofs of concept This directory is used to highlight proofs of concept and help ease the understanding and development of the sparse framework Each example/proof of concept listed is listed in the order it was added, and highlights the feature being developed that was supplemented by such a proof of concept. -To learn more about the project, it is recommended to follow along in the same order when reviewing source code. +To learn more about the project, it is recommended to follow along the proofs of concept in the following order. -* bind-shell +## bind-shell -[[./bind-shell/README.org][README]] +[bind-shell README](./bind-shell/README.md) This example was used to set up the dev containers workspace, to verify that the static linking against libpcap was actually possible and feasible, and to see how small binaries could get when statically linked -* reverse-shell +## reverse-shell -[[./reverse-shell/README.org][README]] +[reverse-shell README](./reverse-shell/README.md) -Used to set up nl-sys to allow for better interfacing with the routing tables of the host operating system \ No newline at end of file +Used to set up nl-sys to allow for better interfacing with the routing tables of the host operating system in order to gather all the information necessary to send out packets knowing only the destination IP address \ No newline at end of file diff --git a/examples/bind-shell/README.org b/examples/bind-shell/README.md similarity index 65% rename from examples/bind-shell/README.org rename to examples/bind-shell/README.md index c8a9da1..f05c032 100644 --- a/examples/bind-shell/README.org +++ b/examples/bind-shell/README.md @@ -1,13 +1,13 @@ -#+TITLE: Example bind shell proof of concept +# Example bind shell proof of concept This bind shell works through local host firewalls on Linux systems using UDP to receive messages, verify them against a public key, run the commands specified, and return the results and display it over the network. -* Running the code +## Running the code In a dev containers terminal, run: -#+BEGIN_SRC shell +```sh cargo make examples-bindshell-run -#+END_SRC +``` This will build the code, generate the keys, create the environment, and run the service and the client in parallel. -To verify the execution of the environment, try running ~iptables -nL~ and see that the firweall tries to block all packets. \ No newline at end of file +To verify the execution of the environment, try running `iptables -nL` and see that the firweall tries to block all packets. \ No newline at end of file diff --git a/examples/reverse-shell/README.md b/examples/reverse-shell/README.md new file mode 100644 index 0000000..1633ad0 --- /dev/null +++ b/examples/reverse-shell/README.md @@ -0,0 +1,10 @@ +# Example reverse shell proof of concept + +This bind shell works through local host firewalls on Linux systems using UDP to send and receive messages + +## Running the code +In a dev containers terminal, run: + +```sh +cargo make examples-revshell-run +``` \ No newline at end of file diff --git a/examples/reverse-shell/README.org b/examples/reverse-shell/README.org deleted file mode 100644 index 09e49e4..0000000 --- a/examples/reverse-shell/README.org +++ /dev/null @@ -1,13 +0,0 @@ -#+TITLE: Example reverse shell proof of concept - -This bind shell works through local host firewalls on Linux systems using UDP to send and receive messages - -* Setup -** libpcap -Follow the directions in the main README in order to pull in the libpcap dependency - -** Build the code -Once the previous step is completed, run ~cargo build --release~ in a terminal. - -* Running the code -First, open two shells. In one, run ~docker-compose up examples_reverseshell_target~, and in the other run ~docker-compose run examples_reverseshell_server~. It will be possible to type in commands to examples_bindshell_server and run them in the target container \ No newline at end of file diff --git a/nl-sys/README.org b/nl-sys/README.md similarity index 91% rename from nl-sys/README.org rename to nl-sys/README.md index efb4469..8945ac1 100644 --- a/nl-sys/README.org +++ b/nl-sys/README.md @@ -1,3 +1,3 @@ -#+TITLE: nl-sys +# nl-sys This library provides Rust wrappers around the netlink socket protocol that the Linux kernel uses in order to provide access to routing tables and interface information \ No newline at end of file diff --git a/pcap-sys/README.org b/pcap-sys/README.md similarity index 88% rename from pcap-sys/README.org rename to pcap-sys/README.md index 9eb32fe..58efa1f 100644 --- a/pcap-sys/README.org +++ b/pcap-sys/README.md @@ -1,3 +1,3 @@ -#+TITLE: pcap-sys +# pcap-sys This library provides wrappers around libpcap that when built in the dev container environment allow for full static linking against libpcap \ No newline at end of file