Metadata-Version: 2.4
Name: wazoo
Version: 0.1.1
Summary: Python Wazuh runtime server to handle agent registration and log receive
License-File: LICENSE.md
Requires-Python: >=3.13
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: pycryptodome>=3.23.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: sqlmodel>=0.0.39
Requires-Dist: uvloop>=0.22.1
Description-Content-Type: text/markdown

# 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**:

```sh
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:

```sh
uv sync
uv run wazoo -v
```

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

```sh
uv run python -m wazoo -v
```

List every available option with:

```sh
uv run wazoo --help
```

> If you want to use TCP+SSL, create the certificates first — see [Setup development environment](#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](https://github.com/souzomain/wazoo/releases). 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:

```sh
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](https://github.com/souzomain/wazoo/releases) 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**

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

Sync the project 

```sh
uv sync
```

Create the SSL pem

```
./scripts/generate_ssl.sh
```

Now you can run the server

```sh
uv run wazoo -v
```

# Test

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

```sh
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**: 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/
