neighbors

Graph · From docs/MCP_TOOLS.md on GitHub

Category graph · sensitivity confidential · capabilities read_state · readOnly true, destructive false, idempotent true, openWorld false · outputSchema yes · timeout: layer default (300 s)

Breadth-first walk from one asset over the raw edges, up to depth hops. direction: "out" follows edges that start at the current node, "in" edges that end there, "both" either. Walking stops adding nodes after limit nodes and edges after 2 * limit edges, and truncated turns true. Links cloudg://assets/{ref}/neighbors (one hop, all edges).

Argument	Type	Default	Constraints	Description
ref	string	required	min length 1	Asset reference: internal id, ARN / cloud resource id, unique name, or unique ARN tail (e.g. 'function:api' or 'i-0abc').
direction	string	"both"	one of out, in, both	out = edges from the asset, in = edges to it.
edge_types	string[] or null	null		Only these EdgeType values, e.g. ['ASSUMES_ROLE','GRANTS_ACCESS'].
depth	integer	1	1..4	Hops to walk from the asset.
limit	integer	100	1..500	Node cap. The edge cap is twice this value.
dataset	string	""		Dataset name (see list_datasets). Empty = the active dataset.

Returns dataset, asset (brief of the start node), nodes (briefs of the nodes reached, start excluded), edges (edge briefs of every edge walked), node_count, edge_count, truncated.

Called with the arguments below, neighbors returned this structuredContent.

{"ref": "web-1"}

{
  "dataset": "sample",
  "asset": {
    "id": "web-1",
    "name": "web-1",
    "type": "EC2",
    "provider": "AWS",
    "region": "us-east-1",
    "account_id": "111111111111",
    "arn": "arn:aws:ec2:us-east-1:111111111111:instance/i-0web1",
    "internet_exposed": false,
    "open_findings": 1,
    "max_severity": "HIGH",
    "uri": "cloudg://assets/web-1"
  },
  "nodes": [
    {
      "id": "subnet-private",
      "name": "prod-private-a",
      "type": "SUBNET",
      "provider": "AWS",
      "region": "us-east-1",
      "account_id": "111111111111",
      "arn": "arn:aws:ec2:us-east-1:111111111111:subnet/subnet-0priv",
      "internet_exposed": false,
      "open_findings": 0,
      "max_severity": null,
      "uri": "cloudg://assets/subnet-private"
    },
    {
      "id": "sg-app",
      "name": "sg-app",
      "type": "SECURITY_GROUP",
      "provider": "AWS",
      "region": "us-east-1",
      "account_id": "111111111111",
      "arn": "arn:aws:ec2:us-east-1:111111111111:security-group/sg-0app",
      "internet_exposed": false,
      "open_findings": 0,
      "max_severity": null,
      "uri": "cloudg://assets/sg-app"
    },
    "... 3 more"
  ],
  "edges": [
    {
      "id": "e-priv-web1",
      "source": "subnet-private",
      "source_name": "prod-private-a",
      "target": "web-1",
      "target_name": "web-1",
      "edge_type": "CONTAINS",
      "relationship": null
    },
    {
      "id": "e-web1-sg",
      "source": "web-1",
      "source_name": "web-1",
      "target": "sg-app",
      "target_name": "sg-app",
      "edge_type": "ATTACHED_TO",
      "relationship": null
    },
    "... 3 more"
  ],
  "node_count": 5,
  "edge_count": 5,
  "truncated": false
}

The result also carried these resource links in content:

[
  {
    "type": "resource_link",
    "uri": "cloudg://assets/web-1/neighbors",
    "name": "neighbors",
    "mimeType": "application/json"
  }
]

What a Lambda can reach through its role, two hops out over identity edges:

Called with the arguments below, neighbors returned this structuredContent.

{
  "ref": "api-handler",
  "direction": "out",
  "edge_types": [
    "ASSUMES_ROLE",
    "GRANTS_ACCESS"
  ],
  "depth": 2
}

