lambda-preflight 0.1.0__tar.gz → 0.1.1__tar.gz

lambda_preflight-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest tests/ -v

lambda_preflight-0.1.1/.gitignore

@@ -0,0 +1,11 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+.pytest_cache/
+.coverage
+htmlcov/
+.venv/
+venv/
+.DS_Store

lambda_preflight-0.1.1/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.1.1] - 2026-07-21
+
+### Fixed
+- Handler-load failures (bad handler string, missing module, missing function)
+  are now returned as an error `InvocationResult` with `ok=False` and
+  `errorType="HandlerLoadError"`, instead of raising out of `invoke()`. This
+  gives callers a single consistent `result.ok` contract for both load-time and
+  runtime failures, mirroring how AWS surfaces initialization errors. A handler
+  that fails to load no longer marks the harness as "warm".
+
+### Added
+- Comprehensive test suite (128 tests) covering the runtime shim, event
+  builders, IAM evaluator, boto3 intercept, policy puller/cache, and a set of
+  adversarial cases that document known fidelity limits (`NotAction`
+  under-grant, ARN wildcard matching, resource-based-policy omission).
+
+## [0.1.0] - 2026-07-21
+
+### Added
+- Initial release.
+- In-process Lambda runtime shim: faithful `context`, timeout enforcement,
+  cold/warm semantics, AWS-shape error envelopes, environment injection.
+- Schema-accurate event builders: API Gateway v1 & v2, SQS, SNS, S3,
+  EventBridge, DynamoDB Streams.
+- Local IAM linter: policy evaluator (explicit-deny / allow / implicit-deny,
+  permission-boundary intersection), common condition operators, `pull_role`
+  fan-out with disk cache, and a boto3 intercept hook. Strict mode raises
+  `CannotEvaluate` on constructs it cannot faithfully assess.
+- pytest fixtures, auto-registered via entry point.

