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

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

# Documentation

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

see [Documentation](./docs/)

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