{
  "dataset": "sample",
  "asset": {
    "id": "api-handler",
    "name": "api-handler",
    "type": "LAMBDA_FUNCTION",
    "provider": "AWS",
    "region": "us-east-1",
    "account_id": "111111111111",
    "arn": "arn:aws:lambda:us-east-1:111111111111:function:api-handler",
    "internet_exposed": false,
    "open_findings": 1,
    "max_severity": "LOW",
    "uri": "cloudg://assets/api-handler"
  },
  "nodes": [
    {
      "id": "lambda-role",
      "name": "api-lambda-role",
      "type": "IAM_ROLE",
      "provider": "AWS",
      "region": "global",
      "account_id": "111111111111",
      "arn": "arn:aws:iam::111111111111:role/api-lambda-role",
      "internet_exposed": false,
      "open_findings": 0,
      "max_severity": null,
      "uri": "cloudg://assets/lambda-role"
    },
    {
      "id": "db-secret",
      "name": "orders-db-credentials",
      "type": "SECRET",
      "provider": "AWS",
      "region": "us-east-1",
      "account_id": "111111111111",
      "arn": "arn:aws:secretsmanager:us-east-1:111111111111:secret:orders-db-credentials-AbC",
      "internet_exposed": false,
      "open_findings": 0,
      "max_severity": null,
      "uri": "cloudg://assets/db-secret"
    }
  ],
  "edges": [
    {
      "id": "e-lambda-role",
      "source": "api-handler",
      "source_name": "api-handler",
      "target": "lambda-role",
      "target_name": "api-lambda-role",
      "edge_type": "ASSUMES_ROLE",
      "relationship": null
    },
    {
      "id": "e-lrole-secret",
      "source": "lambda-role",
      "source_name": "api-lambda-role",
      "target": "db-secret",
      "target_name": "orders-db-credentials",
      "edge_type": "GRANTS_ACCESS",
      "relationship": null
    }
  ],
  "node_count": 2,
  "edge_count": 2,
  "truncated": false
}

The internet node works as a start:

Called with the arguments below, neighbors returned this structuredContent.

{"ref": "internet", "direction": "out"}

{
  "dataset": "sample",
  "asset": {
    "id": "0.0.0.0/0",
    "name": "0.0.0.0/0",
    "type": "EXTERNAL",
    "external": true
  },
  "nodes": [
    {
      "id": "sg-web",
      "name": "sg-web",
      "type": "SECURITY_GROUP",
      "provider": "AWS",
      "region": "us-east-1",
      "account_id": "111111111111",
      "arn": "arn:aws:ec2:us-east-1:111111111111:security-group/sg-0web",
      "internet_exposed": false,
      "open_findings": 0,
      "max_severity": null,
      "uri": "cloudg://assets/sg-web"
    },
    {
      "id": "sg-admin",
      "name": "sg-admin",
      "type": "SECURITY_GROUP",
      "provider": "AWS",
      "region": "us-east-1",
      "account_id": "111111111111",
      "arn": "arn:aws:ec2:us-east-1:111111111111:security-group/sg-0admin",
      "internet_exposed": false,
      "open_findings": 1,
      "max_severity": "CRITICAL",
      "uri": "cloudg://assets/sg-admin"
    },
    "... 4 more"
  ],
  "edges": [
    {
      "id": "e-inet-sgweb",
      "source": "0.0.0.0/0",
      "source_name": "0.0.0.0/0",
      "target": "sg-web",
      "target_name": "sg-web",
      "edge_type": "SECURITY_GROUP_RULE",
      "relationship": null,
      "port_range": "80,443",
      "protocol": "TCP",
      "cidr": "0.0.0.0/0",
      "ports": [
        443,
        80
      ],
      "direction": "ingress"
    },
    {
      "id": "e-inet-sgadmin",
      "source": "0.0.0.0/0",
      "source_name": "0.0.0.0/0",
      "target": "sg-admin",
      "target_name": "sg-admin",
      "edge_type": "SECURITY_GROUP_RULE",
      "relationship": null,
      "port_range": "22",
      "protocol": "TCP",
      "cidr": "0.0.0.0/0",
      "ports": [
        22
      ],
      "direction": "ingress"
    },
    "... 4 more"
  ],
  "node_count": 7,
  "edge_count": 7,
  "truncated": false
}

The result also carried these resource links in content:

[
  {
    "type": "resource_link",
    "uri": "cloudg://assets/0.0.0.0%2F0/neighbors",
    "name": "neighbors",
    "mimeType": "application/json"
  }
]

Errors:

{
  "tool": "neighbors",
  "arguments": {
    "ref": "web-1",
    "depth": 9
  },
  "isError": true,
  "text": "Invalid arguments: depth: Input should be less than or equal to 4",
  "_meta": {
    "cloudg/error_code": -32602,
    "cloudg/error_data": [
      {
        "loc": "depth",
        "msg": "Input should be less than or equal to 4",
        "type": "less_than_equal"
      }
    ]
  }
}

Related: get_edges (search edges directly), subgraph_export (the same neighbourhood as a graph document), ontology_neighbourhood (semantic relations).