cyntrisec 0.1.7__py3-none-any.whl

cyntrisec/core/schema.py

@@ -0,0 +1,317 @@
+"""
+Core Schema - Pydantic models for the capability graph.
+
+Simplified from the SaaS version:
+- No tenant_id, workspace_id, connection_id (single-account CLI)
+- No SQLAlchemy relationship hints
+- Added monthly_cost_usd for cost analysis
+- Added proof field for evidence chains
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from decimal import Decimal
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+INTERNET_ASSET_ID = uuid.UUID("00000000-0000-0000-0000-000000000001")
+
+
+class SnapshotStatus(str, Enum):
+    """Status of a scan snapshot."""
+
+    running = "running"
+    completed = "completed"
+    completed_with_errors = "completed_with_errors"
+    failed = "failed"
+
+
+class FindingSeverity(str, Enum):
+    """Severity level for security findings."""
+
+    critical = "critical"
+    high = "high"
+    medium = "medium"
+    low = "low"
+    info = "info"
+
+
+class EdgeKind(str, Enum):
+    """Classification of relationship edges.
+    
+    - STRUCTURAL: Context only (CONTAINS, USES) - not traversed during attack path discovery
+    - CAPABILITY: Attacker movement (CAN_ASSUME, MAY_*) - traversed during attack path discovery
+    - UNKNOWN: Unclassified - not traversed by default
+    """
+
+    STRUCTURAL = "structural"
+    CAPABILITY = "capability"
+    UNKNOWN = "unknown"
+
+
+class ConditionResult(str, Enum):
+    """Tri-state result for IAM condition evaluation.
+    
+    - TRUE: Condition satisfied
+    - FALSE: Condition not satisfied
+    - UNKNOWN: Cannot evaluate locally
+    """
+
+    TRUE = "true"
+    FALSE = "false"
+    UNKNOWN = "unknown"
+
+
+class ConfidenceLevel(str, Enum):
+    """Confidence that an attack path is exploitable.
+    
+    - HIGH: All preconditions verified
+    - MED: Some conditions unknown or explicit deny detected
+    - LOW: Missing motif components or many unknowns
+    """
+
+    HIGH = "high"
+    MED = "med"
+    LOW = "low"
+
+
+class BaseSchema(BaseModel):
+    """Base configuration for all models."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+        use_enum_values=True,
+        str_strip_whitespace=True,
+    )
+
+
+class EdgeEvidence(BaseSchema):
+    """Provenance data explaining why an edge exists.
+    
+    Every capability edge should include evidence explaining why it exists,
+    so that security analysts can verify and understand attack paths.
+    """
+
+    policy_sid: str | None = None
+    policy_arn: str | None = None
+    rule_id: str | None = None
+    source_arn: str | None = None
+    target_arn: str | None = None
+    permission: str | None = None
+    raw_statement: dict[str, Any] | None = None
+
+
+class Snapshot(BaseSchema):
+    """
+    A snapshot represents a single scan run.
+
+    Contains metadata about the scan including timing,
+    status, and aggregate counts.
+    """
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4)
+    aws_account_id: str = Field(..., min_length=12, max_length=12)
+    regions: list[str]
+    status: SnapshotStatus = SnapshotStatus.running
+    started_at: datetime = Field(default_factory=datetime.utcnow)
+    completed_at: datetime | None = None
+
+    # Counts
+    asset_count: int = 0
+    relationship_count: int = 0
+    finding_count: int = 0
+    path_count: int = 0
+
+    # Metadata
+    scan_params: dict[str, Any] = Field(default_factory=dict)
+    error: str | None = None
+    errors: list[dict[str, Any]] | None = None
+
+
+class Asset(BaseSchema):
+    """
+    An asset represents a node in the capability graph.
+
+    Assets include:
+    - AWS resources (EC2, IAM roles, S3 buckets, Lambda, RDS, etc.)
+    - Logical groupings (VPCs, subnets, security groups)
+    """
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4)
+    snapshot_id: uuid.UUID
+
+    # Identity
+    asset_type: str = Field(..., min_length=1, max_length=50)
+    aws_region: str | None = None
+    aws_resource_id: str = Field(..., min_length=1, max_length=255)
+    arn: str | None = None
+    name: str = Field(..., min_length=1, max_length=500)
+
+    # Properties and tags
+    properties: dict[str, Any] = Field(default_factory=dict)
+    tags: dict[str, str] = Field(default_factory=dict)
+    labels: set[str] = Field(default_factory=set)
+
+    # Cost analysis
+    monthly_cost_usd: Decimal | None = None
+
+    # Flags for analysis
+    is_internet_facing: bool = False
+    is_sensitive_target: bool = False
+
+
+class Relationship(BaseSchema):
+    """
+    A relationship represents an edge in the capability graph.
+
+    Relationship types:
+    - TRUSTS: IAM trust relationships
+    - ALLOWS: Security group rules, NACLs, IAM policies
+    - ROUTES_TO: Route table entries, LB targets
+    - ATTACHED_TO: ENIs, EBS volumes, instance profiles
+    - CONTAINS: VPC → Subnet, Subnet → Instance
+    
+    Edge kinds:
+    - STRUCTURAL: Context only (CONTAINS, USES) - not traversed during attack path discovery
+    - CAPABILITY: Attacker movement (CAN_ASSUME, MAY_*) - traversed during attack path discovery
+    - UNKNOWN: Unclassified - not traversed by default
+    """
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4)
+    snapshot_id: uuid.UUID
+
+    source_asset_id: uuid.UUID
+    target_asset_id: uuid.UUID
+    relationship_type: str = Field(..., min_length=1, max_length=50)
+
+    # Edge classification
+    edge_kind: EdgeKind = EdgeKind.UNKNOWN
+
+    # Edge properties (ports, protocols, conditions)
+    properties: dict[str, Any] = Field(default_factory=dict)
+    labels: set[str] = Field(default_factory=set)
+
+    # Evidence for capability edges
+    evidence: EdgeEvidence | None = None
+
+    # Condition evaluation result
+    conditions_evaluated: bool = True
+    condition_result: ConditionResult = ConditionResult.TRUE
+
+    # For attack path analysis
+    traversal_cost: float = 1.0  # Lower = easier to traverse
+
+    # Edge weight for scoring
+    edge_weight: float = 1.0
+
+
+class Finding(BaseSchema):
+    """
+    A security finding discovered during scanning.
+
+    Findings include:
+    - Misconfigurations (public S3, overly permissive IAM)
+    - Security risks (missing encryption, weak TLS)
+    - Attack surface exposure (internet-facing without WAF)
+    """
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4)
+    snapshot_id: uuid.UUID
+    asset_id: uuid.UUID
+
+    finding_type: str = Field(..., min_length=1, max_length=100)
+    severity: FindingSeverity
+    title: str = Field(..., min_length=1, max_length=500)
+    description: str | None = None
+    remediation: str | None = None
+
+    # Evidence for proof-carrying output
+    evidence: dict[str, Any] = Field(default_factory=dict)
+
+
+class AttackPath(BaseSchema):
+    """
+    An attack path from an entry point to a sensitive target.
+
+    Attack paths represent traversable routes through the graph
+    that could be exploited by an attacker.
+
+    Risk scoring:
+    - entry_confidence: How likely an attacker can reach entry (0-1)
+    - exploitability: Difficulty of traversing the path (higher = easier)
+    - impact: Value of the target (higher = more valuable)
+    - risk_score: Combined score (entry * exploit * impact)
+    
+    Path structure:
+    - attack_chain_relationship_ids: Capability edges only (attack steps)
+    - context_relationship_ids: Structural edges for explanation
+    - path_relationship_ids: Legacy alias for backward compatibility
+    """
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4)
+    snapshot_id: uuid.UUID
+
+    # Path endpoints
+    source_asset_id: uuid.UUID  # Entry point (internet-facing)
+    target_asset_id: uuid.UUID  # Sensitive target
+
+    # Full path
+    path_asset_ids: list[uuid.UUID] = Field(..., min_length=2)
+    path_relationship_ids: list[uuid.UUID] = Field(..., min_length=1)
+
+    # Capability edges only (attack steps)
+    attack_chain_relationship_ids: list[uuid.UUID] = Field(default_factory=list)
+
+    # Structural edges for context (explanation)
+    context_relationship_ids: list[uuid.UUID] = Field(default_factory=list)
+
+    # Classification
+    attack_vector: str = Field(..., min_length=1, max_length=100)
+    path_length: int = Field(..., ge=1)
+
+    # Risk scoring
+    entry_confidence: Decimal = Field(..., ge=Decimal("0"), le=Decimal("1"))
+    exploitability_score: Decimal = Field(..., ge=Decimal("0"))
+    impact_score: Decimal = Field(..., ge=Decimal("0"))
+    risk_score: Decimal = Field(..., ge=Decimal("0"))
+
+    # Confidence level and reason
+    confidence_level: ConfidenceLevel = ConfidenceLevel.HIGH
+    confidence_reason: str = ""
+
+    # Proof chain - evidence for why this path exists
+    proof: dict[str, Any] = Field(default_factory=dict)
+
+
+class CostCutCandidate(BaseSchema):
+    """
+    A resource that can potentially be removed or isolated.
+
+    These are assets that:
+    - Appear in attack paths but not in legitimate business paths
+    - Have no observed usage (optional, if traffic data available)
+    - Removal would reduce attack surface without breaking functionality
+    """
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4)
+    snapshot_id: uuid.UUID
+    asset_id: uuid.UUID
+
+    # Why this is a candidate
+    reason: str
+    action: str  # "remove", "isolate", "restrict"
+    confidence: Decimal = Field(..., ge=Decimal("0"), le=Decimal("1"))
+
+    # Cost impact
+    monthly_savings_usd: Decimal = Field(default=Decimal("0"))
+
+    # Security impact
+    paths_blocked: int = 0  # How many attack paths this eliminates
+    risk_reduction: Decimal = Field(default=Decimal("0"))
+
+    # Evidence
+    proof: dict[str, Any] = Field(default_factory=dict)

