lambda-preflight 0.1.0__py3-none-any.whl

lambda_preflight/__init__.py

@@ -0,0 +1,58 @@
+"""lambda_preflight — catch AWS Lambda IAM and event-shape bugs before you deploy.
+
+The headline feature is a local **IAM linter**: it evaluates the AWS calls your
+handler makes against your execution role's *real, pulled* policies and raises
+AccessDenied locally — catching the permission mistakes you'd otherwise only
+discover after deploying. Nothing else in the ecosystem does this.
+
+Around it sits an AWS-faithful local runtime so the linter has something real to
+run against: schema-accurate event fixtures, a faithful context object, timeout
+enforcement, cold/warm semantics, and AWS-shape error envelopes. No Docker, no
+SAM CLI, no cloud invocations (no invocation charges).
+
+Honest scope: this eliminates the shape/contract/runtime-semantics class of
+"works locally, breaks in AWS" failures. It does not and cannot reproduce
+cold-start latency, live concurrency, SCPs, resource-based policies, or
+account quotas — those exist only in the cloud. The IAM layer is a fast
+pre-flight linter, not a parity guarantee, and fails loud (strict mode) on
+anything it cannot faithfully evaluate.
+"""
+
+from . import events
+from .iam import (
+    AccessDenied,
+    CannotEvaluate,
+    PolicyEvaluator,
+    PolicySet,
+    PullError,
+    intercept_boto3,
+    load_role_policies,
+    pull_role,
+)
+from .runtime import (
+    HandlerLoadError,
+    InvocationResult,
+    LambdaContext,
+    LambdaHarness,
+    LambdaTimeout,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "LambdaHarness",
+    "InvocationResult",
+    "LambdaContext",
+    "LambdaTimeout",
+    "HandlerLoadError",
+    "events",
+    "PolicyEvaluator",
+    "PolicySet",
+    "pull_role",
+    "load_role_policies",
+    "intercept_boto3",
+    "AccessDenied",
+    "CannotEvaluate",
+    "PullError",
+    "__version__",
+]

lambda_preflight/events/__init__.py

@@ -0,0 +1,21 @@
+"""Schema-accurate event builders for common Lambda triggers."""
+
+from .builders import (
+    api_gateway_v1,
+    api_gateway_v2,
+    dynamodb_stream,
+    eventbridge,
+    s3,
+    sns,
+    sqs,
+)
+
+__all__ = [
+    "api_gateway_v1",
+    "api_gateway_v2",
+    "sqs",
+    "sns",
+    "s3",
+    "eventbridge",
+    "dynamodb_stream",
+]

lambda_preflight/events/builders.py

