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 — the agent's gateway and telemetry ingestion endpoints both live there
• The release directory for your platform, obtained through your Cert-IX account (see Get the agent binary)

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: Get the Agent Binary

There is no public download URL

The agent binaries are distributed through your Cert-IX account. There is no anonymous public download endpoint today, so treat any instruction to fetch one from a public host as out of date — ask your Cert-IX contact for the release directory for your platform.

Every release directory ships the binary, a CycloneDX SBOM, a cosign signature, a signed SHA256SUMS and the build provenance. Verify them before you run anything — those steps need no network access and apply to whatever directory you receive.

Once you have verified the release directory, install the binary for your platform. Run each command from inside that directory.

Linux (x86_64)

# From the verified release directory — see "Verifying your downloads"
install -m 0755 bitcollector-linux-amd64 /usr/local/bin/bitcollector

# Confirm what you have
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 — Run as Administrator
New-Item -ItemType Directory -Force -Path "C:\Program Files\Cert-IX"
Copy-Item ".\bitcollector-windows-amd64.exe" "C:\Program Files\Cert-IX\bitcollector.exe"

# Confirm what you have
& "C:\Program Files\Cert-IX\bitcollector.exe" -version

Verify before you install, not after

Prove the bytes in the release directory before you copy them onto a host — a checksum taken after an untrusted copy only tells you the copy succeeded. The signed SHA256SUMS that ships with the release is the reference; there is no public checksums.txt to fetch. See Verifying your downloads for the cosign and trust-anchor checks.

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

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"
    # ansible_architecture reports x86_64 / aarch64; release filenames use amd64 / arm64
    bitcollector_arch: "{{ 'arm64' if ansible_architecture == 'aarch64' else 'amd64' }}"
  tasks:
    # Stage the VERIFIED release directory on the control node first — there is no
    # public download URL to fetch from. See "Verifying your downloads".
    - 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 Example (AWS EC2 User Data)

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

  user_data = <<-EOF
    #!/bin/bash
    # There is no public download URL. Ship the VERIFIED binary yourself — e.g. from your
    # own private artifact store or a baked AMI. See "Verifying your downloads".
    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
}

---

Related:

• Scanner Agents Overview
• Agent Configuration Reference
• Devices