diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 116 |
1 files changed, 116 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..e435970 --- /dev/null +++ b/README.md @@ -0,0 +1,116 @@ +# noawareness + +`noawareness` is a lightweight process and network activity logger for +Linux designed for incident response, threat hunting, and postmortem +analysis. + +It monitors and logs: + +- Process creation and destruction. +- UID/GID changes +- `ptrace` activity +- DNS queries +- TCP session activity + +It also has the capability of blocking executions with user-defined +signatures via fanotify's FAN_OPEN_EXEC_PERM feature (see "rules" for +a basic examples of rule definitions). + +All output is formatted with JSON making it easy to ingest into tools +like Splunk, Elasticsearch, or your own log processors. + +Warning: This project is under active development and was designed for +usage at CTFs--not production use. It's crude, incomplete, and +buggy. You've been warned. + +## Building + +To build, run: +```` +make +``` + +This produces a binary named `noawareness` that can be dropped onto most +Linux systems and run as-is. + +## Usage + +Run `./noawareness` with apropriate flags. Example: + +```sh +sudo ./noawareness -xi eth0 +``` + +For a list of command line flags, use the `-h` option: +``` +./noawareness -h +``` + +``` +usage: ./noawareness [-h?] + + -h/-? - Print this menu and exit. + -d - Daemonize. Default: no + -i <iface> - Interface to sniff + -x - Toggle promiscuous mode. Default: false + -m <bytes> - Max size of file to hash. Default: 104857600 + -o <file> - Outfile for JSON output, Default: /var/log/noawareness.json.log + -O - Toggle local JSON logging. Default: false + -P <path> - Path to PID file. Default: /var/run/noawareness.pid + -r - Toggle remote logging. Default: true + -R <path> - Path to AV rule definitions. Default: rules + -s <IP> - Remote log server. Default: 127.0.0.1 + -S - Toggle syslog. Default: true + -p <port> - Port of remote server. Default: 55555 + -q - Toggle quiet mode. Default: false +``` + + +## Logging + +noawareness can send logs over UDP to a remote server for further +processing and ingestion into a log search engine such as Splunk or +Elasticsearch. The choice of UDP was made for simplicity. More robust +and reliable logging over TCP is in the roadmap of upcoming features. + +## musl + +You can statically compile `noawareness` with `musl` to run it on a wide +range of systems, including older or stripped-down Linux installs: + +- Symlink Linux headers if your system uses multiarch paths (some + setups require this). + + ``` + sudo ln -s /usr/include/linux /usr/include/x86_64-linux-musl/ + sudo ln -s /usr/include/asm-generic /usr/include/x86_64-linux-musl/ + sudo ln -s /usr/include/x86_64-linux-gnu/asm /usr/include/x86_64-linux-musl/ + ``` + + Optionally, sanitized kernel headers such as the ones provided by + Sabotage Linux may be used if desired (this is untested): + https://github.com/sabotage-linux/kernel-headers + + See here for more detail: + https://groups.google.com/g/linux.debian.bugs.dist/c/Q2KVBy8QXYM + +- Set CC to musl-gcc or whichever cross-compiler you are using: + + ``` + CC=musl-gcc make + ``` + +## Why? + +I needed a lightweight, easy to deploy, and portable tool to track +activity on Linux boxes at CTFs. Many similar tools require excessive +dependencies, configuration, or were paywalled. + +## Credits + +- base64 implementation by Jouni Malinen + +- The SHA256 implementation by Brad Conte: https://github.com/B-Con/crypto-algorithms + +- The MD5 implementation used in this project was originally written + by RSA Data Security, Inc. |