cyntrisec/core/simulator.py

@@ -0,0 +1,371 @@
+"""
+IAM Policy Simulator - Test whether a principal can perform an action.
+
+Uses AWS IAM Policy Simulator API to evaluate permissions and determine
+whether a given action would be allowed or denied.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+
+class SimulationDecision(str, Enum):
+    """Result of a policy simulation."""
+
+    allowed = "allowed"
+    implicit_deny = "implicitDeny"
+    explicit_deny = "explicitDeny"
+
+
+@dataclass
+class SimulationResult:
+    """
+    Result of simulating an IAM action.
+
+    Attributes:
+        action: The action tested (e.g., 's3:GetObject')
+        resource: The resource tested (e.g., 'arn:aws:s3:::bucket/*')
+        decision: Whether allowed, implicitly denied, or explicitly denied
+        decision_details: Additional info about which policy affected decision
+        matched_statements: Policy statements that matched
+    """
+
+    action: str | None
+    resource: str
+    decision: SimulationDecision
+    decision_details: dict[str, Any] = field(default_factory=dict)
+    matched_statements: list[dict[str, Any]] = field(default_factory=list)
+
+    @property
+    def is_allowed(self) -> bool:
+        return self.decision == SimulationDecision.allowed
+
+    @property
+    def is_denied(self) -> bool:
+        return self.decision in (SimulationDecision.implicit_deny, SimulationDecision.explicit_deny)
+
+
+@dataclass
+class CanAccessResult:
+    """
+    Result of a "can X access Y?" query.
+
+    Attributes:
+        principal_arn: The IAM principal tested
+        target_resource: The resource being accessed
+        action: The specific action tested
+        can_access: Whether access is allowed
+        simulations: All simulation results
+        proof: Evidence chain for the result
+    """
+
+    principal_arn: str
+    target_resource: str
+    action: str | None
+    can_access: bool
+    simulations: list[SimulationResult] = field(default_factory=list)
+    proof: dict[str, Any] = field(default_factory=dict)
+
+
+class PolicySimulator:
+    """
+    Simulate IAM policy evaluation using AWS Policy Simulator API.
+
+    This provides ground truth for "can X access Y?" questions by
+    using the same policy evaluation logic as AWS.
+    """
+
+    def __init__(self, session):
+        """
+        Initialize with a boto3 Session.
+
+        Args:
+            session: boto3.Session with IAM permissions
+        """
+        self._session = session
+        self._iam = session.client("iam")
+
+    def simulate_principal_policy(
+        self,
+        principal_arn: str,
+        actions: list[str],
+        resources: list[str],
+        *,
+        context_entries: list[dict[str, Any]] | None = None,
+    ) -> list[SimulationResult]:
+        """
+        Simulate whether a principal can perform actions on resources.
+
+        Args:
+            principal_arn: ARN of user/role to test
+            actions: List of actions to test (e.g., ['s3:GetObject'])
+            resources: List of resource ARNs to test against
+            context_entries: Optional context values for conditions
+
+        Returns:
+            List of SimulationResult for each action/resource combination
+        """
+        results = []
+
+        try:
+            params = {
+                "PolicySourceArn": principal_arn,
+                "ActionNames": actions,
+                "ResourceArns": resources,
+            }
+
+            if context_entries:
+                params["ContextEntries"] = context_entries
+
+            paginator = self._iam.get_paginator("simulate_principal_policy")
+
+            for page in paginator.paginate(**params):
+                for eval_result in page.get("EvaluationResults", []):
+                    decision_str = eval_result.get("EvalDecision", "implicitDeny")
+
+                    # Map AWS decision to our enum
+                    if decision_str == "allowed":
+                        decision = SimulationDecision.allowed
+                    elif decision_str == "explicitDeny":
+                        decision = SimulationDecision.explicit_deny
+                    else:
+                        decision = SimulationDecision.implicit_deny
+
+                    result = SimulationResult(
+                        action=eval_result.get("EvalActionName", ""),
+                        resource=eval_result.get("EvalResourceName", "*"),
+                        decision=decision,
+                        decision_details=eval_result.get("EvalDecisionDetails", {}),
+                        matched_statements=eval_result.get("MatchedStatements", []),
+                    )
+                    results.append(result)
+
+        except Exception as e:
+            log.warning("Policy simulation failed for %s: %s", principal_arn, e)
+            # Return implicit deny for all requested simulations
+            for action in actions:
+                for resource in resources:
+                    results.append(
+                        SimulationResult(
+                            action=action,
+                            resource=resource,
+                            decision=SimulationDecision.implicit_deny,
+                            decision_details={"error": str(e)},
+                        )
+                    )
+
+        return results
+
+    def can_access(
+        self,
+        principal_arn: str,
+        target_resource: str,
+        *,
+        action: str | None = None,
+    ) -> CanAccessResult:
+        """
+        Check if a principal can access a resource.
+
+        This is the high-level "can X access Y?" query that users run.
+
+        Args:
+            principal_arn: ARN of role/user
+            target_resource: Resource ARN or bucket name/etc.
+            action: Specific action to test (auto-detected if not provided)
+
+        Returns:
+            CanAccessResult with full proof chain
+        """
+        # Normalize resource to ARN if needed
+        resource_arn = self._normalize_resource(target_resource)
+
+        # Determine actions to test based on resource type
+        if action:
+            actions_to_test = [action]
+        else:
+            actions_to_test = self._infer_actions(resource_arn)
+
+        # Run simulation
+        resources_to_test = self._resources_for_actions(resource_arn, actions_to_test)
+        simulations = self.simulate_principal_policy(
+            principal_arn=principal_arn,
+            actions=actions_to_test,
+            resources=resources_to_test,
+        )
+
+        # Determine overall result - allowed if ANY action is allowed
+        can_access = any(s.is_allowed for s in simulations)
+
+        # Build proof
+        proof = {
+            "principal": principal_arn,
+            "resource": resource_arn,
+            "resources_tested": resources_to_test,
+            "actions_tested": actions_to_test,
+            "simulations": [
+                {
+                    "action": s.action,
+                    "decision": s.decision.value,
+                    "matched_statements": len(s.matched_statements),
+                }
+                for s in simulations
+            ],
+        }
+
+        return CanAccessResult(
+            principal_arn=principal_arn,
+            target_resource=target_resource,
+            action=action or actions_to_test[0],
+            can_access=can_access,
+            simulations=simulations,
+            proof=proof,
+        )
+
+    def _normalize_resource(self, resource: str) -> str:
+        """Convert resource identifier to ARN."""
+        if resource.startswith("arn:"):
+            return resource
+
+        # S3 bucket
+        if resource.startswith("s3://"):
+            bucket = resource[5:].split("/")[0]
+            path = "/".join(resource[5:].split("/")[1:]) if "/" in resource[5:] else "*"
+            return f"arn:aws:s3:::{bucket}/{path}"
+
+        # Assume it's an S3 bucket name
+        if "." in resource or resource.islower():
+            return f"arn:aws:s3:::{resource}/*"
+
+        return resource
+
+    def _infer_actions(self, resource_arn: str) -> list[str]:
+        """Infer actions to test based on resource type."""
+        if ":s3:::" in resource_arn:
+            return ["s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:ListBucket"]
+
+        if ":iam::" in resource_arn and ":role/" in resource_arn:
+            return ["sts:AssumeRole"]
+
+        if ":secretsmanager:" in resource_arn:
+            return ["secretsmanager:GetSecretValue"]
+
+        if ":ssm:" in resource_arn:
+            return ["ssm:GetParameter"]
+
+        if ":rds:" in resource_arn:
+            return ["rds:DescribeDBInstances"]
+
+        if ":dynamodb:" in resource_arn:
+            return ["dynamodb:GetItem", "dynamodb:Scan"]
+
+        if ":lambda:" in resource_arn:
+            return ["lambda:InvokeFunction"]
+
+        if ":ec2:" in resource_arn:
+            return ["ec2:DescribeInstances"]
+
+        # Default: test read access
+        return ["*:Get*", "*:Describe*", "*:List*"]
+
+    def _resources_for_actions(self, resource_arn: str, actions: list[str]) -> list[str]:
+        """Build resource ARNs appropriate for the given actions."""
+        if ":s3:::" not in resource_arn:
+            return [resource_arn]
+
+        bucket_arn, object_arn = self._s3_variants(resource_arn)
+        resources: list[str] = []
+        if any(a.lower() == "s3:listbucket" for a in actions):
+            resources.append(bucket_arn)
+        if any(a.lower().startswith("s3:") and a.lower() != "s3:listbucket" for a in actions):
+            resources.append(object_arn)
+        if not resources:
+            resources = [object_arn]
+        return resources
+
+    def _s3_variants(self, resource_arn: str) -> tuple[str, str]:
+        """Return bucket ARN and object ARN variants for S3 resources."""
+        prefix = "arn:aws:s3:::"
+        if not resource_arn.startswith(prefix):
+            return resource_arn, resource_arn
+
+        suffix = resource_arn[len(prefix):]
+        if "/" in suffix:
+            bucket = suffix.split("/", 1)[0]
+            bucket_arn = f"{prefix}{bucket}"
+            object_arn = resource_arn
+        else:
+            bucket_arn = resource_arn
+            object_arn = f"{resource_arn}/*"
+        return bucket_arn, object_arn
+
+
+class OfflineSimulator:
+    """
+    Offline policy evaluation without AWS API calls.
+
+    Uses scan data to make educated guesses about access.
+    Less accurate than PolicySimulator but works offline.
+    """
+
+    def __init__(self, assets: list[Any], relationships: list[Any]):
+        """
+        Initialize with scan data.
+
+        Args:
+            assets: Assets from scan
+            relationships: Relationships from scan
+        """
+        self._assets = {a.arn: a for a in assets if a.arn}
+        self._assets_by_name = {a.name: a for a in assets}
+        self._relationships = relationships
+
+    def can_access(
+        self,
+        principal_arn: str,
+        target_resource: str,
+        *,
+        action: str | None = None,
+    ) -> CanAccessResult:
+        """
+        Check if principal can access resource using scan data.
+
+        This uses the MAY_ACCESS relationships from the graph.
+        """
+        # Find assets
+        principal = self._assets.get(principal_arn) or self._assets_by_name.get(
+            principal_arn.split("/")[-1]
+        )
+        target = self._assets.get(target_resource) or self._assets_by_name.get(target_resource)
+
+        can_access = False
+        proof = {}
+
+        if principal and target:
+            # Check for direct relationship
+            for rel in self._relationships:
+                if (
+                    rel.source_asset_id == principal.id
+                    and rel.target_asset_id == target.id
+                    and rel.relationship_type in ("MAY_ACCESS", "CAN_ASSUME", "ALLOWS")
+                ):
+                    can_access = True
+                    proof = {
+                        "relationship_type": rel.relationship_type,
+                        "properties": rel.properties,
+                    }
+                    break
+
+        return CanAccessResult(
+            principal_arn=principal_arn,
+            target_resource=target_resource,
+            action=action,
+            can_access=can_access,
+            simulations=[],
+            proof=proof,
+        )