@@ -0,0 +1,287 @@
+"""Schema-accurate event builders.
+
+The most common cause of "worked locally, broke in AWS" is an event whose
+*shape* differs from what the trigger actually delivers. These builders emit
+payloads matching AWS's documented schemas so a handler exercised locally
+receives the same structure it will in production.
+
+Notably, API Gateway REST (v1) and HTTP (v2) differ meaningfully, so they are
+separate builders rather than a single parameterised one.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import time
+import uuid
+from typing import Any, Dict, List, Optional
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def _epoch() -> int:
+    return int(time.time())
+
+
+def api_gateway_v1(
+    method: str = "GET",
+    path: str = "/",
+    body: Any = None,
+    headers: Optional[Dict[str, str]] = None,
+    query: Optional[Dict[str, str]] = None,
+    path_parameters: Optional[Dict[str, str]] = None,
+    stage: str = "prod",
+    is_base64: bool = False,
+) -> Dict[str, Any]:
+    """API Gateway REST API (payload format 1.0) proxy event."""
+    headers = headers or {"Content-Type": "application/json"}
+    raw_body = _serialize_body(body)
+    return {
+        "resource": path,
+        "path": path,
+        "httpMethod": method.upper(),
+        "headers": headers,
+        "multiValueHeaders": {k: [v] for k, v in headers.items()},
+        "queryStringParameters": query,
+        "multiValueQueryStringParameters": (
+            {k: [v] for k, v in query.items()} if query else None
+        ),
+        "pathParameters": path_parameters,
+        "stageVariables": None,
+        "requestContext": {
+            "resourceId": uuid.uuid4().hex[:6],
+            "resourcePath": path,
+            "httpMethod": method.upper(),
+            "path": f"/{stage}{path}",
+            "accountId": "000000000000",
+            "protocol": "HTTP/1.1",
+            "stage": stage,
+            "requestId": str(uuid.uuid4()),
+            "requestTimeEpoch": _now_ms(),
+            "identity": {"sourceIp": "127.0.0.1", "userAgent": "lambda_preflight"},
+            "apiId": uuid.uuid4().hex[:10],
+        },
+        "body": raw_body,
+        "isBase64Encoded": is_base64,
+    }
+
+
+def api_gateway_v2(
+    method: str = "GET",
+    path: str = "/",
+    body: Any = None,
+    headers: Optional[Dict[str, str]] = None,
+    query: Optional[Dict[str, str]] = None,
+    path_parameters: Optional[Dict[str, str]] = None,
+    stage: str = "$default",
+    is_base64: bool = False,
+) -> Dict[str, Any]:
+    """API Gateway HTTP API (payload format 2.0) event.
+
+    Differs from v1: single ``rawPath``/``rawQueryString``, a ``routeKey``,
+    ``cookies`` split out, and a flattened ``http`` block in requestContext.
+    """
+    headers = headers or {"content-type": "application/json"}
+    raw_body = _serialize_body(body)
+    raw_query = "&".join(f"{k}={v}" for k, v in (query or {}).items())
+    return {
+        "version": "2.0",
+        "routeKey": f"{method.upper()} {path}",
+        "rawPath": path,
+        "rawQueryString": raw_query,
+        "cookies": [],
+        "headers": headers,
+        "queryStringParameters": query,
+        "pathParameters": path_parameters,
+        "requestContext": {
+            "accountId": "000000000000",
+            "apiId": uuid.uuid4().hex[:10],
+            "domainName": "local.execute-api.us-east-1.amazonaws.com",
+            "http": {
+                "method": method.upper(),
+                "path": path,
+                "protocol": "HTTP/1.1",
+                "sourceIp": "127.0.0.1",
+                "userAgent": "lambda_preflight",
+            },
+            "requestId": str(uuid.uuid4()),
+            "routeKey": f"{method.upper()} {path}",
+            "stage": stage,
+            "time": time.strftime("%d/%b/%Y:%H:%M:%S +0000"),
+            "timeEpoch": _now_ms(),
+        },
+        "body": raw_body,
+        "isBase64Encoded": is_base64,
+    }
+
+
+def sqs(
+    records: Optional[List[Any]] = None,
+    body: Any = None,
+    queue_name: str = "local-queue",
+    region: str = "us-east-1",
+    message_attributes: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """SQS event. Pass ``records`` for a batch, or ``body`` for one message."""
+    if records is None:
+        records = [body if body is not None else {}]
+
+    arn = f"arn:aws:sqs:{region}:000000000000:{queue_name}"
+    built = []
+    for item in records:
+        raw = _serialize_body(item)
+        built.append(
+            {
+                "messageId": str(uuid.uuid4()),
+                "receiptHandle": base64.b64encode(uuid.uuid4().bytes).decode(),
+                "body": raw,
+                "attributes": {
+                    "ApproximateReceiveCount": "1",
+                    "SentTimestamp": str(_now_ms()),
+                    "SenderId": "AIDAIENQZJOLO23YVJ4VO",
+                    "ApproximateFirstReceiveTimestamp": str(_now_ms()),
+                },
+                "messageAttributes": message_attributes or {},
+                "md5OfBody": hashlib.md5(raw.encode()).hexdigest(),
+                "eventSource": "aws:sqs",
+                "eventSourceARN": arn,
+                "awsRegion": region,
+            }
+        )
+    return {"Records": built}
+
+
+def sns(
+    message: Any = None,
+    subject: Optional[str] = None,
+    topic_name: str = "local-topic",
+    region: str = "us-east-1",
+) -> Dict[str, Any]:
+    """SNS event (single record, as SNS delivers)."""
+    arn = f"arn:aws:sns:{region}:000000000000:{topic_name}"
+    raw = _serialize_body(message)
+    return {
+        "Records": [
+            {
+                "EventSource": "aws:sns",
+                "EventVersion": "1.0",
+                "EventSubscriptionArn": f"{arn}:{uuid.uuid4()}",
+                "Sns": {
+                    "Type": "Notification",
+                    "MessageId": str(uuid.uuid4()),
+                    "TopicArn": arn,
+                    "Subject": subject,
+                    "Message": raw,
+                    "Timestamp": time.strftime("%Y-%m-%dT%H:%M:%S.000Z"),
+                    "SignatureVersion": "1",
+                    "MessageAttributes": {},
+                },
+            }
+        ]
+    }
+
+
+def s3(
+    bucket: str = "local-bucket",
+    key: str = "object.txt",
+    event_name: str = "ObjectCreated:Put",
+    size: int = 1024,
+    region: str = "us-east-1",
+) -> Dict[str, Any]:
+    """S3 notification event (single record)."""
+    return {
+        "Records": [
+            {
+                "eventVersion": "2.1",
+                "eventSource": "aws:s3",
+                "awsRegion": region,
+                "eventTime": time.strftime("%Y-%m-%dT%H:%M:%S.000Z"),
+                "eventName": event_name,
+                "s3": {
+                    "s3SchemaVersion": "1.0",
+                    "configurationId": "local-config",
+                    "bucket": {
+                        "name": bucket,
+                        "arn": f"arn:aws:s3:::{bucket}",
+                    },
+                    "object": {
+                        "key": key,
+                        "size": size,
+                        "eTag": uuid.uuid4().hex,
+                        "sequencer": uuid.uuid4().hex[:16].upper(),
+                    },
+                },
+            }
+        ]
+    }
+
+
+def eventbridge(
+    detail: Optional[Dict[str, Any]] = None,
+    detail_type: str = "local.event",
+    source: str = "lambda_preflight",
+    region: str = "us-east-1",
+) -> Dict[str, Any]:
+    """EventBridge (CloudWatch Events) event."""
+    return {
+        "version": "0",
+        "id": str(uuid.uuid4()),
+        "detail-type": detail_type,
+        "source": source,
+        "account": "000000000000",
+        "time": time.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "region": region,
+        "resources": [],
+        "detail": detail or {},
+    }
+
+
+def dynamodb_stream(
+    keys: Optional[Dict[str, Any]] = None,
+    new_image: Optional[Dict[str, Any]] = None,
+    old_image: Optional[Dict[str, Any]] = None,
+    event_name: str = "INSERT",
+    table_name: str = "local-table",
+    region: str = "us-east-1",
+) -> Dict[str, Any]:
+    """DynamoDB Streams event (single record, values in DDB JSON form)."""
+    arn = (
+        f"arn:aws:dynamodb:{region}:000000000000:table/{table_name}"
+        f"/stream/{time.strftime('%Y-%m-%dT%H:%M:%S.000')}"
+    )
+    record_body: Dict[str, Any] = {
+        "Keys": keys or {},
+        "SequenceNumber": str(_now_ms()),
+        "SizeBytes": 64,
+        "StreamViewType": "NEW_AND_OLD_IMAGES",
+    }
+    if new_image is not None:
+        record_body["NewImage"] = new_image
+    if old_image is not None:
+        record_body["OldImage"] = old_image
+    return {
+        "Records": [
+            {
+                "eventID": uuid.uuid4().hex,
+                "eventName": event_name,
+                "eventVersion": "1.1",
+                "eventSource": "aws:dynamodb",
+                "awsRegion": region,
+                "dynamodb": record_body,
+                "eventSourceARN": arn,
+            }
+        ]
+    }
+
+
+def _serialize_body(body: Any) -> Optional[str]:
+    """Match AWS: bodies arrive as strings. dict/list -> JSON, None -> None."""
+    if body is None:
+        return None
+    if isinstance(body, str):
+        return body
+    return json.dumps(body)

lambda_preflight/iam/__init__.py

@@ -0,0 +1,32 @@
+"""Local IAM evaluation: pull real policies, evaluate calls, fail loud.
+
+Scope: identity policies (managed + inline) and permission boundary, with the
+documented deny/allow/implicit-deny flow and common condition operators. SCPs
+and resource-based policies are out of scope and recorded as such — this is a
+fast pre-flight linter, not an IAM parity guarantee.
+"""
+
+from .evaluator import (
+    AccessDenied,
+    CannotEvaluate,
+    Decision,
+    PolicyEvaluator,
+)
+from .intercept import BotoIntercept, intercept_boto3, operation_to_action
+from .model import PolicySet, Statement
+from .puller import PullError, load_role_policies, pull_role
+
+__all__ = [
+    "PolicyEvaluator",
+    "Decision",
+    "AccessDenied",
+    "CannotEvaluate",
+    "PolicySet",
+    "Statement",
+    "pull_role",
+    "load_role_policies",
+    "PullError",
+    "intercept_boto3",
+    "BotoIntercept",
+    "operation_to_action",
+]

lambda_preflight/iam/conditions.py

@@ -0,0 +1,131 @@
+"""Condition-operator evaluation and wildcard matching.
+
+IAM's real bite lives in ``Condition`` blocks and wildcard action/resource
+matching. This module implements the commonly used operators. Operators that
+are *not* implemented are reported (not silently treated as true) so strict
+mode can fail loudly rather than produce a false allow.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import ipaddress
+from typing import Any, Dict, List, Tuple
+
+# Operators this module can evaluate. Anything outside this set is surfaced
+# as "unevaluable" rather than assumed to pass.
+SUPPORTED_OPERATORS = {
+    "StringEquals",
+    "StringNotEquals",
+    "StringLike",
+    "StringNotLike",
+    "Bool",
+    "NumericEquals",
+    "NumericLessThan",
+    "NumericGreaterThan",
+    "IpAddress",
+    "NotIpAddress",
+    "ArnLike",
+    "ArnEquals",
+}
+
+
+def wildcard_match(pattern: str, value: str) -> bool:
+    """IAM ``*``/``?`` wildcard match (case-insensitive for actions)."""
+    return fnmatch.fnmatchcase(value, pattern)
+
+
+def action_matches(pattern: str, action: str) -> bool:
+    """Match an action against a policy action pattern, case-insensitively."""
+    return fnmatch.fnmatchcase(action.lower(), pattern.lower())
+
+
+def resource_matches(pattern: str, resource: str) -> bool:
+    """Match a resource ARN against a policy resource pattern."""
+    if pattern == "*":
+        return True
+    return fnmatch.fnmatchcase(resource, pattern)
+
+
+def _coerce_list(value: Any) -> List[str]:
+    if isinstance(value, list):
+        return [str(v) for v in value]
+    return [str(value)]
+
+
+def evaluate_condition(
+    condition: Dict[str, Dict[str, Any]], context: Dict[str, Any]
+) -> Tuple[bool, List[str]]:
+    """Evaluate a statement's Condition block against a request context.
+
+    Returns ``(passed, unevaluable_operators)``. A condition with no operators
+    passes trivially. Any operator not in SUPPORTED_OPERATORS is added to the
+    unevaluable list so the caller (strict mode) can decide how to treat it.
+    """
+    unevaluable: List[str] = []
+    if not condition:
+        return True, unevaluable
+
+    for operator, mapping in condition.items():
+        base_op = operator.replace("IfExists", "")
+        if base_op not in SUPPORTED_OPERATORS:
+            unevaluable.append(operator)
+            continue
+
+        for key, expected in mapping.items():
+            actual = context.get(key)
+            if actual is None:
+                # Key absent from context. For *IfExists, treat as pass;
+                # otherwise the condition cannot be satisfied.
+                if operator.endswith("IfExists"):
+                    continue
+                return False, unevaluable
+
+            if not _apply_operator(base_op, actual, _coerce_list(expected)):
+                return False, unevaluable
+
+    return True, unevaluable
+
+
+def _apply_operator(op: str, actual: Any, expected: List[str]) -> bool:
+    actual_str = str(actual)
+
+    if op == "StringEquals":
+        return actual_str in expected
+    if op == "StringNotEquals":
+        return actual_str not in expected
+    if op == "StringLike":
+        return any(wildcard_match(p, actual_str) for p in expected)
+    if op == "StringNotLike":
+        return not any(wildcard_match(p, actual_str) for p in expected)
+    if op == "Bool":
+        return any(
+            str(actual).lower() == e.lower() for e in expected
+        )
+    if op == "NumericEquals":
+        return any(float(actual) == float(e) for e in expected)
+    if op == "NumericLessThan":
+        return all(float(actual) < float(e) for e in expected)
+    if op == "NumericGreaterThan":
+        return all(float(actual) > float(e) for e in expected)
+    if op in ("IpAddress", "NotIpAddress"):
+        inside = _ip_in_any(actual_str, expected)
+        return inside if op == "IpAddress" else not inside
+    if op in ("ArnLike", "ArnEquals"):
+        return any(wildcard_match(p, actual_str) for p in expected)
+
+    return False
+
+
+def _ip_in_any(addr: str, cidrs: List[str]) -> bool:
+    try:
+        ip = ipaddress.ip_address(addr)
+    except ValueError:
+        return False
+    for cidr in cidrs:
+        try:
+            if ip in ipaddress.ip_network(cidr, strict=False):
+                return True
+        except ValueError:
+            continue
+    return False