{lambda_preflight-0.1.0 → lambda_preflight-0.1.1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: lambda-preflight
-Version: 0.1.0
+Version: 0.1.1
 Summary: Catch AWS Lambda IAM permission errors and event-shape bugs before you deploy — a local pre-flight linter and AWS-faithful runtime. No Docker, no SAM, no invocation charges.
-Project-URL: Homepage, https://github.com/swaranshu-borgaonkar/lambda-preflight
-Project-URL: Issues, https://github.com/swaranshu-borgaonkar/lambda-preflight/issues
+Project-URL: Homepage, https://github.com/yourname/lambda-preflight
+Project-URL: Issues, https://github.com/yourname/lambda-preflight/issues
 Author: Swar Borgaonkar
 License: MIT
 License-File: LICENSE

{lambda_preflight-0.1.0 → lambda_preflight-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lambda-preflight"
-version = "0.1.0"
+version = "0.1.1"
 description = "Catch AWS Lambda IAM permission errors and event-shape bugs before you deploy — a local pre-flight linter and AWS-faithful runtime. No Docker, no SAM, no invocation charges."
 readme = "README.md"
 requires-python = ">=3.8"
@@ -42,8 +42,8 @@ aws = ["boto3>=1.26"]
 dev = ["pytest>=7.0", "boto3>=1.26", "build", "twine"]
 
 [project.urls]
-Homepage = "https://github.com/swaranshu-borgaonkar/lambda-preflight"
-Issues = "https://github.com/swaranshu-borgaonkar/lambda-preflight/issues"
+Homepage = "https://github.com/yourname/lambda-preflight"
+Issues = "https://github.com/yourname/lambda-preflight/issues"
 
 [project.entry-points.pytest11]
 lambda_preflight = "lambda_preflight.testing.fixtures"
@@ -53,3 +53,4 @@ packages = ["src/lambda_preflight"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+pythonpath = ["tests"]

{lambda_preflight-0.1.0 → lambda_preflight-0.1.1}/src/lambda_preflight/__init__.py

@@ -37,7 +37,7 @@ from .runtime import (
     LambdaTimeout,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 
 __all__ = [
     "LambdaHarness",

{lambda_preflight-0.1.0 → lambda_preflight-0.1.1}/src/lambda_preflight/runtime/harness.py

@@ -120,10 +120,14 @@ class LambdaHarness:
     def invoke(
         self, event: Any, client_context: Any = None
     ) -> InvocationResult:
-        """Invoke the handler with ``event`` and an AWS-faithful context."""
+        """Invoke the handler with ``event`` and an AWS-faithful context.
+
+        Handler-resolution failures (bad handler string, missing module or
+        function) are returned as an error ``InvocationResult`` — the same
+        channel as runtime errors — mirroring how AWS surfaces init failures,
+        so callers can rely on a single ``result.ok`` contract.
+        """
         is_cold = not self._has_run
-        handler = self._ensure_handler()
-        self._has_run = True
 
         context = LambdaContext(
             function_name=self.function_name,
@@ -149,6 +153,10 @@ class LambdaHarness:
 
         with lambda_environment(lambda_env):
             try:
+                # Resolve inside the try so handler-load failures are returned
+                # as an error result, not raised — one consistent contract.
+                handler = self._ensure_handler()
+                self._has_run = True
                 payload = _run_with_timeout(
                     handler, (event, context), self.timeout
                 )

lambda_preflight-0.1.1/tests/conftest.py

@@ -0,0 +1,6 @@
+import os
+import sys
+
+# Make handler modules (e.g. handlers.py) importable by their bare name,
+# matching how AWS resolves "module.function" handler strings.
+sys.path.insert(0, os.path.dirname(__file__))

lambda_preflight-0.1.1/tests/handlers.py

@@ -0,0 +1,93 @@
+import os, time, threading
+
+INIT_COUNTER = {"count": 0}
+INIT_COUNTER["count"] += 1  # increments once per import (cold start)
+
+_state = {"invocations": 0, "module_global": []}
+
+def echo(event, context):
+    return {"event": event, "rid": context.aws_request_id}
+
+def return_none(event, context):
+    return None
+
+def return_scalar(event, context):
+    return 42
+
+def return_list(event, context):
+    return [1, 2, {"nested": True}]
+
+def raise_value(event, context):
+    raise ValueError("bad value")
+
+def raise_custom(event, context):
+    class MyCustomError(Exception):
+        pass
+    raise MyCustomError("custom failure")
+
+def raise_keyerror(event, context):
+    d = {}
+    return d["missing"]
+
+def read_all_env(event, context):
+    return {k: os.environ.get(k) for k in [
+        "AWS_LAMBDA_FUNCTION_NAME", "AWS_LAMBDA_FUNCTION_VERSION",
+        "AWS_LAMBDA_FUNCTION_MEMORY_SIZE", "AWS_REGION", "AWS_DEFAULT_REGION",
+        "AWS_EXECUTION_ENV", "_HANDLER", "AWS_LAMBDA_LOG_GROUP_NAME",
+        "AWS_LAMBDA_LOG_STREAM_NAME", "TZ",
+    ]}
+
+def custom_env_reader(event, context):
+    return os.environ.get("MY_CUSTOM_VAR", "NOT_SET")
+
+def env_leak_check(event, context):
+    # returns whether a sentinel that shouldn't exist outside is present
+    return os.environ.get("AWS_LAMBDA_FUNCTION_NAME")
+
+def sleep_long(event, context):
+    time.sleep(5)
+    return "finished"
+
+def sleep_short(event, context):
+    time.sleep(0.05)
+    return "quick"
+
+def remaining_time(event, context):
+    return {"remaining": context.get_remaining_time_in_millis()}
+
+def remaining_time_after_sleep(event, context):
+    start = context.get_remaining_time_in_millis()
+    time.sleep(0.1)
+    end = context.get_remaining_time_in_millis()
+    return {"start": start, "end": end}
+
+def module_global_accumulate(event, context):
+    _state["module_global"].append(event.get("n"))
+    return list(_state["module_global"])
+
+def invocation_counter(event, context):
+    _state["invocations"] += 1
+    return _state["invocations"]
+
+def uses_context_fields(event, context):
+    return {
+        "function_name": context.function_name,
+        "function_version": context.function_version,
+        "memory": context.memory_limit_in_mb,
+        "arn": context.invoked_function_arn,
+        "log_group": context.log_group_name,
+        "log_stream": context.log_stream_name,
+    }
+
+def thread_check(event, context):
+    # Confirms handler runs and can spawn its own threads
+    results = []
+    def work():
+        results.append("worked")
+    t = threading.Thread(target=work)
+    t.start(); t.join()
+    return results
+
+def mutate_event(event, context):
+    event["injected"] = True
+    return event

lambda_preflight-0.1.1/tests/test_adversarial.py

@@ -0,0 +1,137 @@
+"""Adversarial edge cases — probing the documented fidelity limits.
+
+Several of these assert the CURRENT (imperfect) behavior deliberately, to make
+the known gaps visible and regression-proof rather than silently wrong.
+"""
+import pytest
+from lambda_preflight import PolicySet, PolicyEvaluator
+from lambda_preflight.iam import operation_to_action
+
+
+def P(*stmts):
+    return PolicySet.from_policy_documents(documents=[{"Statement": list(stmts)}])
+
+def allow(a, r="*", **k):
+    d = {"Effect": "Allow", "Action": a, "Resource": r}; d.update(k); return d
+
+
+# ===== ARN matching fidelity (KNOWN GAP: fnmatch treats ':' as ordinary) =====
+
+def test_arn_wildcard_crosses_colon_boundary():
+    """A '*' in a policy ARN can greedily cross ':' segments — NOT how IAM
+    matches. This documents the divergence: fnmatch '*' matches across colons."""
+    ev = PolicyEvaluator(P(allow("s3:GetObject", "arn:aws:s3:::bucket*")))
+    # Intended: bucket-prefixed. fnmatch '*' also matches deeper — verify current:
+    r = ev.evaluate("s3:GetObject", "arn:aws:s3:::bucket-a/deep/key")
+    # Current behavior: matches (star is greedy). Real IAM: also matches here
+    # because '*' spans '/'. This one happens to agree.
+    assert r.allowed is True
+
+def test_arn_question_mark_wildcard():
+    """IAM supports '?' single-char wildcard; fnmatch does too."""
+    ev = PolicyEvaluator(P(allow("s3:GetObject", "arn:aws:s3:::bucket-?")))
+    assert ev.evaluate("s3:GetObject", "arn:aws:s3:::bucket-1").allowed
+    assert not ev.evaluate("s3:GetObject", "arn:aws:s3:::bucket-12").allowed
+
+def test_arn_case_sensitivity_of_resource():
+    """Resource ARNs are case-sensitive in IAM; verify matcher respects case."""
+    ev = PolicyEvaluator(P(allow("s3:GetObject", "arn:aws:s3:::MyBucket/*")))
+    assert ev.evaluate("s3:GetObject", "arn:aws:s3:::MyBucket/k").allowed
+    # different case bucket should NOT match
+    assert not ev.evaluate("s3:GetObject", "arn:aws:s3:::mybucket/k").allowed
+
+
+# ===== NotAction / NotResource (KNOWN GAP: not implemented) =====
+
+def test_notaction_not_supported_documents_behavior():
+    """Policies using NotAction aren't modeled. A statement with NotAction has
+    no 'Action' key -> our parser gives empty actions -> matches nothing.
+    This means NotAction-based Allows are effectively ignored (under-grant)."""
+    ps = PolicySet.from_policy_documents(documents=[{"Statement": [
+        {"Effect": "Allow", "NotAction": "s3:DeleteObject", "Resource": "*"}]}])
+    ev = PolicyEvaluator(ps)
+    # Real IAM: this ALLOWS everything except delete. Our tool: allows nothing.
+    # Document the divergence explicitly:
+    assert ev.evaluate("s3:GetObject").allowed is False  # KNOWN under-grant
+
+
+# ===== Principal / cross-account (out of scope) =====
+
+def test_resource_policy_absent_documented():
+    """Resource-based policies aren't modeled; unscoped records this."""
+    ps = P(allow("s3:GetObject"))
+    assert "resource_policy" in ps.unscoped
+
+
+# ===== Condition operator edge cases =====
+
+def test_condition_ifexists_variant():
+    """StringEqualsIfExists passes when the key is absent."""
+    ev = PolicyEvaluator(P(allow("s3:GetObject", "*",
+        Condition={"StringEqualsIfExists": {"aws:username": "admin"}})))
+    # key absent -> IfExists means condition passes
+    d = ev.evaluate("s3:GetObject")
+    assert d.allowed is True
+
+def test_condition_multiple_keys_all_must_pass():
+    ev = PolicyEvaluator(P(allow("s3:GetObject", "*",
+        Condition={"StringEquals": {"aws:RequestedRegion": "us-east-1",
+                                     "s3:prefix": "home/"}})))
+    # both match
+    assert ev.evaluate("s3:GetObject", context={
+        "aws:RequestedRegion": "us-east-1", "s3:prefix": "home/"}).allowed
+    # one fails -> deny
+    assert not ev.evaluate("s3:GetObject", context={
+        "aws:RequestedRegion": "us-east-1", "s3:prefix": "other/"}).allowed
+
+def test_condition_multiple_values_or_semantics():
+    """A list of condition values is OR — any match passes (StringEquals)."""
+    ev = PolicyEvaluator(P(allow("s3:GetObject", "*",
+        Condition={"StringEquals": {"aws:RequestedRegion": ["us-east-1", "eu-west-1"]}})))
+    assert ev.evaluate("s3:GetObject", context={"aws:RequestedRegion": "eu-west-1"}).allowed
+    assert not ev.evaluate("s3:GetObject", context={"aws:RequestedRegion": "ap-south-1"}).allowed
+
+
+# ===== Unknown service mapping =====
+
+def test_unknown_service_passthrough_mapping():
+    """A service not in the override map falls back to service:Operation."""
+    assert operation_to_action("kinesis", "PutRecord") == "kinesis:PutRecord"
+    assert operation_to_action("some-new-svc", "DoThing") == "some-new-svc:DoThing"
+
+
+# ===== Empty / malformed inputs =====
+
+def test_empty_action_list():
+    ps = PolicySet.from_policy_documents(documents=[{"Statement": [
+        {"Effect": "Allow", "Action": [], "Resource": "*"}]}])
+    ev = PolicyEvaluator(ps)
+    assert not ev.evaluate("s3:GetObject").allowed
+
+def test_statement_without_resource_defaults_star():
+    ps = PolicySet.from_policy_documents(documents=[{"Statement": [
+        {"Effect": "Allow", "Action": "s3:GetObject"}]}])  # no Resource
+    ev = PolicyEvaluator(ps)
+    assert ev.evaluate("s3:GetObject", "arn:aws:s3:::anything").allowed
+
+def test_missing_effect_defaults_deny():
+    ps = PolicySet.from_policy_documents(documents=[{"Statement": [
+        {"Action": "s3:GetObject", "Resource": "*"}]}])  # no Effect
+    ev = PolicyEvaluator(ps)
+    # defaults to Deny -> not an allow
+    assert not ev.evaluate("s3:GetObject").allowed
+
+
+# ===== Sid tracking =====
+
+def test_matched_sid_reported():
+    ev = PolicyEvaluator(P(allow("s3:GetObject", "*", Sid="AllowRead")))
+    d = ev.evaluate("s3:GetObject")
+    assert d.allowed and d.matched_sid == "AllowRead"
+
+def test_deny_sid_reported():
+    ev = PolicyEvaluator(P(allow("s3:*"),
+        {"Effect": "Deny", "Action": "s3:DeleteObject", "Resource": "*",
+         "Sid": "NoDelete"}))
+    d = ev.evaluate("s3:DeleteObject")
+    assert not d.allowed and d.matched_sid == "NoDelete"

lambda_preflight-0.1.1/tests/test_events_exhaustive.py

@@ -0,0 +1,165 @@
+import json
+import pytest
+from lambda_preflight import events
+
+
+# ---------- API Gateway v1 ----------
+def test_v1_method_uppercased():
+    assert events.api_gateway_v1(method="post")["httpMethod"] == "POST"
+
+def test_v1_body_serialized_to_string():
+    e = events.api_gateway_v1(body={"k": "v"})
+    assert isinstance(e["body"], str) and json.loads(e["body"]) == {"k": "v"}
+
+def test_v1_string_body_passthrough():
+    e = events.api_gateway_v1(body="raw string")
+    assert e["body"] == "raw string"
+
+def test_v1_none_body():
+    assert events.api_gateway_v1()["body"] is None
+
+def test_v1_has_multivalue_headers():
+    e = events.api_gateway_v1(headers={"X-Test": "1"})
+    assert e["multiValueHeaders"]["X-Test"] == ["1"]
+
+def test_v1_query_multivalue():
+    e = events.api_gateway_v1(query={"q": "search"})
+    assert e["multiValueQueryStringParameters"]["q"] == ["search"]
+
+def test_v1_requestcontext_shape():
+    e = events.api_gateway_v1(method="DELETE", path="/x", stage="dev")
+    rc = e["requestContext"]
+    assert rc["httpMethod"] == "DELETE"
+    assert rc["stage"] == "dev"
+    assert rc["path"] == "/dev/x"
+    assert "identity" in rc and rc["identity"]["sourceIp"]
+
+def test_v1_path_parameters():
+    e = events.api_gateway_v1(path_parameters={"id": "123"})
+    assert e["pathParameters"] == {"id": "123"}
+
+
+# ---------- API Gateway v2 ----------
+def test_v2_version_marker():
+    assert events.api_gateway_v2()["version"] == "2.0"
+
+def test_v2_route_key():
+    assert events.api_gateway_v2(method="post", path="/o")["routeKey"] == "POST /o"
+
+def test_v2_raw_path_and_query():
+    e = events.api_gateway_v2(path="/search", query={"q": "x", "n": "5"})
+    assert e["rawPath"] == "/search"
+    assert "q=x" in e["rawQueryString"] and "n=5" in e["rawQueryString"]
+
+def test_v2_http_block():
+    e = events.api_gateway_v2(method="patch", path="/p")
+    assert e["requestContext"]["http"]["method"] == "PATCH"
+    assert e["requestContext"]["http"]["path"] == "/p"
+
+def test_v2_has_cookies_field():
+    assert "cookies" in events.api_gateway_v2()
+
+def test_v2_body_serialized():
+    e = events.api_gateway_v2(body={"id": 9})
+    assert json.loads(e["body"]) == {"id": 9}
+
+
+# ---------- v1 vs v2 divergence ----------
+def test_v1_v2_structural_difference():
+    v1, v2 = events.api_gateway_v1(), events.api_gateway_v2()
+    assert "httpMethod" in v1 and "httpMethod" not in v2
+    assert "version" in v2 and "version" not in v1
+    assert "rawPath" in v2 and "rawPath" not in v1
+
+
+# ---------- SQS ----------
+def test_sqs_single():
+    e = events.sqs(body={"o": 1})
+    assert len(e["Records"]) == 1
+    assert json.loads(e["Records"][0]["body"]) == {"o": 1}
+
+def test_sqs_batch_count():
+    e = events.sqs(records=[{"a": 1}, {"b": 2}, {"c": 3}])
+    assert len(e["Records"]) == 3
+
+def test_sqs_record_fields():
+    rec = events.sqs(body="x")["Records"][0]
+    for f in ["messageId", "receiptHandle", "body", "attributes",
+              "messageAttributes", "md5OfBody", "eventSource", "eventSourceARN"]:
+        assert f in rec
+    assert rec["eventSource"] == "aws:sqs"
+
+def test_sqs_arn_format():
+    rec = events.sqs(body="x", queue_name="myq", region="eu-central-1")["Records"][0]
+    assert rec["eventSourceARN"] == "arn:aws:sqs:eu-central-1:000000000000:myq"
+
+def test_sqs_unique_message_ids():
+    e = events.sqs(records=[{}, {}, {}])
+    ids = {r["messageId"] for r in e["Records"]}
+    assert len(ids) == 3
+
+def test_sqs_message_attributes_passthrough():
+    attrs = {"attr1": {"DataType": "String", "StringValue": "v"}}
+    rec = events.sqs(body="x", message_attributes=attrs)["Records"][0]
+    assert rec["messageAttributes"] == attrs
+
+
+# ---------- SNS ----------
+def test_sns_shape():
+    rec = events.sns(message={"m": 1}, subject="subj")["Records"][0]
+    assert rec["EventSource"] == "aws:sns"
+    assert rec["Sns"]["Subject"] == "subj"
+    assert json.loads(rec["Sns"]["Message"]) == {"m": 1}
+
+def test_sns_string_message():
+    rec = events.sns(message="plain")["Records"][0]
+    assert rec["Sns"]["Message"] == "plain"
+
+
+# ---------- S3 ----------
+def test_s3_shape():
+    rec = events.s3(bucket="b", key="path/to/k.txt", size=2048)["Records"][0]
+    assert rec["eventSource"] == "aws:s3"
+    assert rec["s3"]["bucket"]["name"] == "b"
+    assert rec["s3"]["bucket"]["arn"] == "arn:aws:s3:::b"
+    assert rec["s3"]["object"]["key"] == "path/to/k.txt"
+    assert rec["s3"]["object"]["size"] == 2048
+
+def test_s3_event_name():
+    rec = events.s3(event_name="ObjectRemoved:Delete")["Records"][0]
+    assert rec["eventName"] == "ObjectRemoved:Delete"
+
+
+# ---------- EventBridge ----------
+def test_eventbridge_shape():
+    e = events.eventbridge(detail={"k": "v"}, detail_type="t", source="s")
+    assert e["detail-type"] == "t"
+    assert e["source"] == "s"
+    assert e["detail"] == {"k": "v"}
+    assert e["version"] == "0"
+
+def test_eventbridge_empty_detail():
+    assert events.eventbridge()["detail"] == {}
+
+
+# ---------- DynamoDB ----------
+def test_dynamodb_insert():
+    rec = events.dynamodb_stream(keys={"id": {"S": "1"}},
+                                 new_image={"id": {"S": "1"}, "v": {"N": "5"}},
+                                 event_name="INSERT")["Records"][0]
+    assert rec["eventSource"] == "aws:dynamodb"
+    assert rec["eventName"] == "INSERT"
+    assert rec["dynamodb"]["Keys"] == {"id": {"S": "1"}}
+    assert rec["dynamodb"]["NewImage"]["v"] == {"N": "5"}
+
+def test_dynamodb_no_new_image_when_absent():
+    rec = events.dynamodb_stream(keys={"id": {"S": "1"}}, event_name="REMOVE")["Records"][0]
+    assert "NewImage" not in rec["dynamodb"]
+
+def test_dynamodb_modify_with_old_image():
+    rec = events.dynamodb_stream(keys={"id": {"S": "1"}},
+                                 new_image={"v": {"N": "2"}},
+                                 old_image={"v": {"N": "1"}},
+                                 event_name="MODIFY")["Records"][0]
+    assert rec["dynamodb"]["OldImage"] == {"v": {"N": "1"}}
+    assert rec["dynamodb"]["NewImage"] == {"v": {"N": "2"}}