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

Security

API: detection and security operations

SharedStatus: SUPPORTED as implemented Manager servicesAudience: security engineer

Admin: AdminAuth() + RoleAuth("admin") unless noted. Source: security_handler.go and sibling detection handlers.

Do not document POST /api/v1/security/analyze-now or alert .../test as daily operator APIs.

GET /api/v1/security/logs

GET /api/v1/security-logs

Purpose. List security logs (same ListSecurityLogs handler on both prefixes).

Authentication. Admin.

Parameters (query):

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

ParamDefaultNotes
limit100invalid/≤0 → 100; cap 1000
offset0invalid → 0
log_idpositive int; 400 Invalid log_id
log_type
agent_idint if parsable
severity
action
source_ip
destination_ip
start_timeRFC3339; invalid logged and ignored
end_timeRFC3339; invalid logged and ignored

Request. Empty.

Example request.

curl -sS 'https://manager.example.com:8443/api/v1/security/logs?limit=100&offset=0' \
  -H "Authorization: Bearer TOKEN"

Response (200). Flat V1 compatibility object (not V1OK):

{
  "logs": [],
  "total": 0,
  "limit": 100,
  "offset": 0
}

logs are SecurityLog domain rows. API_SCHEMA_DOCUMENTATION_BLOCKED for every column beyond the list wrapper — row JSON follows logdomain.SecurityLog tags (id, event_id, log_type, IPs, ports, action, severity, details, agent_id, created_at, …).

Errors. 400 Invalid log_id; 500 Failed to list security logs.

Edition. SHARED.

POST /api/v1/security/logs

POST /api/v1/security-logs

Purpose. Create one security log. Agent-facing on /api/v1/security-logs (JWT + CapabilitySecurityLogIngest). The /api/v1/security/logs POST is registered on the admin security group in inventory as PUBLIC — confirm live middleware: Main router Agent-posts security-logs and also has POST /api/v1/security/logs on the admin security group (CreateSecurityLog still requires agent_id in context). If called without Agent middleware, expect 400 Agent ID not found in context.

Authentication. Agent JWT for /security-logs. Do not call create from a browser.

Audience. Agent-facing ingest — not a browser cookbook.

Request (logdomain.LogRequest), UTF-8 JSON max 16 KiB:

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

FieldRequired
log_typeyes
event_idoptional; validated if present
source_ip / destination_ip / MACs / protocol / ports
action / severityoptional; action normalized
tcp_flags / packet_size / details

Example request.

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "log_type": "ip_blocked",
  "source_ip": "203.0.113.10",
  "action": "blocked",
  "severity": "high"
}

Response (201) new row, or 200 with idempotent_replay: true if already committed:

{
  "success": true,
  "log_id": 1,
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Security log created successfully",
  "metadata": {
    "agent_id": 1,
    "log_type": "ip_blocked",
    "action": "blocked",
    "severity": "high",
    "timestamp": "2026-08-21T12:00:00Z"
  }
}

High/critical severity adds alert.requires_attention, severity, recommendation.

Errors. 400 Invalid request format / Invalid event_id / Agent ID not found in context / Invalid security-log contract; 500 Invalid agent ID type / Failed to create security log; 409 Security-log identity conflict.

Edition. SHARED.

Security. Hosting vs virtualization contracts differ (validateAgentLogContractWithProfile). Empty event_id is assigned server-side and is not safely retryable.

POST /api/v1/security-logs/batch

POST /api/v1/logs/batch

Purpose. Batch ingest (max 1000). Agent capability CapabilitySecurityLogIngest.

Audience. Agent-facing — not a browser cookbook.

Request. Batch of LogRequest / SecurityLogRequest. API_SCHEMA_DOCUMENTATION_BLOCKED for the exact top-level JSON key (logs vs raw array) — handler bind is local; errors include No logs provided, Too many logs (max 1000 per batch).

Response (201/200). Keys: success, count / created_count, idempotent_replay_count, message.

Errors. 400 contract/event_id; 409 identity conflict; 401 Agent auth.

Edition. SHARED.

GET /api/v1/security-logs/advanced

GET /api/v1/security-logs/summary

GET /api/v1/security-logs/timeseries

GET /api/v1/security-logs/severity/:level

GET /api/v1/security-logs/action/:action

GET /api/v1/security-log/summary

Purpose. Reporting widgets. Advanced/timeseries also pass Enterprise FeatureAdvancedReporting license write-gate on Main.

