Compliance API 🟡 BETA

ISO 27001 compliance management — security checks, issue tracking, audit trails, training, evidence collection, and reporting.

Base URL

/api/compliance

Authentication

All endpoints require a valid session token via Authorization: Bearer <token> header. Audit and evidence endpoints require compliance_admin or admin role.

Endpoints

Security Checks

GET /api/compliance/checks

Lists all compliance checks with optional filters.

Response:

{
  "checks": [
    {
      "check_id": "chk_001",
      "name": "Asset Inventory",
      "control": "A.8.1.1",
      "category": "asset-management",
      "description": "Verify all information assets are inventoried",
      "status": "pass",
      "last_checked": "2025-06-04T08:00:00Z",
      "next_scheduled": "2025-06-11T08:00:00Z",
      "evidence_count": 3
    }
  ],
  "total": 42,
  "summary": {
    "pass": 35,
    "fail": 4,
    "pending": 2,
    "skip": 1
  }
}

POST /api/compliance/checks

Creates a new compliance check.

Request Body:

{
  "name": "Password Policy Enforcement",
  "control": "A.9.4.3",
  "category": "access-control",
  "description": "Verify password complexity and rotation policies are enforced",
  "frequency": "weekly",
  "automated": true
}

Response:

{
  "check_id": "chk_043",
  "name": "Password Policy Enforcement",
  "control": "A.9.4.3",
  "status": "pending",
  "created_at": "2025-06-04T09:00:00Z"
}

Get Check Details

GET /api/compliance/checks/:check_id

Retrieves full details and history for a specific check.

Response:

{
  "check_id": "chk_001",
  "name": "Asset Inventory",
  "control": "A.8.1.1",
  "category": "asset-management",
  "description": "Verify all information assets are inventoried",
  "status": "pass",
  "frequency": "monthly",
  "automated": false,
  "history": [
    {
      "date": "2025-06-04T08:00:00Z",
      "status": "pass",
      "checked_by": "admin@company.com",
      "notes": "All 127 assets accounted for in inventory system"
    },
    {
      "date": "2025-05-04T08:00:00Z",
      "status": "fail",
      "checked_by": "admin@company.com",
      "notes": "3 laptops missing from inventory",
      "issue_id": "iss_012"
    }
  ],
  "evidence_count": 3,
  "created_at": "2025-01-15T10:00:00Z"
}

Security Issues

GET /api/compliance/issues

Lists security issues found during compliance checks.

Response:

{
  "issues": [
    {
      "issue_id": "iss_014",
      "title": "Unencrypted backup storage",
      "severity": "critical",
      "status": "in_progress",
      "control": "A.10.1.1",
      "check_id": "chk_015",
      "assigned_to": "security@company.com",
      "created_at": "2025-06-01T10:00:00Z",
      "due_date": "2025-06-15T00:00:00Z",
      "description": "Backup files stored without encryption at rest"
    }
  ],
  "total": 7,
  "by_severity": {
    "critical": 1,
    "high": 3,
    "medium": 2,
    "low": 1
  }
}

POST /api/compliance/issues

Creates a new security issue.

Request Body:

{
  "title": "Missing MFA on admin panel",
  "severity": "high",
  "control": "A.9.4.2",
  "check_id": "chk_022",
  "assigned_to": "devops@company.com",
  "due_date": "2025-06-20T00:00:00Z",
  "description": "Administrative panel does not enforce multi-factor authentication"
}

Response:

{
  "issue_id": "iss_015",
  "title": "Missing MFA on admin panel",
  "severity": "high",
  "status": "open",
  "created_at": "2025-06-04T09:30:00Z"
}

PUT /api/compliance/issues/:issue_id

Updates an existing issue (status, assignment, notes).

Request Body:

{
  "status": "resolved",
  "resolution_notes": "MFA enabled on all admin accounts via TOTP. Verified on 2025-06-04."
}

Response:

{
  "issue_id": "iss_015",
  "status": "resolved",
  "resolved_at": "2025-06-04T14:00:00Z",
  "resolved_by": "admin@company.com"
}

Audit Trail

GET /api/compliance/audit

