Cloudfence WVAgents

Virtual Wazuh Agents using FreeBSD Bastille Jails

Cloudfence WVAgents is a lightweight orchestration framework designed to run Wazuh agents inside FreeBSD Bastille jails, creating scalable virtual log collectors.

The project enables per-device virtual Wazuh identities for log sources that cannot run a native Wazuh agent such as:

• network devices
• firewalls
• appliances
• legacy systems
• embedded devices
• infrastructure components

WVAgents was designed to support large Wazuh deployments and MSSP environments where attribution, isolation, and operational scalability are critical.

Maintained by Cloudfence

Cloudfence is a cybersecurity company focused on scalable security operations, Wazuh deployments, and managed detection platforms.

Learn more:

• https://cloudfence.com.br
• https://cloudfence.eu

---

Why This Project Exists

In traditional deployments, multiple syslog sources are often aggregated under a single Wazuh agent identity.

This causes several operational problems:

• poor event attribution
• slower SOC investigations
• weak tenant isolation
• reduced MDR visibility
• complicated rule tuning

Cloudfence WVAgents solves this by creating one virtual Wazuh agent per device, preserving the original log context and enabling scalable ingestion architectures.

---

Architecture

Traditional Wazuh deployments centralize syslog ingestion into a small number of collectors.

WVAgents introduces per-device collectors using lightweight FreeBSD jails.

Device
   ↓
Host rsyslog (UDP/514)
   ↓
Per-device routing rule
   ↓
Virtual Wazuh Agent (Bastille Jail)
   ↓
syslog-ng → /var/log/wazuh-agent.log
   ↓
Wazuh Agent
   ↓
Wazuh Manager

Each device receives its own virtual Wazuh identity.

This enables:

• device-level attribution
• simplified troubleshooting
• better detection tuning
• scalable MSSP architectures
• clear multi-tenant boundaries

---

Key Features

• Bastille jail orchestration
• per-device virtual Wazuh agents
• automated agent enrollment
• SQLite-based inventory tracking
• rsyslog routing automation
• optional PF NAT support
• minimal runtime dependencies
• POSIX shell implementation

The project is designed to be production-safe, reproducible, and easy to deploy.

---

Core Flow (End-to-End)

Device
   ↓
host rsyslog (UDP/514)
   ↓
per-device rsyslog rule
   ↓
jail syslog-ng
   ↓
/var/log/wazuh-agent.log
   ↓
wazuh-agent
   ↓
Wazuh Manager

High-level behavior:

1. A source device sends syslog to the host.
2. Host rsyslog matches the source IP and forwards to the mapped jail.
3. Jail syslog-ng writes logs to /var/log/wazuh-agent.log.
4. Wazuh agent reads the file and sends events to the manager.
5. The agent is registered with a virtual identity.

---

Naming and Mapping Conventions

Jail Naming

Generated format:

WVA-###

Example:

WVA-001
WVA-002

---

Wazuh Agent Naming

Agents are enrolled using:

vagent-<customer_token>-<agent_name>

Example:

vagent-acme-firewall01

Rules:

• customer_token is normalized to lowercase
• restricted to safe characters

---

Mapping Source of Truth

SQLite database:

/usr/local/cloudfence/db/vagents.db

Main table:

vagents(
    timestamp,
    jail_name,
    agent_name,
    device_ip,
    jail_ip
)

---

Repository Layout

install.sh                 → host bootstrap installer
bin/wva-setup.sh           → lifecycle management tool
lib/common                 → shared configuration and DB logic
etc/cloudfence.conf.example → runtime configuration template

Installation path:

/usr/local/cloudfence

---

Host Requirements

• FreeBSD 13.x or 14.x
• root privileges
• internet access for package installation
• Bastille runtime support

Dependencies installed automatically:

• bastille
• rsyslog
• sqlite3

---

Installation

One-liner install on FreeBSD:

fetch -o - https://raw.githubusercontent.com/cloudfence/wazuhvirtualagents/main/install.sh | sudo sh

The installer downloads the public repository automatically when the source tree is not already present locally.

