Logging

The Opservant agent produces structured logs and an immutable audit trail for all operations. This page covers log configuration, output destinations, correlation, and compliance considerations.

Log Levels

Level Description
DEBUG Detailed diagnostic information for troubleshooting.
INFO Normal operational events (task started, completed).
WARNING Unexpected but recoverable conditions.
ERROR Operation failures that require attention.
CRITICAL Severe failures that may affect agent availability.

Set the log level in config.yaml:

logging:
  level: INFO

Tip

Use DEBUG only during development or troubleshooting. It produces high-volume output and may include sensitive context.

Structured Log Format

All logs are emitted as JSON for consistent parsing:

{
  "timestamp": "2026-04-28T12:00:01.234Z",
  "level": "INFO",
  "agent_id": "ag-prod-001",
  "executor": "port-scanner",
  "action_id": "act-port-scan",
  "execution_id": "exec-8821",
  "correlation_id": "corr-4f9a2b1c",
  "message": "Port scan completed for 10.0.1.5",
  "details": {
    "target": "10.0.1.5",
    "ports_scanned": 3,
    "open_ports": [22, 80]
  }
}

Log Fields

Field Type Description
timestamp string ISO 8601 timestamp with milliseconds.
level string Log level.
agent_id string Identifier of the agent instance.
executor string Name of the executor that produced the log.
action_id string The action being executed.
execution_id string Unique execution instance ID.
correlation_id string Shared ID for tracing across agent and platform.
message string Human-readable log message.
details object Structured data specific to the log event.

Output Destinations

Configure one or more log destinations:

logging:
  level: INFO
  outputs:
    - type: stdout
    - type: file
      path: /var/log/opservant/agent.log
      max_size_mb: 100
      max_files: 10
    - type: syslog
      protocol: tcp_tls
      host: siem.example.com
      port: 6514
      format: cef
    - type: platform
      buffer_size: 1000
      flush_interval_seconds: 30

Output Types

Type Description
stdout Write to standard output (useful for Docker/K8s).
file Write to local log files with rotation.
syslog Forward to a remote syslog server (UDP, TCP, TLS).
platform Ship logs to the S4E platform for centralized viewing.

File Rotation

When using file output, configure rotation to prevent disk exhaustion:

logging:
  outputs:
    - type: file
      path: /var/log/opservant/agent.log
      max_size_mb: 100
      max_files: 10
      compress: true
Parameter Default Description
max_size_mb 50 Maximum size per log file before rotation.
max_files 5 Number of rotated files to retain.
compress true Gzip-compress rotated files.

Remote Log Shipping

To S4E Platform

Logs shipped to the platform are visible in Settings > Agents > [Agent] > Logs and can be searched, filtered, and correlated with platform events.

logging:
  outputs:
    - type: platform
      buffer_size: 1000
      flush_interval_seconds: 30
      min_level: WARNING

The min_level filter reduces bandwidth by shipping only important logs to the platform.

To Syslog / SIEM

Forward logs to your SIEM in CEF or RFC 5424 format:

logging:
  outputs:
    - type: syslog
      protocol: tcp_tls
      host: siem.example.com
      port: 6514
      format: cef
      tls:
        ca_cert: /etc/opservant/certs/ca.pem
        client_cert: /etc/opservant/certs/agent.pem
        client_key: /etc/opservant/certs/agent-key.pem

Correlation IDs

Every task received from the S4E platform includes a correlation_id. This ID links agent-side logs to platform-side events, enabling end-to-end tracing.

Platform: Action triggered (correlation_id: corr-4f9a2b1c)
  --> Agent: Task received (correlation_id: corr-4f9a2b1c)
  --> Agent: Executor started (correlation_id: corr-4f9a2b1c)
  --> Agent: Executor completed (correlation_id: corr-4f9a2b1c)
  --> Platform: Action result received (correlation_id: corr-4f9a2b1c)

Search by correlation ID across both agent logs and platform logs to trace any operation end-to-end.

Audit Trail

The audit trail is a separate, immutable log of all security-relevant operations. Unlike operational logs, audit entries cannot be deleted or modified by the agent process.

Audited Events

Event Description
agent.started Agent process started.
agent.registered Agent registered with the platform.
agent.heartbeat Periodic heartbeat sent.
command.received Command received from platform.
command.signature.valid Command signature verified successfully.
command.signature.invalid Command signature verification failed.
command.rejected Command rejected (expired, invalid, unauthorized).
executor.started Executor began processing a task.
executor.completed Executor finished successfully.
executor.failed Executor returned an error.
executor.timeout Executor exceeded time limit.
permission.denied An executor attempted an unauthorized operation.
secret.accessed A secret was retrieved from the vault.
config.changed Agent configuration was modified.

Audit Log Configuration

audit:
  enabled: true
  path: /var/log/opservant/audit.log
  max_size_mb: 500
  max_files: 30
  ship_to_platform: true

Example Audit Entry

{
  "timestamp": "2026-04-28T12:00:00.000Z",
  "event": "executor.started",
  "agent_id": "ag-prod-001",
  "executor": "port-scanner",
  "execution_id": "exec-8821",
  "correlation_id": "corr-4f9a2b1c",
  "user": "system",
  "source_ip": "10.0.1.100",
  "details": {
    "action_id": "act-port-scan",
    "parameters_hash": "sha256:a1b2c3d4..."
  }
}

Note

Parameter values are never logged in the audit trail. Only a SHA-256 hash of the parameters is recorded for integrity verification.

Sensitive Data Redaction

The agent automatically redacts known sensitive patterns from operational logs:

  • API keys and tokens (Bearer, X-API-Key headers).
  • Passwords and secret values.
  • Credit card numbers and SSNs.
  • Custom patterns defined in configuration.
logging:
  redaction:
    enabled: true
    patterns:
      - "password=.*"
      - "secret_key=.*"
      - "AKIA[0-9A-Z]{16}"

Redacted values appear as [REDACTED] in log output.

Compliance Logging

The Opservant logging system supports requirements for:

Standard Requirement How S4E Complies
SOC 2 Type II Audit trail of all system activities Immutable audit log with all events.
ISO 27001 Logging of access and security events Secret access and permission logs.
GDPR Data processing records Correlation IDs for request tracing.
PCI DSS Log retention and integrity Configurable retention, hash integrity.

Viewing Logs

Agent CLI

opservant logs --level ERROR --since 1h
opservant logs --correlation-id corr-4f9a2b1c
opservant audit --since 24h

S4E Platform

Navigate to Settings > Agents > [Agent Name] > Logs for a searchable, filterable log viewer with real-time streaming.

Local Files

tail -f /var/log/opservant/agent.log | jq .

Next Steps