diff --git a/README.md b/README.md index 088a10e..bcdb87c 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,21 @@ -# Macgonuts ![ci-status](https://github.com/rafael-santiago/macgonuts/actions/workflows/forge-specs.yml/badge.svg) ![c](https://img.shields.io/badge/is_what_we_speak-black?logo=c&logoColor=white&style=plastic) ![suckless](https://img.shields.io/badge/is_what_we_seek_to_follow-white?logo=suckless&logoColor=blue&style=plastic) +# Macgonuts ![ci-status](https://github.com/rafael-santiago/macgonuts/actions/workflows/forge-specs.yml/badge.svg) ![linux-function-coverage](https://img.shields.io/badge/function_coverage-95.9%25-lime?logo=linux&logoColor=white&style=plastic) ![linux-line-coverage](https://img.shields.io/badge/line_coverage-84.3%25-lime?logo=linux&logoColor=white&style=plastic) ![freebsd-function-coverage](https://img.shields.io/badge/function_coverage-91.9%25-lime?logo=freebsd&logoColor=white&style=plastic) ![freebsd-line-coverage](https://img.shields.io/badge/line_coverage-82.0%25-lime?logo=freebsd&logoColor=white&style=plastic) ``Macgonuts`` is an ``ARP/NDP`` swiss army knife to make ``MAC addresses`` going nuts on networks around! -It supports ``IPv4/ARP`` and ``IPv6/NDP``. It intends to bring you all in a shell. Anything related to +It supports ``IPv4/ARP`` and ``IPv6/NDP``. It intends to bring you all in a shell. Anything related to spoof `layer-2` addresses can be done elegantly with a single f_cking nice ``non-scripted`` tool, a -badass executable without clumsy zillions of dependencies. Suckless is the key here. +badass executable without clumsy zillions of dependencies. Suckless is the key here, but simple in a +*non-hollow-claimed-simple* is what we try to deliver here. -Currently ``Macgonuts`` is compatible with ``Linux`` and ``FreeBSD`` platforms. +Currently, ``Macgonuts`` is compatible with ``Linux`` and ``FreeBSD`` platforms. Still, if you want to do spoof from your own code, you can use basic stuff from ``Macgonuts`` as a ``C library`` or ``Go``, ``Python`` bind as well. -You should take your first steps [here](https://github.com/rafael-santiago/macgonuts/blob/main/doc/BUILD.md) and so -buckle up and quickly mastering all the tool [here](https://github.com/rafael-santiago/macgonuts/blob/main/doc/MANUAL.md). +You should take your first steps [here](doc/BUILD.md) and so +buckle up and quickly mastering all the tool [here](doc/MANUAL.md). I hope you like it, enjoy! @@ -29,8 +30,8 @@ only into well controlled environments. If you will run ``Macgonuts`` on public users of your actions before. Also be sure of loading your ``ethics.ko`` module before any network hacking action. Finally, this software is provided with no warranty. -Again, ``Macgonuts`` is an ``ARP/NDP`` swiss army knife with batteries included but ethics you need to bring it from home. -:wink: +Again, ``Macgonuts`` is an ``ARP/NDP`` swiss army knife with batteries included but ethics you need to bring it +from home. :wink: Remember to be ethical when using it. Macgonuts is a tool designed to ethical hacking, pentests and red teams. *Once it stated, when using this tool you are assuming that any damage, data loss or even @@ -43,6 +44,6 @@ with money, try to redirect it to a local charity institution, an ONG of your ch You can also do [pull requests](https://github.com/rafael-santiago/macgonuts/pulls) proposing improvements. Do some [bug report](https://github.com/rafael-santiago/macgonuts/issues) if a bug is annoying you. Maybe you should also instruct people about network security issues by using this software showing them ways of being protected against -the attacks proposed here. Use it as a classroom lab tool. Spread your knowledge. Thank you! +the attacks proposed here. Use it as a classroom lab tool, too. Well, spread your knowledge! Thank you! **Obvious but always good to remember**: all opinions expressed here are my own and not the views of my employers. diff --git a/doc/BUILD.md b/doc/BUILD.md index fe58c3c..78f47df 100644 --- a/doc/BUILD.md +++ b/doc/BUILD.md @@ -13,6 +13,7 @@ fresh ``macgonuts`` binary to get your stuff done, you can give ``the low-cost b - [The low-cost build](#the-low-cost-build) - [The developer's build](#developers-build) - [Extracting code coverage](#extracting-code-coverage) + - [List of all build options](#list-of-all-build-options) - [Installing the command line tool](#installing-the-command-line-tool) ## Getting newest macgonuts source code revision @@ -42,7 +43,7 @@ build ``Macgonuts`` is: Any other dependency we ship it as sub-modules and build it during build but ``DO NOT`` polute your system with nothing. It is used into ``src/libs`` folder of your copy. If you delete your copy, all will gone -with this deletion, simply, self contained and clean. Tideness is everything! :wink: +with this deletion, simple, self contained and clean. Tideness is everything! :wink: ## Installing Hefesto @@ -110,7 +111,7 @@ subdirectory is ``src/cmd``. This ``cmd`` subdirectory stands for the ``macgonut Codes directly hosted into ``src`` compound the static libraries ``libmacgonuts.a`` and ``libmacgonutssock.a``. The ``libmacgonutssock.a`` is a special case where all codes related to socket (into native implementations -``macgonuts_socket.o`` and ``macgonuts_socket_common.o`` are put together into a separated `ar` file, this +``macgonuts_socket.o`` and ``macgonuts_socket_common.o`` are put together into a separated ``ar`` file, this is done in order to make easy to test some communication parts). Any specific code for some platform is hosted into a subdirectory with the name of the platform, so, @@ -150,7 +151,7 @@ you@somewhere-over-the-rainbow:~/macgonuts/src# hefesto ``` Libraries will be built into ``../lib`` and binaries into ``../bin``. Tests will ran automatically, if you have been -doing a good job you will not fear them and, I am pretty sure that you will like to see them running every single time +doing a good job you will not fear them and, I am pretty sure that you will like to watch them running every single time remembering you that your code is actually working and that ``TDD`` matters. :raised_hands: [``Back``](#topics) @@ -160,7 +161,7 @@ remembering you that your code is actually working and that ``TDD`` matters. :ra ``Macgonuts`` build gives support for code coverage extraction, it support ``gcov`` or ``llvm-cov``. You also need to have ``lcov`` well-installed more on that [here](https://github.com/linux-test-project/lcov). -By using ``Hefesto`` we can easily extract the code coverage of ``Macgonuts`` by invoking ``Hefesto`` as follows: +By using ``Hefesto`` we can easily extract ``Macgonuts``' code coverage by invoking ``Hefesto`` as follows: ``` you@somewhere-over-the-rainbow:~/macgonuts/src# hefesto --coverage @@ -175,8 +176,8 @@ you@somewhere-over-the-rainbow:~/macgonuts/src# hefesto --coverage \ ``` By design we are only extracting code coverage from ``libmacgnuts`` (the main project under ``src``). -The ``cmd-tool`` is pretty hard for unit testing since it would involve run all attacks that this tool -implements in form of commands (a.k.a tasks) from the github actions' runner. Sincerely, it would be not +The ``cmd-tool`` is pretty hard for automate tests since it would involve run all attacks that this tool +implements in form of commands (a.k.a tasks) from the `CI`. Sincerely, it would be not easy to do from a rather ``restricted-docker-velotrol-like`` [sic] environment. So, *C'est la vie!* > - Wait. What does *"velotrol"* is?! @@ -185,6 +186,27 @@ Well, a image will make you understand my point much better, [look](https://duck [``Back``](#topics) +### List of all build options + +Take a look at **Table 1** to know all build options supported by the ``Hefesto`` based build. + +**Table 1** : All relevant ``Macgonuts`` build options. +| **Option** | **Type** | **Description** | +|:-------------------:|:---------:|:-----------------------------------------------------------------------------------:| +| ``--includes`` | list | Specifies additional include directories | +| ``--cflags`` | list | Specifies additional compilation flags | +| ``--libraries`` | list | Specifies additional library directories | +| ``--ldflags`` | list | Specifies additional linker flags | +| ``--bin-output-dir``| value | Specifies the binary artifact target directory | +| ``--obj-output-dir``| value | Specifies the object files target directory | +| ``--install`` | flag | Runs installing build task | +| ``--uninstall`` | flag | Runs uninstalling build task | +| ``--coverage`` | flag | Runs coverage build task | +|``--genhtml-outpath``| value | Specifies a file path for the ``LCOV`` coverage report | +| ``--toolset`` | value | Specifies the name of wanted compiler, can being ``gcc`` or ``clang`` | + +[``Back``](#topics) + ## Installing the command line tool Having ``Hefesto`` well installed all you need is move to ``src`` toplevel subdirectory and run the following: diff --git a/doc/CodeOrganization.md b/doc/CodeOrganization.md new file mode 100644 index 0000000..97478b2 --- /dev/null +++ b/doc/CodeOrganization.md @@ -0,0 +1,133 @@ +# Code organization + +**Abstract**: This document aims to inform how ``Macgonuts`` code follows organized, +besides some project and design decisions. + +## Topics + +- [The repo layout](#repo-layout) +- [Code coverage parameters](#code-coverage-parameters) + - [How to avoid breaking coverage build?](#how-to-avoid-breaking-coverage-build) + - [Coverage measures updating](#coverage-measures-updating) + +## The repo layout + +This is the current repo layout: + +``` +. ++-- CODE_OF_CONDUCT-PT_BR.md ++-- CODE_OF_CONDUCT.md ++-- LICENSE ++-- README.md ++-- .github/ +| +-- workflows/ +| +-- forge-specs.yml ++-- doc/ +| +-- BUILD.md +| +-- CodeOrganization.md +| +-- CodingStyle.md +| +-- MANUAL.md +| +-- man1/ +| +-- macogonuts.1 ++-- etc/ +| +-- hoax +| +-- oui +| +-- ... ++-- src/ +| +-- Forgefile.hsl +| +-- ... +| +-- build/ +| +-- toolsets.hsl +| +-- cmd/ +| +-- Forgefile.hsl +| +-- hooks/ +| +-- ... +| +-- test/ +| +-- Forgefile.hsl +| +-- ... +| +-- ... +| +-- freebsd/ +| +-- ... +| +-- libs/ +| +-- ... +| +-- linux/ +| +-- ... +| +-- test/ +| +-- Forgefile.hsl +| +-- ... +| +-- unix/ +| +-- ... +``` + +In order to know more details about each directory level take a look at **Table 1**. + +**Table 1**: Directory levels overview. +| **Directory level** | **Here goes** | +|:----------------------:|:------------------------------------------------:| +| toplevel | Main configuration and information files | +| ``.github`` | Files related to github configuration | +| ``.github/workspaces`` | Configuration of ``CI`` stuff | +| ``doc`` | More specific documentation | +| ``doc/man1`` | ``Macgonuts`` tool man page | +| ``etc`` | Miscellaneous stuff | +| ``src`` | Main source (library) | +| ``src/build`` | Build conveniences stuff | +| ``src/cmd`` | Command line tool source code | +| ``src/cmd/hooks`` | Source code for task hooks of ``CLI`` tool | +| ``src/cmd/test`` | Tests for the ``CLI`` tool | +| ``src/freebsd`` | ``FreeBSD`` native code of main source (library) | +| ``src/libs`` | All dependencies used by ``Macgonuts`` code | +| ``src/linux`` | ``Linux`` native code of main source (library) | +| ``src/test`` | Tests for the library | +| ``src/unix`` | Common ``UNIX-like`` codes | + +[``Back``](#topics) + +## Code coverage parameters + +Code coverage here it is not a fancy measure only to plot meanginless graphs. In fact, +here you will not find any graph (thanks gosh!); here code coverage is destined to +developers and as pragmatic developers we like boolean stuff that help us solve quickly +the problem, in other words: + +- it is good. +- it is acceptable. +- it is bad (shame on us, let's get better), btw the build is broken, fix it before continuing. + +and, period. No fiddle-faddle. **Table 2** summarizes what exactly is good, acceptable and shame on us. + +**Table 2**: Our adopted coverage measure range. +| **Coverage range (line/function)**| **Description** | +|:---------------------------------:|:----------------------------------------------------:| +| ``>= 90%`` | it is considered high, good | +| ``>= 75% && <= 90%`` | it is considered medium, acceptable | +| ``< 75%`` | it is considered low, bad, shame on us | + +*Coverage build breaks when some low coverage is detected*. By default ``CI`` runs coverage build. + +[``Back``](#topics) + +### How to avoid breaking coverage build? + +Well, if you have added new codes to ``Macgonuts`` you need to exercize this new code with some testing, +no small talk. The ``CI`` produces as artifact the ``LCOV`` report from the part of ``Macgonuts`` that +is watched (the library). With this report you can *clearly see (as *C* code)* how uncovered parts are +needing to be more exercized during tests to make ``CI`` pass again. + +[``Back``](#topics) + +### Coverage measures updating + +At each ``CI`` execution the coverage build runs on Linux based build step. The coverage build is +able to update the coverage measures indicated in the toplevel ``README.md`` file. Likewise, the ``CI`` part +is able to detected that ``README.md`` has changed and it pushes these changes through an automated commit. + +Unfortunately, until now, the ``FreeBSD CI``'s part is not executing the coverage build, because it is +just about a workaround done from a ``VM``. + +When you are in a coverage increasing task you will need to run the coverage build by yourself in your own +development environment, and after hitting good coverage indexes all you need to do is committing your +changes what btw will include the ``README.md`` coverage badges updating. + +[``Back``](#topics) diff --git a/doc/Codingstyle.md b/doc/Codingstyle.md index b6acfd4..e1ed6c9 100644 --- a/doc/Codingstyle.md +++ b/doc/Codingstyle.md @@ -6,7 +6,6 @@ well as in many other segments, ``the Truth`` is such a ``big, biiiig winged unicorn``... Anyway, the following text seeks to describe ``objectively`` the main features of ``my current Unicorn``. - # Topics - [Basic formatting](#basic-formatting) @@ -134,7 +133,7 @@ int do_something(const int i_know_but_better_to_const, const char *buf, const si Since ``C language`` does not feature a deferring or ``try..finally`` statements, here we use ``goto`` for accomplishing clean up necessities. With it you can conclude that here ``gotos`` only -jump forward and to the end of the function. Try to never use explicit gotos to jump backward, please. +jump forward and to the end of the function. Try to never use explicit gotos for jumping backward, please. ```c int do_messy_prologue(void) { @@ -193,7 +192,8 @@ A new feature is considered done when: 1. It does what it must do. 2. It does not add mess, confusion or even unstability nor bugs in the previous stuff. -3. It ships what it promises in a simple (but not simpler) way. In other words, you have used Occam's razor principle on it. +3. It ships what it promises in a simple (but not hollow claimed "simple") way. In other words, you have used Occam's + razor principle on it. 4. It is being well tested. 5. It must not be tied up with some compiler or toolchain to work on. The opposite would be an example of lousy engineering, here. More concepts, less dependencies is what we love. diff --git a/doc/MANUAL.md b/doc/MANUAL.md index 8c34843..835790d 100644 --- a/doc/MANUAL.md +++ b/doc/MANUAL.md @@ -41,7 +41,7 @@ my main goal was to have something to use the pun. This section describes in details all implemented commands in ``macgonuts``. Keep on reading to master up the tool and making a youtube video about it (because I do not have any talent or even patience to do this), -many thanks in advance! +many thanks in advance! :satisfied: ### The spoof command @@ -63,7 +63,7 @@ Okay, it expects at least three options: - ``target-addr`` - ``addr2spoff`` -Nice, it does support ``ARP`` and ``NDP`` because options related to addressing stuff supports ``ipv4`` or ``ipv6``. +Nice, it does support ``ARP`` and ``NDP`` because options related to addressing stuff supports ``ipv4`` or ``ipv6``! The option ``lo-iface`` stands for "local interface", thus you need to indicate the interface that your machine uses to access the network that you are wanting to.. err... mess up... The option ``target-addr`` @@ -78,7 +78,7 @@ Once upon time, three persons: Alice, Bob and Eve... How creative, huh? - Bob is on host ``192.30.70.10``. - Eve is on host ``192.30.70.9``. -Eve wants to use ``macgonuts`` to make Bob thinks that she is Alice on the network. So Eve runs: +Eve wants to use ``macgonuts`` to make Bob thinks that she is Alice in the network. So Eve runs: ``` eve@RestaurantAtTheEndOfTheUniverse:~# macgonuts spoof --lo-iface=eth1 \ @@ -119,7 +119,7 @@ eve@RestaurantAtTheEndOfTheUniverse:~# macgonuts spoof --lo-iface=eth1 \ > --target-addr=192.30.70.10 --addr2spoof=192.30.70.8 --timeout=500 --redirect ``` -Same effect, still spoofed but now redirecting packets and it does not abuse network throughput. +Same effect, still spoofed but now redirecting packets and it does not abuse the network throughput. Eve hits ``ctrl+c`` to exit the application (by the way, this is how you exit spoof command, sorry!). However, Bob still thinks that Eve's computer is Alice's computer and at this moment he will notice that "Alice" @@ -172,7 +172,7 @@ So... Story time!!!!!! Once upon time Alice and Bob, they were communicating each other by using the local network but they were in different network segments! Connected through switches! In order to avoid Eve of doing passive sniffing, bad girl! -Eve, after some evil laughs (``- MuHahuahuahuAH...``, ``- Muhahauahuahau...``) however, she was using ``macgonuts`` +Eve, after some "evil" laughs (``- MuHahuahuahuAH...``, ``- Muhahauahuahau...``) however, she was using ``macgonuts`` that has btw her favorite command that is able to deceive bridged/segmented networks when sniffing (Well, I love puns, I have to admit). @@ -217,7 +217,7 @@ eve-the-sysadmin-with-lasers-and-very-silent@Tender:~# macgonuts eavesdrop --lo- ``` Opposingly what all crypto folks tend to think, Eve respect privacy issues, so she decided to use a filter to -log only what should be abuses on her cooporative network environment: +log only what should be abuses on her corporate network environment: ``` eve-the-sysadmin-with-lasers-and-very-silent@Tender:~# macgonuts eavesdrop --lo-iface=eth1 \ @@ -304,8 +304,8 @@ to communicate each other or at least unable to communicate each other without u In order to work on this command needs three basic options: -1. The local interface -2. A CIDR +1. The local interface. +2. A CIDR. 3. A list of targets. So, story time!!!! @@ -440,7 +440,7 @@ Facts about the network configuration: - ``Ulisses``'s address is ``192.168.5.111`` and his host name at the local network is ``ulisses.lo`` - ``Polifemo``'s address is ``192.168.5.142`` and his host name at the local network is ``polifemo.lo`` -- ``Ninguém``'s address is ``192.168.5.171`` and his host name at the local network is ``ninguem.lo`` +- ``Ninguém``'s address is ``192.168.5.171`` and his host name at the local network is ``ninguem.lo`` - The gateway address is ``192.168.5.1``. ``Ulisses`` knows that ``Polifemo`` is always seeking to troll him host up at this local network. So ``Ulisses`` want to @@ -471,7 +471,7 @@ ulisses@cave:~# macgonuts dnsspooof --lo-iface=eth0 --target-addrs=192.168.5.142 > --etc-hoax=/tmp/i_am_ninguem --hoax-ttl=3600 ``` -Now the resolutions should last for 1 hour in ``Polifemo``'s dns cache (but it also depends on his operation system policy about). +Now the resolutions should last for 1 hour in ``Polifemo``'s dns cache (but it also depends on his operating system policy). Anyway, ``Polifemo`` has some friends in this network that should annoy ``Ulisses``, too. In this way, ``Ulisses`` only have to indicate the ip addresss of each: @@ -485,7 +485,7 @@ ulisses@cave:~# macgonuts dnsspooof --lo-iface=eth0 \ Now the hosts from ``192.168.5.142`` to ``192.168.5.145`` when trying to reach ``Ulisses`` by his host name will reach ``Ninguém``. -But ``Ulisses`` is smart and does not want to warn them of his ``FQDN escape``. Supposing that ``ulisses.lo`` +But ``Ulisses`` is smart and does not want to warn them of his ``FQDN escapade``. Supposing that ``ulisses.lo`` goes off, it does not necessarily will do ``ninguem.lo`` goes off too, and, it could alarm ``Polifemo`` and his not so clever gang... Trying to make his fakery more perfect, ``Ulisses`` uses ``undo-spoof`` option: @@ -511,7 +511,7 @@ meaningful fake web pages at ``192.168.5.101`` and updated his ``/tmp/i_am_ningu 192.168.5.101 *.kwai.com ``` -Now supposing that this network start using a internal ``DNS`` at ``192.168.5.8``. All ``Ulisses`` must do +Now supposing that this network start using an internal ``DNS`` at ``192.168.5.8``. All ``Ulisses`` must do is indicate the internal ``DNS`` address in ``dns-addrs`` list: ``` @@ -552,8 +552,8 @@ By using ``xablau`` you are able to discover all reachable nodes that could be p ``layer-2`` misconducts and, there is not much secret on using it but: story time!!!! Once upon time ``Trollman Burbank`` was looking for targets to have some fun with ``macgonuts``. He had -just ingress into your hotel the network by getting a valid ``IP`` but he knew nothing about other hosts. -Someone tell him to use a weird command called "xablau". "- Xa who?" he said... Even so, he gaves ``xablau``'s +just ingress into your hotel network by getting a valid ``IP`` but he knew nothing about other hosts. +Someone tell him to use a weird command called "xablau". "- Xa who?" he said... Even so, he gave ``xablau``'s quick help a try: ``` @@ -562,7 +562,7 @@ use: macgonuts xablau --lo-iface=