Guía de implementación de agentes

Esta guía le lleva paso a paso a través de la implementación de un agente de escaneo Cert-IX en su red privada. El agente se registrará automáticamente en la plataforma, comenzará a recopilar telemetría y hará visibles sus activos internos en el panel.

Requisitos previos

Antes de implementar un agente, asegúrese de tener:

• Una cuenta Cert-IX con una suscripción activa
• Su ID de inquilino (se encuentra en Configuración → Organización → ID de inquilino)
• Acceso root o de administrador en el host objetivo
• Acceso HTTPS saliente (puerto 443) a api.cert-ix.com: allí residen tanto la pasarela del agente como los puntos de ingesta de telemetría
• El directorio de publicación para su plataforma, obtenido a través de su cuenta Cert-IX (véase Obtener el binario del agente)

Implementación rápida

La forma más rápida de implementar es desde el panel: vaya a Gestión de activos → Dispositivos → haga clic en el botón verde Implementar agente. El asistente genera todos los comandos prellenados con su ID de inquilino.

Paso 1: Obtener el binario del agente

No existe ninguna URL de descarga pública

Los binarios de los agentes se distribuyen a través de su cuenta Cert-IX. Hoy no existe ningún punto de descarga público anónimo, así que considere obsoleta cualquier instrucción que le pida obtenerlos de un host público: pida a su contacto de Cert-IX el directorio de publicación correspondiente a su plataforma.

Cada directorio de publicación incluye el binario, un SBOM CycloneDX, una firma cosign, un SHA256SUMS firmado y la procedencia de compilación. Verifíquelos antes de ejecutar nada — esos pasos no requieren acceso a la red y se aplican a cualquier directorio que reciba.

Una vez verificado el directorio de publicación, instale el binario de su plataforma. Ejecute cada comando desde dentro de ese directorio.

Linux (x86_64)

# Desde el directorio de publicación verificado — véase «Verificar sus descargas»
install -m 0755 bitcollector-linux-amd64 /usr/local/bin/bitcollector

# Confirme lo que tiene
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 — ejecutar como administrador
New-Item -ItemType Directory -Force -Path "C:\Program Files\Cert-IX"
Copy-Item ".\bitcollector-windows-amd64.exe" "C:\Program Files\Cert-IX\bitcollector.exe"

# Confirme lo que tiene
& "C:\Program Files\Cert-IX\bitcollector.exe" -version

Verifique antes de instalar, no después

Demuestre la integridad de los bytes en el directorio de publicación antes de copiarlos a un host: un checksum calculado tras una copia no fiable solo indica que la copia funcionó. El SHA256SUMS firmado que acompaña a la publicación es la referencia; no hay ningún checksums.txt público que descargar. Consulte Verificar sus descargas para las comprobaciones de cosign y del ancla de confianza.

Paso 2: Crear el archivo de configuración

Cree el directorio de configuración del agente y el archivo.

Linux / macOS

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

Cree /etc/bitcollector/config.yaml con el siguiente contenido:

# 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

Cree C:\ProgramData\Cert-IX\bitcollector\config.yaml con el mismo contenido, ajustando las rutas:

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

Variables de entorno

También puede establecer la configuración mediante variables de entorno en lugar de editar el archivo YAML:

Variable	Descripción
CERTIX_TENANT_ID	Su ID de inquilino (obligatorio)
CERTIX_GATEWAY_URL	URL del Gateway de agentes
CERTIX_INGEST_URL	URL del Gateway de ingestión
CERTIX_TLS_CA_CERT	Ruta del certificado CA
CERTIX_TLS_CLIENT_CERT	Ruta del certificado del cliente
CERTIX_TLS_CLIENT_KEY	Ruta de la clave del cliente

Las variables de entorno tienen precedencia sobre los valores del archivo de configuración.

Paso 3: Ejecutar el agente

Opción A: Servicio systemd (recomendado para Linux)

