Compliance API

Endpoints for CIS security compliance monitoring.

Policies

List Policies

GET /api/v1/compliance/policies
Authorization: Bearer YOUR_TOKEN

Query Parameters

Parameter	Type	Description
skip	integer	Number of records to skip (pagination)
limit	integer	Maximum records to return (default: 50)
enabled	boolean	Filter by enabled status

Response

{
  "items": [
    {
      "id": "policy-uuid",
      "name": "Windows CIS Level 1",
      "description": "CIS Level 1 checks for Windows",
      "enabled": true,
      "cis_level": "level_1",
      "target_os": "windows",
      "schedule_type": "continuous",
      "check_interval_minutes": 60,
      "passing_score_threshold": 80,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 5
}

Create Policy

POST /api/v1/compliance/policies
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "name": "Linux CIS Level 1",
  "description": "CIS Level 1 checks for Linux servers",
  "cis_level": "level_1",
  "target_os": "linux",
  "schedule_type": "continuous",
  "check_interval_minutes": 60,
  "passing_score_threshold": 80
}

Get Policy

GET /api/v1/compliance/policies/{id}
Authorization: Bearer YOUR_TOKEN

Update Policy

PUT /api/v1/compliance/policies/{id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "passing_score_threshold": 90
}

Delete Policy

DELETE /api/v1/compliance/policies/{id}
Authorization: Bearer YOUR_TOKEN

Toggle Policy

Enable or disable a policy.

POST /api/v1/compliance/policies/{id}/toggle
Authorization: Bearer YOUR_TOKEN

Checks

List Checks

GET /api/v1/compliance/checks
Authorization: Bearer YOUR_TOKEN

Query Parameters

Parameter	Type	Description
category	string	Filter by category (firewall, encryption, etc.)
severity	string	Filter by severity (critical, high, medium, low)
target_os	string	Filter by OS (windows, darwin, linux)
enabled	boolean	Filter by enabled status

Response

{
  "items": [
    {
      "id": "check-uuid",
      "cis_id": "1.1.1",
      "cis_title": "Ensure Windows Firewall is enabled",
      "cis_description": "Windows Firewall should be enabled on all profiles",
      "cis_level": "level_1",
      "category": "firewall",
      "severity": "critical",
      "target_os": "windows",
      "enabled": true,
      "is_builtin": true,
      "remediation_guidance": "Enable Windows Firewall..."
    }
  ],
  "total": 35
}

Seed Built-in Checks

Import default CIS benchmark checks.

POST /api/v1/compliance/checks/seed
Authorization: Bearer YOUR_TOKEN

Response

{
  "checks_created": 35,
  "checks_updated": 0
}

Results

Get Agent Results

GET /api/v1/compliance/results/agent/{uuid}
Authorization: Bearer YOUR_TOKEN

Query Parameters

Parameter	Type	Description
policy_id	string	Filter by policy ID
status	string	Filter by status (passed, failed, error, skipped, exempted)

Response

{
  "items": [
    {
      "id": "result-uuid",
      "check_id": "check-uuid",
      "policy_id": "policy-uuid",
      "status": "passed",
      "actual_value": {"enabled": true},
      "expected_value": {"enabled": true},
      "severity": "critical",
      "checked_at": "2024-01-01T12:00:00Z",
      "check": {
        "cis_id": "1.1.1",
        "cis_title": "Ensure Windows Firewall is enabled",
        "category": "firewall"
      }
    }
  ],
  "total": 35
}

Scores

Get Agent Score

GET /api/v1/compliance/score/agent/{uuid}
Authorization: Bearer YOUR_TOKEN

Query Parameters

Parameter	Type	Description
policy_id	string	Policy ID (required)

Response

{
  "score": 85.5,
  "risk_level": "medium",
  "passed_checks": 30,
  "failed_checks": 5,
  "skipped_checks": 0,
  "exempted_checks": 2,
  "total_checks": 37,
  "critical_failed": 0,
  "high_failed": 2,
  "medium_failed": 3,
  "low_failed": 0,
  "last_checked_at": "2024-01-01T12:00:00Z"
}

History

Get Agent History

GET /api/v1/compliance/history/agent/{uuid}
Authorization: Bearer YOUR_TOKEN

Query Parameters

Parameter	Type	Description
policy_id	string	Filter by policy ID
days	integer	Number of days of history (default: 30)

Response

[
  {
    "recorded_at": "2024-01-01T00:00:00Z",
    "score": 85.5,
    "risk_level": "medium",
    "passed_checks": 30,
    "failed_checks": 5
  }
]

Get Trend Data

GET /api/v1/compliance/trend
Authorization: Bearer YOUR_TOKEN

Query Parameters

Parameter	Type	Description
policy_id	string	Filter by policy ID
days	integer	Number of days (default: 30)

Exceptions

List Exceptions

GET /api/v1/compliance/exceptions
Authorization: Bearer YOUR_TOKEN

Response

{
  "items": [
    {
      "id": "exception-uuid",
      "check_id": "check-uuid",
      "agent_uuid": "agent-uuid",
      "reason": "Legacy system cannot support this configuration",
      "is_active": true,
      "expires_at": "2024-12-31T23:59:59Z",
      "created_at": "2024-01-01T00:00:00Z",
      "created_by": "user-uuid"
    }
  ],
  "total": 3
}

Create Exception

POST /api/v1/compliance/exceptions
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "check_id": "check-uuid",
  "agent_uuid": "agent-uuid",
  "reason": "Business requirement - approved by security team",
  "expires_at": "2024-12-31T23:59:59Z"
}

Revoke Exception

DELETE /api/v1/compliance/exceptions/{id}
Authorization: Bearer YOUR_TOKEN

Statistics

Get Overall Stats

GET /api/v1/compliance/stats
Authorization: Bearer YOUR_TOKEN

Query Parameters

Parameter	Type	Description
policy_id	string	Filter by policy ID

Response

{
  "total_agents": 100,
  "compliant_agents": 85,
  "non_compliant_agents": 15,
  "average_score": 87.3,
  "risk_distribution": {
    "critical": 2,
    "high": 8,
    "medium": 5,
    "low": 85
  }
}

Get Top Failing Checks

GET /api/v1/compliance/stats/top-failing
Authorization: Bearer YOUR_TOKEN

Query Parameters

Parameter	Type	Description
limit	integer	Number of checks to return (default: 10)

Response

[
  {
    "check_id": "check-uuid",
    "cis_id": "5.2.1",
    "cis_title": "Ensure SSH Protocol is set to 2",
    "category": "remote_access",
    "severity": "high",
    "fail_count": 25,
    "total_agents": 100
  }
]

Get Non-Compliant Agents

GET /api/v1/compliance/stats/non-compliant
Authorization: Bearer YOUR_TOKEN

Response

{
  "agents": [
    {
      "agent_uuid": "agent-uuid",
      "hostname": "server-01",
      "os": "linux",
      "score": 65.0,
      "risk_level": "high",
      "failed_checks": 12
    }
  ],
  "total": 15
}

Scanning

Trigger Agent Scan

Run compliance checks immediately on an agent.

POST /api/v1/compliance/scan/agent/{uuid}
Authorization: Bearer YOUR_TOKEN

Query Parameters

Parameter	Type	Description
policy_id	string	Policy ID to use for scanning (required)

Response

{
  "status": "triggered",
  "agent_uuid": "agent-uuid",
  "policy_id": "policy-uuid"
}