cartography 0.114.0__py3-none-any.whl → 0.116.0__py3-none-any.whl

cartography/rules/cli.py

@@ -0,0 +1,342 @@
+"""
+Cartography RunRules CLI
+
+Execute security frameworks and present facts about your environment.
+"""
+
+import builtins
+import logging
+import os
+from enum import Enum
+from typing import Generator
+
+import typer
+from typing_extensions import Annotated
+
+from cartography.rules.data.frameworks import FRAMEWORKS
+from cartography.rules.runners import run_frameworks
+from cartography.rules.spec.model import Fact
+from cartography.rules.spec.model import Requirement
+
+app = typer.Typer(
+    help="Execute Cartography security frameworks",
+    no_args_is_help=True,
+)
+
+
+class OutputFormat(str, Enum):
+    """Output format options."""
+
+    text = "text"
+    json = "json"
+
+
+def complete_frameworks(incomplete: str) -> Generator[str, None, None]:
+    """Autocomplete framework names."""
+    for name in FRAMEWORKS.keys():
+        if name.startswith(incomplete):
+            yield name
+
+
+def complete_frameworks_with_all(incomplete: str) -> Generator[str, None, None]:
+    """Autocomplete framework names plus 'all'."""
+    for name in builtins.list(FRAMEWORKS.keys()) + ["all"]:
+        if name.startswith(incomplete):
+            yield name
+
+
+def complete_requirements(
+    ctx: typer.Context, incomplete: str
+) -> Generator[str, None, None]:
+    """Autocomplete requirement IDs based on selected framework."""
+    framework = ctx.params.get("framework")
+    if not framework or framework not in FRAMEWORKS:
+        return
+
+    for req in FRAMEWORKS[framework].requirements:
+        if req.id.lower().startswith(incomplete.lower()):
+            yield req.id
+
+
+def complete_facts(ctx: typer.Context, incomplete: str) -> Generator[str, None, None]:
+    """Autocomplete fact IDs based on selected framework and requirement."""
+    framework = ctx.params.get("framework")
+    requirement_id = ctx.params.get("requirement")
+
+    if not framework or framework not in FRAMEWORKS:
+        return
+    if not requirement_id:
+        return
+
+    # Find the requirement
+    for req in FRAMEWORKS[framework].requirements:
+        if req.id.lower() == requirement_id.lower():
+            for fact in req.facts:
+                if fact.id.lower().startswith(incomplete.lower()):
+                    yield fact.id
+            break
+
+
+@app.command()  # type: ignore[misc]
+def list(
+    framework: Annotated[
+        str | None,
+        typer.Argument(
+            help="Framework name (e.g., mitre-attack)",
+            autocompletion=complete_frameworks,
+        ),
+    ] = None,
+    requirement: Annotated[
+        str | None,
+        typer.Argument(
+            help="Requirement ID (e.g., T1190)",
+            autocompletion=complete_requirements,
+        ),
+    ] = None,
+) -> None:
+    """
+    List available frameworks, requirements, and facts.
+
+    \b
+    Examples:
+        cartography-rules list
+        cartography-rules list mitre-attack
+        cartography-rules list mitre-attack T1190
+    """
+    # List all frameworks
+    if not framework:
+        typer.secho("\nAvailable Frameworks\n", bold=True)
+        for fw_name, fw in FRAMEWORKS.items():
+            typer.secho(f"{fw_name}", fg=typer.colors.CYAN)
+            typer.echo(f"  Name:         {fw.name}")
+            typer.echo(f"  Version:      {fw.version}")
+            typer.echo(f"  Requirements: {len(fw.requirements)}")
+            total_facts = sum(len(req.facts) for req in fw.requirements)
+            typer.echo(f"  Total Facts:  {total_facts}")
+            if fw.source_url:
+                typer.echo(f"  Source:       {fw.source_url}")
+            typer.echo()
+        return
+
+    # Validate framework
+    if framework not in FRAMEWORKS:
+        typer.secho(
+            f"Error: Unknown framework '{framework}'", fg=typer.colors.RED, err=True
+        )
+        typer.echo(f"Available: {', '.join(FRAMEWORKS.keys())}", err=True)
+        raise typer.Exit(1)
+
+    fw = FRAMEWORKS[framework]
+
+    # List all requirements in framework
+    if not requirement:
+        typer.secho(f"\n{fw.name}", bold=True)
+        typer.echo(f"Version: {fw.version}\n")
+        for r in fw.requirements:
+            typer.secho(f"{r.id}", fg=typer.colors.CYAN)
+            typer.echo(f"  Name:  {r.name}")
+            typer.echo(f"  Facts: {len(r.facts)}")
+            if r.requirement_url:
+                typer.echo(f"  URL:   {r.requirement_url}")
+            typer.echo()
+        return
+
+    # Find and list facts in requirement
+    req: Requirement | None = None
+    for r in fw.requirements:
+        if r.id.lower() == requirement.lower():
+            req = r
+            break
+
+    if not req:
+        typer.secho(
+            f"Error: Requirement '{requirement}' not found",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        typer.echo("\nAvailable requirements:", err=True)
+        for r in fw.requirements:
+            typer.echo(f"  {r.id}", err=True)
+        raise typer.Exit(1)
+
+    typer.secho(f"\n{req.name}\n", bold=True)
+    typer.echo(f"ID:  {req.id}")
+    if req.requirement_url:
+        typer.echo(f"URL: {req.requirement_url}")
+    typer.secho(f"\nFacts ({len(req.facts)})\n", bold=True)
+
+    for fact in req.facts:
+        typer.secho(f"{fact.id}", fg=typer.colors.CYAN)
+        typer.echo(f"  Name:        {fact.name}")
+        typer.echo(f"  Description: {fact.description}")
+        typer.echo(f"  Provider:    {fact.module.value}")
+        typer.echo()
+
+
+@app.command()  # type: ignore[misc]
+def run(
+    framework: Annotated[
+        str,
+        typer.Argument(
+            help="Framework to execute (or 'all' for all frameworks)",
+            autocompletion=complete_frameworks_with_all,
+        ),
+    ],
+    requirement: Annotated[
+        str | None,
+        typer.Argument(
+            help="Specific requirement ID to run",
+            autocompletion=complete_requirements,
+        ),
+    ] = None,
+    fact: Annotated[
+        str | None,
+        typer.Argument(
+            help="Specific fact ID to run",
+            autocompletion=complete_facts,
+        ),
+    ] = None,
+    uri: Annotated[
+        str,
+        typer.Option(help="Neo4j URI", envvar="NEO4J_URI"),
+    ] = "bolt://localhost:7687",
+    user: Annotated[
+        str,
+        typer.Option(help="Neo4j username", envvar="NEO4J_USER"),
+    ] = "neo4j",
+    database: Annotated[
+        str,
+        typer.Option(help="Neo4j database name", envvar="NEO4J_DATABASE"),
+    ] = "neo4j",
+    neo4j_password_env_var: Annotated[
+        str | None,
+        typer.Option(help="Environment variable containing Neo4j password"),
+    ] = None,
+    neo4j_password_prompt: Annotated[
+        bool,
+        typer.Option(help="Prompt for Neo4j password interactively"),
+    ] = False,
+    output: Annotated[
+        OutputFormat,
+        typer.Option(help="Output format"),
+    ] = OutputFormat.text,
+) -> None:
+    """
+    Execute a security framework.
+
+    \b
+    Examples:
+        cartography-rules run all
+        cartography-rules run mitre-attack
+        cartography-rules run mitre-attack T1190
+        cartography-rules run mitre-attack T1190 aws_rds_public_access
+    """
+    # Validate framework
+    valid_frameworks = builtins.list(FRAMEWORKS.keys()) + ["all"]
+    if framework not in valid_frameworks:
+        typer.secho(
+            f"Error: Unknown framework '{framework}'", fg=typer.colors.RED, err=True
+        )
+        typer.echo(f"Available: {', '.join(valid_frameworks)}", err=True)
+        raise typer.Exit(1)
+
+    # Validate fact requires requirement
+    if fact and not requirement:
+        typer.secho(
+            "Error: Cannot specify fact without requirement",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    # Validate filtering with 'all'
+    if framework == "all" and (requirement or fact):
+        typer.secho(
+            "Error: Cannot filter by requirement/fact when running all frameworks",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    # Validate requirement exists
+    if requirement and framework != "all":
+        fw = FRAMEWORKS[framework]
+        req: Requirement | None = None
+        for r in fw.requirements:
+            if r.id.lower() == requirement.lower():
+                req = r
+                break
+
+        if not req:
+            typer.secho(
+                f"Error: Requirement '{requirement}' not found",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            typer.echo("\nAvailable requirements:", err=True)
+            for r in fw.requirements:
+                typer.echo(f"  {r.id}", err=True)
+            raise typer.Exit(1)
+
+        # Validate fact exists
+        if fact:
+            fact_found: Fact | None = None
+            for f in req.facts:
+                if f.id.lower() == fact.lower():
+                    fact_found = f
+                    break
+
+            if not fact_found:
+                typer.secho(
+                    f"Error: Fact '{fact}' not found in requirement '{requirement}'",
+                    fg=typer.colors.RED,
+                    err=True,
+                )
+                typer.echo("\nAvailable facts:", err=True)
+                for f in req.facts:
+                    typer.echo(f"  {f.id}", err=True)
+                raise typer.Exit(1)
+
+    # Get password
+    password = None
+    if neo4j_password_prompt:
+        password = typer.prompt("Neo4j password", hide_input=True)
+    elif neo4j_password_env_var:
+        password = os.environ.get(neo4j_password_env_var)
+    else:
+        password = os.getenv("NEO4J_PASSWORD")
+        if not password:
+            password = typer.prompt("Neo4j password", hide_input=True)
+
+    # Determine frameworks to run
+    if framework == "all":
+        frameworks_to_run = builtins.list(FRAMEWORKS.keys())
+    else:
+        frameworks_to_run = [framework]
+
+    # Execute
+    try:
+        exit_code = run_frameworks(
+            frameworks_to_run,
+            uri,
+            user,
+            password,
+            database,
+            output.value,
+            requirement_filter=requirement,
+            fact_filter=fact,
+        )
+        raise typer.Exit(exit_code)
+    except KeyboardInterrupt:
+        raise typer.Exit(130)
+
+
+def main():
+    """Entrypoint for cartography-rules CLI."""
+    logging.basicConfig(level=logging.INFO)
+    logging.getLogger("neo4j").setLevel(logging.ERROR)
+    app()
+
+
+if __name__ == "__main__":
+    main()

cartography/rules/data/frameworks/__init__.py

@@ -0,0 +1,12 @@
+"""
+Framework Registry
+
+Central registry of all available security frameworks for Cartography Rules.
+"""
+
+from cartography.rules.data.frameworks.mitre_attack import mitre_attack_framework
+
+# Framework registry - all available frameworks
+FRAMEWORKS = {
+    "mitre-attack": mitre_attack_framework,
+}

cartography/rules/data/frameworks/mitre_attack/__init__.py

@@ -0,0 +1,14 @@
+# MITRE ATT&CK Framework
+from cartography.rules.data.frameworks.mitre_attack.requirements.t1190_exploit_public_facing_application import (
+    t1190,
+)
+from cartography.rules.spec.model import Framework
+
+mitre_attack_framework = Framework(
+    id="MITRE_ATTACK",
+    name="MITRE ATT&CK",
+    description="Comprehensive security assessment framework based on MITRE ATT&CK tactics and techniques",
+    version="1.0",
+    requirements=(t1190,),
+    source_url="https://attack.mitre.org/",
+)

cartography/rules/data/frameworks/mitre_attack/requirements/t1190_exploit_public_facing_application/__init__.py

@@ -0,0 +1,135 @@
+"""
+MITRE ATT&CK Framework
+Security framework based on MITRE ATT&CK tactics and techniques
+"""
+
+from cartography.rules.spec.model import Fact
+from cartography.rules.spec.model import Module
+from cartography.rules.spec.model import Requirement
+
+# AWS
+_aws_ec2_instance_internet_exposed = Fact(
+    id="aws_ec2_instance_internet_exposed",
+    name="Internet-Exposed EC2 Instances on Common Management Ports",
+    description=(
+        "EC2 instances exposed to the internet on ports 22, 3389, 3306, 5432, 6379, 9200, 27017"
+    ),
+    cypher_query="""
+    MATCH (a:AWSAccount)-[:RESOURCE]->(ec2:EC2Instance)-[:MEMBER_OF_EC2_SECURITY_GROUP]->(sg:EC2SecurityGroup)<-[:MEMBER_OF_EC2_SECURITY_GROUP]-(rule:IpPermissionInbound)
+    MATCH (rule)<-[:MEMBER_OF_IP_RULE]-(ip:IpRange{range:'0.0.0.0/0'})
+    WHERE rule.fromport IN [22, 3389, 3306, 5432, 6379, 9200, 27017]
+    RETURN a.name AS account, ec2.instanceid AS instance, rule.fromport AS port, sg.groupid AS sg order by account, instance, port, sg
+    """,
+    cypher_visual_query="""
+    MATCH p=(a:AWSAccount)-[:RESOURCE]->(ec2:EC2Instance)-[:MEMBER_OF_EC2_SECURITY_GROUP]->(sg:EC2SecurityGroup)<-[:MEMBER_OF_EC2_SECURITY_GROUP]-(rule:IpPermissionInbound)
+    MATCH p2=(rule)<-[:MEMBER_OF_IP_RULE]-(ip:IpRange{range:'0.0.0.0/0'})
+    WHERE rule.fromport IN [22, 3389, 3306, 5432, 6379, 9200, 27017]
+    RETURN *
+    """,
+    module=Module.AWS,
+)
+_aws_s3_public = Fact(
+    id="aws_s3_public",
+    name="Internet-Accessible S3 Storage Attack Surface",
+    description=("AWS S3 buckets accessible from the internet"),
+    cypher_query="""
+    MATCH (b:S3Bucket)
+    WHERE b.anonymous_access = true
+    OR (b.anonymous_actions IS NOT NULL AND size(b.anonymous_actions) > 0)
+    OR EXISTS {
+        MATCH (b)-[:POLICY_STATEMENT]->(stmt:S3PolicyStatement)
+        WHERE stmt.effect = 'Allow'
+        AND (stmt.principal = '*' OR stmt.principal CONTAINS 'AllUsers')
+    }
+    RETURN b.name AS bucket,
+        b.region AS region,
+        b.anonymous_access AS public_access,
+        b.anonymous_actions AS public_actions
+    """,
+    cypher_visual_query="""
+    MATCH (b:S3Bucket)
+    WHERE b.anonymous_access = true
+    OR (b.anonymous_actions IS NOT NULL AND size(b.anonymous_actions) > 0)
+    OR EXISTS {
+        MATCH (b)-[:POLICY_STATEMENT]->(stmt:S3PolicyStatement)
+        WHERE stmt.effect = 'Allow'
+        AND (stmt.principal = '*' OR stmt.principal CONTAINS 'AllUsers')
+    }
+    WITH b
+    OPTIONAL MATCH p=(b)-[:POLICY_STATEMENT]->(:S3PolicyStatement)
+    RETURN *
+    """,
+    module=Module.AWS,
+)
+_aws_rds_public_access = Fact(
+    id="aws_rds_public_access",
+    name="Internet-Accessible RDS Database Attack Surface",
+    description="AWS RDS instances accessible from the internet",
+    cypher_query="""
+    MATCH (rds:RDSInstance)
+    WHERE rds.publicly_accessible = true
+    RETURN rds.id AS instance_id,
+        rds.engine AS engine,
+        rds.db_instance_class AS instance_class,
+        rds.endpoint_address AS endpoint,
+        rds.endpoint_port AS port,
+        rds.region AS region,
+        rds.storage_encrypted AS encrypted
+    """,
+    cypher_visual_query="""
+    MATCH p1=(rds:RDSInstance{publicly_accessible: true})
+    OPTIONAL MATCH p2=(rds)-[:MEMBER_OF_EC2_SECURITY_GROUP]->(sg:EC2SecurityGroup)
+    OPTIONAL MATCH p3=(rds)-[:MEMBER_OF_EC2_SECURITY_GROUP]->(sg:EC2SecurityGroup)<-[:MEMBER_OF_EC2_SECURITY_GROUP]-(rule:IpPermissionInbound:IpRule)
+    OPTIONAL MATCH p4=(rds)-[:MEMBER_OF_EC2_SECURITY_GROUP]->(sg:EC2SecurityGroup)<-[:MEMBER_OF_EC2_SECURITY_GROUP]-(rule:IpPermissionInbound:IpRule)<-[:MEMBER_OF_IP_RULE]-(ip:IpRange)
+    RETURN *
+    """,
+    module=Module.AWS,
+)
+
+# Azure
+_azure_storage_public_blob_access = Fact(
+    id="azure_storage_public_blob_access",
+    name="Azure Storage Accounts with Public Blob Containers",
+    description=(
+        "Azure Storage Accounts that have blob containers with public access. "
+        "If a storage blob container has public_access set to 'Container' or 'Blob', "
+        "it means that the container is publicly accessible."
+    ),
+    cypher_query="""
+    MATCH (sa:AzureStorageAccount)-[:USES]->(bs:AzureStorageBlobService)-[:CONTAINS]->(bc:AzureStorageBlobContainer)
+    WHERE bc.publicaccess IN ['Container', 'Blob']
+    RETURN sa.name AS storage_account,
+        sa.resourcegroup AS resource_group,
+        sa.location AS location,
+        bc.name AS container_name,
+        bc.publicaccess AS public_access
+    """,
+    cypher_visual_query="""
+    MATCH p=(sa:AzureStorageAccount)-[:USES]->(bs:AzureStorageBlobService)-[:CONTAINS]->(bc:AzureStorageBlobContainer)
+    WHERE bc.publicaccess IN ['Container', 'Blob']
+    RETURN *
+    """,
+    module=Module.AZURE,
+)
+
+t1190 = Requirement(
+    id="t1190",
+    name="Exploit Public-Facing Application",
+    description="Adversaries may attempt to take advantage of a weakness in an Internet-facing computer or program using software, data, or commands in order to cause unintended or unanticipated behavior.",
+    facts=(
+        # AWS
+        _aws_ec2_instance_internet_exposed,
+        _aws_s3_public,
+        _aws_rds_public_access,
+        # Azure
+        _azure_storage_public_blob_access,
+    ),
+    requirement_url="https://attack.mitre.org/techniques/T1190/",
+    # TODO: should we have a per-framework class represent the attributes?
+    attributes={
+        "tactic": "initial_access",
+        "technique_id": "T1190",
+        "services": ["ec2", "s3", "rds", "azure_storage"],
+        "providers": ["AWS", "AZURE"],
+    },
+)

cartography/rules/formatters.py

@@ -0,0 +1,46 @@
+"""
+Output formatting utilities for Cartography rules.
+"""
+
+import re
+from urllib.parse import quote
+
+
+def _generate_neo4j_browser_url(neo4j_uri: str, cypher_query: str) -> str:
+    """Generate a clickable Neo4j Browser URL with pre-populated query."""
+    # Handle different Neo4j URI protocols
+    if neo4j_uri.startswith("bolt://"):
+        browser_uri = neo4j_uri.replace("bolt://", "http://", 1)
+    elif neo4j_uri.startswith("bolt+s://"):
+        browser_uri = neo4j_uri.replace("bolt+s://", "https://", 1)
+    elif neo4j_uri.startswith("bolt+ssc://"):
+        browser_uri = neo4j_uri.replace("bolt+ssc://", "https://", 1)
+    elif neo4j_uri.startswith("neo4j://"):
+        browser_uri = neo4j_uri.replace("neo4j://", "http://", 1)
+    elif neo4j_uri.startswith("neo4j+s://"):
+        browser_uri = neo4j_uri.replace("neo4j+s://", "https://", 1)
+    elif neo4j_uri.startswith("neo4j+ssc://"):
+        browser_uri = neo4j_uri.replace("neo4j+ssc://", "https://", 1)
+    else:
+        browser_uri = neo4j_uri
+
+    # Handle port mapping for local instances
+    if ":7687" in browser_uri and (
+        "localhost" in browser_uri or "127.0.0.1" in browser_uri
+    ):
+        browser_uri = browser_uri.replace(":7687", ":7474")
+
+    # For Neo4j Aura (cloud), remove the port as it uses standard HTTPS port
+    if ".databases.neo4j.io" in browser_uri:
+        # Remove any port number for Aura URLs
+        browser_uri = re.sub(r":\d+", "", browser_uri)
+
+    # Ensure the URL ends properly
+    if not browser_uri.endswith("/"):
+        browser_uri += "/"
+
+    # URL encode the cypher query
+    encoded_query = quote(cypher_query.strip())
+
+    # Construct the Neo4j Browser URL with pre-populated query
+    return f"{browser_uri}browser/?cmd=edit&arg={encoded_query}"