permitprobe 0.1.1__py3-none-any.whl

permitprobe/__init__.py

@@ -0,0 +1,3 @@
+"""PermitProbe: explicit boundaries, reproducible checks, scoped conclusions."""
+
+__version__ = "0.1.1"

permitprobe/__main__.py

@@ -0,0 +1,3 @@
+from permitprobe.cli import main
+
+raise SystemExit(main())

permitprobe/api.py

@@ -0,0 +1,266 @@
+"""Overstep plans/classifies; PermitProbe adds strict delivery and data contracts.
+
+Only the compiled GET-only REST subset is accepted. No upstream fixtures, auth
+providers, MCP commands, waivers, or raw upstream reports are executed/written.
+"""
+
+import asyncio
+import json
+import os
+from importlib.metadata import version
+
+import httpx
+from jsonschema import Draft202012Validator
+from overstep.matrix import Matrix
+from overstep.models import Effect, Observation
+from overstep.pipeline import run_pipeline
+from overstep.planner import plan
+
+from permitprobe.policy import API
+from permitprobe.report import Report
+
+OVERSTEP_VERSION = "1.5.0"
+DENIAL_STATUSES = {401, 403, 404}
+
+
+async def fetch(url: str, headers: dict[str, str], config: API) -> tuple[int, str]:
+    # Absolute deadline includes connect, headers, and a trickling response body.
+    # A per-read socket timeout alone cannot bound a slow-drip server.
+    async with asyncio.timeout(config.timeout_seconds):
+        # New client per case: cookies cannot cross identity boundaries.
+        async with httpx.AsyncClient(
+            trust_env=False, follow_redirects=False, timeout=config.timeout_seconds
+        ) as client:
+            async with client.stream("GET", url, headers=headers) as response:
+                if response.headers.get("content-encoding", "identity") != "identity":
+                    raise ValueError("encoded response")
+                body = bytearray()
+                async for chunk in response.aiter_raw():
+                    if len(body) + len(chunk) > config.max_response_bytes:
+                        raise ValueError("response budget exceeded")
+                    body.extend(chunk)
+                return response.status_code, body.decode("utf-8")
+
+
+def compile_matrix(config: API, *, resolve_tokens: bool = False) -> dict:
+    subjects = []
+    seen_tokens = set()
+    for s in config.subjects:
+        token = None
+        if s.token_env:
+            token = "${" + s.token_env + "}"
+            if resolve_tokens:
+                token = os.environ.get(s.token_env, "")
+                if (
+                    not token
+                    or token in seen_tokens
+                    or len(token) > 8192
+                    or any(ord(c) < 33 or ord(c) > 126 for c in token)
+                ):
+                    raise ValueError("missing, duplicated, or invalid subject credential")
+                seen_tokens.add(token)
+        subjects.append(
+            {
+                "name": s.name,
+                "role": s.role,
+                "token": token,
+                "attributes": s.attributes,
+                "marker": s.marker,
+            }
+        )
+    resources = []
+    for r in config.resources:
+        item = {"name": r.name, "type": r.kind, "request": {"method": "GET", "path": r.path}}
+        if r.kind == "object":
+            item.update(owner=r.owner_param, owner_attr=r.owner_attr)
+        resources.append(item)
+    return {
+        "roles": list(dict.fromkeys(["anonymous", *[s.role for s in config.subjects]])),
+        "modules": {"rest": {"base_url": config.base_url}},
+        "subjects": subjects,
+        "resources": resources,
+        "policy": {r.name: {"allow": [a.model_dump() for a in r.allow]} for r in config.resources},
+    }
+
+
+def pointer_value(data, pointer: str):
+    value = data
+    for key in pointer[1:].split("/"):
+        key = key.replace("~1", "/").replace("~0", "~")
+        if isinstance(value, list):
+            if not key.isdecimal():
+                raise KeyError(key)
+            value = value[int(key)]
+        elif isinstance(value, dict):
+            value = value[key]
+        else:
+            raise KeyError(key)
+    return value
+
+
+def check_api(config: API, report: Report) -> None:
+    report.configured.extend(["api", "data"])
+    report.engines["overstep"] = version("overstep")
+    if report.engines["overstep"] != OVERSTEP_VERSION:
+        report.add("api.engine_version", "inconclusive", "api", "Untested Overstep version.")
+        return
+    try:
+        matrix = Matrix.model_validate(compile_matrix(config, resolve_tokens=True))
+        cases = plan(matrix)
+    except Exception:
+        report.add(
+            "api.configuration",
+            "inconclusive",
+            "api",
+            "Cannot compile matrix; check distinct credentials and resource declarations.",
+        )
+        return
+    if not cases or len(cases) > config.max_cases or not any(c.is_negative for c in cases):
+        report.add(
+            "api.coverage",
+            "inconclusive",
+            "api",
+            "Expected a bounded plan containing both allowed and denied requests.",
+        )
+        return
+    # A public endpoint cannot establish that an authenticated credential works.
+    anonymous = next(s.name for s in config.subjects if s.role == "anonymous")
+    protected = {
+        r.name for r in config.resources if not any(a.role == "anonymous" for a in r.allow)
+    }
+    for s in config.subjects:
+        if s.name != anonymous and not any(
+            c.subject == s.name and c.is_positive_control and c.resource in protected for c in cases
+        ):
+            report.add(
+                "api.positive_control",
+                "inconclusive",
+                s.name,
+                "Each authenticated subject needs an allowed request on a protected resource.",
+            )
+            return
+    resources = {r.name: r for r in config.resources}
+    subjects = {s.name: s for s in config.subjects}
+    validators = {r.name: Draft202012Validator(r.response_schema) for r in config.resources}
+    denial_validators = {r.name: Draft202012Validator(r.denial_schema) for r in config.resources}
+
+    def executor(base_url, engine_subjects, planned, **_):
+        tokens = {s.name: s.token for s in engine_subjects}
+        observations = []
+        for case in planned:
+            target = f"{case.resource}/{case.subject}/{case.variant.value}"
+            headers = {"Accept": "application/json", "Accept-Encoding": "identity"}
+            if tokens[case.subject]:
+                headers["Authorization"] = "Bearer " + tokens[case.subject]
+            try:
+                status, text = asyncio.run(fetch(base_url.rstrip("/") + case.path, headers, config))
+            except Exception:
+                report.add(
+                    "api.delivery",
+                    "inconclusive",
+                    target,
+                    "Request failed, response encoding unsupported, or budget exceeded.",
+                )
+                observations.append(
+                    Observation(
+                        test_id=case.id, status=0, effect=Effect.DENY, error="delivery failed"
+                    )
+                )
+                continue
+            effect = Effect.ALLOW if 200 <= status < 300 else Effect.DENY
+            observations.append(
+                Observation(
+                    test_id=case.id,
+                    status=status,
+                    effect=effect,
+                    matched_markers=[m for m in case.expect_markers if m and m in text],
+                )
+            )
+            if not 200 <= status < 300 and status not in DENIAL_STATUSES:
+                report.add(
+                    "api.unexpected_status",
+                    "inconclusive",
+                    target,
+                    f"HTTP {status} does not establish an access-control decision.",
+                )
+                continue
+            if case.expected == effect:
+                report.add(
+                    "api.authorization",
+                    "pass",
+                    target,
+                    f"Expected {case.expected.value}; received HTTP {status}.",
+                )
+            elif case.expected == Effect.ALLOW:
+                report.add(
+                    "api.positive_control",
+                    "inconclusive",
+                    target,
+                    f"Allowed control returned HTTP {status}; identity is unverified.",
+                )
+            # Unexpected allows are classified by Overstep below.
+            try:
+                data = json.loads(
+                    text, parse_constant=lambda _: (_ for _ in ()).throw(ValueError())
+                )
+            except (ValueError, RecursionError):
+                report.add(
+                    "data.json",
+                    "inconclusive",
+                    target,
+                    "Response is not valid JSON; fields were not verified.",
+                )
+                continue
+            validator = (validators if effect == Effect.ALLOW else denial_validators)[case.resource]
+            errors = list(validator.iter_errors(data))
+            schema_code = "data.schema" if effect == Effect.ALLOW else "data.denial_schema"
+            if errors:
+                keywords = ", ".join(sorted({str(e.validator) for e in errors}))
+                report.add(
+                    schema_code,
+                    "fail",
+                    target,
+                    f"Response violates declared schema ({keywords}); values omitted.",
+                )
+            else:
+                report.add(schema_code, "pass", target, "Response matches declared schema.")
+            resource = resources[case.resource]
+            if (
+                resource.kind == "object"
+                and case.expected == Effect.ALLOW
+                and effect == Effect.ALLOW
+            ):
+                owner = subjects[case.victim or case.subject]
+                try:
+                    actual = pointer_value(data, resource.identity_pointer)
+                    valid_identity = actual == owner.attributes[resource.owner_attr]
+                except (KeyError, IndexError, TypeError, ValueError):
+                    valid_identity = False
+                report.add(
+                    "api.object_control",
+                    "pass" if valid_identity else "inconclusive",
+                    target,
+                    "Expected object identity returned."
+                    if valid_identity
+                    else "Allowed control did not return its declared object identity.",
+                )
+        return observations
+
+    try:
+        result = run_pipeline(
+            matrix, executor=executor, concurrency=1, read_only=True, max_retries=0
+        )
+    except Exception:
+        report.add("api.engine", "inconclusive", "api", "Overstep did not complete the run.")
+        return
+    if result.coverage.unprobed:
+        report.add("api.coverage", "inconclusive", "api", "Some object boundaries were not probed.")
+    if len(result.observations) != len(cases):
+        report.add("api.coverage", "inconclusive", "api", "Some planned observations are missing.")
+    for finding in result.vulnerabilities:
+        report.add(
+            "api." + finding.vuln_class.value,
+            "fail",
+            f"{finding.resource}/{finding.subject}/{finding.variant.value}",
+            f"Expected denial; HTTP {finding.status}. Evidence: {finding.confidence}.",
+        )

