Security Auditing & REST API Reference

CollectorCtrl meets enterprise compliance and security standards by providing built-in audit trails, real-time SIEM streaming, CycloneDX Software Bill of Materials (SBOM), and a secure REST API.

---

1. Compliance Auditing & Log Schema

Every administrative interaction (such as starting or stopping agents, publishing configurations, modifying user roles, or fetching agent logs) generates an immutable audit record in the system database (audit_logs table).

Schema Structure

An audit event captures the following fields to facilitate corporate audits:

• timestamp: ISO 8601 UTC timestamp of the action.
• actor: The user account or OIDC email that initiated the transaction.
• source_ip: The network IP address of the client connection.
• action: The operation performed (e.g. agent.restart, policy.publish).
• status: Result of the operation (success or failed).
• payload: JSON object detailing the changes (e.g. structural diff of modified YAML).

---

2. SIEM Integration & OTLP Log Streaming

To prevent tampering, audit logs should not be stored solely on the local database. CollectorCtrl features an outbound OTLP log transmitter that streams audit events in real-time to your security information and event management (SIEM) system.

+------------------+     (Admin Event)     +----------------------+
|  User Action     | -------------------> | CollectorCtrl Server |
+------------------+                      +----------------------+
                                                     |
                                                     | Streams OTLP/HTTP Logs
                                                     v
+------------------+                      +----------------------+
|  SIEM Backend    | <------------------- |  OTel SIEM Receiver  |
| (Splunk/Elastic) |                      +----------------------+
+------------------+

Configuring SIEM Streaming

Configure these environment variables on the Management Server to activate streaming:

# Enable OTLP audit logs streaming
COLLECTORCTRL_AUDIT_STREAM_ENABLED=true

# Destination OTLP/HTTP or OTLP/gRPC endpoint
COLLECTORCTRL_AUDIT_STREAM_ENDPOINT="https://siem-collector.internal:4318/v1/logs"

# Optional authentication token headers
COLLECTORCTRL_AUDIT_STREAM_HEADERS="Authorization=Bearer your-siem-token"

Once enabled, audit logs are formatted according to the OpenTelemetry Security Log Semantic Conventions and forwarded immediately.

---

3. Supply Chain Security: CycloneDX SBOM

To comply with federal regulations and software supply chain standards, every release build of CollectorCtrl is distributed with a CycloneDX Software Bill of Materials (SBOM).

• Format: CycloneDX JSON (compliant with standard schema version 1.5).
• Location: Available in the root installation directory as cyclonedx-sbom.json.
• Details Documented: All third-party Go dependencies, package licenses, compiler versions, and metadata signatures.
• Scanning Integration: Security teams can upload this JSON payload to tools like Dependency-Track or Snyk to continuously audit the application for newly discovered CVE vulnerabilities.

---

4. REST API Reference & SDK Integration

CollectorCtrl is built as an API-first application. All features exposed in the Admin UI Console utilize standard JSON REST endpoints.

Authentication

Every REST request must include your API Token in the HTTP Authorization header:

Authorization: Bearer cct_your_secret_token

Core API Endpoints

A. Fleet Inventory Management

1. List All Agents

• Endpoint: GET /api/agents
• Description: Retrieves all registered supervisors and collectors, their connection state, active versions, and host attributes.
• Request Example:

curl -H "Authorization: Bearer cct_prod_secret" \
  https://collectorctrl.internal:4321/api/agents

• Response Payload (JSON):

[
  {
    "id": "agent-uuid-112233",
    "hostname": "srv-prod-api-01",
    "ip_address": "172.16.82.11",
    "status": "connected",
    "os": "linux",
    "arch": "amd64",
    "supervisor_version": "v0.2.0",
    "collector_status": "running",
    "effective_config_hash": "2f7b8d4e92a10d...",
    "last_seen": "2026-07-06T17:15:00Z"
  }
]

2. Remote Command Control

• Endpoint: POST /api/agents/{id}/control
• Description: Sends remote process control commands (e.g., restarts or shutdowns) directly to the target agent.
• Request Example:

curl -X POST \
  -H "Authorization: Bearer cct_prod_secret" \
  -H "Content-Type: application/json" \
  -d '{"command": "restart_collector"}' \
  https://collectorctrl.internal:4321/api/agents/agent-uuid-112233/control

• Supported Commands: start_collector, stop_collector, restart_collector, restart_supervisor
• Response Payload (JSON):

{
  "agent_id": "agent-uuid-112233",
  "command": "restart_collector",
  "status": "accepted",
  "message": "OpAMP process action scheduled successfully"
}

---

B. Configuration Policies

1. Create a Configuration Policy

• Endpoint: POST /api/policies
• Description: Defines a new fleet-wide configuration template, target rules, and OTel YAML pipelines.
• Request Example:

curl -X POST \
  -H "Authorization: Bearer cct_prod_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-k8s-exporters",
    "target_selector": { "env": "production", "platform": "k8s" },
    "config_yaml": "exporters:\n  otlp:\n    endpoint: datadog.internal:4317"
  }' \
  https://collectorctrl.internal:4321/api/policies

• Response Payload (JSON):

{
  "policy_id": "policy-uuid-445566",
  "name": "prod-k8s-exporters",
  "version": 1,
  "target_selector": {
    "env": "production",
    "platform": "k8s"
  },
  "config_hash": "d5a8e1b6f001c...",
  "status": "active_rollout"
}

2. List Active Policies

• Endpoint: GET /api/policies
• Description: Retrieves all versioned configuration templates and matching agent counts.
• Response Payload (JSON):

[
  {
    "id": "policy-uuid-445566",
    "name": "prod-k8s-exporters",
    "version": 3,
    "target_selector": {
      "env": "production",
      "platform": "k8s"
    },
    "matching_agents_count": 8,
    "updated_at": "2026-07-06T16:00:00Z"
  }
]