Guide de déploiement des agents

Ce guide vous accompagne dans le déploiement d'un agent de scan Cert-IX sur votre réseau privé. L'agent s'enregistrera automatiquement auprès de la plateforme, commencera à collecter la télémétrie et rendra vos actifs internes visibles dans le tableau de bord.

Prérequis

Avant de déployer un agent, assurez-vous de disposer de :

• Un compte Cert-IX avec un abonnement actif
• Votre Identifiant de locataire (disponible dans Paramètres → Organisation → Identifiant de locataire)
• Un accès root ou administrateur sur l'hôte cible
• Un accès HTTPS sortant (port 443) vers api.cert-ix.com — la passerelle de l'agent et les points d'ingestion de télémétrie s'y trouvent tous les deux
• Le répertoire de publication pour votre plateforme, obtenu via votre compte Cert-IX (voir Obtenir le binaire de l'agent)

Déploiement rapide

Le moyen le plus rapide de déployer est depuis le tableau de bord : allez dans Gestion des actifs → Appareils → cliquez sur le bouton vert Déployer l'agent. L'assistant génère toutes les commandes pré-remplies avec votre identifiant de locataire.

Étape 1 : Obtenir le binaire de l'agent

Il n'existe aucune URL de téléchargement publique

Les binaires des agents sont distribués via votre compte Cert-IX. Il n'existe aujourd'hui aucun point de téléchargement public anonyme : considérez donc comme obsolète toute instruction vous demandant d'en récupérer un depuis un hôte public — demandez à votre contact Cert-IX le répertoire de publication correspondant à votre plateforme.

Chaque répertoire de publication contient le binaire, un SBOM CycloneDX, une signature cosign, un fichier SHA256SUMS signé et la provenance de compilation. Vérifiez-les avant d'exécuter quoi que ce soit — ces étapes ne nécessitent aucun accès réseau et s'appliquent à tout répertoire reçu.

Une fois le répertoire de publication vérifié, installez le binaire correspondant à votre plateforme. Exécutez chaque commande depuis ce répertoire.

Linux (x86_64)

# Depuis le répertoire de publication vérifié — voir « Vérifier vos téléchargements »
install -m 0755 bitcollector-linux-amd64 /usr/local/bin/bitcollector

# Vérifiez ce que vous avez
bitcollector --version

Linux (ARM64)

install -m 0755 bitcollector-linux-arm64 /usr/local/bin/bitcollector

bitcollector --version

macOS (Apple Silicon)

install -m 0755 bitcollector-darwin-arm64 /usr/local/bin/bitcollector

bitcollector --version

macOS (Intel)

install -m 0755 bitcollector-darwin-amd64 /usr/local/bin/bitcollector

bitcollector --version

Windows (x86_64)

# PowerShell — à exécuter en tant qu'administrateur
New-Item -ItemType Directory -Force -Path "C:\Program Files\Cert-IX"
Copy-Item ".\bitcollector-windows-amd64.exe" "C:\Program Files\Cert-IX\bitcollector.exe"

# Vérifiez ce que vous avez
& "C:\Program Files\Cert-IX\bitcollector.exe" -version

Vérifiez avant d'installer, pas après

Prouvez l'intégrité des octets dans le répertoire de publication avant de les copier sur un hôte : une somme de contrôle calculée après une copie non fiable ne prouve que la réussite de la copie. Le fichier SHA256SUMS signé livré avec la publication fait référence ; il n'existe aucun checksums.txt public à télécharger. Voir Vérifier vos téléchargements pour les contrôles cosign et d'ancre de confiance.

Étape 2 : Créer le fichier de configuration

Créez le répertoire de configuration et le fichier de l'agent.

Linux / macOS

# Create config and data directories
sudo mkdir -p /etc/bitcollector
sudo mkdir -p /var/lib/bitcollector

Créez /etc/bitcollector/config.yaml avec le contenu suivant :

# Bitcollector Configuration — Cert-IX Platform
# Replace <YOUR_TENANT_ID> with your actual Tenant ID

control_plane:
  gateway_url: https://api.cert-ix.com/api/v1/agents
  ingest_url: https://api.cert-ix.com/api/v1/ingest
  tenant_id: "<YOUR_TENANT_ID>"
  heartbeat_interval: 60s
  token_path: /var/lib/bitcollector/.agent-token
  retry_max_attempts: 5
  retry_base_delay: 2s
  # Uncomment for mTLS (recommended for production)
  # tls:
  #   ca_cert: /etc/bitcollector/certs/ca.crt
  #   client_cert: /etc/bitcollector/certs/client.crt
  #   client_key: /etc/bitcollector/certs/client.key

agent:
  data_dir: /var/lib/bitcollector
  collection_interval: 60s
  startup_delay: 5s
  max_memory_mb: 50
  graceful_shutdown: 30s

collectors:
  process:
    enabled: true
    interval: 60s
  port:
    enabled: true
    interval: 60s
  software:
    enabled: true
    interval: 300s
  system:
    enabled: true
    interval: 300s
  metrics:
    enabled: true
    interval: 30s
  network:
    enabled: false  # Enable if elevated privileges available

logging:
  level: info
  format: json
  output: stdout

Windows

Créez C:\ProgramData\Cert-IX\bitcollector\config.yaml avec le même contenu, en ajustant les chemins :

control_plane:
  gateway_url: https://api.cert-ix.com/api/v1/agents
  ingest_url: https://api.cert-ix.com/api/v1/ingest
  tenant_id: "<YOUR_TENANT_ID>"
  heartbeat_interval: 60s
  token_path: "C:\\ProgramData\\Cert-IX\\bitcollector\\.agent-token"
  retry_max_attempts: 5
  retry_base_delay: 2s

agent:
  data_dir: "C:\\ProgramData\\Cert-IX\\bitcollector"
  collection_interval: 60s
  startup_delay: 5s
  max_memory_mb: 50
  graceful_shutdown: 30s

collectors:
  process:
    enabled: true
    interval: 60s
  port:
    enabled: true
    interval: 60s
  software:
    enabled: true
    interval: 300s
  system:
    enabled: true
    interval: 300s
  metrics:
    enabled: true
    interval: 30s
  network:
    enabled: false

logging:
  level: info
  format: json
  output: stdout

Variables d'environnement

Vous pouvez également définir la configuration via des variables d'environnement au lieu de modifier le fichier YAML :

Variable	Description
CERTIX_TENANT_ID	Votre identifiant de locataire (requis)
CERTIX_GATEWAY_URL	URL du Agent Gateway
CERTIX_INGEST_URL	URL du Ingestion Gateway
CERTIX_TLS_CA_CERT	Chemin du certificat CA
CERTIX_TLS_CLIENT_CERT	Chemin du certificat client
CERTIX_TLS_CLIENT_KEY	Chemin de la clé client

Les variables d'environnement ont priorité sur les valeurs du fichier de configuration.

Étape 3 : Exécuter l'agent

Option A : Service Systemd (recommandé pour Linux)

Créez un utilisateur de service dédié :

sudo useradd --system --no-create-home --shell /usr/sbin/nologin bitcollector
sudo chown -R bitcollector:bitcollector /var/lib/bitcollector

Créez le fichier d'unité systemd dans /etc/systemd/system/bitcollector.service :

[Unit]
Description=Cert-IX Bitcollector Agent
Documentation=https://docs.cert-ix.com/docs/features/asset-management/agent-deployment-guide
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=bitcollector
Group=bitcollector
ExecStart=/usr/local/bin/bitcollector -config /etc/bitcollector/config.yaml
Restart=always
RestartSec=10
Environment=CERTIX_TENANT_ID=<YOUR_TENANT_ID>
Environment=CERTIX_GATEWAY_URL=https://api.cert-ix.com/api/v1/agents
Environment=CERTIX_INGEST_URL=https://api.cert-ix.com/api/v1/ingest

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/bitcollector
PrivateTmp=true

[Install]
WantedBy=multi-user.target

Activez et démarrez le service :

sudo systemctl daemon-reload
sudo systemctl enable bitcollector
sudo systemctl start bitcollector

Option B : Conteneur Docker

docker run -d \
  --name bitcollector \
  --restart unless-stopped \
  -e CERTIX_TENANT_ID="<YOUR_TENANT_ID>" \
  -e CERTIX_GATEWAY_URL="https://api.cert-ix.com/api/v1/agents" \
  -e CERTIX_INGEST_URL="https://api.cert-ix.com/api/v1/ingest" \
  -v /var/lib/bitcollector:/var/lib/bitcollector \
  --pid=host \
  --net=host \
  registry.cert-ix.com/bitcollector:latest

Note Docker

Les options --pid=host et --net=host sont nécessaires pour que l'agent puisse voir les processus et connexions réseau de l'hôte. Sans elles, l'agent ne verra que les données au niveau du conteneur.

Option C : Manuel / Premier plan

export CERTIX_TENANT_ID="<YOUR_TENANT_ID>"
/usr/local/bin/bitcollector -config /etc/bitcollector/config.yaml -log-level debug

Option D : Service Windows

# Register as a Windows service
sc.exe create bitcollector binPath= "\"C:\Program Files\Cert-IX\bitcollector.exe\" -config \"C:\ProgramData\Cert-IX\bitcollector\config.yaml\"" start= auto

# Set environment variables for the service
[System.Environment]::SetEnvironmentVariable("CERTIX_TENANT_ID", "<YOUR_TENANT_ID>", "Machine")

# Start the service
sc.exe start bitcollector

Étape 4 : Vérifier le déploiement

Vérifier le statut du service

# Linux (systemd)
sudo systemctl status bitcollector

# View recent logs
journalctl -u bitcollector -n 50 --no-pager

# Windows
Get-Service bitcollector | Format-List
Get-EventLog -LogName Application -Source bitcollector -Newest 20

Ce qu'il faut vérifier

Dans les journaux de l'agent, vous devriez voir ces messages dans l'ordre :

1. Agent identity loaded — L'agent a généré ou chargé sa paire de clés ECDSA
2. Registering with control plane — Connexion au Agent Gateway Service
3. Agent registered successfully — Enregistrement terminé, jeton JWT reçu
4. Starting heartbeat loop — Heartbeats périodiques vers le gateway d'ingestion
5. Collection cycle complete — Premières données de télémétrie collectées et envoyées

Vérifier le tableau de bord

Dans les 60 secondes suivant un enregistrement réussi :

1. Allez dans Gestion des actifs → Appareils
2. Le nouvel appareil devrait apparaître avec un badge vert En ligne
3. Cliquez sur l'appareil pour voir les données collectées :
   • Infos système — OS, noyau, CPU, mémoire, disque
   • Processus — Processus en cours avec utilisation des ressources
   • Ports — Ports ouverts et services en écoute
   • Logiciels — Paquets installés
   • Métriques — Graphiques CPU, mémoire, charge en temps réel

Dépannage

L'agent ne démarre pas

Symptôme	Cause	Solution
permission denied	Binaire non exécutable	chmod +x /usr/local/bin/bitcollector
config file not found	Mauvais chemin de configuration	Vérifiez que l'option -config correspond à l'emplacement réel du fichier
tenant_id is required	Identifiant de locataire manquant	Définissez la variable CERTIX_TENANT_ID ou tenant_id dans la configuration

L'agent ne s'enregistre pas

Symptôme	Cause	Solution
connection refused	Pare-feu bloquant le sortant	Autorisez HTTPS (443) vers api.cert-ix.com
certificate verify failed	Proxy d'entreprise/MITM	Ajoutez le CA du proxy au magasin de confiance système
401 Unauthorized	Identifiant de locataire invalide	Vérifiez l'identifiant dans Paramètres → Organisation
timeout	Échec de résolution DNS	Vérifiez que le DNS résout api.cert-ix.com

Agent enregistré mais pas de données

Symptôme	Cause	Solution
Pas de processus affichés	Permissions insuffisantes	Exécutez en root ou avec CAP_SYS_PTRACE
Pas de ports affichés	Permissions insuffisantes	Exécutez en root ou avec CAP_NET_ADMIN
Pas de données réseau	Collecteur réseau désactivé	Définissez collectors.network.enabled: true
Données obsolètes	Collecte non exécutée	Vérifiez les journaux pour les erreurs de collecte

Messages de journal courants

# Healthy operation
INFO  Agent registered successfully  agent_id=abc123 tenant=your-tenant
INFO  Heartbeat sent                 status=200 next_in=60s
INFO  Collection cycle complete      collectors=5 duration=2.3s
INFO  Telemetry batch sent           payloads=5 status=202

# Warning signs
WARN  Heartbeat failed, retrying     status=503 retry_in=5s
WARN  Token expired, refreshing      expires_at=2025-01-01T00:00:00Z

# Errors requiring attention
ERROR Registration failed            error="tenant not found"
ERROR Collection failed              collector=network error="permission denied"

Désinstallation

Linux (systemd)

sudo systemctl stop bitcollector
sudo systemctl disable bitcollector
sudo rm /etc/systemd/system/bitcollector.service
sudo systemctl daemon-reload
sudo rm /usr/local/bin/bitcollector
sudo rm -rf /etc/bitcollector
sudo rm -rf /var/lib/bitcollector
sudo userdel bitcollector

Docker

docker stop bitcollector
docker rm bitcollector
sudo rm -rf /var/lib/bitcollector

Windows

sc.exe stop bitcollector
sc.exe delete bitcollector
Remove-Item "C:\Program Files\Cert-IX\bitcollector.exe" -Force
Remove-Item "C:\ProgramData\Cert-IX\bitcollector" -Recurse -Force

attention

Après la désinstallation, l'appareil apparaîtra comme Hors ligne dans le tableau de bord après le prochain heartbeat manqué (par défaut : 2 minutes). Vous pouvez le supprimer manuellement de la liste des appareils.

Déploiement de plusieurs agents

Pour les déploiements à grande échelle, utilisez des outils de gestion de configuration :

Exemple Ansible

- name: Deploy Bitcollector agent
  hosts: all_servers
  become: true
  vars:
    certix_tenant_id: "your-tenant-id"
    bitcollector_version: "1.0.0"
    # ansible_architecture reports x86_64 / aarch64; release filenames use amd64 / arm64
    bitcollector_arch: "{{ 'arm64' if ansible_architecture == 'aarch64' else 'amd64' }}"
  tasks:
    # Placez d'abord le répertoire de publication VÉRIFIÉ sur le nœud de contrôle — il
    # n'existe aucune URL publique. Voir « Vérifier vos téléchargements ».
    - name: Copy verified agent binary from the control node
      copy:
        src: "bitcollector-release/bitcollector-linux-{{ bitcollector_arch }}"
        dest: /usr/local/bin/bitcollector
        mode: '0755'

    - name: Create config directory
      file:
        path: /etc/bitcollector
        state: directory
        mode: '0755'

    - name: Deploy configuration
      template:
        src: bitcollector.yaml.j2
        dest: /etc/bitcollector/config.yaml
        mode: '0644'

    - name: Deploy systemd service
      template:
        src: bitcollector.service.j2
        dest: /etc/systemd/system/bitcollector.service
      notify: restart bitcollector

    - name: Enable and start service
      systemd:
        name: bitcollector
        enabled: true
        state: started
        daemon_reload: true

  handlers:
    - name: restart bitcollector
      systemd:
        name: bitcollector
        state: restarted

Exemple Terraform (AWS EC2 User Data)

resource "aws_instance" "server" {
  ami           = "ami-0abcdef1234567890"
  instance_type = "t3.micro"

  user_data = <<-EOF
    #!/bin/bash
    # Il n'existe aucune URL de téléchargement public. Livrez vous-même le binaire VÉRIFIÉ —
    # par ex. depuis votre propre dépôt d'artefacts privé ou une AMI pré-construite.
    aws s3 cp "s3://$${var.certix_artifacts_bucket}/bitcollector-linux-amd64" \
      /usr/local/bin/bitcollector
    chmod 0755 /usr/local/bin/bitcollector
    mkdir -p /etc/bitcollector /var/lib/bitcollector

    cat > /etc/bitcollector/config.yaml <<CONFIG
    control_plane:
      gateway_url: https://api.cert-ix.com/api/v1/agents
      ingest_url: https://api.cert-ix.com/api/v1/ingest
      tenant_id: "${var.certix_tenant_id}"
      heartbeat_interval: 60s
      token_path: /var/lib/bitcollector/.agent-token
    agent:
      data_dir: /var/lib/bitcollector
      collection_interval: 60s
    collectors:
      process: { enabled: true, interval: 60s }
      port: { enabled: true, interval: 60s }
      system: { enabled: true, interval: 300s }
      metrics: { enabled: true, interval: 30s }
    logging:
      level: info
      format: json
    CONFIG

    useradd --system --no-create-home bitcollector
    chown -R bitcollector:bitcollector /var/lib/bitcollector

    # Create and start systemd service
    cat > /etc/systemd/system/bitcollector.service <<SERVICE
    [Unit]
    Description=Cert-IX Bitcollector Agent
    After=network-online.target
    [Service]
    Type=simple
    User=bitcollector
    ExecStart=/usr/local/bin/bitcollector -config /etc/bitcollector/config.yaml
    Restart=always
    RestartSec=10
    NoNewPrivileges=true
    ProtectSystem=strict
    ReadWritePaths=/var/lib/bitcollector
    [Install]
    WantedBy=multi-user.target
    SERVICE

    systemctl daemon-reload
    systemctl enable --now bitcollector
  EOF
}

---

Connexe :

• Aperçu des agents de scan
• Référence de configuration des agents
• Appareils