permitprobe/cli.py

@@ -0,0 +1,147 @@
+"""Public CLI. Inspect, test and bundle; never deploy, upload or alter a target."""
+
+import argparse
+import json
+from pathlib import Path
+
+from permitprobe import __version__
+from permitprobe.api import check_api, compile_matrix
+from permitprobe.demo import example_policy, run_demo
+from permitprobe.handoff import check_handoff, write_bundle
+from permitprobe.policy import Policy, PolicyError, load_policy
+from permitprobe.report import Report
+
+
+def emit(report: Report, fmt: str, output: str | None = None) -> int:
+    payload = report.to_dict()
+    if output:
+        try:
+            with Path(output).open("x", encoding="utf-8") as f:
+                json.dump(payload, f, indent=2)
+                f.write("\n")
+        except OSError:
+            report.add(
+                "report.write",
+                "inconclusive",
+                "report",
+                "Cannot create report; no file overwritten.",
+            )
+            payload = report.to_dict()
+    if fmt == "json":
+        print(json.dumps(payload, indent=2))
+    else:
+        c = payload["counts"]
+        print(
+            f"PermitProbe {payload['status'].upper()}: "
+            f"{c['pass']} passed, {c['fail']} failed, {c['inconclusive']} inconclusive"
+        )
+        for item in report.checks:
+            if item.outcome != "pass":
+                print(f"  {item.outcome.upper()} {item.code} [{item.target}]: {item.detail}")
+        if payload["unconfigured_surfaces"]:
+            print("  Not configured: " + ", ".join(payload["unconfigured_surfaces"]))
+    return report.exit_code
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(
+        description="Check declared API, data and AI handoff boundaries."
+    )
+    root.add_argument("--version", action="version", version=__version__)
+    commands = root.add_subparsers(dest="command", required=True)
+    for name in ("check", "bundle"):
+        p = commands.add_parser(name)
+        p.add_argument("policy", type=Path)
+        p.add_argument("--gitleaks", help="Path to Gitleaks 8.30.1; defaults to PATH lookup")
+        p.add_argument("--format", choices=("text", "json"), default="text")
+        p.add_argument("--report", help="Create a new JSON report (never overwrite)")
+        if name == "bundle":
+            p.add_argument(
+                "--output", required=True, type=Path, help="Create a checked ZIP locally"
+            )
+    demo = commands.add_parser("demo", help="Run synthetic fixtures on loopback")
+    demo.add_argument(
+        "--scenario",
+        choices=("safe", "leaky", "schema-leak", "expired", "server-error"),
+        default="safe",
+    )
+    demo.add_argument("--gitleaks")
+    demo.add_argument("--format", choices=("text", "json"), default="text")
+    demo.add_argument("--report")
+    init = commands.add_parser("init", help="Create a starter in a NEW directory")
+    init.add_argument("directory", type=Path)
+    export = commands.add_parser(
+        "export-overstep", help="Export an auth-only matrix, without secrets"
+    )
+    export.add_argument("policy", type=Path)
+    export.add_argument("--output", required=True, type=Path)
+    commands.add_parser("schema", help="Print the policy JSON Schema")
+    return root
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    try:
+        if args.command == "schema":
+            print(json.dumps(Policy.model_json_schema(), indent=2))
+            return 0
+        if args.command == "init":
+            args.directory.mkdir(parents=True, exist_ok=False)
+            (args.directory / "permitprobe.json").write_text(
+                json.dumps(example_policy(), indent=2) + "\n"
+            )
+            (args.directory / "review.txt").write_text(
+                "Replace with the text you intend to hand off.\n"
+            )
+            print(
+                "Starter created. Set your staging origin, object IDs, response schema and token environment variables."
+            )
+            return 0
+        if args.command == "demo":
+            return emit(run_demo(args.scenario, args.gitleaks), args.format, args.report)
+        policy = load_policy(args.policy)
+        if args.command == "export-overstep":
+            if not policy.api:
+                raise PolicyError("policy has no API surface")
+            with args.output.open("x", encoding="utf-8") as f:
+                json.dump(compile_matrix(policy.api), f, indent=2)
+                f.write("\n")
+            print(
+                "Auth-only matrix exported. PermitProbe data/control checks are not part of this export."
+            )
+            return 0
+        report = Report()
+        snapshot = {}
+        if args.command == "check" and policy.api:
+            check_api(policy.api, report)
+        if policy.handoff:
+            snapshot = check_handoff(policy.handoff, args.policy.parent, report, args.gitleaks)
+        elif args.command == "bundle":
+            raise PolicyError("policy has no handoff surface")
+        if args.command == "bundle" and report.exit_code == 0:
+            try:
+                write_bundle(snapshot, args.output)
+                report.add(
+                    "handoff.bundle",
+                    "pass",
+                    "handoff",
+                    "Checked bytes written to a local ZIP; nothing sent.",
+                )
+            except OSError:
+                report.add(
+                    "handoff.bundle",
+                    "inconclusive",
+                    "handoff",
+                    "Cannot create bundle; no existing file overwritten.",
+                )
+        return emit(report, args.format, args.report)
+    except (PolicyError, OSError, ValueError, RecursionError):
+        # No exception text: parsers and network libraries may quote secret input.
+        report = Report()
+        report.add(
+            "configuration",
+            "inconclusive",
+            "policy",
+            "Invalid or unreadable policy, unsupported operation, or existing output path.",
+        )
+        return emit(report, getattr(args, "format", "text"))

