authztrace 0.3.1__py3-none-any.whl

authztrace/__init__.py

@@ -0,0 +1,3 @@
+"""AuthzTrace — authorization contract testing for IDOR/BOLA."""
+
+__version__ = "0.3.1"

authztrace/cli.py

@@ -0,0 +1,130 @@
+"""Command-line entry point: authztrace run -c authztrace.yaml"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .config import load_contract
+from .engine import run as run_checks
+from .matrix import generate
+from .openapi import generate_contract, write_contract
+from .report import counts, to_json, to_junit, to_sarif, to_terminal
+
+
+def _exit_code(results, strict: bool = False) -> int:
+    c = counts(results)
+    if any(result.outcome == "error" and result.category == "setup" for result in results):
+        return 2
+    if c["fail"] or (strict and c["warn"]):
+        return 1
+    return 0
+
+
+def _run(args) -> int:
+    try:
+        contract = load_contract(args.config)
+    except (OSError, ValueError) as exc:
+        print(f"authztrace: cannot load contract: {exc}", file=sys.stderr)
+        return 2
+
+    if args.base_url:
+        contract.base_url = args.base_url.rstrip("/")
+
+    checks = generate(contract)
+    results = run_checks(
+        contract,
+        checks,
+        timeout=args.timeout,
+        include_unsafe=args.include_unsafe,
+    )
+
+    print(to_terminal(results, color=not args.no_color))
+
+    if args.sarif:
+        with open(args.sarif, "w", encoding="utf-8") as f:
+            f.write(to_sarif(results, artifact_uri=args.config))
+        print(f"\nSARIF written to {args.sarif}")
+
+    if args.json:
+        with open(args.json, "w", encoding="utf-8") as f:
+            f.write(to_json(results))
+        print(f"\nJSON written to {args.json}")
+
+    if args.junit:
+        with open(args.junit, "w", encoding="utf-8") as f:
+            f.write(to_junit(results))
+        print(f"\nJUnit written to {args.junit}")
+
+    return _exit_code(results, strict=args.strict)
+
+
+def _init(args) -> int:
+    try:
+        contract = generate_contract(args.from_file, base_url=args.base_url)
+        write_contract(contract, args.output, force=args.force)
+    except (OSError, ValueError, FileExistsError) as exc:
+        print(f"authztrace: cannot generate contract: {exc}", file=sys.stderr)
+        return 2
+
+    print(f"AuthzTrace contract written to {args.output}")
+    print("Set the generated *_ID and *_TOKEN environment variables before running it.")
+    return 0
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="authztrace",
+        description="Authorization contract testing for IDOR/BOLA — "
+        "prove user A cannot touch user B's objects, in CI.",
+    )
+    parser.add_argument("--version", action="version", version=f"authztrace {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    run_p = sub.add_parser("run", help="run an authorization contract against a live API")
+    run_p.add_argument(
+        "-c", "--config", default="authztrace.yaml",
+        help="path to the authorization contract (default: authztrace.yaml)",
+    )
+    run_p.add_argument("--sarif", metavar="FILE", help="also write SARIF results to FILE")
+    run_p.add_argument("--json", metavar="FILE", help="also write machine-readable JSON to FILE")
+    run_p.add_argument("--junit", metavar="FILE", help="also write JUnit XML to FILE")
+    run_p.add_argument("--base-url", help="override base_url from the contract")
+    run_p.add_argument("--timeout", type=float, default=10.0, help="per-request timeout in seconds")
+    run_p.add_argument("--strict", action="store_true", help="return non-zero when warnings occur")
+    run_p.add_argument(
+        "--include-unsafe",
+        action="store_true",
+        help="execute non-read-only endpoints such as POST, PUT, PATCH, and DELETE",
+    )
+    run_p.add_argument("--no-color", action="store_true", help="disable ANSI colors")
+
+    init_p = sub.add_parser("init", help="scaffold a contract from an OpenAPI spec")
+    init_p.add_argument(
+        "--from",
+        dest="from_file",
+        required=True,
+        help="path to an OpenAPI JSON/YAML file",
+    )
+    init_p.add_argument(
+        "-o",
+        "--output",
+        default="authztrace.yaml",
+        help="contract path to write (default: authztrace.yaml)",
+    )
+    init_p.add_argument("--base-url", help="override server URL from the OpenAPI spec")
+    init_p.add_argument("--force", action="store_true", help="overwrite output if it exists")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "run":
+        return _run(args)
+    if args.command == "init":
+        return _init(args)
+
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

authztrace/config.py

@@ -0,0 +1,224 @@
+"""Load and validate an authztrace.yaml contract, expanding ${ENV_VARS}."""
+from __future__ import annotations
+
+import os
+import re
+from typing import Any
+
+import yaml
+
+from .models import Actor, Check, Contract, Endpoint, Policy, Resource, effective_safe
+from .templating import render
+
+_ENV = re.compile(r"\$\{([A-Z0-9_]+)\}")
+
+
+def _expand(value):
+    """Recursively replace ${VAR} with the environment value (empty if unset)."""
+    if isinstance(value, str):
+        return _ENV.sub(lambda m: os.environ.get(m.group(1), ""), value)
+    if isinstance(value, dict):
+        return {k: _expand(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_expand(v) for v in value]
+    return value
+
+
+def _as_list(value: Any, default: list[str] | None = None) -> list[str]:
+    if value is None:
+        return list(default or [])
+    if isinstance(value, list):
+        return [str(item) for item in value]
+    return [str(value)]
+
+
+def _split_request(value: str) -> tuple[str, str]:
+    parts = value.strip().split(None, 1)
+    if len(parts) != 2:
+        raise ValueError(f"invalid request (expected 'METHOD /path'): {value!r}")
+    method, path = parts
+    return method.upper(), path
+
+
+def _endpoint(raw: Any, name: str) -> Endpoint:
+    """Parse either ``GET /path`` or a structured endpoint object."""
+    if isinstance(raw, str):
+        method, path = _split_request(raw)
+        return Endpoint(name=name, method=method, path=path)
+
+    if not isinstance(raw, dict):
+        raise ValueError(f"endpoint {name!r} must be a string or object")
+
+    spec = dict(raw)
+    request = spec.pop("request", None)
+    if request:
+        if not isinstance(request, str):
+            raise ValueError(f"endpoint {name!r} request must be 'METHOD /path'")
+        method, path = _split_request(request)
+    else:
+        method = str(spec.pop("method", "")).upper()
+        path = str(spec.pop("path", ""))
+
+    if not method or not path:
+        raise ValueError(f"endpoint {name!r} must define method/path")
+
+    safe = spec.pop("safe", None)
+    if safe is not None and not isinstance(safe, bool):
+        raise ValueError(f"endpoint {name!r} safe must be true or false")
+
+    return Endpoint(
+        name=str(spec.pop("name", name)),
+        method=method,
+        path=path,
+        query=spec.pop("query", {}) or spec.pop("params", {}) or {},
+        headers=spec.pop("headers", {}) or {},
+        json=spec.pop("json", None),
+        data=spec.pop("data", None),
+        allow=_as_list(spec.pop("allow", None), ["owner"]),
+        assertions=spec.pop("assertions", {}) or {},
+        safe=safe,
+    )
+
+
+def _context(
+    resource: Resource | None,
+    actor: str,
+    owner: str,
+    object_id: Any,
+) -> dict[str, Any]:
+    marker = ""
+    if resource and owner:
+        marker = resource.markers.get(owner, "")
+    return {
+        "actor": actor,
+        "owner": owner,
+        "id": object_id,
+        "object_id": object_id,
+        "resource": resource.name if resource else "",
+        "marker": marker,
+    }
+
+
+def _explicit_check(spec: dict[str, Any], index: int, resources: dict[str, Resource]) -> Check:
+    name = str(spec.get("name") or f"contract-{index}")
+    actor = str(spec.get("as") or spec.get("actor") or "")
+    if not actor:
+        raise ValueError(f"contract {name!r} must define 'as' or 'actor'")
+
+    resource_name = str(spec.get("resource") or "")
+    resource = resources.get(resource_name) if resource_name else None
+    owner = str(spec.get("target_owner") or spec.get("owner") or spec.get("target") or "")
+
+    object_id = spec.get("id", "")
+    if object_id == "" and resource and owner:
+        object_id = resource.ids.get(owner, "")
+
+    params = spec.get("params") or {}
+    ctx = _context(resource, actor, owner, object_id)
+    ctx.update(params)
+
+    request = spec.get("request")
+    if isinstance(request, str):
+        endpoint_spec = {
+            "request": request,
+            "query": spec.get("query") or spec.get("params") or {},
+            "headers": spec.get("headers") or {},
+            "json": spec.get("json", None),
+            "data": spec.get("data", None),
+            "assertions": spec.get("assertions") or {},
+            "safe": spec.get("safe", None),
+        }
+        endpoint = _endpoint(endpoint_spec, name)
+    elif isinstance(request, dict):
+        endpoint_spec = {
+            "query": spec.get("query") or spec.get("params") or {},
+            "headers": spec.get("headers") or {},
+            "json": spec.get("json", None),
+            "data": spec.get("data", None),
+            "assertions": spec.get("assertions") or {},
+            "safe": spec.get("safe", None),
+        }
+        endpoint_spec.update(request)
+        endpoint = _endpoint(endpoint_spec, name)
+    else:
+        endpoint = _endpoint(spec, name)
+
+    return Check(
+        name=name,
+        resource=resource_name,
+        actor=actor,
+        method=endpoint.method,
+        path=render(endpoint.path, ctx),
+        path_template=endpoint.path,
+        endpoint_name=endpoint.name,
+        query=render(endpoint.query, ctx),
+        headers=render(endpoint.headers, ctx),
+        json=render(endpoint.json, ctx),
+        data=render(endpoint.data, ctx),
+        target_owner=owner,
+        object_id=str(object_id),
+        expect=str(spec.get("expect") or "deny"),
+        assertions=render(endpoint.assertions | (spec.get("assertions") or {}), ctx),
+        safe=effective_safe(endpoint.method, endpoint.safe),
+    )
+
+
+def load_contract(path: str) -> Contract:
+    with open(path, encoding="utf-8") as f:
+        raw = _expand(yaml.safe_load(f))
+
+    if not raw or "base_url" not in raw:
+        raise ValueError("contract must define 'base_url'")
+
+    actors: dict[str, Actor] = {}
+    for name, spec in (raw.get("actors") or {}).items():
+        auth = (spec or {}).get("auth") or {"type": "none"}
+        actors[name] = Actor(name=name, auth=auth)
+    if not actors:
+        raise ValueError("contract must define at least one actor")
+
+    resources: dict[str, Resource] = {}
+    for name, spec in (raw.get("resources") or {}).items():
+        spec = spec or {}
+        endpoint_specs = spec.get("endpoints") or []
+        if not endpoint_specs:
+            raise ValueError(f"resource {name!r} must define at least one endpoint")
+        ids = spec.get("ids") or {}
+        if not isinstance(ids, dict) or not ids:
+            raise ValueError(f"resource {name!r} must define ids by owner")
+        resources[name] = Resource(
+            name=name,
+            endpoints=[
+                _endpoint(endpoint_spec, f"{name}.{idx}")
+                for idx, endpoint_spec in enumerate(endpoint_specs, start=1)
+            ],
+            ids=ids,
+            markers=spec.get("markers", {}) or {},
+        )
+    if not resources:
+        raise ValueError("contract must define at least one resource")
+
+    pol = raw.get("policy") or {}
+    policy = Policy(
+        default=pol.get("default", "owner-only"),
+        deny_status=pol.get("deny_status", [401, 403, 404]),
+        allow_status=pol.get("allow_status", []),
+    )
+
+    checks = [
+        _explicit_check(spec or {}, idx, resources)
+        for idx, spec in enumerate(raw.get("contracts") or raw.get("checks") or [], start=1)
+    ]
+    for chk in checks:
+        if chk.actor not in actors:
+            raise ValueError(f"contract {chk.name!r} references unknown actor {chk.actor!r}")
+        if chk.resource and chk.resource not in resources:
+            raise ValueError(f"contract {chk.name!r} references unknown resource {chk.resource!r}")
+
+    return Contract(
+        base_url=raw["base_url"].rstrip("/"),
+        actors=actors,
+        resources=resources,
+        policy=policy,
+        checks=checks,
+    )

authztrace/engine.py

@@ -0,0 +1,284 @@
+"""Replay every check against the live API and grade it against the contract."""
+from __future__ import annotations
+
+import base64
+import time
+from typing import Any
+
+import requests
+
+from .models import Check, Contract, Result
+
+
+def _headers(auth: dict) -> dict:
+    kind = (auth or {}).get("type", "none")
+    if kind == "bearer":
+        return {"Authorization": f"Bearer {auth.get('token', '')}"}
+    if kind == "header":
+        return {auth.get("name", "X-API-Key"): auth.get("value", "")}
+    if kind == "cookie":
+        return {"Cookie": f"{auth.get('name', 'session')}={auth.get('value', '')}"}
+    if kind == "basic":
+        raw = f"{auth.get('username', '')}:{auth.get('password', '')}".encode()
+        return {"Authorization": "Basic " + base64.b64encode(raw).decode("ascii")}
+    return {}
+
+
+def _is_allowed_status(contract: Contract, status: int) -> bool:
+    if contract.policy.allow_status:
+        return status in contract.policy.allow_status
+    return 200 <= status < 300
+
+
+def _field_exists(value: Any, path: str) -> bool:
+    current = value
+    for part in path.split("."):
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+            continue
+        if isinstance(current, list) and part.isdigit() and int(part) < len(current):
+            current = current[int(part)]
+            continue
+        return False
+    return True
+
+
+def _no_field_failures(resp: requests.Response, check: Check) -> list[str]:
+    failures: list[str] = []
+    assertions = check.assertions or {}
+
+    no_fields = assertions.get("no_fields") or []
+    if isinstance(no_fields, str):
+        no_fields = [no_fields]
+    if no_fields:
+        try:
+            body = resp.json()
+        except ValueError:
+            body = None
+        if body is not None:
+            for field_path in no_fields:
+                if _field_exists(body, str(field_path)):
+                    failures.append(f"response contains forbidden JSON field {field_path!r}")
+
+    return failures
+
+
+def _allow_assertions(resp: requests.Response, check: Check) -> list[str]:
+    failures: list[str] = []
+    assertions = check.assertions or {}
+
+    allowed_markers = assertions.get("allow_contains") or []
+    if isinstance(allowed_markers, str):
+        allowed_markers = [allowed_markers]
+    for marker in allowed_markers:
+        marker = str(marker)
+        if marker and marker not in resp.text:
+            failures.append(f"allowed response missed required marker {marker!r}")
+
+    failures.extend(_no_field_failures(resp, check))
+    return failures
+
+
+def _deny_assertions(resp: requests.Response, check: Check) -> list[str]:
+    failures: list[str] = []
+    assertions = check.assertions or {}
+
+    denied_markers = assertions.get("deny_not_contains") or assertions.get("not_contains") or []
+    if isinstance(denied_markers, str):
+        denied_markers = [denied_markers]
+    for marker in denied_markers:
+        marker = str(marker)
+        if marker and marker in resp.text:
+            failures.append(f"denied response leaked forbidden marker {marker!r}")
+
+    failures.extend(_no_field_failures(resp, check))
+    return failures
+
+
+def _setup_target(check: Check) -> str:
+    target = check.resource or "resource"
+    if check.object_id:
+        target = f"{target} ({check.object_id})"
+    if check.target_owner:
+        target = f"{check.target_owner}'s {target}"
+    return target
+
+
+def _grade_allow(
+    contract: Contract,
+    check: Check,
+    resp: requests.Response,
+    elapsed_ms: int,
+) -> Result:
+    status = resp.status_code
+    allowed = _is_allowed_status(contract, status)
+    if not allowed:
+        return Result(
+            check=check,
+            status=status,
+            outcome="error",
+            category="setup",
+            note=(
+                f"setup: expected '{check.actor}' to access {_setup_target(check)} "
+                f"but got HTTP {status}; authorization fixtures or credentials are not trustworthy"
+            ),
+            elapsed_ms=elapsed_ms,
+        )
+
+    assertion_failures = _allow_assertions(resp, check)
+    if assertion_failures:
+        return Result(
+            check=check,
+            status=status,
+            outcome="error",
+            category="setup",
+            note="setup: " + "; ".join(assertion_failures),
+            elapsed_ms=elapsed_ms,
+        )
+
+    return Result(
+        check=check,
+        status=status,
+        outcome="pass",
+        category="ok",
+        elapsed_ms=elapsed_ms,
+    )
+
+
+def _grade_deny(
+    contract: Contract,
+    check: Check,
+    resp: requests.Response,
+    elapsed_ms: int,
+) -> Result:
+    status = resp.status_code
+    allowed = _is_allowed_status(contract, status)
+
+    if allowed:
+        outcome = "fail"
+        category = "bola"
+        note = (
+            f"BOLA: '{check.actor}' accessed {check.target_owner}'s "
+            f"{check.resource} ({check.object_id}) - HTTP {status}"
+        )
+    elif status in contract.policy.deny_status:
+        outcome, category, note = "pass", "ok", ""
+    else:
+        outcome = "warn"
+        category = "over_restrictive"
+        note = f"denied with {status}, not in deny_status {contract.policy.deny_status}"
+
+    assertion_failures = _deny_assertions(resp, check)
+    if assertion_failures:
+        details = "; ".join(assertion_failures)
+        note = f"{note}; {details}" if note else details
+        if outcome != "fail":
+            outcome = "fail"
+            category = "leak"
+
+    return Result(
+        check=check,
+        status=status,
+        outcome=outcome,
+        category=category,
+        note=note,
+        elapsed_ms=elapsed_ms,
+    )
+
+
+def _execute_check(
+    session: requests.Session,
+    contract: Contract,
+    check: Check,
+    timeout: float,
+) -> Result:
+    actor = contract.actors[check.actor]
+    url = contract.base_url + check.path
+    headers = _headers(actor.auth)
+    headers.update(check.headers)
+    started = time.monotonic()
+    try:
+        resp = session.request(
+            check.method,
+            url,
+            params=check.query or None,
+            headers=headers,
+            json=check.json,
+            data=check.data,
+            timeout=timeout,
+        )
+        elapsed_ms = int((time.monotonic() - started) * 1000)
+    except requests.RequestException as exc:
+        elapsed_ms = int((time.monotonic() - started) * 1000)
+        return Result(
+            check=check,
+            status=None,
+            outcome="error",
+            category="setup",
+            note=f"setup: request failed: {exc}",
+            elapsed_ms=elapsed_ms,
+        )
+
+    if check.expect == "allow":
+        return _grade_allow(contract, check, resp, elapsed_ms)
+    return _grade_deny(contract, check, resp, elapsed_ms)
+
+
+def _unsafe_skipped(check: Check) -> Result:
+    return Result(
+        check=check,
+        status=None,
+        outcome="skipped",
+        category="unsafe_skipped",
+        note=(
+            f"unsafe {check.method} skipped in read-only mode; mark the endpoint "
+            "safe: true or pass --include-unsafe to execute it"
+        ),
+    )
+
+
+def _setup_skipped(check: Check) -> Result:
+    return Result(
+        check=check,
+        status=None,
+        outcome="skipped",
+        category="setup",
+        note="skipped because preflight failed; fix setup errors before trusting attack rows",
+    )
+
+
+def run(
+    contract: Contract,
+    checks: list[Check],
+    timeout: float = 10.0,
+    include_unsafe: bool = False,
+) -> list[Result]:
+    results_by_index: dict[int, Result] = {}
+    executable_indices: list[int] = []
+    session = requests.Session()
+
+    for idx, check in enumerate(checks):
+        if not include_unsafe and not check.safe:
+            results_by_index[idx] = _unsafe_skipped(check)
+        else:
+            executable_indices.append(idx)
+
+    preflight_indices = [idx for idx in executable_indices if checks[idx].expect == "allow"]
+    for idx in preflight_indices:
+        results_by_index[idx] = _execute_check(session, contract, checks[idx], timeout)
+
+    preflight_failed = any(
+        result.outcome == "error" and result.category == "setup"
+        for result in results_by_index.values()
+    )
+    if preflight_failed:
+        for idx in executable_indices:
+            if idx not in results_by_index:
+                results_by_index[idx] = _setup_skipped(checks[idx])
+        return [results_by_index[idx] for idx in range(len(checks))]
+
+    for idx in executable_indices:
+        if idx not in results_by_index:
+            results_by_index[idx] = _execute_check(session, contract, checks[idx], timeout)
+
+    return [results_by_index[idx] for idx in range(len(checks))]