Blocklists

External blocklists

What it does #

Periodically fetches operator-configured URL/file sources (cidr, ip, or csv) and feeds IPs/CIDRs into Manager blocklist cache for Agents to pull.

Edition #

SHARED.

Prerequisites #

• Manager can reach source URLs (or local files)
• Admin JWT for /api/v1/blocklists*
• Disk/memory for the merged set (no published scale number)

Required permissions / credentials #

• Outbound HTTPS if sources are remote
• No Zwall-issued third-party API key unless the source itself requires one (put tokens in URL query only if you accept log leakage — prefer authenticated fetch not implemented as a generic OAuth product)

Configuration #

security.blocklists.*:

• enabled
• sources[]: name, url, enabled, format (optional auto-detect)
• update_interval, timeout, sync_schedule (cron string example 0 2 * * *), retry_attempts, retry_delay

Setup #

1. Enable security.blocklists.enabled: true.
2. Add a source with a name and url you are licensed to use.
3. Restart Manager.
4. POST /api/v1/blocklists/sync as admin.
5. GET /api/v1/blocklists/stats and GET /api/v1/blocklists/check/203.0.113.10.

Verification #

• Stats show last sync time / counts (shape: API_SCHEMA_DOCUMENTATION_BLOCKED)
• Agent GET /api/v1/agents/:id/sync/blocklist returns entries

Expected signals / results #

Hits may appear as blocklist-related security logs / block reasons after Agents sync. Not instantaneous globally.

Failure modes #

Troubleshooting #

• POST /api/v1/blocklists/:id/sync for one source
• Confirm Manager egress and DNS
• Retry keys: retry_attempts, retry_delay

Security considerations #

Third-party lists can false-positive. Review license of the list. HTTPS sources still need integrity judgment. Do not auto-block without monitoring.

Limitations #

• Not a threat-intel platform
• No certified freshness SLA
• Community 3-Agent cap is unrelated to list size

Related #

• API blocks
• Blocks product