Skip to main content

Edges API

Edges represent relationships between nodes in Infracast's infrastructure graph. An edge between a security group and an EC2 instance means the instance is a member of that group. An edge between a load balancer and an instance means traffic routes from the LB to the instance. Edges are how Infracast understands network paths, trust relationships, and attack surface.

Endpoints​

MethodPathDescriptionPermission
GET/api/v1/tenants/{tenantID}/edgesList edgesnodes:read
POST/api/v1/tenants/{tenantID}/edgesCreate an edgejobs:create

List Edges​

GET /api/v1/tenants/{tenantID}/edges

Returns a paginated list of edges in the infrastructure graph.

Query Parameters​

ParameterTypeDescription
limitintNumber of results to return (default: 50, max: 500)
cursorstringPagination cursor from previous response
source_idstringFilter edges where source node ID matches
target_idstringFilter edges where target node ID matches
typestringFilter by edge type (e.g., MEMBER_OF)

Example Request​

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.infracast.io/api/v1/tenants/acme-corp/edges?limit=50"

Example Response​

{
  "items": [
    {
      "id": "edge-abc123",
      "tenant_id": "acme-corp",
      "source_id": "aws:us-east-1:aws.ec2.instance:i-0abc123def456789a",
      "target_id": "aws:us-east-1:aws.ec2.security_group:sg-0abc123",
      "type": "MEMBER_OF",
      "properties": {},
      "created_at": "2024-03-16T08:30:00Z"
    },
    {
      "id": "edge-def456",
      "tenant_id": "acme-corp",
      "source_id": "aws:us-east-1:aws.elbv2.load_balancer:arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/app/prod-alb/0abc123",
      "target_id": "aws:us-east-1:aws.ec2.instance:i-0abc123def456789a",
      "type": "ROUTES_TO",
      "properties": {
        "port": "443",
        "protocol": "HTTPS"
      },
      "created_at": "2024-03-16T08:30:00Z"
    },
    {
      "id": "edge-ghi789",
      "tenant_id": "acme-corp",
      "source_id": "aws:us-east-1:aws.ec2.instance:i-0abc123def456789a",
      "target_id": "aws:us-east-1:aws.rds.db_instance:prod-postgres",
      "type": "CONNECTS_TO",
      "properties": {
        "port": "5432",
        "protocol": "TCP"
      },
      "created_at": "2024-03-16T08:30:00Z"
    }
  ],
  "total": 18340,
  "limit": 50,
  "next_cursor": "eyJpZCI6ImVkZ2UtZ2hpNzg5In0="
}

Edge Types​

Infracast uses edge types to describe the nature of the relationship between two nodes:

Network & Traffic Edges​

Edge TypeDescriptionExample
ROUTES_TOTraffic is routed from source to targetALB → EC2 instance
CONNECTS_TOApplication-level connection (port/protocol)EC2 → RDS database
EXPOSESSource exposes target to a networkInternet Gateway → Public subnet
ALLOWS_TRAFFIC_FROMSource security rule permits traffic from targetSecurity group → CIDR range

Identity & Access Edges​

Edge TypeDescriptionExample
MEMBER_OFResource belongs to a group/clusterEC2 → Security group
ASSUMES_ROLEEntity can assume an IAM roleEC2 instance profile → IAM role
HAS_POLICYIAM entity has an attached policyIAM role → IAM policy
GRANTED_BYPermission is granted through this edgeIAM user → IAM group

Infrastructure Relationship Edges​

Edge TypeDescriptionExample
CONTAINSParent resource contains child resourceVPC → Subnet
DEPLOYED_INResource is deployed within a containerEC2 → Subnet
ATTACHED_TOResource is physically/logically attachedEBS volume → EC2 instance
MANAGED_BYResource is managed by another (e.g., auto scaling)EC2 → Auto Scaling Group
REPLICATES_TOData replication relationshipRDS primary → RDS replica
BACKED_UP_TOBackup destination relationshipRDS → S3 backup bucket

Kubernetes Edges​

Edge TypeDescriptionExample
RUNS_ONPod runs on a nodePod → K8s Node
EXPOSES_SERVICEDeployment exposes through a serviceDeployment → Service
BOUND_TORole binding relationshipServiceAccount → ClusterRole

Graph Traversal and Network Paths​

Edges are the foundation of Infracast's network path analysis. The Path Tracer uses edges to determine if a network path exists between any two nodes:

# Trace a network path
POST /api/v1/tenants/{tenantID}/pathtracer/trace
{
  "source_node_id": "aws:us-east-1:aws.ec2.instance:i-0abc123def456789a",
  "destination_cidr": "0.0.0.0/0",
  "port": 22,
  "protocol": "tcp"
}

Response shows the complete path (sequence of edges) from source to destination:

{
  "reachable": true,
  "path": [
    {
      "from": "aws:us-east-1:aws.ec2.instance:i-0abc123def456789a",
      "to": "aws:us-east-1:aws.ec2.security_group:sg-0abc123",
      "edge_type": "MEMBER_OF"
    },
    {
      "from": "aws:us-east-1:aws.ec2.security_group:sg-0abc123",
      "to": "0.0.0.0/0",
      "edge_type": "ALLOWS_TRAFFIC_FROM",
      "detail": "Inbound rule: port 22, protocol TCP, source 0.0.0.0/0"
    }
  ],
  "finding": "Instance is reachable from the internet on port 22 (SSH)"
}

This path finding capability is what makes compliance rules like CIS-AWS-5.2 (no SSH from internet) accurate — Infracast traces actual reachability, not just security group rules in isolation.

Graph Topology​

Beyond listing individual edges, you can retrieve the full graph topology for visualization:

# Clustered topology (grouped by VPC/region)
GET /api/v1/tenants/{tenantID}/graph/clustered

# Full topology (all nodes and edges)
GET /api/v1/tenants/{tenantID}/graph/full

# Lightweight topology summary for rendering
GET /api/v1/tenants/{tenantID}/graph/topology

Create an Edge (Manual)​

For resources not discovered automatically (e.g., on-premises systems connected via VPN), you can create edges manually:

POST /api/v1/tenants/{tenantID}/edges
{
  "source_id": "aws:us-east-1:aws.ec2.vpn_gateway:vgw-0abc123",
  "target_id": "on-prem:datacenter-east:network:10.200.0.0/16",
  "type": "CONNECTS_TO",
  "properties": {
    "protocol": "IPSec",
    "tunnel": "VPN"
  }
}

Pagination with Cursor​

The edges endpoint uses cursor-based pagination for efficient traversal of large graphs:

# First page
GET /api/v1/tenants/acme-corp/edges?limit=100

# Next page (use cursor from previous response)
GET /api/v1/tenants/acme-corp/edges?limit=100&cursor=eyJpZCI6ImVkZ2UtZ2hpNzg5In0=
tip

For full graph export, continue paginating until next_cursor is absent from the response. A tenant with 5,000 nodes typically has 15,000–25,000 edges.

Next Steps​