ClamReef Agent

A lightweight, cross-platform control plane agent for ClamAV antivirus that provides centralized monitoring, configuration management, and comprehensive endpoint protection telemetry through OpenTelemetry.

Overview

ClamReef Agent is part of the ClamReef control plane architecture, designed to manage and monitor ClamAV installations across distributed environments. The agent runs alongside ClamAV, collecting comprehensive endpoint protection metrics, executing scheduled scans, and reporting telemetry data to observability backends via OpenTelemetry.

Features

🔒 Endpoint Protection Monitoring: Comprehensive security metrics including threat detection, quarantine, and remediation tracking
📊 Rich Host Metrics: System information including hostname, OS details, hardware serial numbers, and user presence
⏱️ Performance Analytics: Scan duration tracking with real-time, average, and maximum timing metrics
🗓️ Automated Scanning: Cron-based scheduling for ClamAV scans with configurable rules and exclusions
📡 OpenTelemetry Integration: Export metrics to any OTLP-compatible backend (Prometheus, Grafana, Jaeger)
⚙️ Flexible Configuration: Local TOML/YAML configuration with future support for centralized management
🌐 Cross-Platform: Runs on Linux, macOS, and Windows with native OS integration
🚀 Small Footprint: Minimal resource usage, written in Rust for efficiency and safety
✅ Well-Tested: Comprehensive unit, integration, and E2E test coverage

Architecture

┌─────────────────────────────────────────────────────────────┐
│                   ClamReef Architecture                     │
└─────────────────────────────────────────────────────────────┘

┌─────────────┐    ┌─────────────────────────────────────────┐
│   ClamAV    │◄──►│            ClamReef Agent               │
│   Daemon    │    │                                         │
│             │    │  • Scan Scheduler                       │
│             │    │  • Metrics Collector                    │
│             │    │  • Host Information Gatherer            │
│             │    │  • Performance Monitor                  │
│             │    │  • Telemetry Exporter                   │
└─────────────┘    └─────────────────┬───────────────────────┘
                                     │
                                     │ OpenTelemetry OTLP
                                     ▼
                   ┌─────────────────────────────────────────┐
                   │          Observability Stack           │
                   │                                         │
                   │  • Prometheus (metrics storage)        │
                   │  • Grafana (visualization)             │
                   │  • Jaeger (distributed tracing)        │
                   │  • Any OTLP-compatible collector       │
                   └─────────────────────────────────────────┘

Prerequisites

Rust 1.70+ (for building from source)
ClamAV installed and running (clamd daemon or clamscan CLI)
OpenTelemetry Collector or OTLP-compatible backend
Permissions to access ClamAV socket/TCP port and scan directories

Installation

From Source

# Clone the repository
git clone https://github.com/yourusername/clamreef-agent.git
cd clamreef-agent

# Build the agent
make build

# Run tests to verify installation
make test

# Install binary to /usr/local/bin (requires sudo)
sudo make install

Using Cargo

# Install directly from crates.io
cargo install clamreef-agent

# Or install from Git
cargo install --git https://github.com/yourusername/clamreef-agent.git

Pre-built Binaries

Download the latest release for your platform from the releases page.

# Linux/macOS
curl -LO https://github.com/yourusername/clamreef-agent/releases/latest/download/clamreef-agent-$(uname -s)-$(uname -m)
chmod +x clamreef-agent-*
sudo mv clamreef-agent-* /usr/local/bin/clamreef-agent

# Verify installation
clamreef-agent --version

Configuration

Create a configuration file at /etc/clamreef/agent.toml (system-wide) or ~/.clamreef/agent.toml (user-specific):

[agent]
version = "1.0.0"
machine_name = "prod-server-01"  # Optional, auto-detected if not set
log_level = "info"              # trace, debug, info, warn, error

[telemetry]
endpoint = "http://localhost:4317"  # OTLP gRPC endpoint
interval_seconds = 30               # Metrics export interval
timeout_seconds = 10                # Request timeout

[clamav]
# Unix socket (preferred on Linux/macOS)
socket_path = "/var/run/clamav/clamd.ctl"
# OR TCP connection (Windows/remote)
# tcp_host = "127.0.0.1"
# tcp_port = 3310
scan_timeout_seconds = 60

# Scanning rules with cron schedules
[[rules]]
name = "system_binaries"
paths = ["/usr/bin", "/usr/local/bin", "/opt"]
schedule = "0 */6 * * *"  # Every 6 hours
exclude_patterns = ["*.log", "*.tmp", "*.cache"]
recursive = true
follow_symlinks = false

