Download vspam-agent

Operator-Safe Enforcement Defaults

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.1.2_amd64.deb

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

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

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

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

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

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

Verify Packages

All packages are GPG-signed. Verify integrity before installing.

# Debian/Ubuntu — key is imported automatically with the repo setup above
# For manual verification:
curl -fsSL https://packages.vspam.org/apt/vspam-archive-keyring.gpg | gpg --import

# RHEL/CentOS/Fedora
sudo rpm --import https://packages.vspam.org/rpm/RPM-GPG-KEY-vspam

curl -fsSLO https://packages.vspam.org/releases/SHA256SUMS
curl -fsSLO https://packages.vspam.org/releases/SHA256SUMS.asc

# Verify the checksum file signature
gpg --verify SHA256SUMS.asc SHA256SUMS

# Verify your download
sha256sum -c SHA256SUMS --ignore-missing

# Each tarball has a detached .asc signature
curl -fsSLO https://packages.vspam.org/releases/vspam-agent-0.1.2-linux-amd64.tar.gz
curl -fsSLO https://packages.vspam.org/releases/vspam-agent-0.1.2-linux-amd64.tar.gz.asc
gpg --verify vspam-agent-0.1.2-linux-amd64.tar.gz.asc

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

# Fail open. Postfix defaults to deferring every message with a 451 when a
# policy service is unreachable, on a 100s timeout, so these two lines matter
# more than the third: without them, an agent restart stops your mail.
smtpd_policy_service_default_action = DUNNO
smtpd_policy_service_timeout = 10s

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 operator lookup / exact-host RBL
                         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.
• Operator-safe by design — exact hosts and canonical domains are the main enforcement path; broader IPv6 prefix and ASN context should stay in review workflows unless you have explicit policy for them.

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

Command Line

The same binary is the CLI, so installing the package gets you both — one version, one signature, one thing to upgrade. Serving stays the default, so the systemd unit is unaffected.

vspam-agent check <indicator>...   # exit 1 if any are listed
vspam-agent report <indicator>     # submit one
vspam-agent bulk [file]            # submit many, one per line (stdin by default)
vspam-agent eml [file]             # extract indicators from a message

Checking

Exit codes are the interface: 0 nothing listed, 1 something listed, 2 the lookup failed. A failed lookup is deliberately not 0 — a script gating mail on this should fail loudly rather than let a message through because DNS was down. No API key is needed; one raises the rate limit.

$ vspam-agent check login-paypa1.com safe.example.org
login-paypa1.com                         LISTED   phishing_domain (consensus)
safe.example.org                         clean

if ! vspam-agent check "$DOMAIN" >/dev/null; then echo "refusing $DOMAIN"; fi

Reporting

Type and category are inferred using the same rules as the web submit form, and defanged input is normalized. Lists longer than the API’s 100-per-request cap are split across requests rather than rejected. --dry-run prints what would be sent and submits nothing.

vspam-agent report --evidence "credential harvest, seen 2026-08-26" \
  'hxxps://login-paypa1[.]com/verify'

grep -oP 'https?://\S+' quarantine.log | vspam-agent bulk

Message files

Reads the sender addresses, the connecting IP from the header your own MX wrote, and links in the text parts. The message is parsed locally and never uploaded — only the extracted indicators are sent, and only with --report.

$ vspam-agent eml suspicious.eml
email      from             support@evil.example.net
ip         received         203.0.113.66
url        body             https://login.evil.example.net/verify?u=1

3 indicators. Re-run with --report to submit them.

Running the daemon

# Serving is the default, so the subcommand is optional
vspam-agent
vspam-agent --config /etc/vspam/agent.yml serve

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/public/operator-lookup) — canonical domain and ASN checks without client-side hashing
3. IP RBL / DNSBL (GET /api/v1/rbl/check?ip=... or dig <domain>.dnsbl.vspam.org A) — exact IPv4 / IPv6 host checks and direct DNSBL policy lookups

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

Source

The filter configuration — the Rspamd module, the SpamAssassin rules, the Ansible role and the mailcow overlay — is public and AGPL-3.0 licensed at github.com/vspam-org/integrations. The agent daemon's repository is not published yet; the binaries above are built from it and signed with the key below.