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

cartography/intel/azure/__init__.py

@@ -12,6 +12,7 @@ from . import compute
 from . import cosmosdb
 from . import functions
 from . import logic_apps
+from . import resource_groups
 from . import sql
 from . import storage
 from . import subscription
@@ -78,6 +79,13 @@ def _sync_one_subscription(
         update_tag,
         common_job_parameters,
     )
+    resource_groups.sync(
+        neo4j_session,
+        credentials,
+        subscription_id,
+        update_tag,
+        common_job_parameters,
+    )
 
 
 def _sync_tenant(

cartography/intel/azure/resource_groups.py

@@ -0,0 +1,82 @@
+import logging
+from typing import Any
+
+import neo4j
+from azure.core.exceptions import ClientAuthenticationError
+from azure.core.exceptions import HttpResponseError
+from azure.mgmt.resource import ResourceManagementClient
+
+from cartography.client.core.tx import load
+from cartography.graph.job import GraphJob
+from cartography.models.azure.resource_groups import AzureResourceGroupSchema
+from cartography.util import timeit
+
+from .util.credentials import Credentials
+
+logger = logging.getLogger(__name__)
+
+
+@timeit
+def get_resource_groups(credentials: Credentials, subscription_id: str) -> list[dict]:
+    try:
+        client = ResourceManagementClient(credentials.credential, subscription_id)
+        return [rg.as_dict() for rg in client.resource_groups.list()]
+    except (ClientAuthenticationError, HttpResponseError) as e:
+        logger.warning(
+            f"Failed to get Resource Groups for subscription {subscription_id}: {str(e)}"
+        )
+        return []
+
+
+@timeit
+def transform_resource_groups(resource_groups_response: list[dict]) -> list[dict]:
+    transformed_groups: list[dict[str, Any]] = []
+    for rg in resource_groups_response:
+        transformed_group = {
+            "id": rg.get("id"),
+            "name": rg.get("name"),
+            "location": rg.get("location"),
+            "provisioning_state": rg.get("properties", {}).get("provisioning_state"),
+        }
+        transformed_groups.append(transformed_group)
+    return transformed_groups
+
+
+@timeit
+def load_resource_groups(
+    neo4j_session: neo4j.Session,
+    data: list[dict[str, Any]],
+    subscription_id: str,
+    update_tag: int,
+) -> None:
+    load(
+        neo4j_session,
+        AzureResourceGroupSchema(),
+        data,
+        lastupdated=update_tag,
+        AZURE_SUBSCRIPTION_ID=subscription_id,
+    )
+
+
+@timeit
+def cleanup_resource_groups(
+    neo4j_session: neo4j.Session, common_job_parameters: dict
+) -> None:
+    GraphJob.from_node_schema(AzureResourceGroupSchema(), common_job_parameters).run(
+        neo4j_session
+    )
+
+
+@timeit
+def sync(
+    neo4j_session: neo4j.Session,
+    credentials: Credentials,
+    subscription_id: str,
+    update_tag: int,
+    common_job_parameters: dict,
+) -> None:
+    logger.info(f"Syncing Azure Resource Groups for subscription {subscription_id}.")
+    raw_groups = get_resource_groups(credentials, subscription_id)
+    transformed_groups = transform_resource_groups(raw_groups)
+    load_resource_groups(neo4j_session, transformed_groups, subscription_id, update_tag)
+    cleanup_resource_groups(neo4j_session, common_job_parameters)

cartography/models/aws/ecr/image.py

@@ -7,6 +7,7 @@ from cartography.models.core.relationships import CartographyRelProperties
 from cartography.models.core.relationships import CartographyRelSchema
 from cartography.models.core.relationships import LinkDirection
 from cartography.models.core.relationships import make_target_node_matcher
+from cartography.models.core.relationships import OtherRelationships
 from cartography.models.core.relationships import TargetNodeMatcher
 
 
@@ -16,6 +17,7 @@ class ECRImageNodeProperties(CartographyNodeProperties):
     digest: PropertyRef = PropertyRef("imageDigest")
     region: PropertyRef = PropertyRef("Region", set_in_kwargs=True)
     lastupdated: PropertyRef = PropertyRef("lastupdated", set_in_kwargs=True)
+    layer_diff_ids: PropertyRef = PropertyRef("layer_diff_ids")
 
 
 @dataclass(frozen=True)
@@ -34,8 +36,27 @@ class ECRImageToAWSAccountRel(CartographyRelSchema):
     properties: ECRImageToAWSAccountRelProperties = ECRImageToAWSAccountRelProperties()
 
 
+@dataclass(frozen=True)
+class ECRImageHasLayerRelProperties(CartographyRelProperties):
+    lastupdated: PropertyRef = PropertyRef("lastupdated", set_in_kwargs=True)
+
+
+@dataclass(frozen=True)
+class ECRImageHasLayerRel(CartographyRelSchema):
+    target_node_label: str = "ECRImageLayer"
+    target_node_matcher: TargetNodeMatcher = make_target_node_matcher(
+        {"diff_id": PropertyRef("layer_diff_ids", one_to_many=True)},
+    )
+    direction: LinkDirection = LinkDirection.OUTWARD
+    rel_label: str = "HAS_LAYER"
+    properties: ECRImageHasLayerRelProperties = ECRImageHasLayerRelProperties()
+
+
 @dataclass(frozen=True)
 class ECRImageSchema(CartographyNodeSchema):
     label: str = "ECRImage"
     properties: ECRImageNodeProperties = ECRImageNodeProperties()
     sub_resource_relationship: ECRImageToAWSAccountRel = ECRImageToAWSAccountRel()
+    other_relationships: OtherRelationships = OtherRelationships(
+        [ECRImageHasLayerRel()],
+    )

cartography/models/aws/ecr/image_layer.py

@@ -0,0 +1,107 @@
+from dataclasses import dataclass
+
+from cartography.models.core.common import PropertyRef
+from cartography.models.core.nodes import CartographyNodeProperties
+from cartography.models.core.nodes import CartographyNodeSchema
+from cartography.models.core.nodes import ExtraNodeLabels
+from cartography.models.core.relationships import CartographyRelProperties
+from cartography.models.core.relationships import CartographyRelSchema
+from cartography.models.core.relationships import LinkDirection
+from cartography.models.core.relationships import make_target_node_matcher
+from cartography.models.core.relationships import OtherRelationships
+from cartography.models.core.relationships import TargetNodeMatcher
+
+
+@dataclass(frozen=True)
+class ECRImageLayerNodeProperties(CartographyNodeProperties):
+    id: PropertyRef = PropertyRef("diff_id")
+    diff_id: PropertyRef = PropertyRef("diff_id")
+    lastupdated: PropertyRef = PropertyRef("lastupdated", set_in_kwargs=True)
+    is_empty: PropertyRef = PropertyRef("is_empty")
+
+
+@dataclass(frozen=True)
+class ECRImageLayerToAWSAccountRelProperties(CartographyRelProperties):
+    lastupdated: PropertyRef = PropertyRef("lastupdated", set_in_kwargs=True)
+
+
+@dataclass(frozen=True)
+class ECRImageLayerToAWSAccountRel(CartographyRelSchema):
+    target_node_label: str = "AWSAccount"
+    target_node_matcher: TargetNodeMatcher = make_target_node_matcher(
+        {"id": PropertyRef("AWS_ID", set_in_kwargs=True)}
+    )
+    direction: LinkDirection = LinkDirection.INWARD
+    rel_label: str = "RESOURCE"
+    properties: ECRImageLayerToAWSAccountRelProperties = (
+        ECRImageLayerToAWSAccountRelProperties()
+    )
+
+
+@dataclass(frozen=True)
+class ECRImageLayerToNextRelProperties(CartographyRelProperties):
+    lastupdated: PropertyRef = PropertyRef("lastupdated", set_in_kwargs=True)
+
+
+@dataclass(frozen=True)
+class ECRImageLayerToNextRel(CartographyRelSchema):
+    target_node_label: str = "ECRImageLayer"
+    target_node_matcher: TargetNodeMatcher = make_target_node_matcher(
+        {"diff_id": PropertyRef("next_diff_ids", one_to_many=True)}
+    )
+    direction: LinkDirection = LinkDirection.OUTWARD
+    rel_label: str = "NEXT"
+    properties: ECRImageLayerToNextRelProperties = ECRImageLayerToNextRelProperties()
+
+
+@dataclass(frozen=True)
+class ECRImageLayerHeadOfImageRelProperties(CartographyRelProperties):
+    lastupdated: PropertyRef = PropertyRef("lastupdated", set_in_kwargs=True)
+
+
+@dataclass(frozen=True)
+class ECRImageLayerHeadOfImageRel(CartographyRelSchema):
+    target_node_label: str = "ECRImage"
+    target_node_matcher: TargetNodeMatcher = make_target_node_matcher(
+        {"id": PropertyRef("head_image_ids", one_to_many=True)}
+    )
+    direction: LinkDirection = LinkDirection.INWARD
+    rel_label: str = "HEAD"
+    properties: ECRImageLayerHeadOfImageRelProperties = (
+        ECRImageLayerHeadOfImageRelProperties()
+    )
+
+
+@dataclass(frozen=True)
+class ECRImageLayerTailOfImageRelProperties(CartographyRelProperties):
+    lastupdated: PropertyRef = PropertyRef("lastupdated", set_in_kwargs=True)
+
+
+@dataclass(frozen=True)
+class ECRImageLayerTailOfImageRel(CartographyRelSchema):
+    target_node_label: str = "ECRImage"
+    target_node_matcher: TargetNodeMatcher = make_target_node_matcher(
+        {"id": PropertyRef("tail_image_ids", one_to_many=True)}
+    )
+    direction: LinkDirection = LinkDirection.INWARD
+    rel_label: str = "TAIL"
+    properties: ECRImageLayerTailOfImageRelProperties = (
+        ECRImageLayerTailOfImageRelProperties()
+    )
+
+
+@dataclass(frozen=True)
+class ECRImageLayerSchema(CartographyNodeSchema):
+    label: str = "ECRImageLayer"
+    properties: ECRImageLayerNodeProperties = ECRImageLayerNodeProperties()
+    sub_resource_relationship: ECRImageLayerToAWSAccountRel = (
+        ECRImageLayerToAWSAccountRel()
+    )
+    other_relationships: OtherRelationships = OtherRelationships(
+        [
+            ECRImageLayerToNextRel(),
+            ECRImageLayerHeadOfImageRel(),
+            ECRImageLayerTailOfImageRel(),
+        ]
+    )
+    extra_node_labels: ExtraNodeLabels = ExtraNodeLabels(["ImageLayer"])

cartography/models/azure/resource_groups.py

@@ -0,0 +1,52 @@
+import logging
+from dataclasses import dataclass
+
+from cartography.models.core.common import PropertyRef
+from cartography.models.core.nodes import CartographyNodeProperties
+from cartography.models.core.nodes import CartographyNodeSchema
+from cartography.models.core.relationships import CartographyRelProperties
+from cartography.models.core.relationships import CartographyRelSchema
+from cartography.models.core.relationships import LinkDirection
+from cartography.models.core.relationships import make_target_node_matcher
+from cartography.models.core.relationships import TargetNodeMatcher
+
+logger = logging.getLogger(__name__)
+
+
+# --- Node Definitions ---
+@dataclass(frozen=True)
+class AzureResourceGroupProperties(CartographyNodeProperties):
+    id: PropertyRef = PropertyRef("id")
+    name: PropertyRef = PropertyRef("name")
+    location: PropertyRef = PropertyRef("location")
+    provisioning_state: PropertyRef = PropertyRef("provisioning_state")
+    lastupdated: PropertyRef = PropertyRef("lastupdated", set_in_kwargs=True)
+
+
+# --- Relationship Definitions ---
+@dataclass(frozen=True)
+class AzureResourceGroupToSubscriptionRelProperties(CartographyRelProperties):
+    lastupdated: PropertyRef = PropertyRef("lastupdated", set_in_kwargs=True)
+
+
+@dataclass(frozen=True)
+class AzureResourceGroupToSubscriptionRel(CartographyRelSchema):
+    target_node_label: str = "AzureSubscription"
+    target_node_matcher: TargetNodeMatcher = make_target_node_matcher(
+        {"id": PropertyRef("AZURE_SUBSCRIPTION_ID", set_in_kwargs=True)},
+    )
+    direction: LinkDirection = LinkDirection.INWARD
+    rel_label: str = "RESOURCE"
+    properties: AzureResourceGroupToSubscriptionRelProperties = (
+        AzureResourceGroupToSubscriptionRelProperties()
+    )
+
+
+# --- Main Schema ---
+@dataclass(frozen=True)
+class AzureResourceGroupSchema(CartographyNodeSchema):
+    label: str = "AzureResourceGroup"
+    properties: AzureResourceGroupProperties = AzureResourceGroupProperties()
+    sub_resource_relationship: AzureResourceGroupToSubscriptionRel = (
+        AzureResourceGroupToSubscriptionRel()
+    )

cartography/rules/README.md

@@ -0,0 +1 @@
+See [the rules docs](https://cartography-cncf.github.io/cartography/usage/rules.html) for how Cartography develops and approaches security rules.

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/",
+)