Agent Deployment Guide

This guide walks you through deploying a Cert-IX scanner agent on your private network. The agent will automatically register with the platform, begin collecting telemetry, and make your internal assets visible in the dashboard.

Prerequisites

Before deploying an agent, ensure you have:

• A Cert-IX account with an active subscription
• Your Tenant ID (found in Settings → Organization → Tenant ID)
• Root or administrator access on the target host
• Outbound HTTPS (port 443) access to api.cert-ix.com and downloads.cert-ix.com

Quick Deploy

The fastest way to deploy is from the dashboard: go to Asset Management → Devices → click the green Deploy Agent button. The wizard generates all commands pre-filled with your tenant ID.

Step 1: Download the Agent

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

Security

Always verify the SHA256 checksum after downloading. The expected checksums are published at https://downloads.cert-ix.com/checksums.txt and signed with the Cert-IX release key.

Step 2: Create the Configuration File

Create the agent configuration directory and file.

Linux / macOS

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

Create /etc/bitcollector/config.yaml with the following content:

# 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 with the same content, adjusting paths:

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

Environment Variables

You can also set configuration via environment variables instead of editing the YAML file:

Variable	Description
CERTIX_TENANT_ID	Your tenant ID (required)
CERTIX_GATEWAY_URL	Agent Gateway URL
CERTIX_INGEST_URL	Ingestion Gateway URL
CERTIX_TLS_CA_CERT	CA certificate path
CERTIX_TLS_CLIENT_CERT	Client certificate path
CERTIX_TLS_CLIENT_KEY	Client key path

Environment variables take precedence over config file values.

Step 3: Run the Agent

Option A: Systemd Service (Recommended for Linux)

Create a dedicated service user:

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

Create the systemd unit file at /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

Enable and start the service:

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 Note

The --pid=host and --net=host flags are required so the agent can see host processes and network connections. Without them, the agent will only see container-level data.

Option C: Manual / Foreground

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

Option D: Windows Service

# 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

Step 4: Verify Deployment

Check Service Status

# 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

What to Look For

In the agent logs, you should see these messages in order:

1. Agent identity loaded — The agent generated or loaded its ECDSA keypair
2. Registering with control plane — Connecting to the Agent Gateway Service
3. Agent registered successfully — Registration complete, JWT token received
4. Starting heartbeat loop — Periodic heartbeats to the ingestion gateway
5. Collection cycle complete — First telemetry data collected and sent

Check the Dashboard

Within 60 seconds of successful registration:

1. Go to Asset Management → Devices
2. The new device should appear with a green Online badge
3. Click the device to see collected data:
   • System Info — OS, kernel, CPU, memory, disk
   • Processes — Running processes with resource usage
   • Ports — Open ports and listening services
   • Software — Installed packages
   • Metrics — Real-time CPU, memory, load graphs

Troubleshooting

Agent Won't Start

Symptom	Cause	Fix
permission denied	Binary not executable	chmod +x /usr/local/bin/bitcollector
config file not found	Wrong config path	Check -config flag matches actual file location
tenant_id is required	Missing tenant ID	Set CERTIX_TENANT_ID env var or tenant_id in config

Agent Won't Register

Symptom	Cause	Fix
connection refused	Firewall blocking outbound	Allow HTTPS (443) to api.cert-ix.com
certificate verify failed	Corporate proxy/MITM	Add proxy CA to system trust store
401 Unauthorized	Invalid tenant ID	Verify tenant ID in Settings → Organization
timeout	DNS resolution failure	Check DNS resolves api.cert-ix.com

Agent Registered but No Data

Symptom	Cause	Fix
No processes shown	Insufficient permissions	Run as root or with CAP_SYS_PTRACE
No ports shown	Insufficient permissions	Run as root or with CAP_NET_ADMIN
No network data	Network collector disabled	Set collectors.network.enabled: true
Stale data	Collection not running	Check logs for collection errors

Common Log Messages

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

Uninstalling

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

After uninstalling, the device will show as Offline in the dashboard after the next missed heartbeat (default: 2 minutes). You can manually remove it from the device list.

Deploying Multiple Agents

For large-scale deployments, use configuration management tools:

Ansible Example

- 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 Example (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
}

---

Related:

• Scanner Agents Overview
• Agent Configuration Reference
• Devices