Agent Configuration Reference

Complete reference for all Bitcollector agent configuration options. The agent reads configuration from a YAML file and environment variables. Environment variables always take precedence over file values.

Configuration File Location

Platform	Default Path
Linux	/etc/bitcollector/config.yaml
macOS	/etc/bitcollector/config.yaml
Windows	C:\ProgramData\Cert-IX\bitcollector\config.yaml

Override with the -config CLI flag:

bitcollector -config /path/to/custom-config.yaml

CLI Flags

Flag	Description	Default
-config	Path to configuration file	(none — uses defaults)
-log-level	Override log level (debug, info, warn, error)	From config file
-version	Print version and exit	—

Full Configuration Reference

# =============================================================================
# CONTROL PLANE
# =============================================================================
# Connects the agent to the Cert-IX platform for registration, heartbeat,
# and telemetry ingestion via the Kafka-first pipeline.
control_plane:
  # Agent Gateway Service URL — handles registration and token refresh
  gateway_url: https://api.cert-ix.com/api/v1/agents

  # Agent Ingestion Gateway URL — receives heartbeat and telemetry data
  # Data is written directly to Kafka topics for stream processing
  ingest_url: https://api.cert-ix.com/api/v1/ingest

  # Tenant ID — identifies which organization this agent belongs to
  # REQUIRED for control plane mode
  # Env: CERTIX_TENANT_ID
  tenant_id: ""

  # mTLS certificates for mutual authentication (optional, recommended for production)
  tls:
    ca_cert: ""        # CA certificate path — Env: CERTIX_TLS_CA_CERT
    client_cert: ""    # Client certificate path — Env: CERTIX_TLS_CLIENT_CERT
    client_key: ""     # Client private key path — Env: CERTIX_TLS_CLIENT_KEY

  # How often the agent sends heartbeat to the ingestion gateway
  # The server may override this value during registration
  heartbeat_interval: 60s

  # File path to persist the JWT token between agent restarts
  # Avoids re-registration on every restart
  token_path: /var/lib/bitcollector/.agent-token

  # Retry settings for failed API calls (exponential backoff)
  retry_max_attempts: 5
  retry_base_delay: 2s

# =============================================================================
# AGENT
# =============================================================================
agent:
  # Directory for agent identity (ECDSA keypair), state, and cached data
  data_dir: /var/lib/bitcollector

  # Default collection interval for all collectors (can be overridden per collector)
  collection_interval: 60s

  # Delay before first collection cycle (allows system to stabilize after boot)
  startup_delay: 5s

  # Maximum memory usage in megabytes — agent will throttle if exceeded
  max_memory_mb: 50

  # Timeout for graceful shutdown when receiving SIGTERM/SIGINT
  graceful_shutdown: 30s

# =============================================================================
# COLLECTORS
# =============================================================================
# Each collector gathers a specific type of telemetry data.
# Disable collectors you don't need to reduce resource usage.
collectors:
  # Process collector — running processes with PID, owner, CPU/memory usage
  process:
    enabled: true
    interval: 60s
    timeout: 30s

  # Port collector — open ports, listening services, bound addresses
  port:
    enabled: true
    interval: 60s
    timeout: 30s

  # Software collector — installed packages and applications
  software:
    enabled: true
    interval: 300s    # 5 minutes — software changes less frequently
    timeout: 120s

  # System collector — OS, kernel, architecture, CPU, memory, disk info
  system:
    enabled: true
    interval: 300s
    timeout: 30s

  # Metrics collector — real-time CPU, memory, load, I/O statistics
  metrics:
    enabled: true
    interval: 30s
    timeout: 10s

  # Network collector — per-service traffic statistics
  # Requires elevated privileges (root or CAP_NET_ADMIN)
  network:
    enabled: false
    interval: 60s
    timeout: 30s
    track_connections: true     # Track individual TCP connections
    aggregate_by_pid: true      # Aggregate traffic stats by process

  # File collector — log file monitoring and content collection
  # file:
  #   enabled: false
  #   interval: 60s
  #   timeout: 30s
  #   inputs:
  #     - id: syslog
  #       type: syslog
  #       paths:
  #         - /var/log/syslog
  #         - /var/log/messages
  #       tail_mode: true
  #       parse_content: true

