Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › API › Blocks

Blocks

API: blocks and blocklists

SharedStatus: SUPPORTEDAudience: security engineer

Admin: AdminAuth() + RoleAuth("admin"). Source: blocking_handler.go, blocklist_handler.go.

Designed to fail closed at the blocking pipeline; not a product-wide certification.

GET /api/v1/security/blocked-ips

Purpose. List IPs currently recorded as blocked.

Authentication. Admin.

Parameters. Common list handlers may accept limit/offset; API_SCHEMA_DOCUMENTATION_BLOCKED if this GET uses an untyped map rather than ListSecurityLogs defaults — GetBlockedIPs (method name in inventory: list blocked) returns gin.H. Known pattern: success payload contains IP list from the blocking repository.

Request. Empty.

Example request.

curl -sS https://manager.example.com:8443/api/v1/security/blocked-ips \
  -H "Authorization: Bearer TOKEN"

Response (200). gin.H with blocked IP records. API_SCHEMA_DOCUMENTATION_BLOCKED for column set (BlockingHandler list uses repository structs or maps). zwallctl list consumes this family.

Errors. 500/503 when blocking repository is not configured (Blocking repository not configured on write paths).

Edition. SHARED.

POST /api/v1/security/blocked-ips/block

Purpose. Manually block an IP or CIDR through the blocking pipeline.

Authentication. Admin.

Request (anonymous struct on BlockIP):

Scroll sideways to see the full table. Use the arrow keys when focused.

FieldRequired
ipyes
ip_versionno
directionno
reasonno

Example request.

{"ip": "203.0.113.10", "reason": "manual", "direction": "inbound"}

Response (200). Keys observed: success, blocked, ip, ip_version, plus reason/source/direction/details on success path.

Errors. 400 ip required, invalid ip address or CIDR format, Cannot block critical system IP address; 503 Blocking repository not configured; 500 Failed to block IP.

Edition. SHARED.

Security. Manual blocks are privileged. Do not block the Manager’s own address. RFC 5737 only in examples.

DELETE /api/v1/security/blocked-ips/:ip

Purpose. Unblock one IP/CIDR.

Authentication. Admin.

Parameters. :ip.

Request. Empty.

Response (200). Keys: success, unblocked, ip, ip_version, already_clear when the IP was not blocked.

Errors. 400 invalid IP/CIDR; 503 repository missing; 500 Failed to unblock IP.

Edition. SHARED.

POST /api/v1/security/login-failures/:ip/unblock

Purpose. Unblock an IP that was blocked via login-failure / brute-force path (UnblockIPFromLoginFailures).

Authentication. Admin.

Parameters. :ip.

Response. Same unblock family (success / error). API_SCHEMA_DOCUMENTATION_BLOCKED if extra keys differ from UnblockIP.

Edition. SHARED.

Blocklists (external sources)

GET /api/v1/blocklists/stats

Purpose. Blocklist source statistics.

Authentication. Admin.

Response. API_SCHEMA_DOCUMENTATION_BLOCKED — BlocklistHandler stats gin.H.

Edition. SHARED.

POST /api/v1/blocklists/sync

Purpose. Trigger sync of configured HTTP/file blocklist sources.

Authentication. Admin.

Request. Empty or service-defined. API_SCHEMA_DOCUMENTATION_BLOCKED for body.

Edition. SHARED.

GET /api/v1/blocklists/check/:ip

Purpose. Check whether an IP hits a loaded blocklist.

Authentication. Admin.

Parameters. :ip.

Response. API_SCHEMA_DOCUMENTATION_BLOCKED — hit/miss gin.H.

Edition. SHARED.

GET /api/v1/blocklists/:id

PUT /api/v1/blocklists/:id

POST /api/v1/blocklists/:id/sync

Purpose. Per-source get/update/sync.

Authentication. Admin.

Response/request. API_SCHEMA_DOCUMENTATION_BLOCKED — handler uses maps/gin.H around BlocklistsConfig sources rather than a single public DTO.

Known YAML source fields (configuration authority, not necessarily the PUT body): name, url, enabled, format.

Edition. SHARED.

Agent pull

GET /api/v1/agent-blocked-ips — Agent JWT + CapabilityBlocklistSync. Agent-facing; not a public website cookbook.