permitprobe/demo.py

@@ -0,0 +1,161 @@
+"""Synthetic, loopback-only fixtures; no product data or live service dependency."""
+
+import json
+import os
+import tempfile
+import threading
+from contextlib import contextmanager
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from permitprobe.api import check_api
+from permitprobe.handoff import check_handoff
+from permitprobe.policy import Policy
+from permitprobe.report import Report
+
+DEMO_TOKENS = {"PP_ALICE_TOKEN": "demo-only-alice-token", "PP_BOB_TOKEN": "demo-only-bob-token"}
+
+
+def example_policy(base_url: str = "https://staging.example.invalid") -> dict:
+    return {
+        "version": 1,
+        "api": {
+            "base_url": base_url,
+            "subjects": [
+                {"name": "anon", "role": "anonymous"},
+                {
+                    "name": "alice",
+                    "role": "user",
+                    "token_env": "PP_ALICE_TOKEN",
+                    "attributes": {"document_id": "alice"},
+                    "marker": "alice",
+                },
+                {
+                    "name": "bob",
+                    "role": "user",
+                    "token_env": "PP_BOB_TOKEN",
+                    "attributes": {"document_id": "bob"},
+                    "marker": "bob",
+                },
+            ],
+            "resources": [
+                {
+                    "name": "documents",
+                    "kind": "object",
+                    "path": "/documents/{id}",
+                    "owner_param": "id",
+                    "owner_attr": "document_id",
+                    "identity_pointer": "/id",
+                    "allow": [{"role": "user", "scope": "own"}],
+                    "response_schema": {
+                        "type": "object",
+                        "required": ["id", "title"],
+                        "properties": {"id": {"type": "string"}, "title": {"type": "string"}},
+                        "additionalProperties": False,
+                    },
+                    "denial_schema": {
+                        "type": "object",
+                        "required": ["error"],
+                        "properties": {"error": {"enum": ["denied"]}},
+                        "additionalProperties": False,
+                    },
+                }
+            ],
+        },
+        "handoff": {"root": ".", "files": ["review.txt"], "allow": ["*.txt", "docs/*.md"]},
+    }
+
+
+@contextmanager
+def fixture_server(scenario: str = "safe"):
+    requests = []
+
+    class Handler(BaseHTTPRequestHandler):
+        def log_message(self, *_):
+            pass
+
+        def do_GET(self):
+            owner = urlsplit(self.path).path.rsplit("/", 1)[-1]
+            token = self.headers.get("Authorization", "").removeprefix("Bearer ")
+            subject = {v: k.split("_")[1].lower() for k, v in DEMO_TOKENS.items()}.get(token)
+            if scenario == "expired" and subject == "alice":
+                subject = None
+            requests.append((subject, owner, dict(self.headers)))
+            status = 200 if subject and (subject == owner or scenario == "leaky") else 403
+            if scenario == "server-error" and subject and subject != owner:
+                status = 500
+            if scenario == "redirect" and subject and subject != owner:
+                status = 302
+            if scenario == "cookie" and self.headers.get("Cookie"):
+                status = 200
+            body = (
+                {"id": owner, "title": "Synthetic document"}
+                if status == 200
+                else {"error": "denied"}
+            )
+            if scenario == "denied-leak" and status == 403:
+                body["private_email"] = "synthetic@example.invalid"
+            if scenario in ("leaky", "schema-leak") and status == 200:
+                body["private_email"] = "synthetic@example.invalid"
+            if scenario == "wrong-object" and status == 200:
+                body["id"] = "unrelated"
+            if scenario == "nested-leak" and status == 200:
+                body["metadata"] = {"private": "synthetic-sensitive-value"}
+            raw = json.dumps(body).encode()
+            if scenario == "html" and status == 200:
+                raw = b"<html>login page</html>"
+            if scenario == "oversize" and status == 200:
+                raw = b"x" * 2048
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            if scenario == "cookie":
+                self.send_header("Set-Cookie", "privileged=alice; Path=/")
+            if status == 302:
+                self.send_header("Location", "http://127.0.0.1:1/never-follow")
+            self.send_header("Content-Length", str(len(raw)))
+            self.end_headers()
+            self.wfile.write(raw)
+
+    server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        yield f"http://127.0.0.1:{server.server_port}", requests
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=5)
+
+
+@contextmanager
+def demo_environment():
+    old = {key: os.environ.get(key) for key in DEMO_TOKENS}
+    os.environ.update(DEMO_TOKENS)
+    try:
+        yield
+    finally:
+        for key, value in old.items():
+            if value is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = value
+
+
+def run_demo(scenario: str, binary: str | None = None) -> Report:
+    report = Report()
+    with (
+        fixture_server(scenario) as (url, _),
+        demo_environment(),
+        tempfile.TemporaryDirectory() as tmp,
+    ):
+        directory = Path(tmp)
+        text = "Review only these synthetic notes.\n"
+        if scenario == "leaky":
+            # Intentionally fake credential assembled for an actual scanner test.
+            text += "github_token = '" + "ghp_" + "7Qx4Kp9Vn2Ms8Rt6Wj3Yz5Bc1Df0Ha9Lu4Se" + "'\n"
+        (directory / "review.txt").write_text(text)
+        policy = Policy.model_validate(example_policy(url))
+        check_api(policy.api, report)
+        check_handoff(policy.handoff, directory, report, binary)
+    return report