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 Overview

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

Authentication

Include your API Token in the HTTP request header: Authorization: Bearer cct_your_secret_token

Core Endpoints Reference

A. Fleet Inventory Management

GET /api/agents: Retrieves a list of all registered agents, their connection statuses, and reported attributes.
GET /api/agents/{id}: Retrieves detailed status metrics and the active configuration hash of a specific agent.
POST /api/agents/{id}/control: Executes remote commands.
- Payload: {"command": "restart_collector"} (Supports start_collector, stop_collector, restart_collector, restart_supervisor).

B. Configuration Policies

GET /api/policies: Lists all active policy configurations and matching group counts.
POST /api/policies: Creates a new configuration template policy.
PUT /api/policies/{id}: Updates an existing policy and schedules a fleet reconciliation rollout.

C. Telemetry Governor Taps

POST /api/telemetry_governor/taps/toggle: Enables or disables data tapping for a specific agent.
- Payload: {"agent_id": "uuid", "sampling_rate": 5.0}
GET /api/telemetry_governor/volume: Returns aggregate signal counts and log severity statistics.