Discovery Overview

Infracast's discovery system continuously maps your infrastructure — cloud accounts, on-premises networks, identity systems, and security devices — into a unified, queryable graph. This page explains how the discovery engine works under the hood and how to configure it.

What Is a Discovery Plugin?

A discovery plugin is a purpose-built collector for a specific platform or technology. Each plugin knows how to authenticate, query, and normalize data from its target into Infracast's common schema.

Plugins exist for:

Plugin	Target
aws	Amazon Web Services accounts
azure	Microsoft Azure subscriptions
gcp	Google Cloud Platform projects
cisco-ios	Cisco IOS/IOS-XE network devices
palo-alto	Palo Alto Networks firewalls (PAN-OS)
vmware-vsphere	VMware vCenter / ESXi
active-directory	Microsoft Active Directory / LDAP

How Plugins Work

gRPC Plugin Protocol

Infracast uses a gRPC-based plugin protocol. Each plugin runs as a sidecar process alongside the Infracast collector daemon and communicates over a local Unix socket or loopback TCP connection.

┌─────────────────────────────────────┐
│          Infracast Collector         │
│                                     │
│  ┌─────────────┐  gRPC   ┌───────┐  │
│  │  Scheduler  │◄───────►│Plugin │  │
│  └─────────────┘         └───┬───┘  │
│          │                   │      │
│  ┌───────▼──────┐            │      │
│  │  Graph Store │            │      │
│  └──────────────┘            │      │
└──────────────────────────────┼──────┘
                               │ API calls
                    ┌──────────▼──────────┐
                    │   Target Platform    │
                    │ (AWS/Azure/network)  │
                    └─────────────────────┘

The plugin protocol defines three RPC methods:

• Validate — Test credentials and connectivity before a full run
• Discover — Stream discovered resources back to the collector
• Diff — Return only changed resources since a given checkpoint (incremental updates)

Poll-Based Discovery

Most plugins operate in poll mode — they run on a configurable schedule, enumerate all resources in their scope, and compare results against the previous snapshot. Changes (additions, modifications, deletions) are written to the graph.

Some plugins also support event-driven mode where available (e.g., AWS CloudTrail + EventBridge), allowing near-real-time updates between scheduled polls.

Timeline:
  T=0    Full discovery run (baseline)
  T=15m  Poll: only changes since T=0
  T=30m  Poll: only changes since T=15m
  T=24h  Full discovery run (re-baseline)

info

Incremental polling reduces API call volume significantly. For large AWS accounts with thousands of resources, this can mean going from tens of thousands of API calls per run down to a few hundred.

Credential Management

Credentials for discovery plugins are stored encrypted in Infracast's credential vault. No plaintext secrets are written to disk.

Storing Credentials

Use the Infracast CLI to register credentials:

# AWS role-based credential
infracast creds add --plugin aws \
  --name "prod-account" \
  --type assume-role \
  --role-arn arn:aws:iam::123456789012:role/InfracastDiscovery \
  --external-id your-external-id

# Generic username/password
infracast creds add --plugin active-directory \
  --name "corp-ad" \
  --type ldap \
  --username "svc-infracast@corp.example.com" \
  --password-file /run/secrets/ad-password

# API key
infracast creds add --plugin palo-alto \
  --name "fw01" \
  --type api-key \
  --api-key-file /run/secrets/panos-apikey

Credential Rotation

Credentials can be rotated without downtime:

# Update an existing credential set
infracast creds update --name "prod-account" \
  --role-arn arn:aws:iam::123456789012:role/InfracastDiscovery-v2

# Verify the new credential works
infracast creds validate --name "prod-account"

warning

Infracast never logs credential values. If you see secrets in log output, check your logging configuration and rotate the affected credentials immediately.

Credential Scoping

Each credential is scoped to a specific plugin type. A credential registered for aws cannot be used by the azure plugin. This prevents cross-plugin credential leakage.

Scheduling Discovery Jobs

Discovery jobs are defined in infracast.yaml (or via the UI). Each job binds a plugin to a credential and a schedule.

Basic Job Configuration

discovery:
  jobs:
    - name: aws-production
      plugin: aws
      credential: prod-account
      schedule: "*/15 * * * *"   # every 15 minutes
      config:
        regions:
          - us-east-1
          - us-west-2
        account_id: "123456789012"

    - name: corp-active-directory
      plugin: active-directory
      credential: corp-ad
      schedule: "0 * * * *"      # every hour
      config:
        host: dc01.corp.example.com
        base_dn: "DC=corp,DC=example,DC=com"

Schedule Syntax

Infracast uses standard cron syntax (5-field, UTC):

Field	Allowed Values
Minute	0–59
Hour	0–23
Day of month	1–31
Month	1–12
Day of week	0–6 (Sunday = 0)

Common schedules:

Schedule	Cron Expression
Every 15 minutes	*/15 * * * *
Every hour	0 * * * *
Every 6 hours	0 */6 * * *
Daily at 2 AM UTC	0 2 * * *
Weekly on Sunday	0 0 * * 0

tip

For dynamic cloud environments (AWS, Azure, GCP), use a 15–30 minute interval. For slower-changing systems like Active Directory or vSphere, hourly or 6-hour intervals are usually sufficient.

Running a Job Manually

# Trigger an immediate run outside the schedule
infracast discovery run --job aws-production

# Run in dry-run mode (no writes to graph)
infracast discovery run --job aws-production --dry-run

# Run with verbose output
infracast discovery run --job aws-production --verbose

Viewing Job Status

# List all jobs and their last run status
infracast discovery jobs list

# Get details on a specific job
infracast discovery jobs status --name aws-production

# View recent job logs
infracast discovery jobs logs --name aws-production --tail 100

Resource Graph

All discovered resources flow into Infracast's resource graph — a property graph database where nodes represent resources and edges represent relationships between them.

Example relationships Infracast builds automatically:

• EC2 instance → belongs to → VPC subnet
• EC2 instance → attached to → Security Group
• EC2 instance → runs → AMI
• Lambda function → has permission → S3 bucket
• AD user → member of → AD group
• AD group → assigned to → GPO

These relationships power Infracast's attack path analysis, compliance mapping, and blast radius calculations.

Next Steps

Configure your first discovery plugin:

• AWS — Start here if you're cloud-first
• Azure — For Microsoft Azure environments
• GCP — For Google Cloud Platform
• Cisco IOS — For on-premises Cisco networks
• Palo Alto — For Palo Alto firewalls
• VMware vSphere — For virtualized infrastructure
• Active Directory — For identity and access mapping