wazoo 0.3.0

Python Wazuh runtime server to handle agent registration and log receive

Wazoo. Wazuh server 4.x made in python

What is Wazoo

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

wazoo does not replace wazuh. wazoo does not decode logs, it only get logs from wazuh agent and decode the encrypted message.

You can use wazoo 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.

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

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

Getting Started

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

Run with docker

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

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.

Configuration

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

Configuration 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 as a library:

from wazoo import WazooLog

async def on_log(log: bytes):
    print("received:", log)

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

await log.connect()
await log.sendLog(b"hello world")
await log.close()

See docs/README.md for more details.

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