cyntrisec 0.1.7__py3-none-any.whl

cyntrisec/core/__init__.py

@@ -0,0 +1,31 @@
+"""
+Core module - Pydantic models, graph, and path algorithms.
+
+No I/O dependencies. Pure data structures and algorithms.
+"""
+
+from cyntrisec.core.graph import AwsGraph, GraphBuilder
+from cyntrisec.core.paths import PathFinder, PathFinderConfig
+from cyntrisec.core.schema import (
+    Asset,
+    AttackPath,
+    Finding,
+    FindingSeverity,
+    Relationship,
+    Snapshot,
+    SnapshotStatus,
+)
+
+__all__ = [
+    "Asset",
+    "AttackPath",
+    "AwsGraph",
+    "Finding",
+    "FindingSeverity",
+    "GraphBuilder",
+    "PathFinder",
+    "PathFinderConfig",
+    "Relationship",
+    "Snapshot",
+    "SnapshotStatus",
+]

cyntrisec/core/business_config.py

@@ -0,0 +1,110 @@
+"""
+Business Configuration - Define legitimate business context.
+
+This module provides the schema for users to define what paths and assets
+are "Business Critical" or "Legitimate Exposure". This inputs into the
+graph engine to calculate the "Delta" (Attack Graph - Business Graph).
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class BaseConfig(BaseModel):
+    """Base configuration for business rules."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+        str_strip_whitespace=True,
+    )
+
+
+class CriticalFlow(BaseConfig):
+    """A required business flow between two assets."""
+
+    source: str = Field(..., description="Source asset ID or tag selector")
+    target: str = Field(..., description="Target asset ID or tag selector")
+    description: str | None = None
+    ports: list[int] | None = None
+
+
+class EntrypointCriteria(BaseConfig):
+    """Criteria for identifying legitimate entrypoints."""
+
+    by_id: list[str] = Field(default_factory=list)
+    by_tags: dict[str, str] = Field(default_factory=dict)
+    by_type: list[str] = Field(
+        default_factory=list,
+        description="Asset types considered safe entrypoints (e.g. 'cloudfront:distribution')",
+    )
+
+
+class BusinessConfig(BaseConfig):
+    """
+    Configuration for defining legitimate business context.
+
+    This allows the engine to distinguish between:
+    - Business Critical paths (must exist)
+    - Legitimate Exposure (accepted risk)
+    - Attack Paths (unnecessary exposure)
+    """
+
+    # Versioning for the config file format
+    version: Literal["1.0"] = "1.0"
+
+    # 1. Entrypoints: Where legitimate traffic enters
+    # Assets matching these criteria are considered "Authorized Exposure"
+    entrypoints: EntrypointCriteria = Field(default_factory=EntrypointCriteria)
+
+    # 2. Critical Flows: Traffic that MUST flow
+    # Explicitly authorized paths
+    critical_flows: list[CriticalFlow] = Field(default_factory=list)
+
+    # 3. Global Allowlist: Tags that mark assets as "Business Critical"
+    # Assets with these tags are considered "Authorized" even if exposed.
+    # e.g. {"Environment": "Production", "App": "Frontend"}
+    global_allowlist: dict[str, str] = Field(default_factory=dict)
+
+    @classmethod
+    def load(cls, path: str) -> BusinessConfig:
+        """Load configuration from a JSON or YAML file."""
+        import json
+        from pathlib import Path
+
+        path_obj = Path(path)
+        text = path_obj.read_text(encoding="utf-8")
+
+        data: object | None = None
+        suffix = path_obj.suffix.lower()
+
+        def parse_yaml() -> object | None:
+            import yaml
+
+            return yaml.safe_load(text)
+
+        def parse_json() -> object | None:
+            return json.loads(text)
+
+        try:
+            if suffix in {".yaml", ".yml"}:
+                data = parse_yaml()
+            elif suffix == ".json":
+                data = parse_json()
+            else:
+                # Default: YAML first (JSON is valid YAML), then JSON for clearer errors.
+                try:
+                    data = parse_yaml()
+                except Exception:
+                    data = parse_json()
+        except Exception as e:
+            raise ValueError(f"Failed to parse business config: {path}") from e
+
+        if data is None:
+            data = {}
+        if not isinstance(data, dict):
+            raise ValueError(f"Business config must be a mapping/object: {path}")
+
+        return cls(**data)

cyntrisec/core/business_logic.py

