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 — dort liegen sowohl das Agent-Gateway als auch die Telemetrie-Ingestion-Endpunkte
• Das Release-Verzeichnis für Ihre Plattform, bezogen über Ihr Cert-IX-Konto (siehe Agent-Binärdatei beziehen)

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-Binärdatei beziehen

Es gibt keine öffentliche Download-URL

Die Agent-Binärdateien werden über Ihr Cert-IX-Konto bereitgestellt. Es gibt derzeit keinen anonymen öffentlichen Download-Endpunkt. Betrachten Sie daher jede Anweisung, eine Datei von einem öffentlichen Host zu laden, als veraltet — fragen Sie Ihren Cert-IX-Kontakt nach dem Release-Verzeichnis für Ihre Plattform.

Jedes Release-Verzeichnis enthält die Binärdatei, ein CycloneDX-SBOM, eine cosign-Signatur, eine signierte SHA256SUMS sowie die Build-Provenance. Prüfen Sie diese, bevor Sie irgendetwas ausführen — diese Schritte benötigen keinen Netzwerkzugriff und gelten für jedes erhaltene Verzeichnis.

Sobald Sie das Release-Verzeichnis geprüft haben, installieren Sie die Binärdatei für Ihre Plattform. Führen Sie jeden Befehl aus diesem Verzeichnis heraus aus.

Linux (x86_64)

# Aus dem geprüften Release-Verzeichnis — siehe „Ihre Downloads verifizieren“
install -m 0755 bitcollector-linux-amd64 /usr/local/bin/bitcollector

# Prüfen, was Sie haben
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 — als Administrator ausführen
New-Item -ItemType Directory -Force -Path "C:\Program Files\Cert-IX"
Copy-Item ".\bitcollector-windows-amd64.exe" "C:\Program Files\Cert-IX\bitcollector.exe"

# Prüfen, was Sie haben
& "C:\Program Files\Cert-IX\bitcollector.exe" -version

Vor der Installation prüfen, nicht danach

Weisen Sie die Bytes im Release-Verzeichnis nach, bevor Sie sie auf einen Host kopieren: Eine Prüfsumme nach einer nicht vertrauenswürdigen Kopie belegt nur, dass das Kopieren geklappt hat. Maßgeblich ist die signierte SHA256SUMS aus dem Release; eine öffentliche checksums.txt zum Herunterladen gibt es nicht. Siehe Ihre Downloads verifizieren für die cosign- und Trust-Anchor-Prüfungen.

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/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

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"
    # ansible_architecture reports x86_64 / aarch64; release filenames use amd64 / arm64
    bitcollector_arch: "{{ 'arm64' if ansible_architecture == 'aarch64' else 'amd64' }}"
  tasks:
    # Legen Sie zuerst das GEPRÜFTE Release-Verzeichnis auf dem Control Node ab — es gibt
    # keine öffentliche Download-URL. Siehe „Ihre Downloads verifizieren“.
    - 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

Terraform-Beispiel (AWS EC2 User Data)

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

  user_data = <<-EOF
    #!/bin/bash
    # Es gibt keine öffentliche Download-URL. Liefern Sie die GEPRÜFTE Binärdatei selbst aus —
    # z. B. aus Ihrem eigenen privaten Artefakt-Store oder einem vorgefertigten AMI.
    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
}

---

Verwandt:

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