Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update documentation #4

Merged
merged 1 commit into from
Jul 23, 2023
Merged

Update documentation #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 10 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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!

Expand All @@ -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
Expand All @@ -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.
34 changes: 28 additions & 6 deletions doc/BUILD.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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)
Expand All @@ -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
Expand All @@ -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?!
Expand All @@ -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:
Expand Down
133 changes: 133 additions & 0 deletions doc/CodeOrganization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
6 changes: 3 additions & 3 deletions doc/Codingstyle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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.
Expand Down
Loading
Loading