Cree un usuario de servicio dedicado:

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

Cree el archivo de unidad systemd en /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

Habilite e inicie el servicio:

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

Opción B: Contenedor 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 sobre Docker

Los flags --pid=host y --net=host son necesarios para que el agente pueda ver los procesos del host y las conexiones de red. Sin ellos, el agente solo verá datos a nivel de contenedor.

Opción C: Manual / Primer plano

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

Opción D: Servicio de 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

Paso 4: Verificar la implementación

Verificar el estado del servicio

# 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

Qué buscar

En los registros del agente, debería ver estos mensajes en orden:

1. Agent identity loaded — El agente generó o cargó su par de claves ECDSA
2. Registering with control plane — Conectándose al servicio de Gateway de agentes
3. Agent registered successfully — Registro completado, token JWT recibido
4. Starting heartbeat loop — Latidos periódicos al gateway de ingestión
5. Collection cycle complete — Primeros datos de telemetría recopilados y enviados

Verificar en el panel

Dentro de los 60 segundos posteriores al registro exitoso:

1. Vaya a Gestión de activos → Dispositivos
2. El nuevo dispositivo debería aparecer con una insignia verde En línea
3. Haga clic en el dispositivo para ver los datos recopilados:
   • Información del sistema — SO, kernel, CPU, memoria, disco
   • Procesos — Procesos en ejecución con uso de recursos
   • Puertos — Puertos abiertos y servicios en escucha
   • Software — Paquetes instalados
   • Métricas — Gráficos en tiempo real de CPU, memoria, carga

Solución de problemas

El agente no inicia

Síntoma	Causa	Solución
permission denied	Binario no ejecutable	chmod +x /usr/local/bin/bitcollector
config file not found	Ruta de configuración incorrecta	Verifique que el flag -config coincida con la ubicación real del archivo
tenant_id is required	ID de inquilino faltante	Establezca la variable CERTIX_TENANT_ID o tenant_id en la configuración

El agente no se registra

Síntoma	Causa	Solución
connection refused	Firewall bloqueando salida	Permita HTTPS (443) hacia api.cert-ix.com
certificate verify failed	Proxy corporativo/MITM	Agregue el CA del proxy al almacén de confianza del sistema
401 Unauthorized	ID de inquilino inválido	Verifique el ID en Configuración → Organización
timeout	Fallo en la resolución DNS	Verifique que DNS resuelva api.cert-ix.com

Agente registrado pero sin datos

Síntoma	Causa	Solución
No se muestran procesos	Permisos insuficientes	Ejecute como root o con CAP_SYS_PTRACE
No se muestran puertos	Permisos insuficientes	Ejecute como root o con CAP_NET_ADMIN
Sin datos de red	Colector de red deshabilitado	Establezca collectors.network.enabled: true
Datos obsoletos	Recopilación no ejecutándose	Verifique los registros en busca de errores de recopilación

Mensajes de registro comunes

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

Desinstalación

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

precaución

Después de la desinstalación, el dispositivo aparecerá como Fuera de línea en el panel después del siguiente latido perdido (por defecto: 2 minutos). Puede eliminarlo manualmente de la lista de dispositivos.

Implementación de múltiples agentes

Para implementaciones a gran escala, use herramientas de gestión de configuración:

Ejemplo con 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:
    # Coloque primero el directorio de publicación VERIFICADO en el nodo de control: no
    # existe ninguna URL pública. Véase «Verificar sus descargas».
    - 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

Ejemplo con Terraform (AWS EC2 User Data)

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

  user_data = <<-EOF
    #!/bin/bash
    # No existe ninguna URL de descarga pública. Distribuya usted mismo el binario VERIFICADO,
    # p. ej. desde su propio almacén de artefactos privado o una AMI preconstruida.
    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
}

---

Relacionado:

• Descripción general de agentes de escaneo
• Referencia de configuración del agente
• Dispositivos