Retrieves audit log entries.

Response:

{
  "entries": [
    {
      "audit_id": "aud_001",
      "timestamp": "2025-06-04T14:00:00Z",
      "actor": "admin@company.com",
      "action": "issue.resolved",
      "resource": "iss_015",
      "details": {
        "issue_title": "Missing MFA on admin panel",
        "resolution": "MFA enabled on all admin accounts"
      },
      "ip_address": "192.168.1.100"
    },
    {
      "audit_id": "aud_002",
      "timestamp": "2025-06-04T13:45:00Z",
      "actor": "security@company.com",
      "action": "check.completed",
      "resource": "chk_015",
      "details": {
        "result": "fail",
        "notes": "Backup encryption not configured"
      },
      "ip_address": "192.168.1.105"
    }
  ],
  "total": 256
}

POST /api/compliance/audit

Creates a manual audit log entry.

Request Body:

{
  "action": "policy.reviewed",
  "resource": "pol_003",
  "details": {
    "policy_name": "Data Retention Policy",
    "review_result": "approved",
    "next_review_date": "2025-12-01"
  }
}

Response:

{
  "audit_id": "aud_003",
  "timestamp": "2025-06-04T15:00:00Z",
  "actor": "admin@company.com",
  "action": "policy.reviewed"
}

Training

POST /api/compliance/training

Records a completed training session or enrolls a user.

Request Body:

{
  "user_email": "dev@company.com",
  "training_name": "Security Awareness 2025",
  "score": 92,
  "expires_at": "2026-06-04T00:00:00Z"
}

Response:

{
  "training_id": "trn_001",
  "user_email": "dev@company.com",
  "training_name": "Security Awareness 2025",
  "status": "completed",
  "score": 92,
  "completed_at": "2025-06-04T15:00:00Z",
  "expires_at": "2026-06-04T00:00:00Z"
}

Compliance Report

GET /api/compliance/report

Generates an ISO 27001 compliance report.

Response (json):

{
  "report_id": "rpt_001",
  "generated_at": "2025-06-04T16:00:00Z",
  "period": "2025-05-01T00:00:00Z/2025-06-01T00:00:00Z",
  "summary": {
    "total_checks": 42,
    "passed": 35,
    "failed": 4,
    "pending": 2,
    "skipped": 1,
    "compliance_score": 83.3,
    "open_issues": 7,
    "critical_issues": 1
  },
  "by_domain": [
    {
      "domain": "Access Control (A.9)",
      "checks": 8,
      "passed": 7,
      "score": 87.5
    },
    {
      "domain": "Cryptography (A.10)",
      "checks": 4,
      "passed": 2,
      "score": 50.0
    }
  ],
  "training_status": {
    "total_employees": 25,
    "trained": 22,
    "pending": 3,
    "coverage_percent": 88.0
  }
}

Evidence Collection

POST /api/compliance/evidence

Uploads evidence for a compliance check or issue.

Request Body (multipart/form-data):

check_id: chk_001
title: Asset inventory export from 2025-06-04
type: log_export
notes: Full export from asset management system

Response:

{
  "evidence_id": "evd_001",
  "check_id": "chk_001",
  "title": "Asset inventory export from 2025-06-04",
  "type": "log_export",
  "file_url": "/compliance/evidence/evd_001_asset_export.csv",
  "uploaded_by": "admin@company.com",
  "uploaded_at": "2025-06-04T16:30:00Z"
}

ISO 27001 Domains

Response Codes

Compliance Dashboard

Server-rendered HTMX fragments for the admin compliance dashboard:

GET /api/compliance/dashboard/overview          # score cards + counts
GET /api/compliance/dashboard/tsc               # Trust Service Criteria grid
GET /api/compliance/dashboard/failing-controls  # failing control list
GET /api/compliance/dashboard/evidence          # evidence items
GET /api/compliance/dashboard/audit-log         # recent audit events
POST /api/compliance/scan                        # run compliance checks
GET  /api/compliance/export                      # CSV report download

See Also

• Legal / LGPD API — data protection and consent
• Security API — application security endpoints
• Audit Logs — system-wide audit trails