condor-scan 0.3.0__py3-none-any.whl

condor_scan/__init__.py

@@ -0,0 +1,23 @@
+"""condor-scan: GCP conditional IAM & tag-based privilege-escalation scanner."""
+
+from __future__ import annotations
+
+from .analysis import build_context
+from .findings import Finding, Severity
+from .graph import PostureReport, analyze_posture
+from .loaders import load_from_dict, load_from_file
+from .rules import EscalationEngine
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "EscalationEngine",
+    "Finding",
+    "PostureReport",
+    "Severity",
+    "analyze_posture",
+    "build_context",
+    "load_from_dict",
+    "load_from_file",
+    "__version__",
+]

condor_scan/analysis.py

@@ -0,0 +1,224 @@
+"""Pre-computation layer: turn an Environment into queryable index structures.
+
+This separates the (pure, cacheable) work of expanding roles and bindings from
+the escalation engine that walks them. Keeping it separate makes both halves
+straightforward to unit-test.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from .knowledge import (
+    ACT_AS_PERMISSIONS,
+    KEY_CREATE_PERMISSIONS,
+    TOKEN_CREATE_PERMISSIONS,
+    role_permissions,
+)
+from .model import Binding, Environment
+from .temporal import TemporalWindow, parse_temporal_window
+
+
+@dataclass
+class ConditionalGrant:
+    """A role granted to a member only when an IAM Condition holds."""
+
+    role: str
+    permissions: frozenset[str]
+    condition_title: str
+    condition_expression: str
+    resource: str
+    temporal: TemporalWindow = field(default_factory=TemporalWindow)
+
+
+@dataclass(frozen=True)
+class GrantRecord:
+    """An unconditional binding that granted a role to a principal.
+
+    Retained so escalation steps can be attributed back to the specific,
+    remediable binding that enabled them (used by choke-point analysis).
+    """
+
+    role: str
+    resource: str
+    permissions: frozenset[str]
+
+
+@dataclass(frozen=True)
+class ImpersonationGrant:
+    """A binding on a service-account resource that lets a member act as it."""
+
+    role: str
+    resource: str
+    permissions: frozenset[str]
+
+
+@dataclass
+class PrincipalIndex:
+    """Everything we need to know about one principal's starting position."""
+
+    member: str
+    permissions: set[str] = field(default_factory=set)
+    roles: set[str] = field(default_factory=set)
+    conditional_grants: list[ConditionalGrant] = field(default_factory=list)
+    grants: list[GrantRecord] = field(default_factory=list)
+
+
+@dataclass
+class ServiceAccountIndex:
+    """A service account's own privileges and who can impersonate it."""
+
+    email: str
+    permissions: set[str] = field(default_factory=set)
+    roles: set[str] = field(default_factory=set)
+    # member -> impersonation grants that member holds on this SA
+    impersonators: dict[str, list[ImpersonationGrant]] = field(
+        default_factory=dict
+    )
+
+
+@dataclass
+class AnalysisContext:
+    """The fully indexed environment passed to the escalation engine."""
+
+    principals: dict[str, PrincipalIndex]
+    service_accounts: dict[str, ServiceAccountIndex]
+    custom_roles: dict[str, frozenset[str]]
+    group_members: dict[str, tuple[str, ...]]
+    exposed_principals: tuple[str, ...] = ()
+
+    def members_including_groups(self, member: str) -> set[str]:
+        """Resolve a member to itself plus any groups that contain it.
+
+        Used so that a conditional binding granted to a *group* is recognised
+        as applying to its members.
+        """
+        result = {member}
+        for group, members in self.group_members.items():
+            if member in members:
+                result.add(group)
+        return result
+
+    def untrusted_sources(self) -> set[str]:
+        """Members that an attacker can act as without prior access.
+
+        These are the "initial access" footholds: the public IAM members
+        ``allUsers`` / ``allAuthenticatedUsers`` (when actually bound to
+        something), plus any principals declared internet-exposed in the export
+        (e.g. service accounts attached to a public Cloud Run service).
+        """
+        sources = set(self.exposed_principals)
+        for special in ("allUsers", "allAuthenticatedUsers"):
+            if special in self.principals:
+                sources.add(special)
+        return sources
+
+
+_SA_RESOURCE_MARKER = "serviceAccounts/"
+
+
+def _sa_email_from_resource(resource: str) -> str | None:
+    if _SA_RESOURCE_MARKER not in resource:
+        return None
+    return resource.rsplit("/", 1)[-1]
+
+
+def build_context(env: Environment) -> AnalysisContext:
+    """Index an :class:`Environment` for escalation analysis."""
+    custom_roles = {name: role.permissions for name, role in env.roles.items()}
+
+    principals: dict[str, PrincipalIndex] = {}
+    service_accounts: dict[str, ServiceAccountIndex] = {}
+
+    def principal(member: str) -> PrincipalIndex:
+        return principals.setdefault(member, PrincipalIndex(member=member))
+
+    def service_account(email: str) -> ServiceAccountIndex:
+        return service_accounts.setdefault(
+            email, ServiceAccountIndex(email=email)
+        )
+
+    for policy in env.iam_policies:
+        sa_email = _sa_email_from_resource(policy.resource)
+        for binding in policy.bindings:
+            perms = role_permissions(binding.role, custom_roles)
+            for member in binding.members:
+                _apply_binding(
+                    member=member,
+                    binding=binding,
+                    perms=perms,
+                    resource=policy.resource,
+                    principal=principal,
+                )
+                # If this policy is attached to a service account, the binding
+                # describes who may impersonate that SA.
+                if sa_email is not None:
+                    _record_impersonation(
+                        sa=service_account(sa_email),
+                        member=member,
+                        role=binding.role,
+                        resource=policy.resource,
+                        perms=perms,
+                    )
+            # A service account that is itself a *member* gains those perms.
+            for member in binding.members:
+                if member.startswith("serviceAccount:"):
+                    email = member.split(":", 1)[1]
+                    sa = service_account(email)
+                    sa.permissions.update(perms)
+                    sa.roles.add(binding.role)
+
+    return AnalysisContext(
+        principals=principals,
+        service_accounts=service_accounts,
+        custom_roles=custom_roles,
+        group_members=dict(env.group_members),
+        exposed_principals=tuple(env.exposed_principals),
+    )
+
+
+def _apply_binding(
+    *,
+    member: str,
+    binding: Binding,
+    perms: frozenset[str],
+    resource: str,
+    principal: Callable[[str], PrincipalIndex],
+) -> None:
+    idx = principal(member)
+    if binding.is_conditional:
+        assert binding.condition is not None
+        idx.conditional_grants.append(
+            ConditionalGrant(
+                role=binding.role,
+                permissions=perms,
+                condition_title=binding.condition.title,
+                condition_expression=binding.condition.expression,
+                resource=resource,
+                temporal=parse_temporal_window(binding.condition.expression),
+            )
+        )
+    else:
+        idx.permissions.update(perms)
+        idx.roles.add(binding.role)
+        idx.grants.append(
+            GrantRecord(role=binding.role, resource=resource, permissions=perms)
+        )
+
+
+def _record_impersonation(
+    *,
+    sa: ServiceAccountIndex,
+    member: str,
+    role: str,
+    resource: str,
+    perms: frozenset[str],
+) -> None:
+    relevant = perms & (
+        TOKEN_CREATE_PERMISSIONS | KEY_CREATE_PERMISSIONS | ACT_AS_PERMISSIONS
+    )
+    if relevant:
+        sa.impersonators.setdefault(member, []).append(
+            ImpersonationGrant(role=role, resource=resource, permissions=relevant)
+        )

condor_scan/cel.py

@@ -0,0 +1,50 @@
+"""A conservative, well-scoped parser for IAM Condition (CEL) expressions.
+
+We do not implement a full CEL evaluator. For escalation analysis we only need
+to answer one question: *can a principal who is able to attach tags satisfy this
+condition?* That requires recognising tag-based predicates:
+
+    resource.matchTag('123456789/env', 'prod')
+    resource.matchTagId('tagKeys/123', 'tagValues/456')
+
+Anything we do not recognise is treated as **not** tag-satisfiable, which is the
+safe (non-false-positive) default. Limitations are documented in the README.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# resource.matchTag('<namespaced key>', '<short value>')
+_MATCH_TAG = re.compile(
+    r"resource\.matchTag\(\s*['\"]([^'\"]+)['\"]\s*,\s*['\"]([^'\"]+)['\"]\s*\)"
+)
+# resource.matchTagId('tagKeys/<id>', 'tagValues/<id>')
+_MATCH_TAG_ID = re.compile(
+    r"resource\.matchTagId\(\s*['\"]([^'\"]+)['\"]\s*,\s*['\"]([^'\"]+)['\"]\s*\)"
+)
+
+
+@dataclass(frozen=True)
+class TagPredicate:
+    """A single tag requirement extracted from a condition."""
+
+    key: str
+    value: str
+    by_id: bool
+
+
+def extract_tag_predicates(expression: str) -> list[TagPredicate]:
+    """Return all tag predicates found in a CEL expression."""
+    predicates: list[TagPredicate] = []
+    for key, value in _MATCH_TAG.findall(expression):
+        predicates.append(TagPredicate(key=key, value=value, by_id=False))
+    for key, value in _MATCH_TAG_ID.findall(expression):
+        predicates.append(TagPredicate(key=key, value=value, by_id=True))
+    return predicates
+
+
+def is_tag_based(expression: str) -> bool:
+    """True if the condition's satisfiability depends on resource tags."""
+    return bool(extract_tag_predicates(expression))

condor_scan/cli.py

@@ -0,0 +1,187 @@
+"""Command-line interface for condor-scan.
+
+Uses only the standard library (argparse) to keep the supply-chain footprint of
+a security tool minimal. Subcommands:
+
+    condor-scan scan EXPORT.json [--format json|sarif|table] [--fail-on SEVERITY]
+    condor-scan posture EXPORT.json [--format text|json] [--fail-on-exposed]
+    condor-scan gen-constraints [--out-dir DIR]
+
+``scan`` and ``posture`` exit non-zero on policy violations so they can gate a
+CI pipeline.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timedelta
+from pathlib import Path
+
+from .analysis import build_context
+from .constraints import generate_constraint_yaml, generate_rego
+from .findings import Severity, render
+from .graph import analyze_posture
+from .loaders import LoaderError, load_from_file
+from .rules import EscalationEngine
+from .temporal import parse_timestamp
+
+_EXIT_OK = 0
+_EXIT_FINDINGS = 1
+_EXIT_USAGE = 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="condor-scan",
+        description=(
+            "Detect GCP IAM privilege-escalation chains, including tag-based "
+            "and IAM-Conditions escalation paths."
+        ),
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    scan = sub.add_parser("scan", help="scan an IAM/asset export for escalation")
+    scan.add_argument("export", help="path to a JSON IAM/asset export")
+    scan.add_argument(
+        "--format",
+        choices=["json", "sarif", "table"],
+        default="table",
+        help="output format (default: table)",
+    )
+    scan.add_argument(
+        "--fail-on",
+        choices=[s.name.lower() for s in Severity if s >= Severity.LOW],
+        default=None,
+        help="exit non-zero if any finding is at or above this severity",
+    )
+    scan.add_argument(
+        "--as-of",
+        default=None,
+        metavar="ISO8601",
+        help="evaluate time-bound conditions as of this instant (default: now)",
+    )
+
+    gen = sub.add_parser(
+        "gen-constraints", help="emit Policy Library / OPA constraints"
+    )
+    gen.add_argument(
+        "--out-dir",
+        default=None,
+        help="write constraint files to this directory instead of stdout",
+    )
+
+    posture = sub.add_parser(
+        "posture",
+        help="attack-path posture: exposure, choke points, detection blind spots",
+    )
+    posture.add_argument("export", help="path to a JSON IAM/asset export")
+    posture.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="output format (default: text)",
+    )
+    posture.add_argument(
+        "--fail-on-exposed",
+        action="store_true",
+        help="exit non-zero if any externally-exposed Tier-Zero path exists",
+    )
+    posture.add_argument(
+        "--as-of",
+        default=None,
+        metavar="ISO8601",
+        help="evaluate time-bound conditions as of this instant (default: now)",
+    )
+    posture.add_argument(
+        "--jit-threshold-hours",
+        type=float,
+        default=24.0,
+        help="windows shorter than this count as JIT/short-lived (default: 24)",
+    )
+    return parser
+
+
+def _parse_as_of(value: str | None) -> datetime | None:
+    if value is None:
+        return None
+    parsed = parse_timestamp(value)
+    if parsed is None:
+        raise ValueError(f"invalid --as-of timestamp: {value!r}")
+    return parsed
+
+
+def _run_scan(args: argparse.Namespace) -> int:
+    try:
+        env = load_from_file(args.export)
+        now = _parse_as_of(args.as_of)
+    except (LoaderError, FileNotFoundError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return _EXIT_USAGE
+
+    ctx = build_context(env)
+    findings = EscalationEngine(ctx, now=now).analyze_all()
+    print(render(findings, args.format))
+
+    if args.fail_on is not None:
+        threshold = Severity.from_name(args.fail_on)
+        if any(f.severity >= threshold for f in findings):
+            return _EXIT_FINDINGS
+    return _EXIT_OK
+
+
+def _run_gen_constraints(args: argparse.Namespace) -> int:
+    rego = generate_rego()
+    yaml = generate_constraint_yaml()
+    if args.out_dir:
+        out = Path(args.out_dir)
+        out.mkdir(parents=True, exist_ok=True)
+        (out / "tag_condition_escalation.rego").write_text(rego, encoding="utf-8")
+        (out / "tag_condition_escalation.yaml").write_text(yaml, encoding="utf-8")
+        print(f"wrote constraint template and instance to {out}/")
+    else:
+        print(rego)
+        print("---")
+        print(yaml)
+    return _EXIT_OK
+
+
+def _run_posture(args: argparse.Namespace) -> int:
+    try:
+        env = load_from_file(args.export)
+        now = _parse_as_of(args.as_of)
+    except (LoaderError, FileNotFoundError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return _EXIT_USAGE
+
+    ctx = build_context(env)
+    engine = EscalationEngine(
+        ctx, now=now, jit_threshold=timedelta(hours=args.jit_threshold_hours)
+    )
+    report = analyze_posture(ctx, engine)
+    if args.format == "json":
+        print(json.dumps(report.to_dict(), indent=2))
+    else:
+        print(report.to_text())
+
+    if args.fail_on_exposed and report.exposed_tier_zero:
+        return _EXIT_FINDINGS
+    return _EXIT_OK
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "scan":
+        return _run_scan(args)
+    if args.command == "gen-constraints":
+        return _run_gen_constraints(args)
+    if args.command == "posture":
+        return _run_posture(args)
+    parser.error("unknown command")  # pragma: no cover
+    return _EXIT_USAGE
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

condor_scan/constraints.py

@@ -0,0 +1,81 @@
+"""Generate Policy Library / OPA constraints from the engine's knowledge.
+
+This is the "Google-adoptable" artifact: Forseti's policy-library and the
+Config Validator / Gatekeeper ecosystem consume OPA (Rego) constraint templates.
+We emit a constraint that flags the tag-conditional escalation pattern the
+engine detects, so the same rule can run as a *preventive* policy at deploy time
+(Terraform validation, CI gate) rather than only as a detective scan.
+"""
+
+from __future__ import annotations
+
+from . import knowledge as kb
+
+_REGO_HEADER = """\
+# Auto-generated by condor-scan.
+# Flags conditional IAM bindings whose condition is keyed on resource tags and
+# whose granted role confers escalation-relevant permissions. Such bindings let
+# any principal able to attach tags satisfy the condition and self-escalate
+# (the "Tag Your Way In" pattern; Mitiga, 2026).
+package templates.gcp.GCPIAMTagConditionEscalationConstraintV1
+
+import data.validator.gcp.lib as lib
+"""
+
+
+def _escalation_roles() -> list[str]:
+    return sorted(kb.TIER_ZERO_ROLES)
+
+
+def generate_rego() -> str:
+    """Return a Rego constraint-template body for tag-conditional escalation."""
+    roles_list = ",\n        ".join(f'"{r}"' for r in _escalation_roles())
+    return (
+        _REGO_HEADER
+        + f"""
+escalation_roles := {{
+        {roles_list}
+}}
+
+# A condition expression is tag-based if it references resource tag matchers.
+is_tag_condition(expr) {{
+    contains(expr, "resource.matchTag(")
+}}
+is_tag_condition(expr) {{
+    contains(expr, "resource.matchTagId(")
+}}
+
+deny[{{"msg": msg, "details": details}}] {{
+    binding := input.asset.iam_policy.bindings[_]
+    escalation_roles[binding.role]
+    expr := binding.condition.expression
+    is_tag_condition(expr)
+
+    msg := sprintf(
+        "Conditional binding grants escalation role %v under a tag-based condition (%v); tag-attach permission holders can self-escalate.",
+        [binding.role, binding.condition.title]
+    )
+    details := {{
+        "resource": input.asset.name,
+        "role": binding.role,
+        "condition": binding.condition.title,
+        "expression": expr,
+    }}
+}}
+"""
+    )
+
+
+def generate_constraint_yaml(name: str = "deny-tag-condition-escalation") -> str:
+    """Return the constraint instance YAML that binds the template above."""
+    return f"""\
+apiVersion: constraints.gatekeeper.sh/v1alpha1
+kind: GCPIAMTagConditionEscalationConstraintV1
+metadata:
+  name: {name}
+spec:
+  severity: high
+  match:
+    target: ["organizations/**"]
+  parameters: {{}}
+"""