cartography 0.115.0__py3-none-any.whl → 0.116.1__py3-none-any.whl

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}"

cartography/rules/runners.py

@@ -0,0 +1,338 @@
+"""
+Framework and Fact execution logic for Cartography rules.
+"""
+
+import json
+from dataclasses import asdict
+
+from neo4j import Driver
+from neo4j import GraphDatabase
+
+from cartography.client.core.tx import read_list_of_dicts_tx
+from cartography.rules.data.frameworks import FRAMEWORKS
+from cartography.rules.formatters import _generate_neo4j_browser_url
+from cartography.rules.spec.model import Fact
+from cartography.rules.spec.model import Framework
+from cartography.rules.spec.model import Requirement
+from cartography.rules.spec.result import FactResult
+from cartography.rules.spec.result import FrameworkResult
+from cartography.rules.spec.result import RequirementResult
+
+
+def _run_fact(
+    fact: Fact,
+    requirement: Requirement,
+    framework: Framework,
+    driver: Driver,
+    database: str,
+    fact_counter: int,
+    total_facts: int,
+    output_format: str,
+    neo4j_uri: str,
+):
+    """Execute a single fact and return the result."""
+    if output_format == "text":
+        print(f"\n\033[1mFact {fact_counter}/{total_facts}: {fact.name}\033[0m")
+        print(f"  \033[36m{'Framework:':<12}\033[0m {framework.name}")
+        # Display requirement with optional clickable link
+        if requirement.requirement_url:
+            print(
+                f"  \033[36m{'Requirement:':<12}\033[0m \033]8;;{requirement.requirement_url}\033\\{requirement.id}\033]8;;\033\\ - {requirement.name}"
+            )
+        else:
+            print(
+                f"  \033[36m{'Requirement:':<12}\033[0m {requirement.id} - {requirement.name}"
+            )
+        print(f"  \033[36m{'Fact ID:':<12}\033[0m {fact.id}")
+        print(f"  \033[36m{'Description:':<12}\033[0m {fact.description}")
+        print(f"  \033[36m{'Provider:':<12}\033[0m {fact.module.value}")
+
+        # Generate and display clickable Neo4j Browser URL
+        browser_url = _generate_neo4j_browser_url(neo4j_uri, fact.cypher_visual_query)
+        print(
+            f"  \033[36m{'Neo4j Query:':<12}\033[0m \033]8;;{browser_url}\033\\Click to run visual query\033]8;;\033\\"
+        )
+
+    with driver.session(database=database) as session:
+        findings = session.execute_read(read_list_of_dicts_tx, fact.cypher_query)
+        finding_count = len(findings)
+
+    if output_format == "text":
+        if finding_count > 0:
+            print(f"  \033[36m{'Results:':<12}\033[0m {finding_count} item(s) found")
+
+            # Show sample findings
+            print("    Sample results:")
+            for idx, finding in enumerate(findings[:3]):  # Show first 3
+                # Format finding nicely
+                formatted_items = []
+                for key, value in finding.items():
+                    if value is not None:
+                        # Truncate long values
+                        str_value = str(value)
+                        if len(str_value) > 50:
+                            str_value = str_value[:47] + "..."
+                        formatted_items.append(f"{key}={str_value}")
+
+                if formatted_items:
+                    print(f"      {idx + 1}. {', '.join(formatted_items)}")
+
+            if finding_count > 3:
+                print(
+                    f"      ... and {finding_count - 3} more (use --output json to see all)"
+                )
+        else:
+            print(f"  \033[36m{'Results:':<12}\033[0m No items found")
+
+    # Create and return fact result
+    return FactResult(
+        fact_id=fact.id,
+        fact_name=fact.name,
+        fact_description=fact.description,
+        fact_provider=fact.module.value,
+        finding_count=finding_count,
+        findings=findings if output_format == "json" else findings[:10],
+    )
+
+
+def _run_single_requirement(
+    requirement: Requirement,
+    framework: Framework,
+    driver: Driver,
+    database: str,
+    output_format: str,
+    neo4j_uri: str,
+    fact_counter_start: int,
+    total_facts: int,
+    fact_filter: str | None = None,
+) -> tuple[RequirementResult, int]:
+    """
+    Execute a single requirement and return its result.
+
+    Returns:
+        A tuple of (RequirementResult, facts_executed_count)
+    """
+    # Filter facts if needed
+    facts_to_run = requirement.facts
+    if fact_filter:
+        facts_to_run = tuple(
+            f for f in requirement.facts if f.id.lower() == fact_filter.lower()
+        )
+
+    fact_results = []
+    requirement_findings = 0
+    fact_counter = fact_counter_start
+
+    for fact in facts_to_run:
+        fact_counter += 1
+        fact_result = _run_fact(
+            fact,
+            requirement,
+            framework,
+            driver,
+            database,
+            fact_counter,
+            total_facts,
+            output_format,
+            neo4j_uri,
+        )
+        fact_results.append(fact_result)
+        requirement_findings += fact_result.finding_count
+
+    # Create requirement result
+    requirement_result = RequirementResult(
+        requirement_id=requirement.id,
+        requirement_name=requirement.name,
+        requirement_url=requirement.requirement_url,
+        facts=fact_results,
+        total_facts=len(fact_results),
+        total_findings=requirement_findings,
+    )
+
+    return requirement_result, len(facts_to_run)
+
+
+def _run_single_framework(
+    framework_name: str,
+    driver: GraphDatabase.driver,
+    database: str,
+    output_format: str,
+    neo4j_uri: str,
+    requirement_filter: str | None = None,
+    fact_filter: str | None = None,
+) -> FrameworkResult:
+    """Execute a single framework and return results."""
+    framework = FRAMEWORKS[framework_name]
+
+    # Filter requirements if needed
+    requirements_to_run = framework.requirements
+    if requirement_filter:
+        requirements_to_run = tuple(
+            req
+            for req in framework.requirements
+            if req.id.lower() == requirement_filter.lower()
+        )
+
+    # Count total facts for display (before filtering)
+    total_facts_display = sum(len(req.facts) for req in requirements_to_run)
+
+    if output_format == "text":
+        print(f"Executing {framework.name} framework")
+        if requirement_filter:
+            print(f"Filtered to requirement: {requirement_filter}")
+            if fact_filter:
+                print(f"Filtered to fact: {fact_filter}")
+        print(f"Requirements: {len(requirements_to_run)}")
+        print(f"Total facts: {total_facts_display}")
+
+    # Execute requirements and collect results
+    total_findings = 0
+    total_facts_executed = 0
+    requirement_results = []
+    fact_counter = 0
+
+    for requirement in requirements_to_run:
+        requirement_result, facts_executed = _run_single_requirement(
+            requirement,
+            framework,
+            driver,
+            database,
+            output_format,
+            neo4j_uri,
+            fact_counter,
+            total_facts_display,
+            fact_filter,
+        )
+        requirement_results.append(requirement_result)
+        total_findings += requirement_result.total_findings
+        total_facts_executed += facts_executed
+        fact_counter += facts_executed
+
+    # Create and return framework result
+    return FrameworkResult(
+        framework_id=framework.id,
+        framework_name=framework.name,
+        framework_version=framework.version,
+        requirements=requirement_results,
+        total_requirements=len(requirements_to_run),
+        total_facts=total_facts_executed,  # Use actual executed count
+        total_findings=total_findings,
+    )
+
+
+def _format_and_output_results(
+    all_results: list[FrameworkResult],
+    framework_names: list[str],
+    output_format: str,
+    total_requirements: int,
+    total_facts: int,
+    total_findings: int,
+):
+    """Format and output the results of framework execution."""
+    if output_format == "json":
+        combined_output = [asdict(result) for result in all_results]
+        print(json.dumps(combined_output, indent=2))
+    else:
+        # Text summary
+        print("\n" + "=" * 60)
+        if len(framework_names) == 1:
+            print(f"EXECUTION SUMMARY - {FRAMEWORKS[framework_names[0]].name}")
+        else:
+            print("OVERALL SUMMARY")
+        print("=" * 60)
+
+        if len(framework_names) > 1:
+            print(f"Frameworks executed: {len(framework_names)}")
+        print(f"Requirements: {total_requirements}")
+        print(f"Total facts: {total_facts}")
+        print(f"Total results: {total_findings}")
+
+        if total_findings > 0:
+            print(
+                f"\n\033[36mFramework execution completed with {total_findings} total results\033[0m"
+            )
+        else:
+            print("\n\033[90mFramework execution completed with no results\033[0m")
+
+
+def run_frameworks(
+    framework_names: list[str],
+    uri: str,
+    neo4j_user: str,
+    neo4j_password: str,
+    neo4j_database: str,
+    output_format: str = "text",
+    requirement_filter: str | None = None,
+    fact_filter: str | None = None,
+):
+    """
+    Execute the specified frameworks and present results.
+
+    :param framework_names: The names of the frameworks to execute.
+    :param uri: The URI of the Neo4j database. E.g. "bolt://localhost:7687" or "neo4j+s://tenant123.databases.neo4j.io:7687"
+    :param neo4j_user: The username for the Neo4j database.
+    :param neo4j_password: The password for the Neo4j database.
+    :param neo4j_database: The name of the Neo4j database.
+    :param output_format: Either "text" or "json". Defaults to "text".
+    :param requirement_filter: Optional requirement ID to filter execution (case-insensitive).
+    :param fact_filter: Optional fact ID to filter execution (case-insensitive).
+    :return: The exit code.
+    """
+    # Validate all frameworks exist
+    for framework_name in framework_names:
+        if framework_name not in FRAMEWORKS:
+            if output_format == "text":
+                print(f"Unknown framework: {framework_name}")
+                print(f"Available frameworks: {', '.join(FRAMEWORKS.keys())}")
+            return 1
+
+    # Connect to Neo4j
+    if output_format == "text":
+        print(f"Connecting to Neo4j at {uri}...")
+    driver = GraphDatabase.driver(uri, auth=(neo4j_user, neo4j_password))
+
+    try:
+        driver.verify_connectivity()
+
+        # Execute frameworks
+        all_results = []
+        total_requirements = 0
+        total_facts = 0
+        total_findings = 0
+
+        for i, framework_name in enumerate(framework_names):
+            if output_format == "text" and len(framework_names) > 1:
+                if i > 0:
+                    print("\n" + "=" * 60)
+                print(
+                    f"Executing framework {i + 1}/{len(framework_names)}: {framework_name}"
+                )
+
+            framework_result = _run_single_framework(
+                framework_name,
+                driver,
+                neo4j_database,
+                output_format,
+                uri,
+                requirement_filter,
+                fact_filter,
+            )
+            all_results.append(framework_result)
+
+            total_requirements += framework_result.total_requirements
+            total_facts += framework_result.total_facts
+            total_findings += framework_result.total_findings
+
+        # Output results
+        _format_and_output_results(
+            all_results,
+            framework_names,
+            output_format,
+            total_requirements,
+            total_facts,
+            total_findings,
+        )
+
+        return 0
+    finally:
+        driver.close()

