Security Auditing, SIEM Streaming & REST API

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

---

1. Immutable Compliance Auditing

Every administrative action -- configuration publishes, remote process restarts, user role updates, and AI-approved changes -- generates an immutable record in the audit_logs database table.

Audit Record Schema

• timestamp: UTC timestamp in RFC3339 format.
• actor: The user account, OIDC email, or MCP AI agent (mcp:<username>) that initiated the action.
• source_ip: Client network IP address.
• action: Discrete operation performed (e.g. fleet.restart, policy.publish, mcp.approve).
• status: Outcome (success or failed).
• duration_ms: Execution latency in milliseconds.
• payload: JSON payload containing detailed before/after diffs and parameters.

---

2. SIEM Integration & OTLP Audit Streaming

To support corporate Security Operations Centers (SOC) and prevent local audit tampering, CollectorCtrl features a native OTLP log streamer that forwards audit events in real-time to Splunk, Elastic, Datadog, or any OTel-compatible SIEM collector:

[ Administrative Action / MCP Tool Call ]
                   |
                   v
       [ CollectorCtrl Server ]
                   |
                   | OTLP/HTTP or OTLP/gRPC Streaming
                   v
       [ Enterprise SIEM Ingest ]
       (Splunk . Elastic . Datadog)

Configuration Environment Variables

Enable real-time SIEM streaming using server environment variables:

# Activate outbound audit streaming
COLLECTORCTRL_AUDIT_STREAM_ENABLED=true

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

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

Audit events conform to the standard OpenTelemetry Security Log Semantic Conventions.

---

3. CycloneDX Software Bill of Materials (SBOM)

Every official binary release includes a machine-readable CycloneDX Software Bill of Materials (SBOM) to support continuous vulnerability auditing:

• Format: CycloneDX JSON (schema version 1.5).
• Location: Shipped alongside the server binary as cyclonedx-sbom.json.
• Security Scanning: Integrates directly with SAST and SCA tools such as Dependency-Track, Snyk, and Trivy for automated CVE detection.

---

4. Comprehensive REST API Reference

All capabilities available in the web dashboard are accessible via standard JSON REST endpoints:

Authentication Header

Every REST request must present an API token in the HTTP Authorization header:

Authorization: Bearer cct_your_api_token

Core API Endpoints Summary

Endpoint	Method	Permission Required	Description
/api/agents	GET	fleet:view	Retrieve connected collectors, health status, and metadata.
/api/agents/{id}/control	POST	fleet:control	Execute remote process actions (restart_collector, stop_collector).
/api/policies	GET, POST	policies:view, policies:configure	List or publish versioned configuration templates.
/api/mcp	POST	Scoped per tool	Model Context Protocol JSON-RPC 2.0 endpoint for AI assistants.
/api/mcp/pending_actions	GET	mcp:approve	List staged AI actions awaiting human review.
/api/mcp/approve_action	POST	mcp:approve	Approve a pending AI action (enforces Two-Person Rule).
/api/governor/simulate	POST	governor:view	Dry-run What-If cost simulation against real telemetry samples.
/api/system/env_rules	GET, POST, DELETE	system:env_rules	Manage fleet classification and tagging rules.
/api/database/backup	GET	system:database	Export an encrypted database backup snapshot.