Security¶

Console-facing security controls: failed-authentication monitoring and IP blocking, IP access rules (enforced live by the Postfix policy server), geo access policies, and DLP (data-loss-prevention) policies with a content-redacted violation feed.

Base path: /api/v1/security Auth: every endpoint requires platform scope with an operator session (require_scope("platform", ...)). Reads and most writes require role operator or above; DLP policy writes require admin — a disabled DLP policy is an open exfiltration channel. Every mutation requires a reason, recorded by the operator audit middleware. Responses use the standard {"type", "msg", "data"} envelope.

Failed Authentication¶

List Failed Authentication Attempts¶

Paginated view over failed_auth_attempts, filterable by IP, account, service, block state, and date range. Each row is a collapsed counter (attempts within a window), not a single failure.

GET /api/v1/security/failed-auth

Query Parameters

curl -H "X-API-Key: YOUR_PLATFORM_KEY" \
  "http://your-server:5000/api/v1/security/failed-auth?blocked=true&sort_dir=desc"

Failed-Auth Summary¶

The shape of the attack rather than a list of its rows: top IPs, top targeted accounts, and totals over a lookback window.

GET /api/v1/security/failed-auth/summary

Query Parameters: hours (default 24, min 1) — lookback window.

Block an IP¶

Sets blocked_until on every failed_auth_attempts row for the IP — which is what the auth path consults before it will consider a credential at all.

POST /api/v1/security/failed-auth/{client_ip}/block

Request Body

curl -X POST -H "X-API-Key: YOUR_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"minutes": 1440, "reason": "Credential stuffing against 40+ accounts"}' \
  http://your-server:5000/api/v1/security/failed-auth/203.0.113.9/block

Unblock an IP¶

Clears blocked_until for the IP. The attempt counters are left intact on purpose — unblocking is a decision about the future, and erasing the history that justified the block would falsify the audit trail.

DELETE /api/v1/security/failed-auth/{client_ip}/block

Request Body: { "reason": "..." } (required, audited).

IP Access Rules¶

Rules in ip_access_rules are enforced by Postfix's policy delegation service on authenticated submission — changes apply on the next connection.

List IP Rules¶

GET /api/v1/security/ip-rules

Query Parameters: rule_type (whitelist | blacklist), active, organization_id, q (free text over IP/description), sort_by, sort_dir, page, per_page.

Create IP Rule¶

POST /api/v1/security/ip-rules

Request Body

curl -X POST -H "X-API-Key: YOUR_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "whitelist",
    "ip_address": "203.0.113.0/24",
    "organization_id": "01J8ZJ...",
    "reason": "Office egress range"
  }' \
  http://your-server:5000/api/v1/security/ip-rules

Update IP Rule¶

Changes description, active flag, or rule type. ip_address is deliberately immutable — editing the address in place would silently repoint an existing audit trail at a different network. Delete and re-create instead.

PUT /api/v1/security/ip-rules/{rule_id}

Request Body: description, active, rule_type (all optional) + required reason.

Delete IP Rule¶

DELETE /api/v1/security/ip-rules/{rule_id}

Request Body: { "reason": "..." } (required).

Geo Access Policies¶

One policy per tenant (geo_policies has a UNIQUE key on organization_id), enforced by the geo-blocking service. No policy row = allow-all.

List Geo Policies¶

GET /api/v1/security/geo-policies

Query Parameters: organization_id, action (block | challenge | log_only), enabled, page, per_page.

Create Geo Policy¶

POST /api/v1/security/geo-policies

Request Body

A second create for the same tenant returns 409, not a second row.

Update Geo Policy¶

Partial update. The allowed/blocked conflict check runs against the merged policy, not just the fields in the request.

PUT /api/v1/security/geo-policies/{policy_id}

Request Body: any of allowed_countries, blocked_countries, time_restrictions, action, enabled + required reason.

Delete Geo Policy¶

Removes the tenant's geo policy entirely, returning that tenant to unrestricted country access. Prefer PUT with enabled: false to keep the policy on file.

DELETE /api/v1/security/geo-policies/{policy_id}

Request Body: { "reason": "..." } (required).

DLP Policies¶

List DLP Policies¶

GET /api/v1/security/dlp/policies

Auth: role operator+ (reads). Writes below require admin.

Query Parameters: organization_id, policy_type, severity, apply_to, enabled, q, sort_by, sort_dir, page, per_page.

Create DLP Policy¶

POST /api/v1/security/dlp/policies

Auth: role admin+.

Request Body

curl -X POST -H "X-API-Key: YOUR_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "01J8ZJ...",
    "name": "Card numbers outbound",
    "policy_type": "regex",
    "patterns": ["\\b(?:\\d[ -]*?){13,16}\\b"],
    "action": "block",
    "severity": "critical",
    "reason": "PCI scope"
  }' \
  http://your-server:5000/api/v1/security/dlp/policies

Update DLP Policy¶

Partial update; patterns, when supplied, replaces the array wholesale rather than merging — a merge would make removing a pattern impossible.

PUT /api/v1/security/dlp/policies/{policy_id}

Auth: role admin+. Body: any policy field + required reason.

Delete DLP Policy¶

DELETE /api/v1/security/dlp/policies/{policy_id}

Auth: role admin+. Body: { "reason": "..." }.

Past violations are deliberately not removed with the policy — the violation history survives.

DLP Violations¶

List DLP Violations¶

Cross-tenant violation feed: which policy fired, on whose message, and what was done about it.

GET /api/v1/security/dlp/violations

Query Parameters: organization_id, policy_id, severity, violation_type, action_taken, date_from, date_to, q (over sender/recipient), sort_by, sort_dir, page, per_page.

DLP Violation Summary¶

Counts by severity, policy, and action taken, plus a daily series — the "is exfiltration increasing" view. Aggregates only.

GET /api/v1/security/dlp/violations/summary

Query Parameters: organization_id, days (default 30, 1–365).

Get One DLP Violation¶

Same fields, and the same redaction, as the list view. There is deliberately no "reveal" variant of this endpoint.

GET /api/v1/security/dlp/violations/{violation_id}