Authentication. Admin.

Response. Summary uses SecurityLogSummary / SecurityLogTimeSeriesPoint when returned as those types. Several handlers wrap gin.H. API_SCHEMA_DOCUMENTATION_BLOCKED for advanced filter maps.

Edition. SHARED.

GET /api/v1/security/metrics/severity-distribution

Purpose. Severity histogram.

Authentication. Admin.

Response. API_SCHEMA_DOCUMENTATION_BLOCKED — GetSeverityDistribution gin.H.

Edition. SHARED.

Blocked IPs

See Blocks for GET/POST/DELETE /api/v1/security/blocked-ips*.

Distributed attacks

GET /api/v1/security/distributed-attacks

GET /api/v1/security/distributed-attacks/:id

GET /api/v1/security/attack-candidates

GET /api/v1/security/attack-stats

GET /api/v1/security/correlation-stats

POST /api/v1/security/analyze-now

Purpose. Attack correlation views. analyze-now is not a daily operator button.

Authentication. Admin.

Response. Domain AttackEvent / AttackCandidate / DistributedAttackStats when returned as those structs; otherwise API_SCHEMA_DOCUMENTATION_BLOCKED.

Edition. SHARED.

Login failures and rate limit

GET /api/v1/security/login-failures

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

GET /api/v1/security/login-rate-limit/stats

POST /api/v1/security/login-rate-limit/check

GET /api/v1/security/login-successes

GET /api/v1/security/login-successes/user/:username

POST /api/v1/security/login-successes

Purpose. Brute-force / login-rate visibility and unblock.

Authentication. Admin. Login-rate-limit group is registered only if the handler is non-nil.

Request (check/create). API_SCHEMA_DOCUMENTATION_BLOCKED — local bind structs. Unblock: see Blocks.

Edition. SHARED.

RBL

POST /api/v1/security/rbl-check

GET /api/v1/security/rbl-results/:ip

GET /api/v1/security/rbl-stats

Purpose. DNS RBL check/results/stats. Enterprise writes may be license-gated.

Authentication. Admin.

Request (check). IP list or single IP. API_SCHEMA_DOCUMENTATION_BLOCKED for batch vs single bind (RBLHandler.CheckIP accepts JSON with ips or similar — handler has handleBatchCheck). Known error pattern: 400 invalid IP.

Edition. SHARED.

ModSecurity (observe)

GET /api/v1/security/modsecurity/stats

GET /api/v1/security/modsecurity/alerts

GET /api/v1/security/modsecurity/overrides

POST /api/v1/security/modsecurity/overrides

DELETE /api/v1/security/modsecurity/overrides/:rule_id

POST /api/v1/modsecurity/webhook

Purpose. Observation of ModSecurity alerts; webhook ingest.

Authentication. Admin for CRUD. Webhook: HMAC/signature, no JWT.

Audience. Webhook uses an integration secret. Not an unauthenticated cookbook.

Response. Domain ModSecurityAlert / ModSecurityRuleOverride when returned as structs. Webhook: API_SCHEMA_DOCUMENTATION_BLOCKED for payload map (ReceiveWebhook).

Edition. SHARED handlers; Hosting collector is global metadata only.

Netblock / temp-to-perm / UDP flood / SMTP / SSH / sudo

Families (admin):

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

PrefixNotes
/api/v1/security/netblock-*candidates, stats, check, whitelist CRUD
/api/v1/security/ssh-login-alerts/*status/config/stats/check; POST .../test is not a daily operator procedure
/api/v1/security/sudo-alerts/*same
/api/v1/security/repeat-offenders
/api/v1/security/temp-to-perm/*stats/check/history/whitelist/promote/cleanup
/api/v1/security/udp-flood/*per-agent config ENTERPRISE; blocked list/delete/block
/api/v1/security/smtp/*status/config/stats/rules CRUD enable/disable

Request/response. Config PUT bodies follow YAML-adjacent structs (UDPFloodConfig, SSHLoginAlertConfig, SudoAlertConfig, TempToPermConfig, SMTPControlsConfig) when the handler binds those types; otherwise API_SCHEMA_DOCUMENTATION_BLOCKED. Status/stats are gin.H or service structs.

Known status codes: 400 bind, 404 missing, 500/503 service unavailable, 403 license on Enterprise writes.

Edition. SHARED unless noted.

Security. Test endpoints must not be exposed as unauthenticated tools.