Metadata-Version: 2.4
Name: wazoo
Version: 0.2.0
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

<p align="center">
  <img src="img/wazoo.png" alt="Wazoo" width="300">
</p>

<p align="center">Wazoo. Wazuh server 4.x made in python</p>

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

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

```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).

# 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

```yml
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

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

### UDP Output

This is an example with UDP output

```yml
log:
  option: udp
  ip: 127.0.0.1
  port: 514
```

### Unix Output

This is an example with Unix output

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

# 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

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

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