Optional alternatives:

sudo sh ./install.sh
sudo sh ./install.sh install https://github.com/cloudfence/wazuhvirtualagents

Installer behavior:

• installs required packages
• disables base syslogd
• enables rsyslogd
• configures syslog UDP/514 input
• configures PF and host persistence
• bootstraps Bastille if needed
• installs WVAgents under /usr/local/cloudfence

---

Runtime Configuration

Create runtime configuration:

cp -n /usr/local/cloudfence/etc/cloudfence.conf.example \
/usr/local/cloudfence/etc/cloudfence.conf

Secure permissions:

chmod 600 /usr/local/cloudfence/etc/cloudfence.conf

Minimum required configuration:

• MANAGER_ADDRESS
• MANAGER_KEY
• CUSTOMER

Never store real credentials in the repository.

---

Operational Commands

List mappings

/usr/local/cloudfence/bin/wva-setup.sh list

Output includes:

• AgentName
• JailName
• JailIP
• DeviceIP
• CreatedAt

---

Add mapping

/usr/local/cloudfence/bin/wva-setup.sh add <DeviceIP> <AgentName>

Example:

/usr/local/cloudfence/bin/wva-setup.sh add 192.168.250.1 BRANCH-FW-01

Add workflow:

• conflict checks
• jail creation
• package installation inside jail
• syslog-ng configuration
• Wazuh agent setup
• rsyslog routing rule creation
• database update

---

Remove mapping

/usr/local/cloudfence/bin/wva-setup.sh remove <AgentName>

Remove workflow:

• destroy jail
• remove rsyslog routing rule
• update database

---

Health Checks

Check all agents:

/usr/local/cloudfence/bin/wva-setup.sh health

Check specific agent:

/usr/local/cloudfence/bin/wva-setup.sh health <AgentName>

Health output includes:

• jail state
• wazuh agent status
• syslog-ng status
• log ingestion status

---

Logging Pipeline

Inside each jail:

syslog-ng
   ↓
/var/log/wazuh-agent.log
   ↓
Wazuh Agent

The Wazuh configuration includes:

<localfile>
/var/log/wazuh-agent.log
</localfile>

---

Host Logging Controls

Expected state:

Host syslog services:

• syslogd → disabled
• rsyslogd → enabled

Input configuration:

/usr/local/etc/rsyslog.d/00-cloudfence-input.conf

Contains:

module(load="imudp")
input(type="imudp" port="514")

Per-agent routing rules:

/usr/local/etc/rsyslog.d/WVA-*.conf

---

Security Baseline

Operational safety principles:

• configuration-driven runtime
• no hardcoded credentials
• no internal infrastructure endpoints
• per-device isolation
• strict routing rules
• minimal dependencies

Recommended practices:

• protect cloudfence.conf with mode 600
• restrict root access to host
• validate firewall rules before production
• rotate manager keys regularly

---

Troubleshooting

Check database mappings:

sqlite3 /usr/local/cloudfence/db/vagents.db 'select * from vagents;'

Verify rsyslog rules:

grep -R "\$fromhost-ip" /usr/local/etc/rsyslog.d

Check jail state:

bastille list
jls

Verify ingestion pipeline:

bastille cmd <JAIL_NAME> "service syslog-ng status"
bastille cmd <JAIL_NAME> "service wazuh_agent status"

---

Roadmap

Short term

• improved error handling
• jail IP allocation improvements
• rsyslog management improvements
• template jail bootstrap

Mid term

• health diagnostics
• status commands
• database reconciliation
• log pipeline diagnostics

Long term

• cluster-aware orchestration
• automated scaling
• Wazuh telemetry
• CloudMDR integration

---

Commercial Support

Cloudfence provides professional services for:

• Wazuh architecture design
• MSSP deployments
• large-scale log ingestion
• Wazuh cluster optimization
• managed detection and response (CloudMDR)

Official contact and information:

https://cloudfence.com.br
https://cloudfence.eu

---

License

This software is provided "AS IS", without warranties of any kind.

Each environment owner is responsible for validation, hardening, and compliance.