@@ -0,0 +1,131 @@
+"""
+Business Logic Engine - Apply business context to the capability graph.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import logging
+
+from cyntrisec.core.business_config import BusinessConfig
+from cyntrisec.core.graph import AwsGraph
+from cyntrisec.core.schema import Asset, AttackPath
+
+log = logging.getLogger(__name__)
+
+
+class BusinessLogicEngine:
+    """
+    Applies business rules to the graph to distinguish between:
+    - Business Critical (Must exist)
+    - Legitimate Exposure (Accepted risk)
+    - Unnecessary Exposure (Delta)
+    """
+
+    LABEL_BUSINESS = "business_required"
+    LABEL_ENTRYPOINT = "business_entrypoint"
+    LABEL_AUTHORIZED = "authorized"
+
+    def __init__(self, graph: AwsGraph, config: BusinessConfig | None):
+        self.graph = graph
+        self.config = config
+
+    def apply_labels(self) -> None:
+        """Apply business labels to assets and relationships."""
+        if not self.config:
+            return
+
+        log.info("Applying business labels to graph...")
+        count = 0
+
+        # 1. Label Entrypoints
+        for asset in self.graph.all_assets():
+            if self._is_entrypoint(asset):
+                asset.labels.add(self.LABEL_BUSINESS)
+                asset.labels.add(self.LABEL_ENTRYPOINT)
+                count += 1
+
+            # 2. Global Allowlist
+            if self._matches_allowlist(asset):
+                asset.labels.add(self.LABEL_BUSINESS)
+                asset.labels.add(self.LABEL_AUTHORIZED)
+                count += 1
+
+        # 3. Critical Flows
+        # TODO: Requires PathFinder to trace paths between source/target
+        # Will be implemented in Pathfinding Upgrades phase
+
+        log.info("Labeled %d assets as business-critical", count)
+
+    def compute_delta(self, attack_paths: list[AttackPath]) -> list[AttackPath]:
+        """
+        Compute the 'Delta' (Unnecessary Exposure).
+        
+        Returns only the AttackPaths that are NOT fully legitimate.
+        A path is legitimate if EVERY step is labeled 'business_required' or 'authorized'.
+        """
+        if not self.config:
+            # If no config, everything is potential exposure (or return all)
+            return attack_paths
+
+        delta_paths = []
+        for path in attack_paths:
+            if not self._is_path_legitimate(path):
+                delta_paths.append(path)
+
+        return delta_paths
+
+    def _is_entrypoint(self, asset: Asset) -> bool:
+        """Check if asset matches entrypoint criteria."""
+        criteria = self.config.entrypoints
+
+        # By ID
+        if asset.aws_resource_id in criteria.by_id or asset.id in criteria.by_id:
+            return True
+
+        # By Type
+        if asset.asset_type in criteria.by_type:
+            return True
+
+        # By Tags
+        for tag_key, tag_pattern in criteria.by_tags.items():
+            val = asset.tags.get(tag_key)
+            if val and fnmatch.fnmatch(val, tag_pattern):
+                return True
+
+        return False
+
+    def _matches_allowlist(self, asset: Asset) -> bool:
+        """Check if asset matches global allowlist tags."""
+        for tag_key, tag_pattern in self.config.global_allowlist.items():
+            val = asset.tags.get(tag_key)
+            if val and fnmatch.fnmatch(val, tag_pattern):
+                return True
+        return False
+
+    def _is_path_legitimate(self, path: AttackPath) -> bool:
+        """
+        Check if an attack path is fully justified by business rules.
+        
+        Strict mode: All assets and relationships must be labeled.
+        Relaxed mode: Just check if source and target are authorized? 
+        For now, we implement a check: access must be authorized.
+        """
+        # Optimized: Check if the *target* is authorized (e.g. "It's okay to access this DB")
+        # OR if the *source* is an authorized entrypoint AND the flow is business_required.
+
+        # For Phase 1, we'll check if the path consists of marked assets.
+        # Note: We need to check Edges too eventually.
+
+        for asset_id in path.path_asset_ids:
+            asset = self.graph.asset(asset_id)
+            if not asset: continue
+
+            # If any node in the chain is NOT business-required, the path is suspect.
+            # Exception: Maybe we allow traversal through unmarked nodes if the flow itself is marked?
+            # That requires Critical Flow labeling (Edge labeling).
+
+            if self.LABEL_BUSINESS not in asset.labels:
+                 return False
+
+        return True