Guida alla distribuzione degli agenti

Questa guida vi accompagna passo dopo passo nella distribuzione di un agente scanner Cert-IX nella vostra rete privata. L'agente si registra automaticamente sulla piattaforma, inizia la raccolta della telemetria e rende visibili i vostri asset interni nel dashboard.

Prerequisiti

Prima di distribuire un agente, assicuratevi di avere:

• Un account Cert-IX con abbonamento attivo
• Il vostro ID Tenant (disponibile in Impostazioni → Organizzazione → ID Tenant)
• Accesso root o amministratore sull'host di destinazione
• Accesso HTTPS in uscita (porta 443) verso api.cert-ix.com: lì risiedono sia il gateway dell'agent sia gli endpoint di ingestione della telemetria
• La directory di rilascio per la vostra piattaforma, ottenuta tramite il vostro account Cert-IX (vedi Ottenere il binario dell'agent)

Distribuzione rapida

Il modo più veloce per distribuire è tramite il dashboard: andate su Gestione asset → Dispositivi → cliccate sul pulsante verde Distribuisci agente. La procedura guidata genera tutti i comandi precompilati con il vostro ID Tenant.

Passaggio 1: Ottenere il binario dell'agent

Non esiste alcun URL di download pubblico

I binari degli agent sono distribuiti tramite il vostro account Cert-IX. Oggi non esiste alcun endpoint di download pubblico anonimo: considerate quindi obsoleta qualsiasi istruzione che vi chieda di scaricarli da un host pubblico — chiedete al vostro referente Cert-IX la directory di rilascio per la vostra piattaforma.

Ogni directory di rilascio contiene il binario, un SBOM CycloneDX, una firma cosign, un file SHA256SUMS firmato e la provenance di build. Verificateli prima di eseguire qualsiasi cosa — questi passaggi non richiedono accesso di rete e valgono per qualunque directory riceviate.

Dopo aver verificato la directory di rilascio, installate il binario per la vostra piattaforma. Eseguite ogni comando dall'interno di quella directory.

Linux (x86_64)

# Dalla directory di rilascio verificata — vedi «Verificare i download»
install -m 0755 bitcollector-linux-amd64 /usr/local/bin/bitcollector

# Verificate cosa avete
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 — eseguire come amministratore
New-Item -ItemType Directory -Force -Path "C:\Program Files\Cert-IX"
Copy-Item ".\bitcollector-windows-amd64.exe" "C:\Program Files\Cert-IX\bitcollector.exe"

# Verificate cosa avete
& "C:\Program Files\Cert-IX\bitcollector.exe" -version

Verificate prima di installare, non dopo

Dimostrate l'integrità dei byte nella directory di rilascio prima di copiarli su un host: un checksum calcolato dopo una copia non affidabile dice solo che la copia è riuscita. Il file SHA256SUMS firmato incluso nel rilascio è il riferimento; non esiste alcun checksums.txt pubblico da scaricare. Vedi Verificare i download per i controlli cosign e dell'ancora di fiducia.

Passaggio 2: Creare il file di configurazione

Create la directory di configurazione e il file dell'agente.

Linux / macOS

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

Create /etc/bitcollector/config.yaml con il seguente contenuto:

# 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

Create C:\ProgramData\Cert-IX\bitcollector\config.yaml con lo stesso contenuto e percorsi adattati:

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

Variabili d'ambiente

Potete anche impostare la configurazione tramite variabili d'ambiente invece del file YAML:

Variabile	Descrizione
CERTIX_TENANT_ID	Il vostro ID Tenant (obbligatorio)
CERTIX_GATEWAY_URL	URL del gateway agente
CERTIX_INGEST_URL	URL del gateway di ingestione
CERTIX_TLS_CA_CERT	Percorso del certificato CA
CERTIX_TLS_CLIENT_CERT	Percorso del certificato client
CERTIX_TLS_CLIENT_KEY	Percorso della chiave client

Le variabili d'ambiente hanno la precedenza sui valori del file di configurazione.

Passaggio 3: Eseguire l'agente

Opzione A: Servizio systemd (consigliato per Linux)

Create un utente di servizio dedicato:

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

Create il file unit systemd in /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

Abilitate e avviate il servizio:

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

Opzione B: Container 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

Nota Docker

I flag --pid=host e --net=host sono necessari affinché l'agente possa vedere i processi e le connessioni di rete dell'host. Senza di essi, l'agente vedrà solo i dati a livello di container.

Opzione C: Manuale / Primo piano

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

Opzione D: Servizio 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

Passaggio 4: Verificare la distribuzione

Controllare lo stato del servizio

# 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

Cosa cercare

Nei log dell'agente dovreste vedere questi messaggi in questo ordine:

1. Agent identity loaded — L'agente ha generato o caricato la sua coppia di chiavi ECDSA
2. Registering with control plane — Connessione al servizio gateway agente
3. Agent registered successfully — Registrazione completata, token JWT ricevuto
4. Starting heartbeat loop — Heartbeat periodici al gateway di ingestione
5. Collection cycle complete — Primi dati di telemetria raccolti e inviati

Verificare nel dashboard

Entro 60 secondi dalla registrazione riuscita:

1. Andate su Gestione asset → Dispositivi
2. Il nuovo dispositivo dovrebbe apparire con un badge verde Online
3. Cliccate sul dispositivo per vedere i dati raccolti:
   • Informazioni di sistema — SO, kernel, CPU, memoria, disco
   • Processi — Processi in esecuzione con utilizzo delle risorse
   • Porte — Porte aperte e servizi in ascolto
   • Software — Pacchetti installati
   • Metriche — Grafici in tempo reale per CPU, memoria, carico

Risoluzione dei problemi

L'agente non si avvia

Sintomo	Causa	Soluzione
permission denied	Binario non eseguibile	chmod +x /usr/local/bin/bitcollector
config file not found	Percorso di configurazione errato	Verificate che il flag -config corrisponda alla posizione effettiva del file
tenant_id is required	ID Tenant mancante	Impostate la variabile CERTIX_TENANT_ID o tenant_id nella configurazione

L'agente non si registra

Sintomo	Causa	Soluzione
connection refused	Firewall blocca l'uscita	Consentite HTTPS (443) verso api.cert-ix.com
certificate verify failed	Proxy aziendale/MITM	Aggiungete la CA del proxy al trust store di sistema
401 Unauthorized	ID Tenant non valido	Verificate l'ID Tenant in Impostazioni → Organizzazione
timeout	Errore di risoluzione DNS	Verificate che il DNS risolva api.cert-ix.com

Agente registrato ma nessun dato

Sintomo	Causa	Soluzione
Nessun processo visualizzato	Permessi insufficienti	Eseguite come root o con CAP_SYS_PTRACE
Nessuna porta visualizzata	Permessi insufficienti	Eseguite come root o con CAP_NET_ADMIN
Nessun dato di rete	Collector di rete disabilitato	Impostate collectors.network.enabled: true
Dati obsoleti	Raccolta non in esecuzione	Controllate i log per errori di raccolta

Messaggi di log comuni

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

Disinstallazione

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

attenzione

Dopo la disinstallazione, il dispositivo apparirà come Offline nel dashboard dopo il mancato heartbeat successivo (predefinito: 2 minuti). Potete rimuoverlo manualmente dall'elenco dei dispositivi.

Distribuzione di più agenti

Per distribuzioni su larga scala, utilizzate strumenti di gestione della configurazione:

Esempio 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:
    # Posizionate prima la directory di rilascio VERIFICATA sul control node: non esiste
    # alcun URL pubblico. Vedi «Verificare i download».
    - 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

Esempio Terraform (AWS EC2 User Data)

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

  user_data = <<-EOF
    #!/bin/bash
    # Non esiste alcun URL di download pubblico. Distribuite voi stessi il binario VERIFICATO,
    # ad es. dal vostro artifact store privato o da un'AMI pre-costruita.
    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
}

---

Correlato:

• Panoramica degli agenti scanner
• Riferimento alla configurazione dell'agente
• Dispositivi