[[rules]]
name = "user_directories"
paths = ["/home", "/Users"]
schedule = "0 2 * * *"    # Daily at 2 AM
exclude_patterns = [
    "*.iso", "*.dmg", "*.img",     # Disk images
    "node_modules/", ".git/",       # Development folders
    "*.sock", "*.pid"               # Runtime files
]
recursive = true
follow_symlinks = false

[[rules]]
name = "web_content"
paths = ["/var/www", "/srv/http"]
schedule = "0 */4 * * *"  # Every 4 hours
exclude_patterns = ["uploads/*.zip", "cache/", "logs/"]
recursive = true

[[rules]]
name = "downloads_realtime"
paths = ["/tmp", "/Downloads"]
schedule = "*/15 * * * *"  # Every 15 minutes
exclude_patterns = []
recursive = true

Environment Variables

Override configuration with environment variables:

export CLAMREEF_LOG_LEVEL=debug
export CLAMREEF_TELEMETRY_ENDPOINT=http://otel-collector:4317
export CLAMREEF_CLAMAV_SOCKET=/custom/path/clamd.sock

Usage

Basic Usage

# Run with default configuration
clamreef-agent

# Specify custom config file
clamreef-agent --config /path/to/config.toml

# Set log level
clamreef-agent --log-level debug

# Validate configuration without running
clamreef-agent --dry-run

# Show version and build info
clamreef-agent --version

# Display help
clamreef-agent --help

Systemd Service (Linux)

Create a systemd service for automatic startup:

# Create service file
sudo tee /etc/systemd/system/clamreef-agent.service <<EOF
[Unit]
Description=ClamReef Agent - ClamAV Control Plane Agent
Documentation=https://github.com/yourusername/clamreef-agent
After=network.target clamav-daemon.service
Wants=clamav-daemon.service

[Service]
Type=simple
User=clamreef
Group=clamreef
ExecStart=/usr/local/bin/clamreef-agent --config /etc/clamreef/agent.toml
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=clamreef-agent

# Security settings
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/log/clamreef

[Install]
WantedBy=multi-user.target
EOF

# Create user and directories
sudo useradd -r -s /bin/false clamreef
sudo mkdir -p /etc/clamreef /var/log/clamreef
sudo chown clamreef:clamreef /var/log/clamreef

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable clamreef-agent
sudo systemctl start clamreef-agent

# Check status
sudo systemctl status clamreef-agent

# View logs
journalctl -u clamreef-agent -f

Docker

# Build Docker image
docker build -t clamreef-agent .

# Run with Docker Compose
cat > docker-compose.yml <<EOF
version: '3.8'
services:
  clamreef-agent:
    build: .
    restart: unless-stopped
    volumes:
      - /var/run/clamav:/var/run/clamav:ro
      - /etc/clamreef:/etc/clamreef:ro
      - /var/log/clamreef:/var/log/clamreef
    environment:
      - CLAMREEF_TELEMETRY_ENDPOINT=http://otel-collector:4317
    depends_on:
      - otel-collector

  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    ports:
      - "4317:4317"  # OTLP gRPC
      - "4318:4318"  # OTLP HTTP
    volumes:
      - ./otel-config.yaml:/etc/otel-collector-config.yaml
    command: ["--config=/etc/otel-collector-config.yaml"]
EOF

docker-compose up -d

Metrics

ClamReef Agent exports comprehensive endpoint protection metrics with the clamreef_ prefix:

Scanning Metrics

clamreef_scans_total - Total completed scans
clamreef_threats_detected_total - Total threats found
clamreef_files_scanned_total - Total files processed
clamreef_scan_errors_total - Scan failures and errors
clamreef_rule_executions_total - Rule execution count

Performance Metrics

clamreef_last_scan_duration_ms - Duration of most recent scan
clamreef_avg_scan_duration_ms - Rolling average scan time (last 100 scans)
clamreef_max_scan_duration_ms - Maximum scan duration observed

Endpoint Protection Metrics

clamreef_quarantined_files_total - Files quarantined by the system
clamreef_cleaned_files_total - Files successfully cleaned/disinfected
clamreef_last_threat_timestamp - Unix timestamp of last threat detection
clamreef_database_age_hours - Age of virus definition database
clamreef_realtime_protection_enabled - Real-time scanning status (boolean)
clamreef_last_full_scan_timestamp - Last full system scan completion
clamreef_pending_scans - Number of scans queued for execution

