wazoo 0.1.1

Python Wazuh runtime server to handle agent registration and log receive

Wazoo

This project is a wazuh server 4.X that can handle wazuh agent connection.

What is Wazoo

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

wazoo does not replace wazuh but you can use to send logs to other platforms or make new integrations with wazuh.

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

With this project you can receive logs from wazuh agent and logging into a TCP, UDP, Unix, TCP+SSL or File

Installation & Configuration

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

Run with uv

Install uv:

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

Sync the dependencies and run the server. uv installs the project into an isolated environment automatically, so no manual pip install is needed:

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.

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

This python wazuh server, is not performant than wazuh server but can

• asyncio ( for async connection );
• uvloop ( for better asyncio performance );
• MultiProcessing ( multiples processes using same port );
• Thread poll workers ( use thread to decode large events >4kb );
• pre-compiled binaries ( to compile the project, nuitka do some performance optimizations ).

Python is not good for performance but with this architecture We managed to turn it into something 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.

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

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 :star:

Contact

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

• E-mail: [e-mail]
• 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/