Agentenbereitstellungsanleitung

Diese Anleitung führt Sie Schritt für Schritt durch die Bereitstellung eines Cert-IX-Scanner-Agenten in Ihrem privaten Netzwerk. Der Agent registriert sich automatisch bei der Plattform, beginnt mit der Telemetrieerfassung und macht Ihre internen Assets im Dashboard sichtbar.

Voraussetzungen

Stellen Sie vor der Bereitstellung eines Agenten sicher, dass Sie Folgendes haben:

• Ein Cert-IX-Konto mit aktivem Abonnement
• Ihre Mandanten-ID (zu finden unter Einstellungen → Organisation → Mandanten-ID)
• Root- oder Administratorzugriff auf dem Zielhost
• Ausgehenden HTTPS-Zugriff (Port 443) auf api.cert-ix.com und downloads.cert-ix.com

Schnellbereitstellung

Der schnellste Weg zur Bereitstellung ist über das Dashboard: Gehen Sie zu Asset-Verwaltung → Geräte → klicken Sie auf die grüne Schaltfläche Agent bereitstellen. Der Assistent generiert alle Befehle vorausgefüllt mit Ihrer Mandanten-ID.

Schritt 1: Agent herunterladen

Linux (x86_64)

# Download the Bitcollector agent binary
curl -fsSL "https://downloads.cert-ix.com/bitcollector-linux-amd64" \
  -o /usr/local/bin/bitcollector

# Set executable permissions
chmod +x /usr/local/bin/bitcollector

# Verify the SHA256 checksum
sha256sum /usr/local/bin/bitcollector

Linux (ARM64)

curl -fsSL "https://downloads.cert-ix.com/bitcollector-linux-arm64" \
  -o /usr/local/bin/bitcollector

chmod +x /usr/local/bin/bitcollector
sha256sum /usr/local/bin/bitcollector

macOS (Apple Silicon)

curl -fsSL "https://downloads.cert-ix.com/bitcollector-darwin-arm64" \
  -o /usr/local/bin/bitcollector

chmod +x /usr/local/bin/bitcollector
shasum -a 256 /usr/local/bin/bitcollector

macOS (Intel)

curl -fsSL "https://downloads.cert-ix.com/bitcollector-darwin-amd64" \
  -o /usr/local/bin/bitcollector

chmod +x /usr/local/bin/bitcollector
shasum -a 256 /usr/local/bin/bitcollector

Windows (x86_64)