cartography/rules/spec/model.py

@@ -0,0 +1,88 @@
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+
+class Module(str, Enum):
+    """Services that can be monitored"""
+
+    AWS = "AWS"
+    """Amazon Web Services"""
+
+    AZURE = "Azure"
+    """Microsoft Azure"""
+
+    GCP = "GCP"
+    """Google Cloud Platform"""
+
+    GITHUB = "GitHub"
+    """GitHub source code management"""
+
+    OKTA = "Okta"
+    """Okta identity and access management"""
+
+    CROSS_CLOUD = "CROSS_CLOUD"
+    """Multi-cloud or provider-agnostic rules"""
+
+
+@dataclass(frozen=True)
+class Fact:
+    """A Fact gathers information about the environment using a Cypher query."""
+
+    id: str
+    """A descriptive identifier for the Fact. Should be globally unique within Cartography."""
+    name: str
+    """A descriptive name for the Fact."""
+    description: str
+    """More details about the Fact. Information on details that we're querying for."""
+    module: Module
+    """The Module that the Fact is associated with e.g. AWS, Azure, GCP, etc."""
+    # TODO can we lint the queries. full-on integ tests here are overkill though.
+    cypher_query: str
+    """The Cypher query to gather information about the environment. Returns data field by field e.g. `RETURN node.prop1, node.prop2`."""
+    cypher_visual_query: str
+    """
+    Same as `cypher_query`, returns it in a visual format for the web interface with `.. RETURN *`.
+    Often includes additional relationships to help give context.
+    """
+
+
+@dataclass(frozen=True)
+class Requirement:
+    """
+    A requirement within a security framework with one or more facts.
+
+    Notes:
+    - `attributes` is reserved for metadata such as tags, categories, or references.
+    - Do NOT put evaluation logic, thresholds, or org-specific preferences here.
+    """
+
+    id: str
+    name: str
+    description: str
+    facts: tuple[Fact, ...]
+    attributes: dict[str, Any] | None = None
+    """
+    Metadata attributes for the requirement. Example:
+    ```json
+    {
+        "tactic": "initial_access",
+        "technique_id": "T1190",
+        "services": ["ec2", "s3", "rds", "azure_storage"],
+        "providers": ["AWS", "AZURE"],
+    }
+    ```
+    """
+    requirement_url: str | None = None
+
+
+@dataclass(frozen=True)
+class Framework:
+    """A security framework containing requirements for comprehensive assessment."""
+
+    id: str
+    name: str
+    description: str
+    version: str
+    requirements: tuple[Requirement, ...]
+    source_url: str | None = None

cartography/rules/spec/result.py

@@ -0,0 +1,46 @@
+# Execution result classes
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class FactResult:
+    """
+    Results for a single Fact.
+    """
+
+    fact_id: str
+    fact_name: str
+    fact_description: str
+    fact_provider: str
+    finding_count: int = 0
+    findings: list[dict[str, Any]] | None = None
+
+
+@dataclass
+class RequirementResult:
+    """
+    Results for a single requirement, containing all its Facts.
+    """
+
+    requirement_id: str
+    requirement_name: str
+    requirement_url: str | None
+    facts: list[FactResult]
+    total_facts: int
+    total_findings: int
+
+
+@dataclass
+class FrameworkResult:
+    """
+    The formal object output by `--output json` from the `cartography-rules` CLI.
+    """
+
+    framework_id: str
+    framework_name: str
+    framework_version: str
+    requirements: list[RequirementResult]
+    total_requirements: int
+    total_facts: int
+    total_findings: int