Download vspam-agent

Install from Repositoryrecommended

Automatic updates via your system package manager. Packages hosted on packages.vspam.org.

# Add GPG key
curl -fsSL https://packages.vspam.org/apt/vspam-archive-keyring.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/vspam-archive-keyring.gpg

# Add repository
echo "deb [signed-by=/usr/share/keyrings/vspam-archive-keyring.gpg] \
  https://packages.vspam.org/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/vspam.list

# Install
sudo apt update && sudo apt install vspam-agent

# Add repository
sudo tee /etc/yum.repos.d/vspam.repo <<EOF
[vspam]
name=vspam.org packages
baseurl=https://packages.vspam.org/rpm/el/9/\$basearch/
enabled=1
gpgcheck=1
gpgkey=https://packages.vspam.org/rpm/RPM-GPG-KEY-vspam
EOF

# Install
sudo dnf install vspam-agent

Manual Download

Download individual packages if you prefer manual installation or don't have repo access.

sudo dpkg -i vspam-agent_0.2.0_amd64.deb

sudo dpkg -i vspam-agent_0.2.0_arm64.deb

sudo rpm -i vspam-agent-0.2.0-1.x86_64.rpm

sudo rpm -i vspam-agent-0.2.0-1.aarch64.rpm

tar xzf vspam-agent-0.2.0-linux-amd64.tar.gz && sudo cp vspam-agent-*/vspam-agent /usr/local/bin/

tar xzf vspam-agent-0.2.0-linux-arm64.tar.gz && sudo cp vspam-agent-*/vspam-agent /usr/local/bin/

All packages available on GitHub Releases and packages.vspam.org/releases.

Quick Start

# Debian/Ubuntu (after adding repo — see above)
sudo apt update && sudo apt install vspam-agent

# RHEL/CentOS/Fedora (after adding repo — see above)
sudo dnf install vspam-agent

# /etc/vspam/agent.yml
api_url: https://api.vspam.org
api_key: "your-key-here"        # optional, get one at vspam.org/account
listen: tcp://127.0.0.1:10045
cache_ttl: 10m
dnsbl_enabled: true
dnsbl_zone: dnsbl.vspam.org

sudo systemctl enable --now vspam-agent
sudo systemctl status vspam-agent

# /etc/postfix/main.cf
smtpd_recipient_restrictions =
    permit_mynetworks,
    permit_sasl_authenticated,
    reject_unauth_destination,
    check_policy_service inet:127.0.0.1:10045

# Then reload
sudo postfix reload

How It Works

Incoming email → Postfix (SMTP)
                   → smtpd_recipient_restrictions
                     → check_policy_service inet:127.0.0.1:10045
                       → vspam-agent
                         1. Check local BoltDB cache (sub-ms)
                         2. Query vspam.org REST API (by IOC hash)
                         3. Query dnsbl.vspam.org (DNS blocklist)
                         → DUNNO (allow) or REJECT (block)
                         → Async report new threats back to API

• Fail-open — API down or DNS errors = allow (DUNNO). Mail never blocked by agent failure.
• Fast — BoltDB cache means repeat lookups are sub-millisecond.
• Async reporting — blocked senders are reported to the API in the background. SMTP response is never delayed.
• Lightweight — single Go binary, ~10 MB, no dependencies.

Configuration Reference

Config file: /etc/vspam/agent.yml

# vspam.org API endpoint
api_url: https://api.vspam.org

# API key (get one at https://vspam.org/account)
api_key: "vspam_xxxxxxxxxxxx"

# Policy daemon listen address
listen: tcp://127.0.0.1:10045

# Local cache (BoltDB)
cache_ttl: 10m
cache_path: /var/lib/vspam/cache.db

# DNSBL lookup
dnsbl_enabled: true
dnsbl_zone: dnsbl.vspam.org

# Reject message for blocked senders
reject_message: "550 Message rejected: sender listed in vspam.org (phishing)"

# Auto-report (requires api_key)
reporting_enabled: true
queue_size: 1000

log_level: info

CLI Commands

# Start the policy daemon (foreground)
vspam-agent serve
vspam-agent --config /etc/vspam/agent.yml serve

# Print version
vspam-agent --version

Systemd Service

sudo systemctl start vspam-agent    # Start
sudo systemctl stop vspam-agent     # Stop
sudo systemctl restart vspam-agent  # Restart
sudo systemctl status vspam-agent   # Status
sudo journalctl -u vspam-agent -f   # Logs

Lookup Chain

1. Local cache (BoltDB) — sub-millisecond, avoids network calls for repeat senders
2. REST API (GET /api/v1/lookup/:hash) — SHA-256 hash of sender domain/IP
3. DNSBL (dig <domain>.dnsbl.vspam.org A) — returns 127.0.0.2 if listed

First definitive result wins. Cache stores both positive (malicious) and negative (clean) results with configurable TTL.

Security

• Runs as unprivileged vspam system user
• Systemd hardening: NoNewPrivileges, ProtectSystem=strict, PrivateTmp
• API key stored in config file with 0640 permissions
• Fail-open: lookup errors never block mail delivery
• Cache prevents API/DNS amplification from high mail volume

Troubleshooting

Agent not starting

sudo journalctl -u vspam-agent -e
# Common: config parse error, port already in use, permission denied

Mail not being checked

# Verify Postfix config
postconf smtpd_recipient_restrictions | grep policy

# Verify agent is listening
ss -tlnp | grep 10045

False positives

# Check why a domain was blocked
sudo journalctl -u vspam-agent | grep "domain.com"

# Request delisting at https://vspam.org/delist

Cache issues

sudo systemctl stop vspam-agent
sudo rm /var/lib/vspam/cache.db
sudo systemctl start vspam-agent

Build from Source

git clone https://github.com/vspam-org/vspam.org.git
cd vspam.org/agent
CGO_ENABLED=0 go build -o vspam-agent ./cmd/agent