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

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

{cartography-0.114.0.dist-info → cartography-0.116.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cartography
-Version: 0.114.0
+Version: 0.116.0
 Summary: Explore assets and their relationships across your technical infrastructure.
 Maintainer: Cartography Contributors
 License-Expression: Apache-2.0
@@ -23,9 +23,11 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: backoff>=2.1.2
 Requires-Dist: boto3>=1.15.1
+Requires-Dist: aioboto3>=13.0.0
+Requires-Dist: httpx>=0.24.0
 Requires-Dist: botocore>=1.18.1
 Requires-Dist: dnspython>=1.15.0
-Requires-Dist: neo4j>=5.28.2
+Requires-Dist: neo4j<6.0.0,>=5.28.2
 Requires-Dist: policyuniverse>=1.1.0.0
 Requires-Dist: google-api-python-client>=1.7.8
 Requires-Dist: google-auth>=2.37.0
@@ -43,6 +45,7 @@ Requires-Dist: azure-mgmt-compute>=5.0.0
 Requires-Dist: azure-mgmt-resource>=10.2.0
 Requires-Dist: azure-mgmt-cosmosdb>=6.0.0
 Requires-Dist: azure-mgmt-web>=7.0.0
+Requires-Dist: azure-mgmt-logic>=10.0.0
 Requires-Dist: msrestazure>=0.6.4
 Requires-Dist: azure-mgmt-storage>=16.0.0
 Requires-Dist: azure-mgmt-sql<=1.0.0
@@ -57,6 +60,7 @@ Requires-Dist: duo-client
 Requires-Dist: cloudflare<5.0.0,>=4.1.0
 Requires-Dist: scaleway>=2.9.0
 Requires-Dist: google-cloud-resource-manager>=1.14.2
+Requires-Dist: typer>=0.9.0
 Dynamic: license-file
 
 ![Cartography](docs/root/images/logo-horizontal.png)
@@ -83,7 +87,7 @@ You can learn more about the story behind Cartography in our [presentation at BS
 
 ## Supported platforms
 - [Airbyte](https://cartography-cncf.github.io/cartography/modules/airbyte/index.html) - Organization, Workspace, User, Source, Destination, Connection, Tag, Stream
-- [Amazon Web Services](https://cartography-cncf.github.io/cartography/modules/aws/index.html) - ACM, API Gateway, CloudWatch, CodeBuild, Config, Cognito, EC2, ECS, ECR, EFS, Elasticsearch, Elastic Kubernetes Service (EKS), DynamoDB, Glue,  GuardDuty, IAM, Inspector, KMS, Lambda, RDS, Redshift, Route53, S3, Secrets Manager(Secret Versions), Security Hub, SNS, SQS, SSM, STS, Tags
+- [Amazon Web Services](https://cartography-cncf.github.io/cartography/modules/aws/index.html) - ACM, API Gateway, CloudWatch, CodeBuild, Config, Cognito, EC2, ECS, ECR (including image layers), EFS, Elasticsearch, Elastic Kubernetes Service (EKS), DynamoDB, Glue,  GuardDuty, IAM, Inspector, KMS, Lambda, RDS, Redshift, Route53, S3, Secrets Manager(Secret Versions), Security Hub, SNS, SQS, SSM, STS, Tags
 - [Anthropic](https://cartography-cncf.github.io/cartography/modules/anthropic/index.html) - Organization, ApiKey, User, Workspace
 - [BigFix](https://cartography-cncf.github.io/cartography/modules/bigfix/index.html) - Computers
 - [Cloudflare](https://cartography-cncf.github.io/cartography/modules/cloudflare/index.html) - Account, Role, Member, Zone, DNSRecord
@@ -97,7 +101,7 @@ You can learn more about the story behind Cartography in our [presentation at BS
 - [Keycloak](https://cartography-cncf.github.io/cartography/modules/keycloak/index.html) - Realms, Users, Groups, Roles, Scopes, Clients, IdentityProviders, Authentication Flows, Authentication Executions, Organizations, Organization Domains
 - [Kubernetes](https://cartography-cncf.github.io/cartography/modules/kubernetes/index.html) - Cluster, Namespace, Service, Pod, Container, ServiceAccount, Role, RoleBinding, ClusterRole, ClusterRoleBinding, OIDCProvider
 - [Lastpass](https://cartography-cncf.github.io/cartography/modules/lastpass/index.html) - users
-- [Microsoft Azure](https://cartography-cncf.github.io/cartography/modules/azure/index.html) - App Service, CosmosDB, Functions, SQL, Storage, Virtual Machine
+- [Microsoft Azure](https://cartography-cncf.github.io/cartography/modules/azure/index.html) - App Service, CosmosDB, Functions, Logic Apps, Resource Group, SQL, Storage, Virtual Machine
 - [Microsoft Entra ID](https://cartography-cncf.github.io/cartography/modules/entra/index.html) -  Users, Groups, Applications, OUs, App Roles, federation to AWS Identity Center
 - [NIST CVE](https://cartography-cncf.github.io/cartography/modules/cve/index.html) - Common Vulnerabilities and Exposures (CVE) data from NIST database
 - [Okta](https://cartography-cncf.github.io/cartography/modules/okta/index.html) - users, groups, organizations, roles, applications, factors, trusted origins, reply URIs, federation to AWS roles, federation to AWS Identity Center
@@ -144,6 +148,17 @@ When you are ready to try it in production, read [here](https://cartography-cncf
 
 ## Usage
 
+### Running rules
+
+You can check your environment against common security frameworks using the `cartography-rules` command.
+
+```bash
+cartography-rules run all
+```
+
+See [the rules docs](https://cartography-cncf.github.io/cartography/usage/rules.html) for more detail.
+
+
 ### Querying the database directly
 
 ![poweruser.png](docs/root/images/poweruser.png)