Host Information Metrics

clamreef_hostname - System hostname
clamreef_os_name - Operating system name
clamreef_os_version - OS version information
clamreef_kernel_version - Kernel version
clamreef_serial_number - Hardware serial number (when available)
clamreef_users - List of non-system users (excludes root, _mbsetupuser, etc.)

ClamAV Integration Metrics

clamreef_clamav_database_version - Current virus database version
clamreef_clamav_engine_version - ClamAV engine version string
clamreef_agent_uptime_seconds - Agent uptime in seconds

Sample Telemetry Output

ClamReef Scanning - Total: 1247, Threats: 3, Errors: 0, Files: 45891, Pending: 0
ClamReef Performance - Last Scan: 1250ms, Avg: 980ms, Max: 2100ms
ClamReef Protection - Quarantined: 3, Cleaned: 0, Last Threat: 2 hours ago, RT Protection: Enabled
ClamReef Host - Hostname: prod-server-01, OS: Ubuntu 22.04, Kernel: 5.15.0, Serial: DMI12345
ClamReef System - Users: [alice, bob], Agent: v0.1.0, ClamAV: 1.4.3 (DB: v27763), Uptime: 86400s

Grafana Dashboard

Import the pre-built Grafana dashboard for ClamReef monitoring:

{
  "dashboard": {
    "title": "ClamReef Endpoint Protection",
    "panels": [
      {
        "title": "Threat Detection Rate",
        "type": "stat",
        "targets": [
          {
            "expr": "rate(clamreef_threats_detected_total[5m])"
          }
        ]
      },
      {
        "title": "Scan Performance",
        "type": "timeseries",
        "targets": [
          {
            "expr": "clamreef_avg_scan_duration_ms"
          }
        ]
      }
    ]
  }
}

Development

Building from Source

# Install Rust if needed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone and build
git clone https://github.com/yourusername/clamreef-agent.git
cd clamreef-agent

# Development build
cargo build

# Release build with optimizations
cargo build --release

# Run tests
cargo test

# Run specific test module
cargo test metrics::tests

# Generate test coverage report
cargo tarpaulin --out Html --output-dir coverage

# Lint code
cargo clippy -- -D warnings

# Format code
cargo fmt

# Check for security vulnerabilities
cargo audit

Project Structure

clamreef-agent/
├── src/
│   ├── main.rs              # Entry point and agent lifecycle
│   ├── lib.rs               # Library exports
│   ├── error.rs             # Error types and handling
│   ├── config/
│   │   └── mod.rs           # Configuration management
│   ├── clamav/
│   │   ├── mod.rs           # ClamAV module exports
│   │   ├── client.rs        # ClamAV communication (Unix/TCP)
│   │   ├── parser.rs        # Response parsing logic
│   │   └── types.rs         # Data structures
│   ├── metrics/
│   │   └── mod.rs           # Metrics collection and host info
│   ├── telemetry/
│   │   └── mod.rs           # OpenTelemetry integration
│   └── scheduler/
│       └── mod.rs           # Cron-based task scheduling
├── tests/
│   ├── integration/         # Integration tests
│   └── e2e/                # End-to-end tests
├── examples/
│   └── agent.toml          # Example configuration
├── Cargo.toml              # Rust dependencies and metadata
├── Makefile               # Build automation and common tasks
├── Dockerfile             # Container image definition
├── CLAUDE.md              # Development instructions for Claude Code
└── README.md              # This file

Running Tests

# Run all tests
make test

# Unit tests only
make test-unit

# Integration tests
make test-e2e

# Test with coverage
make coverage

# Run tests with specific output
cargo test -- --nocapture

# Run tests matching pattern
cargo test metrics::tests::test_host_metrics

Making Changes

# Create feature branch
git checkout -b feature/new-metric

# Make changes and add tests
# ...

# Run full test suite
make test

# Check code quality
make lint

# Format code
cargo fmt

# Commit changes
git add .
git commit -m "Add new endpoint protection metric"

# Push and create PR
git push origin feature/new-metric

Troubleshooting

Agent Won't Start

Check ClamAV status:

# Linux
systemctl status clamav-daemon

# macOS
brew services list | grep clamav

# Manual check
clamdscan --version

Validate configuration:

clamreef-agent --dry-run --config /path/to/config.toml

Check permissions:

# Unix socket permissions
ls -la /var/run/clamav/clamd.ctl

# Test socket connection
echo "PING" | nc -U /var/run/clamav/clamd.ctl

