lambda-preflight 0.1.0__py3-none-any.whl

lambda_preflight/iam/evaluator.py

@@ -0,0 +1,177 @@
+"""IAM policy evaluator.
+
+Implements AWS's documented identity-policy decision flow:
+
+    explicit Deny  ->  wins, always
+    else an Allow  ->  required to permit
+    else           ->  implicit deny
+
+When a permission boundary is present, an action must be allowed by *both*
+the identity policies and the boundary (the intersection), matching AWS.
+
+Strict mode turns "I cannot faithfully evaluate this" into an error rather
+than a silent pass — the safe default for a tool whose promise is fidelity.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from .conditions import action_matches, evaluate_condition, resource_matches
+from .model import PolicySet, Statement
+
+
+class AccessDenied(Exception):
+    """Raised when the evaluator denies a simulated call."""
+
+
+class CannotEvaluate(Exception):
+    """Raised in strict mode when a decision depends on unsupported logic."""
+
+
+@dataclass
+class Decision:
+    """Result of an authorization check.
+
+    ``allowed`` is the effective decision. ``reason`` explains it.
+    ``unevaluable`` lists condition operators that could not be assessed;
+    in strict mode a non-empty list turns into CannotEvaluate.
+    """
+
+    allowed: bool
+    reason: str
+    unevaluable: List[str]
+    matched_sid: Optional[str] = None
+
+
+class PolicyEvaluator:
+    """Evaluate simulated AWS calls against a local PolicySet."""
+
+    def __init__(
+        self,
+        policies: PolicySet,
+        strict: bool = False,
+        boundary: Optional[List[Statement]] = None,
+    ) -> None:
+        self.policies = policies
+        self.strict = strict
+        # Explicit boundary arg overrides whatever is on the PolicySet.
+        self.boundary = (
+            boundary if boundary is not None else policies.boundary
+        )
+
+    def evaluate(
+        self,
+        action: str,
+        resource: str = "*",
+        context: Optional[Dict[str, Any]] = None,
+    ) -> Decision:
+        """Return the Decision for ``action`` on ``resource``."""
+        context = context or {}
+        identity = self._evaluate_statements(
+            self.policies.statements, action, resource, context
+        )
+
+        # Explicit deny in identity policies wins immediately.
+        if identity["explicit_deny"]:
+            return Decision(
+                allowed=False,
+                reason=f"Explicit Deny on {action}",
+                unevaluable=identity["unevaluable"],
+                matched_sid=identity["deny_sid"],
+            )
+
+        allowed = identity["allow"]
+        reason = (
+            f"Allowed by {identity['allow_sid'] or 'identity policy'}"
+            if allowed
+            else f"Implicit deny: no matching Allow for {action}"
+        )
+
+        # Permission boundary: must also allow (intersection semantics).
+        if self.boundary:
+            b = self._evaluate_statements(
+                self.boundary, action, resource, context
+            )
+            if b["explicit_deny"]:
+                allowed = False
+                reason = f"Denied by permission boundary on {action}"
+            elif not b["allow"]:
+                allowed = False
+                reason = f"Not permitted by permission boundary: {action}"
+            identity["unevaluable"].extend(b["unevaluable"])
+
+        decision = Decision(
+            allowed=allowed,
+            reason=reason,
+            unevaluable=identity["unevaluable"],
+            matched_sid=identity["allow_sid"],
+        )
+
+        if self.strict and decision.unevaluable:
+            raise CannotEvaluate(
+                f"Cannot faithfully evaluate {action} on {resource}: "
+                f"unsupported condition operators "
+                f"{sorted(set(decision.unevaluable))}"
+            )
+        return decision
+
+    def authorize(
+        self,
+        action: str,
+        resource: str = "*",
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Raise AccessDenied if the call is not allowed; else return None."""
+        decision = self.evaluate(action, resource, context)
+        if not decision.allowed:
+            raise AccessDenied(decision.reason)
+
+    def _evaluate_statements(
+        self,
+        statements: List[Statement],
+        action: str,
+        resource: str,
+        context: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """Scan statements once, collecting allow/deny signals."""
+        allow = False
+        allow_sid: Optional[str] = None
+        explicit_deny = False
+        deny_sid: Optional[str] = None
+        unevaluable: List[str] = []
+
+        for stmt in statements:
+            if not self._action_in(stmt, action):
+                continue
+            if not self._resource_in(stmt, resource):
+                continue
+
+            passed, uneval = evaluate_condition(stmt.conditions, context)
+            unevaluable.extend(uneval)
+            if not passed:
+                continue
+
+            if stmt.effect == "Deny":
+                explicit_deny = True
+                deny_sid = stmt.sid
+            elif stmt.effect == "Allow":
+                allow = True
+                allow_sid = allow_sid or stmt.sid
+
+        return {
+            "allow": allow,
+            "allow_sid": allow_sid,
+            "explicit_deny": explicit_deny,
+            "deny_sid": deny_sid,
+            "unevaluable": unevaluable,
+        }
+
+    @staticmethod
+    def _action_in(stmt: Statement, action: str) -> bool:
+        return any(action_matches(p, action) for p in stmt.actions)
+
+    @staticmethod
+    def _resource_in(stmt: Statement, resource: str) -> bool:
+        return any(resource_matches(p, resource) for p in stmt.resources)

lambda_preflight/iam/intercept.py

@@ -0,0 +1,101 @@
+"""boto3 intercept hook.
+
+Hooks botocore's event system so that AWS SDK calls made *inside* a handler
+are authorized against the local evaluator before they go anywhere. This is
+cleaner than asking developers to annotate every call: it maps the botocore
+operation to an IAM action and checks it, raising AccessDenied locally when
+the role's real policy would not permit it.
+
+Best-effort action mapping: botocore gives ``service`` and an operation name
+like ``PutObject``; the IAM action is ``s3:PutObject``. A small override map
+handles the cases where service id and IAM prefix differ.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any, Dict, Iterator, Optional
+
+from .evaluator import PolicyEvaluator
+
+# botocore service id -> IAM action prefix, where they diverge.
+_SERVICE_PREFIX = {
+    "dynamodb": "dynamodb",
+    "s3": "s3",
+    "sqs": "sqs",
+    "sns": "sns",
+    "lambda": "lambda",
+    "states": "states",
+    "secretsmanager": "secretsmanager",
+    "ssm": "ssm",
+    "events": "events",
+    "sts": "sts",
+    "cloudwatch": "cloudwatch",
+    "logs": "logs",
+}
+
+
+def operation_to_action(service_id: str, operation_name: str) -> str:
+    """Map a botocore operation to an IAM action string."""
+    prefix = _SERVICE_PREFIX.get(service_id, service_id)
+    return f"{prefix}:{operation_name}"
+
+
+class BotoIntercept:
+    """Registers a before-call hook on a boto3 session's event system."""
+
+    def __init__(
+        self,
+        evaluator: PolicyEvaluator,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        self.evaluator = evaluator
+        self.context = context or {}
+        self._registered_session: Any = None
+
+    def _before_call(self, model: Any, params: Any, **kwargs: Any) -> None:
+        service_id = model.service_model.service_name
+        action = operation_to_action(service_id, model.name)
+        # Resource-level ARNs are not always derivable from params, so we
+        # authorize at action granularity with "*" resource by default.
+        # Callers wanting resource-level checks can pre-seed context.
+        self.evaluator.authorize(action, "*", self.context)
+
+    def attach(self, session: Any) -> None:
+        """Attach the hook to a boto3.Session (or boto3 module default)."""
+        events = session.events
+        events.register("before-call", self._before_call)
+        self._registered_session = session
+
+    def detach(self) -> None:
+        if self._registered_session is not None:
+            self._registered_session.events.unregister(
+                "before-call", self._before_call
+            )
+            self._registered_session = None
+
+
+@contextmanager
+def intercept_boto3(
+    evaluator: PolicyEvaluator,
+    session: Any = None,
+    context: Optional[Dict[str, Any]] = None,
+) -> Iterator[BotoIntercept]:
+    """Context manager that authorizes boto3 calls against ``evaluator``.
+
+    Usage::
+
+        with intercept_boto3(evaluator, session=my_session):
+            harness.invoke(event)   # boto3 calls inside are checked
+    """
+    if session is None:
+        import boto3
+
+        session = boto3.DEFAULT_SESSION or boto3.Session()
+
+    hook = BotoIntercept(evaluator, context=context)
+    hook.attach(session)
+    try:
+        yield hook
+    finally:
+        hook.detach()

lambda_preflight/iam/model.py

@@ -0,0 +1,90 @@
+"""IAM policy data model.
+
+A ``PolicySet`` is the merged collection of statements that govern a
+principal, plus optional metadata (permission boundary, source, timestamp)
+used for cache freshness and honest scoping.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+def _as_list(value: Any) -> List[Any]:
+    """IAM fields may be a scalar or a list; normalise to a list."""
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    return [value]
+
+
+@dataclass
+class Statement:
+    """A single IAM policy statement."""
+
+    effect: str
+    actions: List[str]
+    resources: List[str]
+    conditions: Dict[str, Dict[str, Any]] = field(default_factory=dict)
+    sid: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, raw: Dict[str, Any]) -> "Statement":
+        return cls(
+            effect=raw.get("Effect", "Deny"),
+            actions=[a.lower() for a in _as_list(raw.get("Action"))],
+            resources=_as_list(raw.get("Resource")) or ["*"],
+            conditions=raw.get("Condition", {}) or {},
+            sid=raw.get("Sid"),
+        )
+
+
+@dataclass
+class PolicySet:
+    """Merged policies for a principal.
+
+    ``boundary`` holds the permission-boundary statements when known.
+    ``unscoped`` records permission surfaces deliberately not represented
+    (SCPs, resource-based policies) so consumers can report honest coverage.
+    """
+
+    statements: List[Statement] = field(default_factory=list)
+    boundary: List[Statement] = field(default_factory=list)
+    source: str = "unknown"
+    principal: str = "unknown"
+    fetched_at: float = field(default_factory=time.time)
+    unscoped: List[str] = field(
+        default_factory=lambda: ["scp", "resource_policy"]
+    )
+
+    @classmethod
+    def from_policy_documents(
+        cls,
+        documents: List[Dict[str, Any]],
+        boundary_documents: Optional[List[Dict[str, Any]]] = None,
+        source: str = "documents",
+        principal: str = "unknown",
+    ) -> "PolicySet":
+        """Build a PolicySet from raw policy-document dicts."""
+        statements: List[Statement] = []
+        for doc in documents:
+            for raw in _as_list(doc.get("Statement")):
+                statements.append(Statement.from_dict(raw))
+
+        boundary: List[Statement] = []
+        for doc in boundary_documents or []:
+            for raw in _as_list(doc.get("Statement")):
+                boundary.append(Statement.from_dict(raw))
+
+        return cls(
+            statements=statements,
+            boundary=boundary,
+            source=source,
+            principal=principal,
+        )
+
+    def age_seconds(self) -> float:
+        return time.time() - self.fetched_at

lambda_preflight/iam/puller.py

@@ -0,0 +1,190 @@
+"""Fetch a real IAM principal's policies and cache them.
+
+Pulling the *actual* attached/inline/boundary policies of the execution role
+means the evaluator tests against ground truth instead of a hand-written
+guess that drifts. A Lambda runs as its **execution role**, so the puller is
+role-oriented; a user ARN is accepted too for broader testing but resolved
+and labelled accurately.
+
+What can be pulled: identity policies (managed + inline) and the permission
+boundary. What cannot: SCPs and resource-based policies — these are recorded
+in ``PolicySet.unscoped`` rather than silently omitted.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .model import PolicySet
+
+DEFAULT_CACHE_DIR = Path(
+    os.environ.get(
+        "LAMBDALOCAL_CACHE_DIR",
+        str(Path.home() / ".cache" / "lambda_preflight" / "iam"),
+    )
+)
+
+
+class PullError(Exception):
+    """Raised when policies cannot be fetched (e.g. missing IAM read access)."""
+
+
+def pull_role(
+    role_name: str,
+    session: Any = None,
+    cache_dir: Optional[Path] = None,
+    max_age_seconds: Optional[float] = None,
+) -> PolicySet:
+    """Fetch (or load from cache) the merged policies for an execution role.
+
+    ``role_name`` may be a bare name or an ARN; the trailing name is used.
+    If a fresh cache entry exists (within ``max_age_seconds``, when given),
+    it is returned without an AWS call. Otherwise the live fan-out runs and
+    the result is cached.
+
+    Requires ``boto3`` and IAM read permissions for the live path. On an
+    access error, raises PullError with guidance to fall back to BYO-JSON.
+    """
+    name = role_name.split("/")[-1]
+    cache_dir = cache_dir or DEFAULT_CACHE_DIR
+
+    cached = _load_cache(name, cache_dir, max_age_seconds)
+    if cached is not None:
+        return cached
+
+    try:
+        import boto3  # local import: only needed on the live path
+    except ImportError as exc:  # pragma: no cover
+        raise PullError(
+            "boto3 is required to pull policies from AWS. Install it, or use "
+            "PolicySet.from_policy_documents() with a local policy JSON."
+        ) from exc
+
+    session = session or boto3.Session()
+    iam = session.client("iam")
+
+    try:
+        documents = _fetch_role_policy_documents(iam, name)
+        boundary_docs = _fetch_boundary_documents(iam, name)
+    except Exception as exc:  # noqa: BLE001 - normalise all AWS errors
+        raise PullError(
+            f"Could not read policies for role '{name}': {exc}. "
+            f"You may lack IAM read access; provide a policy JSON instead "
+            f"via PolicySet.from_policy_documents()."
+        ) from exc
+
+    policy_set = PolicySet.from_policy_documents(
+        documents=documents,
+        boundary_documents=boundary_docs,
+        source=f"aws:role/{name}",
+        principal=name,
+    )
+    _save_cache(name, policy_set, documents, boundary_docs, cache_dir)
+    return policy_set
+
+
+def _fetch_role_policy_documents(iam: Any, name: str) -> List[Dict[str, Any]]:
+    """Fan out across managed + inline policies for a role."""
+    documents: List[Dict[str, Any]] = []
+
+    # Attached (managed) policies -> default version document.
+    attached = iam.list_attached_role_policies(RoleName=name)
+    for pol in attached.get("AttachedPolicies", []):
+        arn = pol["PolicyArn"]
+        meta = iam.get_policy(PolicyArn=arn)["Policy"]
+        version = iam.get_policy_version(
+            PolicyArn=arn, VersionId=meta["DefaultVersionId"]
+        )
+        documents.append(version["PolicyVersion"]["Document"])
+
+    # Inline policies -> document per policy name.
+    inline = iam.list_role_policies(RoleName=name)
+    for pol_name in inline.get("PolicyNames", []):
+        doc = iam.get_role_policy(RoleName=name, PolicyName=pol_name)
+        documents.append(doc["PolicyDocument"])
+
+    return documents
+
+
+def _fetch_boundary_documents(iam: Any, name: str) -> List[Dict[str, Any]]:
+    """Fetch the permission-boundary document if one is attached."""
+    role = iam.get_role(RoleName=name)["Role"]
+    boundary = role.get("PermissionsBoundary")
+    if not boundary:
+        return []
+    arn = boundary["PermissionsBoundaryArn"]
+    meta = iam.get_policy(PolicyArn=arn)["Policy"]
+    version = iam.get_policy_version(
+        PolicyArn=arn, VersionId=meta["DefaultVersionId"]
+    )
+    return [version["PolicyVersion"]["Document"]]
+
+
+def _cache_path(name: str, cache_dir: Path) -> Path:
+    return cache_dir / f"{name}.json"
+
+
+def _load_cache(
+    name: str, cache_dir: Path, max_age_seconds: Optional[float]
+) -> Optional[PolicySet]:
+    path = _cache_path(name, cache_dir)
+    if not path.exists():
+        return None
+    try:
+        blob = json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+    fetched_at = blob.get("fetched_at", 0)
+    if max_age_seconds is not None and (time.time() - fetched_at) > max_age_seconds:
+        return None
+
+    policy_set = PolicySet.from_policy_documents(
+        documents=blob.get("documents", []),
+        boundary_documents=blob.get("boundary_documents", []),
+        source=blob.get("source", f"cache:{name}"),
+        principal=name,
+    )
+    policy_set.fetched_at = fetched_at
+    return policy_set
+
+
+def _save_cache(
+    name: str,
+    policy_set: PolicySet,
+    documents: List[Dict[str, Any]],
+    boundary_docs: List[Dict[str, Any]],
+    cache_dir: Path,
+) -> None:
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    path = _cache_path(name, cache_dir)
+    payload = {
+        "principal": name,
+        "source": policy_set.source,
+        "fetched_at": policy_set.fetched_at,
+        "documents": documents,
+        "boundary_documents": boundary_docs,
+    }
+    path.write_text(json.dumps(payload, indent=2))
+
+
+def load_role_policies(
+    role_name: str, cache_dir: Optional[Path] = None
+) -> PolicySet:
+    """Load a role's policies from cache only, without any AWS call.
+
+    Convenience for offline mode: reuse the last pull with no charges and no
+    credentials. Raises PullError if nothing is cached.
+    """
+    name = role_name.split("/")[-1]
+    cached = _load_cache(name, cache_dir or DEFAULT_CACHE_DIR, None)
+    if cached is None:
+        raise PullError(
+            f"No cached policies for '{name}'. Run pull_role() once while "
+            f"online, or supply a policy JSON."
+        )
+    return cached

lambda_preflight/runtime/__init__.py

@@ -0,0 +1,13 @@
+"""In-process Lambda runtime shim."""
+
+from .context import LambdaContext
+from .errors import HandlerLoadError, LambdaTimeout
+from .harness import InvocationResult, LambdaHarness
+
+__all__ = [
+    "LambdaHarness",
+    "InvocationResult",
+    "LambdaContext",
+    "LambdaTimeout",
+    "HandlerLoadError",
+]

lambda_preflight/runtime/context.py

@@ -0,0 +1,75 @@
+"""Faithful reproduction of the AWS Lambda ``context`` object.
+
+The context object AWS passes to a handler exposes a specific set of
+attributes and one time-sensitive method, ``get_remaining_time_in_millis``.
+Reproducing these accurately is what lets handler code that reads the
+context behave locally the way it does in AWS.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class ClientContext:
+    """Mobile SDK client context. Present in the real object; usually None."""
+
+    client: Optional[dict] = None
+    custom: Optional[dict] = None
+    env: Optional[dict] = None
+
+
+@dataclass
+class CognitoIdentity:
+    """Cognito identity context. Present in the real object; usually None."""
+
+    cognito_identity_id: Optional[str] = None
+    cognito_identity_pool_id: Optional[str] = None
+
+
+class LambdaContext:
+    """In-process stand-in for the AWS Lambda runtime context.
+
+    The remaining-time clock is backed by a real monotonic deadline so that
+    handlers which budget work against ``get_remaining_time_in_millis()``
+    observe the same countdown behaviour they would in AWS.
+    """
+
+    def __init__(
+        self,
+        function_name: str = "local-function",
+        function_version: str = "$LATEST",
+        memory_limit_in_mb: int = 128,
+        timeout_seconds: float = 3.0,
+        region: str = "us-east-1",
+        account_id: str = "000000000000",
+        aws_request_id: Optional[str] = None,
+        log_group_name: Optional[str] = None,
+        log_stream_name: Optional[str] = None,
+    ) -> None:
+        self.function_name = function_name
+        self.function_version = function_version
+        self.memory_limit_in_mb = str(memory_limit_in_mb)
+        self.aws_request_id = aws_request_id or str(uuid.uuid4())
+        self.log_group_name = log_group_name or f"/aws/lambda/{function_name}"
+        self.log_stream_name = (
+            log_stream_name
+            or f"{time.strftime('%Y/%m/%d')}/[{function_version}]{uuid.uuid4().hex}"
+        )
+        self.invoked_function_arn = (
+            f"arn:aws:lambda:{region}:{account_id}:function:{function_name}"
+        )
+        self.identity = CognitoIdentity()
+        self.client_context = ClientContext()
+
+        # Real monotonic deadline drives the remaining-time countdown.
+        self._deadline = time.monotonic() + timeout_seconds
+
+    def get_remaining_time_in_millis(self) -> int:
+        """Milliseconds left before the configured timeout, floored at 0."""
+        remaining = (self._deadline - time.monotonic()) * 1000.0
+        return max(0, int(remaining))

lambda_preflight/runtime/errors.py

@@ -0,0 +1,34 @@
+"""AWS-shape error serialization.
+
+When a handler raises an unhandled exception, the Lambda runtime returns a
+specific JSON envelope. Downstream consumers (Step Functions, Lambda
+Destinations, the invoke API) parse that exact shape, so reproducing it is
+part of behaving like AWS rather than merely running the function.
+"""
+
+from __future__ import annotations
+
+import traceback
+from typing import Any, Dict
+
+
+class LambdaTimeout(Exception):
+    """Raised when a handler exceeds its configured timeout."""
+
+
+class HandlerLoadError(Exception):
+    """Raised when the ``module.function`` handler string cannot be resolved."""
+
+
+def format_exception(exc: BaseException) -> Dict[str, Any]:
+    """Return the AWS-style error envelope for an unhandled exception.
+
+    Matches the runtime's structure: ``errorType``, ``errorMessage`` and a
+    ``stackTrace`` list of formatted frames.
+    """
+    stack = traceback.format_tb(exc.__traceback__)
+    return {
+        "errorType": type(exc).__name__,
+        "errorMessage": str(exc),
+        "stackTrace": [frame.rstrip("\n") for frame in stack],
+    }