Version: 1.0.0

Référence de configuration des agents

Référence complète de toutes les options de configuration de l'agent Bitcollector. L'agent lit la configuration à partir d'un fichier YAML et de variables d'environnement. Les variables d'environnement ont toujours priorité sur les valeurs du fichier.

Emplacement du fichier de configuration

Plateforme	Chemin par défaut
Linux	`/etc/bitcollector/config.yaml`
macOS	`/etc/bitcollector/config.yaml`
Windows	`C:\ProgramData\Cert-IX\bitcollector\config.yaml`

Remplacez avec l'option CLI -config :

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

Options CLI

Option	Description	Par défaut
`-config`	Chemin vers le fichier de configuration	(aucun — utilise les valeurs par défaut)
`-log-level`	Remplacer le niveau de log (`debug`, `info`, `warn`, `error`)	Depuis le fichier de configuration
`-version`	Afficher la version et quitter	—

Référence complète de la configuration

# =============================================================================
# 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

Variables d'environnement

Toutes les variables d'environnement remplacent les valeurs correspondantes du fichier de configuration.

Variable	Chemin de configuration	Description
`CERTIX_TENANT_ID`	`control_plane.tenant_id`	Identifiant de locataire (requis pour le plan de contrôle)
`CERTIX_GATEWAY_URL`	`control_plane.gateway_url`	URL du Agent Gateway Service
`CERTIX_INGEST_URL`	`control_plane.ingest_url`	URL du Agent Ingestion Gateway
`CERTIX_TLS_CA_CERT`	`control_plane.tls.ca_cert`	Certificat CA pour mTLS
`CERTIX_TLS_CLIENT_CERT`	`control_plane.tls.client_cert`	Certificat client pour mTLS
`CERTIX_TLS_CLIENT_KEY`	`control_plane.tls.client_key`	Clé privée client pour mTLS

Guide des intervalles de collecte

Choisissez les intervalles en fonction de vos besoins de surveillance et contraintes de ressources :

Cas d'utilisation	Process	Port	Software	System	Metrics	Network
Minimal (faibles ressources)	300s	300s	600s	600s	60s	off
Standard (recommandé)	60s	60s	300s	300s	30s	off
Agressif (haute visibilité)	30s	30s	120s	120s	15s	30s
Temps réel (réponse aux incidents)	10s	10s	60s	60s	5s	10s

Impact sur les ressources

Des intervalles plus courts augmentent l'utilisation du CPU, de la mémoire et du réseau. Le profil « Temps réel » ne devrait être utilisé que temporairement lors d'une investigation d'incident active.

Configuration minimale

La configuration absolument minimale pour faire fonctionner un agent :

control_plane:
  tenant_id: "<YOUR_TENANT_ID>"

agent:
  data_dir: /var/lib/bitcollector

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

Toutes les autres valeurs utiliseront des valeurs par défaut raisonnables.

Connexe :

Emplacement du fichier de configuration​

Options CLI​

Référence complète de la configuration​

Variables d'environnement​

Guide des intervalles de collecte​

Configuration minimale​