Review logs:

# Systemd
journalctl -u clamreef-agent -f

# Docker
docker logs clamreef-agent

# Direct execution
clamreef-agent --log-level debug

No Metrics Appearing

Test OTLP endpoint:

# Check if collector is reachable
curl -v http://localhost:4317

# Test with grpcurl
grpcurl -plaintext localhost:4317 list

Check firewall rules:

# Linux
sudo ufw status
sudo iptables -L

# macOS
sudo pfctl -sr

Enable debug logging:

RUST_LOG=debug clamreef-agent --log-level debug

Test with local collector:

# Run basic OTLP collector
docker run -p 4317:4317 -p 4318:4318 \
  otel/opentelemetry-collector:latest

Performance Issues

High CPU usage:
- Reduce scan frequency in rules
- Add more specific exclude patterns
- Limit concurrent scans
High memory usage:
- Decrease telemetry export interval
- Check for memory leaks with valgrind
- Monitor with system tools:
```
top -p $(pgrep clamreef-agent)
ps aux | grep clamreef-agent
```
Slow scans:
- Exclude large binary files
- Use max_file_size limits
- Check ClamAV database updates

Common Error Messages

"Connection refused": ClamAV daemon not running or wrong socket path
"Permission denied": Insufficient permissions for socket or scan directories
"Invalid cron expression": Check schedule format in rules
"OTLP export failed": Telemetry endpoint unreachable or misconfigured

Security

Best Practices

File Permissions: Set config files to 600 (owner read/write only)
```
chmod 600 /etc/clamreef/agent.toml
```
User Isolation: Run agent as dedicated user, not root
```
sudo useradd -r -s /bin/false clamreef
```

Network Security: Use TLS for OTLP connections in production

[telemetry]
endpoint = "https://secure-collector:4318"
headers = { "Authorization" = "Bearer YOUR_TOKEN" }

Secret Management: Use environment variables for sensitive data
```
export CLAMREEF_TELEMETRY_TOKEN="secret_token"
```

Reporting Security Issues

Please report security vulnerabilities privately to security@clamreef.io. Do not create public GitHub issues for security problems.

Include in your report:

Detailed description of the vulnerability
Steps to reproduce the issue
Potential impact assessment
Suggested fix (if known)

See SECURITY.md for our complete security policy.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines.

Quick Start

Fork the repository on GitHub
Create a feature branch: git checkout -b feature/amazing-new-feature
Write tests for your changes
Ensure all tests pass: make test
Run linting: make lint
Submit a pull request with a clear description

Development Setup

# Install development dependencies
cargo install cargo-tarpaulin cargo-audit

# Set up pre-commit hooks
cp scripts/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

# Run development checks
make dev-check

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Documentation: https://docs.clamreef.io
GitHub Issues: Bug reports and feature requests
GitHub Discussions: Community support and questions
Email: support@clamreef.io

Roadmap

View our development roadmap for upcoming features and improvements:

v0.2.0: Real-time file monitoring with inotify/FSEvents
v0.3.0: Remote configuration management
v0.4.0: Distributed scanning coordination
v1.0.0: Production-ready release with full OTLP compliance

Acknowledgments

ClamAV - Open-source antivirus engine
OpenTelemetry - Observability framework
Rust - Systems programming language
Tokio - Asynchronous runtime for Rust
Contributors - Thank you to all who have contributed code, documentation, and feedback

Built with ❤️ in Rust for the open-source security community.

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
.github		.github
examples		examples
src		src
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
TESTING_OAUTH2.md		TESTING_OAUTH2.md
agent.toml		agent.toml
deny.toml		deny.toml
plan.md		plan.md
test-oauth2.toml.example		test-oauth2.toml.example

Folders and files

Latest commit

History

Repository files navigation

ClamReef Agent

Overview

Features

Architecture

Prerequisites

Installation

From Source

Using Cargo

Pre-built Binaries

Configuration

Environment Variables

Usage

Basic Usage

Systemd Service (Linux)

Docker

Metrics

Scanning Metrics

Performance Metrics

Endpoint Protection Metrics

Host Information Metrics

ClamAV Integration Metrics

Sample Telemetry Output

Grafana Dashboard

Development

Building from Source

Project Structure

Running Tests

Making Changes

Troubleshooting

Agent Won't Start

No Metrics Appearing

Performance Issues

Common Error Messages

Security

Best Practices

Reporting Security Issues

Contributing

Quick Start

Development Setup

License

Support

Roadmap

Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 9

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages