Skip to main content

Agent Operator Guide

This guide covers managing Infracast Agents from the web UI and API.

Accessing the Agents Page​

Navigate to Agents from the main navigation menu. This page displays all registered agents for your tenant.

Agent Status​

StatusIconMeaning
Online🟢Agent heartbeat received within last 90 seconds
Stale🟡No heartbeat in 90 seconds–10 minutes
Offline🔴No heartbeat in over 10 minutes

Generating Enrollment Tokens​

Before deploying agents, you need an enrollment token:

  1. Click Generate Token button
  2. Configure options:
    • Label: Descriptive name (e.g., "production-web-servers")
    • Expires in: Token validity period (1–168 hours)
    • Max uses: Limit number of registrations (or unlimited)
  3. Copy the generated token — it's shown only once
  4. Use the token in agent installation commands

Deploying Agents​

The Install Modal provides copy-paste commands for each platform:

Linux​

curl -fsSL https://get.infracast.io/agent | sudo bash -s -- \
  --server https://api.infracast.io \
  --token YOUR_TOKEN

Windows (PowerShell as Administrator)​

irm https://get.infracast.io/agent.ps1 | iex
Register-InfracastAgent -Server https://api.infracast.io -Token YOUR_TOKEN

macOS​

curl -fsSL https://get.infracast.io/agent | sudo bash -s -- \
  --server https://api.infracast.io \
  --token YOUR_TOKEN

Viewing Agent Reports​

Click any agent row to open the Report Drawer with tabs:

Software Tab​

Lists all discovered software packages:

  • Package name and version
  • Installation source (apt, yum, pip, brew, Windows Registry, etc.)
  • CVE alerts for vulnerable versions

Ports Tab​

Shows listening network ports:

  • Port number and protocol (TCP/UDP)
  • Bound address (0.0.0.0, 127.0.0.1, specific IP)
  • Associated process name and PID

Processes Tab​

Lists running processes:

  • Process name and PID
  • Running user
  • Command line
  • CPU and memory usage

Firewall Tab​

Displays firewall rules:

  • Chain (INPUT, OUTPUT, FORWARD)
  • Action (ACCEPT, DROP, REJECT)
  • Protocol and ports
  • Source/destination CIDRs

Connections Tab​

Shows active network connections:

  • Local and remote addresses
  • Connection state (ESTABLISHED, TIME_WAIT, etc.)
  • Associated process

Agent Actions​

Force Re-Scan​

Click the Scan button to trigger an immediate discovery scan. The agent will:

  1. Receive the command on next poll (within 30 seconds)
  2. Execute full discovery
  3. Submit new report

Revoke Token​

Click Revoke to immediately invalidate an agent's authentication token:

  • Agent will receive 401 on next API call
  • Agent must be re-registered with a new enrollment token
  • Use for: compromised hosts, decommissioned servers, security incidents

View in Asset Graph​

Click View Asset to jump to the host's node in the Topology view, showing:

  • Related infrastructure (VPC, subnet, security groups)
  • Compliance findings
  • Connected services

Bulk Operations​

Select multiple agents using checkboxes, then:

  • Bulk Scan: Trigger scan on all selected agents
  • Bulk Revoke: Revoke tokens for selected agents (requires confirmation)

Use the filter bar to narrow the agent list:

  • Status: Online, Stale, Offline
  • OS: Linux, Windows, macOS
  • Search: Hostname substring match

Auto-Refresh​

The Agents page auto-refreshes every 30 seconds to show current status. Disable with the Pause button if needed.

Integrations​

Vulnerability Findings​

When agents discover software with known CVEs, findings are automatically created and appear in:

  • Findings page with severity, CVE ID, and remediation steps
  • Host asset detail page under "Vulnerabilities" section
  • Compliance reports for relevant frameworks

Asset Graph Integration​

Agent-discovered data enriches existing cloud-discovered nodes:

  • EC2 instance in AWS → agent adds process/port/software data
  • On-prem server added manually → agent provides full visibility

Troubleshooting​

Agent Not Appearing​

  1. Check agent logs: journalctl -u infracast-agent (Linux)
  2. Verify enrollment token is valid and not expired
  3. Check network connectivity to Infracast server (outbound 443)
  4. Verify server URL is correct in agent config

Agent Shows Stale/Offline​

  1. Check if agent process is running: systemctl status infracast-agent
  2. Check agent logs for errors
  3. Verify no firewall blocking outbound HTTPS
  4. Check for certificate issues (if using mTLS)

Report Data Missing​

  1. Force a re-scan from the UI
  2. Check agent has sufficient permissions (some collectors need root)
  3. Review agent logs for collector errors

See Troubleshooting Guide for more details.