# PowerShell — Run as Administrator
Invoke-WebRequest -Uri "https://downloads.cert-ix.com/bitcollector-windows-amd64.exe" `
  -OutFile "C:\Program Files\Cert-IX\bitcollector.exe"

# Verify checksum
Get-FileHash "C:\Program Files\Cert-IX\bitcollector.exe" -Algorithm SHA256

Sicherheit

Überprüfen Sie nach dem Download immer die SHA256-Prüfsumme. Die erwarteten Prüfsummen werden unter https://downloads.cert-ix.com/checksums.txt veröffentlicht und mit dem Cert-IX-Release-Schlüssel signiert.

Schritt 2: Konfigurationsdatei erstellen

Erstellen Sie das Agenten-Konfigurationsverzeichnis und die Datei.

Linux / macOS

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

Erstellen Sie /etc/bitcollector/config.yaml mit folgendem Inhalt:

# 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

Erstellen Sie C:\ProgramData\Cert-IX\bitcollector\config.yaml mit demselben Inhalt und angepassten Pfaden:

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

Umgebungsvariablen

Sie können die Konfiguration auch über Umgebungsvariablen anstelle der YAML-Datei festlegen:

Variable	Beschreibung
CERTIX_TENANT_ID	Ihre Mandanten-ID (erforderlich)
CERTIX_GATEWAY_URL	Agent-Gateway-URL
CERTIX_INGEST_URL	Ingestion-Gateway-URL
CERTIX_TLS_CA_CERT	CA-Zertifikatspfad
CERTIX_TLS_CLIENT_CERT	Client-Zertifikatspfad
CERTIX_TLS_CLIENT_KEY	Client-Schlüsselpfad

Umgebungsvariablen haben Vorrang vor Konfigurationsdateiwerten.

Schritt 3: Agent ausführen

Option A: Systemd-Dienst (empfohlen für Linux)

Erstellen Sie einen dedizierten Dienstbenutzer:

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

Erstellen Sie die systemd-Unit-Datei unter /etc/systemd/system/bitcollector.service:

[Unit]
Description=Cert-IX Bitcollector Agent
Documentation=https://docs.cert-ix.com/agents
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

Aktivieren und starten Sie den Dienst:

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

Option B: Docker-Container

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

Docker-Hinweis

Die Flags --pid=host und --net=host sind erforderlich, damit der Agent Host-Prozesse und Netzwerkverbindungen sehen kann. Ohne sie sieht der Agent nur Daten auf Container-Ebene.

Option C: Manuell / Vordergrund

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

Option D: Windows-Dienst

# 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

Schritt 4: Bereitstellung überprüfen

Dienststatus prüfen

# 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

Worauf Sie achten sollten

In den Agentenprotokollen sollten Sie diese Meldungen in dieser Reihenfolge sehen:

1. Agent identity loaded — Der Agent hat sein ECDSA-Schlüsselpaar generiert oder geladen
2. Registering with control plane — Verbindung zum Agent-Gateway-Dienst
3. Agent registered successfully — Registrierung abgeschlossen, JWT-Token erhalten
4. Starting heartbeat loop — Periodische Heartbeats zum Ingestion-Gateway
5. Collection cycle complete — Erste Telemetriedaten gesammelt und gesendet

Im Dashboard prüfen

Innerhalb von 60 Sekunden nach erfolgreicher Registrierung:

1. Gehen Sie zu Asset-Verwaltung → Geräte
2. Das neue Gerät sollte mit einem grünen Online-Badge erscheinen
3. Klicken Sie auf das Gerät, um die gesammelten Daten zu sehen:
   • Systeminformationen — Betriebssystem, Kernel, CPU, Speicher, Festplatte
   • Prozesse — Laufende Prozesse mit Ressourcennutzung
   • Ports — Offene Ports und lauschende Dienste
   • Software — Installierte Pakete
   • Metriken — Echtzeit-Diagramme für CPU, Speicher, Last

Fehlerbehebung

Agent startet nicht

Symptom	Ursache	Lösung
permission denied	Binärdatei nicht ausführbar	chmod +x /usr/local/bin/bitcollector
config file not found	Falscher Konfigurationspfad	Prüfen Sie, ob der -config-Flag mit dem tatsächlichen Dateispeicherort übereinstimmt
tenant_id is required	Fehlende Mandanten-ID	Setzen Sie die Variable CERTIX_TENANT_ID oder tenant_id in der Konfiguration

Agent registriert sich nicht

Symptom	Ursache	Lösung
connection refused	Firewall blockiert ausgehend	HTTPS (443) zu api.cert-ix.com erlauben
certificate verify failed	Unternehmens-Proxy/MITM	Proxy-CA zum System-Vertrauensspeicher hinzufügen
401 Unauthorized	Ungültige Mandanten-ID	Mandanten-ID unter Einstellungen → Organisation überprüfen
timeout	DNS-Auflösungsfehler	Prüfen Sie, ob DNS api.cert-ix.com auflöst

Agent registriert, aber keine Daten

Symptom	Ursache	Lösung
Keine Prozesse angezeigt	Unzureichende Berechtigungen	Als root oder mit CAP_SYS_PTRACE ausführen
Keine Ports angezeigt	Unzureichende Berechtigungen	Als root oder mit CAP_NET_ADMIN ausführen
Keine Netzwerkdaten	Netzwerk-Collector deaktiviert	collectors.network.enabled: true setzen
Veraltete Daten	Sammlung läuft nicht	Protokolle auf Sammlungsfehler prüfen

Häufige Protokollmeldungen

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

Deinstallation

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

vorsicht

Nach der Deinstallation wird das Gerät im Dashboard als Offline angezeigt, nachdem der nächste Heartbeat ausgeblieben ist (Standard: 2 Minuten). Sie können es manuell aus der Geräteliste entfernen.

Bereitstellung mehrerer Agenten

Für großflächige Bereitstellungen verwenden Sie Konfigurationsmanagement-Tools:

Ansible-Beispiel

- name: Deploy Bitcollector agent
  hosts: all_servers
  become: true
  vars:
    certix_tenant_id: "your-tenant-id"
    bitcollector_version: "1.0.0"
  tasks:
    - name: Download agent binary
      get_url:
        url: "https://downloads.cert-ix.com/bitcollector-linux-{{ ansible_architecture }}"
        dest: /usr/local/bin/bitcollector
        mode: '0755'
        checksum: "sha256:https://downloads.cert-ix.com/checksums.txt"

    - 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

Terraform-Beispiel (AWS EC2 User Data)

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

  user_data = <<-EOF
    #!/bin/bash
    curl -fsSL "https://downloads.cert-ix.com/bitcollector-linux-amd64" \
      -o /usr/local/bin/bitcollector
    chmod +x /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
}

---

Verwandt:

• Scanner-Agenten-Übersicht
• Agentenkonfigurationsreferenz
• Geräte