Wazoo. Wazuh framework in python

What is Wazoo

Wazoo is a python wazuh framework and a wazuh server that can handle wazuh agent connection and logging.

wazoo does not replace wazuh. wazoo is a python framework to interact with wazuh protocol and have a server option, it not decode logs like wazuh, only handle the wazuh protocol.

Wazoo server only receive logs from wazuh agents and decode the encrypted message allowing you to extend wazuh functionality.

You can use wazoo to send logs to others platforms or make new integrations.

I made wazoo to study the wazuh agent enrolment and I ended up getting excited and doing this framework and a server.

wazoo is a wazuh framework and server. wazoo can be used as a library for you python project, or you can use the wazoo server to handle wazuh agent connections.

You can use wazoo as a double-edge blade, encrypt and decrypt wazuh protocol.

With wazoo server you can receive logs from wazuh agent and logging the events into a TCP, UDP, Unix, TCP+SSL, File or your own callback function

Getting Started

Framework

You can download the framework using the wazoo pypi package.

Download with uv

You can use uv to add wazoo as dependencie to your project.

uv add wazoo

Download using pip

Use pip to download the wazoo library.

pip install wazoo

Wazoo server

I made this wazuh server using the framework to show how wazuh handle wazuh agent connections. I made some options to handle wazuh agent logs and send over tcp, udp, file, unix, etc...

The cli to run server is configured by default in ./wazoo/__main__.py. You can use the wazoo tool to run the server.

Run with docker

You can run this project using: docker, uv or pre-compiled binaries

TO run wazoo with docker, you can use the ghcr.io (github) docker repository

docker run -p 1515:1515 -p 1514:1514 ghcr.io/souzomain/wazoo:latest

Run with uv

Sync the dependencies and run the server. uv installs the project into an isolated environment automatically:

uv sync
uv run wazoo -v

uv run wazoo calls the CLI entry point. You can also run it as a module:

uv run python -m wazoo -v

List every available option with:

uv run wazoo --help

If you want to use TCP+SSL, create the certificates first — see Setup development environment.

Server Configurations

You can configure the file ./config.yml to send logs over your preference.

Logging options:

• TCP + SSL (send over tcp with ssl);
• TCP (send over tcp):
• UDP (send over udp);
• File (store logs in a file);
• Unix (send to unix socket).

All options that you go through wazoo you can configure in the ./config.yml file.

To run the configuration file, you need to pass the -c option.

wazoo -c config.yml

Configurations example

I will show you differents types of configurations.

File output

This is an example with File output

log:
  option: file
  path: wazoo.log
buffer:
  time_flush: 1 # fush before 1 sec
  line_flush: -1 # does not have a limit
processes: 1
workers: -1 # will use os.cpu_count()

TCP Output

This is an example with TCP output

log:
  option: tcp
  ip: 127.0.0.1
  port: 514
  ssl: false

UDP Output

This is an example with UDP output

log:
  option: udp
  ip: 127.0.0.1
  port: 514

Unix Output

This is an example with Unix output

log:
  option: unix
  path: /var/wazoo.sock

Callback Output (library only)

The callback option hands every log to your own async function instead of a socket or file. A function can't be expressed in config.yml, so this option is only available when using wazoo library:

from wazoo import WazooLog

async def on_log(log: bytes | deque[bytes]):
    print("received:", log)

log = WazooLog({"callback": on_log}, option="callback")

await log.sendLog(b"hello world")

See docs/README.md for more details.

Pre-compiled binaries

If you want to use wazoo as a server, you can use the pre-compiled binaries.

I recommend to use pre-compiled binaries, binaries generated by nuitka will have more performance than running python

Standalone binaries (built with Nuitka, no Python required) are attached to every GitHub Release. Each release ships version-pinned assets plus a rolling latest alias:

Platform	latest asset
Linux x86_64	wazoo-latest-linux-x86_64
Linux arm64	wazoo-latest-linux-arm64
macOS arm64 (Apple Silicon)	wazoo-latest-macos-arm64

Download it, make it executable and run:

curl -L -o wazoo https://github.com/souzomain/wazoo/releases/latest/download/wazoo-latest-linux-x86_64
chmod +x wazoo
./wazoo -v

The releases/latest/download/... URL always resolves to the newest release, so it is safe to script. For a reproducible install, pick a specific version from the releases page instead (e.g. wazoo-<version>-linux-x86_64).

Performance

Python is not good for performance but I made some design decisions to tune and improve this server with high performance.

• uvloop: Uses libuv (C library used in nodejs) under the hood, this increases the speed of all async tasks;
• asyncio: The project has used asyncio from the start;
• caching: I made many caching options on the project, this increases the speed for AES computation, database, etc;
• workers: Workers for log decoding are default. by default it uses all cpus core;
• multiprocessing: By default I added 1 process to handle the connections, but you can increase with the option --processes;
• nuitka: Compile the project and generate a performant binarie.
• log buffering queue: All logs received are stored in the buffer queue. buffer queue is flushed when max_time is reached or the number of logs in queue reach max_lines.

Setup development environment

Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Sync the project

uv sync

Create the SSL pem

./scripts/generate_ssl.sh

Now you can run the server

uv run wazoo -v

Documentation

You can see the library Documentation in ./docs/ directory.

see Documentation

Test

You can test server using docker to run a wazuh agent.

uv run wazoo -v &
docker compose -f docker/agent.yml up 

Conclusion

I dedicated a lot of my time to making this project and tutorial.

I want to do many different things in this project, one thing is implementing a HTTP Api to manage the server, but will do this only if the project get more visibility.

If you want me to continue developing this project, please consider to give a Star ⭐

Contact

If you want to contact me, you can use this options.

• E-mail: me@souzo.me
• Matrix: @souzo:matrix.org
• Linkedin: https://www.linkedin.com/in/vinicius-m-a76ba51b5/
• Twitter/X: https://x.com/souzomain
• Reddit: https://www.reddit.com/user/_souzo/