Anthropic-Cybersecurity-Skills/skills/performing-cloud-asset-inventory-with-cartography/references/api-reference.md

API Reference: Cartography Cloud Asset Inventory

Libraries Used

Library	Purpose
neo4j	Neo4j Python driver for graph database queries
subprocess	Execute Cartography CLI sync commands
boto3	AWS SDK for supplementary asset lookups
json	Parse Cartography output and Neo4j results

Installation

# Cartography
pip install cartography

# Neo4j Python driver
pip install neo4j

# Neo4j server (Docker)
docker run -d --name neo4j \
    -p 7474:7474 -p 7687:7687 \
    -e NEO4J_AUTH=neo4j/changeme \
    neo4j:5

Authentication

Neo4j Connection

from neo4j import GraphDatabase
import os

NEO4J_URI = os.environ.get("NEO4J_URI", "bolt://localhost:7687")
NEO4J_USER = os.environ.get("NEO4J_USER", "neo4j")
NEO4J_PASS = os.environ["NEO4J_PASS"]

driver = GraphDatabase.driver(NEO4J_URI, auth=(NEO4J_USER, NEO4J_PASS))

AWS Credentials for Sync

# Cartography uses standard AWS credential chain
export AWS_PROFILE=security-audit
# Or: AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY

CLI Reference

Sync AWS Assets to Neo4j

cartography --neo4j-uri bolt://localhost:7687 \
    --neo4j-user neo4j \
    --neo4j-password-env-var NEO4J_PASS \
    --aws-sync-all-profiles

Sync Specific AWS Services

cartography --neo4j-uri bolt://localhost:7687 \
    --neo4j-user neo4j \
    --neo4j-password-env-var NEO4J_PASS \
    --aws-requested-syncs ec2:instances,iam:users,s3

Key CLI Flags

Flag	Description
--neo4j-uri	Neo4j Bolt URI
--neo4j-user	Neo4j username
--neo4j-password-env-var	Env var containing Neo4j password
--aws-sync-all-profiles	Sync all configured AWS profiles
--aws-requested-syncs	Sync specific AWS services
--gcp-requested-syncs	Sync specific GCP services
--azure-sync-all-subscriptions	Sync all Azure subscriptions
--statsd-enabled	Enable StatsD metrics
--update-tag	Custom tag for this sync run

Cypher Queries for Security Analysis

Find Public S3 Buckets

def find_public_s3_buckets(driver):
    query = """
    MATCH (s:S3Bucket)
    WHERE s.anonymous_access = true
    RETURN s.name AS bucket, s.region AS region, s.arn AS arn
    """
    with driver.session() as session:
        return [dict(r) for r in session.run(query)]

Find IAM Users Without MFA

def find_users_without_mfa(driver):
    query = """
    MATCH (u:AWSUser)
    WHERE NOT (u)-[:HAS_MFA_DEVICE]->(:MFADevice)
      AND u.password_enabled = true
    RETURN u.name AS username, u.arn AS arn,
           u.password_last_used AS last_login
    """
    with driver.session() as session:
        return [dict(r) for r in session.run(query)]

Find EC2 Instances with Public IPs and Permissive Security Groups

def find_exposed_instances(driver):
    query = """
    MATCH (i:EC2Instance)-[:MEMBER_OF_EC2_SECURITY_GROUP]->(sg:EC2SecurityGroup)
          -[:MEMBER_OF_IP_RULE]->(rule:IpRule)
    WHERE i.publicipaddress IS NOT NULL
      AND rule.cidr_ip = '0.0.0.0/0'
      AND rule.fromport <= 22
      AND rule.toport >= 22
    RETURN DISTINCT i.instanceid AS instance_id,
           i.publicipaddress AS public_ip,
           sg.name AS security_group
    """
    with driver.session() as session:
        return [dict(r) for r in session.run(query)]

Map Cross-Account IAM Trust Relationships

def find_cross_account_roles(driver):
    query = """
    MATCH (role:AWSRole)-[:TRUSTS_AWS_PRINCIPAL]->(principal:AWSPrincipal)
    WHERE principal.arn CONTAINS ':root'
      AND NOT principal.arn CONTAINS role.accountid
    RETURN role.arn AS role_arn,
           principal.arn AS trusted_principal,
           role.accountid AS role_account
    """
    with driver.session() as session:
        return [dict(r) for r in session.run(query)]

Find Unencrypted RDS Instances

def find_unencrypted_rds(driver):
    query = """
    MATCH (rds:RDSInstance)
    WHERE rds.storage_encrypted = false
    RETURN rds.db_instance_identifier AS db_name,
           rds.engine AS engine,
           rds.publicly_accessible AS public
    """
    with driver.session() as session:
        return [dict(r) for r in session.run(query)]

Cartography Node Types

Node Label	Represents
AWSAccount	AWS account
AWSUser	IAM user
AWSRole	IAM role
AWSPolicy	IAM policy
EC2Instance	EC2 instance
EC2SecurityGroup	Security group
S3Bucket	S3 bucket
RDSInstance	RDS database instance
LambdaFunction	Lambda function
EKSCluster	EKS Kubernetes cluster

Output Format

{
  "sync_time": "2025-01-15T10:30:00Z",
  "accounts_synced": 3,
  "nodes_created": 12450,
  "relationships_created": 34200,
  "findings": {
    "public_s3_buckets": 2,
    "users_without_mfa": 5,
    "exposed_instances": 3,
    "cross_account_trusts": 8,
    "unencrypted_databases": 4
  }
}