# =============================================================================
# EXPORTERS
# =============================================================================
# Local exporters for debugging or hybrid deployments.
# When control_plane is configured, telemetry is ALSO sent to the ingestion gateway.
exporters:
  # File exporter — writes telemetry to local NDJSON files
  file:
    enabled: false
    path: /var/lib/bitcollector/telemetry.ndjson
    format: ndjson          # json or ndjson (newline-delimited JSON)
    rotate_size: 104857600  # 100 MB — rotate when file reaches this size
    rotate_count: 5         # Keep 5 rotated files
    flush_interval: 10s
    compress: false          # gzip compress rotated files

  # HTTP/Webhook exporter — POST telemetry to a custom endpoint
  # http:
  #   enabled: false
  #   url: https://your-endpoint.example.com/api/telemetry
  #   method: POST
  #   headers:
  #     Authorization: "Bearer your-token"
  #   batch_size: 100
  #   flush_interval: 30s
  #   retry_attempts: 3
  #   timeout: 30s
  #   sign_payloads: true
  #   tls_enabled: true
  #   tls_cert_file: /etc/bitcollector/certs/client.crt
  #   tls_key_file: /etc/bitcollector/certs/client.key
  #   tls_ca_file: /etc/bitcollector/certs/ca.crt

# =============================================================================
# SECURITY
# =============================================================================
security:
  # Enable mutual TLS for exporters that support it
  enable_mtls: false
  cert_file: ""
  key_file: ""
  ca_file: ""

  # Sign telemetry payloads with the agent's ECDSA private key
  # Allows the platform to verify data integrity and authenticity
  sign_payloads: true

  # Encrypt payloads with a shared key (requires key exchange with platform)
  encrypt_payloads: false

  # Enable nonce-based replay protection on telemetry submissions
  replay_protection: true

  # How long a nonce is considered valid (seconds)
  nonce_validity_secs: 300

# =============================================================================
# LOGGING
# =============================================================================
logging:
  # Log level: debug, info, warn, error
  level: info

  # Log format: json (structured) or text (human-readable)
  format: json

  # Output destination: stdout, stderr, or file
  output: stdout

  # Log file path (only used when output is "file")
  file: /var/log/bitcollector/bitcollector.log

  # Maximum log file size in MB before rotation
  max_size_mb: 100

  # Number of rotated log files to keep
  max_backups: 3

  # Maximum age of rotated log files in days
  max_age_days: 30

# =============================================================================
# POLICY
# =============================================================================
policy:
  # Enable remote policy fetching from the control plane
  remote_enabled: false
  remote_url: ""
  refresh_interval: 300s

  # If true, continue with local policy when remote fetch fails
  fail_open: true

  # Data redaction settings — sanitize sensitive data before sending
  redaction:
    enabled: true
    redact_command_line: false    # Redact process command-line arguments
    redact_env_vars: true         # Redact environment variables from process info
    sensitive_patterns:            # Case-insensitive patterns to redact
      - password
      - secret
      - token
      - key
      - credential
      - api_key
      - apikey
      - auth

Environment Variables

All environment variables override their corresponding config file values.

Variable	Config Path	Description
CERTIX_TENANT_ID	control_plane.tenant_id	Tenant ID (required for control plane)
CERTIX_GATEWAY_URL	control_plane.gateway_url	Agent Gateway Service URL
CERTIX_INGEST_URL	control_plane.ingest_url	Agent Ingestion Gateway URL
CERTIX_TLS_CA_CERT	control_plane.tls.ca_cert	CA certificate for mTLS
CERTIX_TLS_CLIENT_CERT	control_plane.tls.client_cert	Client certificate for mTLS
CERTIX_TLS_CLIENT_KEY	control_plane.tls.client_key	Client private key for mTLS

Collector Intervals Guide

Choose intervals based on your monitoring needs and resource constraints:

Use Case	Process	Port	Software	System	Metrics	Network
Minimal (low resource)	300s	300s	600s	600s	60s	off
Standard (recommended)	60s	60s	300s	300s	30s	off
Aggressive (high visibility)	30s	30s	120s	120s	15s	30s
Real-time (incident response)	10s	10s	60s	60s	5s	10s

Resource Impact

Shorter intervals increase CPU, memory, and network usage. The "Real-time" profile should only be used temporarily during active incident investigation.

Minimal Configuration

The absolute minimum configuration to get an agent running:

control_plane:
  tenant_id: "<YOUR_TENANT_ID>"

agent:
  data_dir: /var/lib/bitcollector

collectors:
  system:
    enabled: true
  metrics:
    enabled: true

All other values will use sensible defaults.

---

Related:

• Scanner Agents Overview
• Agent Deployment Guide
• Devices