authztrace 0.3.1__py3-none-any.whl

authztrace/matrix.py

@@ -0,0 +1,81 @@
+"""Expand a contract into the full actor x object test matrix.
+
+This is the part a human bug-hunter does by hand: take every object, and for
+every *other* identity try to reach it. AuthzTrace generates that whole cross
+product from a few lines of ownership declaration.
+"""
+from __future__ import annotations
+
+from .models import Check, Contract, Endpoint, effective_safe
+from .templating import render
+
+
+def _is_authenticated(auth: dict) -> bool:
+    return (auth or {}).get("type", "none") != "none"
+
+
+def _is_allowed(contract: Contract, endpoint: Endpoint, actor: str, owner: str) -> bool:
+    allow = {item.lower() for item in endpoint.allow}
+    if "all" in allow or "*" in allow:
+        return True
+    if "authenticated" in allow and _is_authenticated(contract.actors[actor].auth):
+        return True
+    if "anonymous" in allow and not _is_authenticated(contract.actors[actor].auth):
+        return True
+    if "owner" in allow and actor == owner:
+        return True
+    return actor.lower() in allow
+
+
+def _context(resource: str, actor: str, owner: str, object_id: object, marker: object) -> dict:
+    return {
+        "resource": resource,
+        "actor": actor,
+        "owner": owner,
+        "id": object_id,
+        "object_id": object_id,
+        "marker": marker,
+    }
+
+
+def generate(contract: Contract) -> list[Check]:
+    """For every object and every actor, assert allowed actors pass and others deny."""
+    checks: list[Check] = []
+    for res in contract.resources.values():
+        for endpoint in res.endpoints:
+            for owner, object_id in res.ids.items():
+                ctx_base = _context(
+                    resource=res.name,
+                    actor="",
+                    owner=owner,
+                    object_id=object_id,
+                    marker=res.markers.get(owner, ""),
+                )
+                for actor_name in contract.actors:
+                    ctx = dict(ctx_base)
+                    ctx["actor"] = actor_name
+                    checks.append(
+                        Check(
+                            name=f"{endpoint.name}: {actor_name} -> {owner}",
+                            resource=res.name,
+                            actor=actor_name,
+                            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=(
+                                "allow"
+                                if _is_allowed(contract, endpoint, actor_name, owner)
+                                else "deny"
+                            ),
+                            assertions=render(endpoint.assertions, ctx),
+                            safe=effective_safe(endpoint.method, endpoint.safe),
+                        )
+                    )
+    return checks + contract.checks

authztrace/models.py

@@ -0,0 +1,98 @@
+"""Core data models for authorization contracts and execution results."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+SAFE_METHODS = {"GET", "HEAD", "OPTIONS"}
+
+
+def effective_safe(method: str, override: bool | None = None) -> bool:
+    """Return whether an operation is safe to execute in read-only mode."""
+    if override is not None:
+        return override
+    return method.upper() in SAFE_METHODS
+
+
+@dataclass
+class Actor:
+    """A test identity (a user, a role, or the anonymous caller)."""
+
+    name: str
+    auth: dict = field(default_factory=lambda: {"type": "none"})
+
+
+@dataclass
+class Endpoint:
+    """A templated API operation that will be expanded across actors and objects."""
+
+    name: str
+    method: str
+    path: str
+    query: dict[str, Any] = field(default_factory=dict)
+    headers: dict[str, Any] = field(default_factory=dict)
+    json: Any = None
+    data: Any = None
+    allow: list[str] = field(default_factory=lambda: ["owner"])
+    assertions: dict[str, Any] = field(default_factory=dict)
+    safe: bool | None = None
+
+
+@dataclass
+class Resource:
+    """A protected object type and concrete object ids owned by each actor."""
+
+    name: str
+    endpoints: list[Endpoint]
+    ids: dict[str, Any]
+    markers: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Policy:
+    """Default expectations for generated checks."""
+
+    default: str = "owner-only"
+    deny_status: list[int] = field(default_factory=lambda: [401, 403, 404])
+    allow_status: list[int] = field(default_factory=list)
+
+
+@dataclass
+class Contract:
+    base_url: str
+    actors: dict[str, Actor]
+    resources: dict[str, Resource]
+    policy: Policy
+    checks: list[Check] = field(default_factory=list)
+
+
+@dataclass
+class Check:
+    """A single HTTP probe the engine will execute."""
+
+    name: str
+    resource: str
+    actor: str
+    method: str
+    path: str
+    path_template: str = ""
+    endpoint_name: str = ""
+    query: dict[str, Any] = field(default_factory=dict)
+    headers: dict[str, Any] = field(default_factory=dict)
+    json: Any = None
+    data: Any = None
+    object_id: str = ""
+    target_owner: str = ""
+    expect: str = "deny"
+    assertions: dict[str, Any] = field(default_factory=dict)
+    safe: bool = True
+
+
+@dataclass
+class Result:
+    check: Check
+    status: int | None
+    outcome: str
+    category: str = "ok"
+    note: str = ""
+    elapsed_ms: int | None = None

authztrace/openapi.py

@@ -0,0 +1,135 @@
+"""Generate starter AuthzTrace contracts from OpenAPI specs."""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+_METHODS = {"get", "post", "put", "patch", "delete", "head", "options"}
+_PATH_PARAM = re.compile(r"\{([^{}]+)\}")
+
+
+def _read_spec(path: str) -> dict[str, Any]:
+    text = Path(path).read_text(encoding="utf-8")
+    if path.endswith(".json"):
+        return json.loads(text)
+    data = yaml.safe_load(text)
+    if not isinstance(data, dict):
+        raise ValueError("OpenAPI file must contain an object")
+    return data
+
+
+def _resource_name(path: str, param: str) -> str:
+    parts = [part for part in path.strip("/").split("/") if part]
+    marker = "{" + param + "}"
+    if marker in parts:
+        idx = parts.index(marker)
+        if idx > 0:
+            return re.sub(r"(?<!s)s$", "", parts[idx - 1].replace("-", "_")) or "resource"
+    return param.removesuffix("_id").removesuffix("Id").replace("-", "_") or "resource"
+
+
+def _operation_parameters(
+    path_item: dict[str, Any],
+    operation: dict[str, Any],
+) -> list[dict[str, Any]]:
+    params: list[dict[str, Any]] = []
+    for item in path_item.get("parameters") or []:
+        if isinstance(item, dict):
+            params.append(item)
+    for item in operation.get("parameters") or []:
+        if isinstance(item, dict):
+            params.append(item)
+    return params
+
+
+def _first_server_url(spec: dict[str, Any]) -> str | None:
+    servers = spec.get("servers") or []
+    if servers and isinstance(servers[0], dict):
+        url = servers[0].get("url")
+        if isinstance(url, str) and url:
+            return url
+    return None
+
+
+def _env_name(resource: str, owner: str) -> str:
+    safe = re.sub(r"[^A-Za-z0-9]+", "_", resource).strip("_").upper() or "RESOURCE"
+    return f"${{{owner.upper()}_{safe}_ID}}"
+
+
+def generate_contract(spec_path: str, base_url: str | None = None) -> dict[str, Any]:
+    spec = _read_spec(spec_path)
+    resources: dict[str, dict[str, Any]] = {}
+
+    for raw_path, path_item in (spec.get("paths") or {}).items():
+        if not isinstance(path_item, dict):
+            continue
+        for method, operation in path_item.items():
+            if method.lower() not in _METHODS or not isinstance(operation, dict):
+                continue
+
+            path_params = _PATH_PARAM.findall(raw_path)
+            endpoint: dict[str, Any] | None = None
+            resource = ""
+
+            if len(path_params) == 1:
+                param = path_params[0]
+                resource = _resource_name(raw_path, param)
+                endpoint = {
+                    "name": operation.get("operationId") or f"{method.upper()} {raw_path}",
+                    "request": f"{method.upper()} {raw_path.replace('{' + param + '}', '{id}')}",
+                }
+            else:
+                query_id = None
+                for param in _operation_parameters(path_item, operation):
+                    name = str(param.get("name") or "")
+                    if param.get("in") == "query" and name.lower() in {"id", "object_id"}:
+                        query_id = name
+                        break
+                if query_id:
+                    resource = _resource_name(raw_path + "/{" + query_id + "}", query_id)
+                    endpoint = {
+                        "name": operation.get("operationId") or f"{method.upper()} {raw_path}",
+                        "method": method.upper(),
+                        "path": raw_path,
+                        "query": {query_id: "{id}"},
+                    }
+
+            if not endpoint or not resource:
+                continue
+
+            resource_spec = resources.setdefault(
+                resource,
+                {
+                    "ids": {
+                        "alice": _env_name(resource, "alice"),
+                        "bob": _env_name(resource, "bob"),
+                    },
+                    "endpoints": [],
+                },
+            )
+            resource_spec["endpoints"].append(endpoint)
+
+    if not resources:
+        raise ValueError("no single-object endpoints found in OpenAPI spec")
+
+    return {
+        "base_url": base_url or _first_server_url(spec) or "http://localhost:3000",
+        "actors": {
+            "alice": {"auth": {"type": "bearer", "token": "${ALICE_TOKEN}"}},
+            "bob": {"auth": {"type": "bearer", "token": "${BOB_TOKEN}"}},
+            "anon": {"auth": {"type": "none"}},
+        },
+        "resources": resources,
+        "policy": {"default": "owner-only", "deny_status": [401, 403, 404]},
+    }
+
+
+def write_contract(contract: dict[str, Any], output: str, force: bool = False) -> None:
+    path = Path(output)
+    if path.exists() and not force:
+        raise FileExistsError(f"{output} already exists; pass --force to overwrite")
+    path.write_text(yaml.safe_dump(contract, sort_keys=False), encoding="utf-8")

authztrace/py.typed

@@ -0,0 +1 @@
+

authztrace/report.py

@@ -0,0 +1,246 @@
+"""Render results as a terminal matrix and as SARIF for GitHub code scanning."""
+from __future__ import annotations
+
+import hashlib
+import json
+import urllib.parse
+import xml.etree.ElementTree as ET
+
+from .models import Result
+
+_OUTCOMES = ("pass", "fail", "warn", "error", "skipped")
+_TAG = {"pass": "PASS", "fail": "FAIL", "warn": "WARN", "error": "ERROR", "skipped": "SKIP"}
+_COLOR = {
+    "pass": "\033[32m",
+    "fail": "\033[31m",
+    "warn": "\033[33m",
+    "error": "\033[35m",
+    "skipped": "\033[36m",
+}
+_RESET = "\033[0m"
+_BOLA_HELP_URI = (
+    "https://owasp.org/API-Security/editions/2023/en/0xa1-broken-object-level-authorization/"
+)
+
+
+def counts(results: list[Result]) -> dict:
+    out = {outcome: 0 for outcome in _OUTCOMES}
+    for r in results:
+        out[r.outcome] += 1
+    return out
+
+
+def category_counts(results: list[Result]) -> dict:
+    out: dict[str, int] = {}
+    for result in results:
+        out[result.category] = out.get(result.category, 0) + 1
+    return out
+
+
+def _display_path(result: Result) -> str:
+    check = result.check
+    if not check.query:
+        return check.path
+    return check.path + "?" + urllib.parse.urlencode(check.query, doseq=True)
+
+
+def to_terminal(results: list[Result], color: bool = True) -> str:
+    lines = [
+        f"{'RESULT':<6} {'ACTOR':<10} {'TARGET':<10} {'EXPECT':<7} {'STATUS':<7} METHOD  PATH",
+        "-" * 96,
+    ]
+    for r in results:
+        c = r.check
+        tag = _TAG[r.outcome]
+        plain_tag = tag
+        if color:
+            tag = f"{_COLOR[r.outcome]}{tag}{_RESET}"
+        status = str(r.status) if r.status is not None else "-"
+        lines.append(
+            f"{tag}{' ' * (6 - len(plain_tag))} {c.actor:<10} {c.target_owner:<10} "
+            f"{c.expect:<7} {status:<7} {c.method:<7} {_display_path(r)}"
+        )
+        if r.note:
+            lines.append(f"         -> {r.note}")
+
+    c = counts(results)
+    categories = category_counts(results)
+    lines.append("-" * 96)
+    lines.append(
+        f"{c['pass']} passed, {c['fail']} failed, {c['warn']} warnings, "
+        f"{c['error']} errors, {c['skipped']} skipped, {len(results)} checks"
+    )
+    interesting = {
+        key: value
+        for key, value in categories.items()
+        if key != "ok" and value
+    }
+    if interesting:
+        lines.append(
+            "categories: "
+            + ", ".join(f"{key}={value}" for key, value in sorted(interesting.items()))
+        )
+    return "\n".join(lines)
+
+
+def to_json(results: list[Result]) -> str:
+    data = {
+        "summary": counts(results) | {
+            "categories": category_counts(results),
+            "total": len(results),
+        },
+        "results": [
+            {
+                "name": r.check.name,
+                "outcome": r.outcome,
+                "category": r.category,
+                "note": r.note,
+                "status": r.status,
+                "elapsed_ms": r.elapsed_ms,
+                "actor": r.check.actor,
+                "target_owner": r.check.target_owner,
+                "resource": r.check.resource,
+                "object_id": r.check.object_id,
+                "expect": r.check.expect,
+                "request": {
+                    "method": r.check.method,
+                    "path": r.check.path,
+                    "path_template": r.check.path_template or r.check.path,
+                    "query": r.check.query,
+                    "headers": r.check.headers,
+                    "json": r.check.json,
+                    "data": r.check.data,
+                },
+            }
+            for r in results
+        ],
+    }
+    return json.dumps(data, indent=2)
+
+
+def to_junit(results: list[Result]) -> str:
+    summary = counts(results)
+    suite = ET.Element(
+        "testsuite",
+        {
+            "name": "authztrace",
+            "tests": str(len(results)),
+            "failures": str(summary["fail"]),
+            "errors": str(summary["error"]),
+            "skipped": str(summary["skipped"]),
+        },
+    )
+    for result in results:
+        case = ET.SubElement(
+            suite,
+            "testcase",
+            {
+                "classname": "authztrace",
+                "name": result.check.name,
+                "time": str((result.elapsed_ms or 0) / 1000),
+            },
+        )
+        if result.outcome == "fail":
+            failure = ET.SubElement(case, "failure", {"message": result.note})
+            failure.text = result.note
+        elif result.outcome == "error":
+            error = ET.SubElement(case, "error", {"message": result.note})
+            error.text = result.note
+        elif result.outcome == "skipped":
+            skipped = ET.SubElement(case, "skipped", {"message": result.note})
+            skipped.text = result.note
+        elif result.outcome == "warn":
+            props = ET.SubElement(case, "properties")
+            ET.SubElement(props, "property", {"name": "warning", "value": result.note})
+
+    return ET.tostring(suite, encoding="unicode")
+
+
+def _finding_rule_id(result: Result) -> str:
+    return "authztrace/leak" if result.category == "leak" else "authztrace/bola"
+
+
+def _owner_relationship(result: Result) -> str:
+    if not result.check.target_owner:
+        return "unknown"
+    return "self" if result.check.actor == result.check.target_owner else "other"
+
+
+def _fingerprint(result: Result) -> str:
+    check = result.check
+    endpoint_id = check.path_template or check.endpoint_name or check.path
+    raw = "\n".join(
+        [
+            _finding_rule_id(result),
+            check.method,
+            endpoint_id,
+            check.resource,
+            check.actor,
+            _owner_relationship(result),
+        ]
+    )
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()[:32]
+
+
+def to_sarif(results: list[Result], artifact_uri: str = "authztrace.yaml") -> str:
+    rules = [
+        {
+            "id": "authztrace/bola",
+            "name": "BrokenObjectLevelAuthorization",
+            "shortDescription": {"text": "Broken Object Level Authorization (IDOR/BOLA)"},
+            "helpUri": _BOLA_HELP_URI,
+        },
+        {
+            "id": "authztrace/leak",
+            "name": "AuthorizationResponseLeak",
+            "shortDescription": {"text": "Denied response leaked protected object data"},
+            "helpUri": _BOLA_HELP_URI,
+        },
+    ]
+    findings = [
+        {
+            "ruleId": _finding_rule_id(r),
+            "level": "warning" if r.category == "leak" else "error",
+            "message": {
+                "text": (
+                    f"{r.check.name}: {r.note} "
+                    f"({r.check.method} {_display_path(r)} as {r.check.actor})"
+                )
+            },
+            "locations": [
+                {
+                    "physicalLocation": {
+                        "artifactLocation": {"uri": artifact_uri},
+                        "region": {"startLine": 1, "startColumn": 1},
+                    },
+                    "logicalLocations": [
+                        {
+                            "fullyQualifiedName": (
+                                f"{r.check.method} {r.check.path_template or r.check.path}"
+                            )
+                        }
+                    ],
+                }
+            ],
+            "partialFingerprints": {"authztraceFinding/v1": _fingerprint(r)},
+        }
+        for r in results
+        if r.outcome == "fail" and r.category in {"bola", "leak"}
+    ]
+    doc = {
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "AuthzTrace",
+                        "informationUri": "https://github.com/Asttr0/authztrace",
+                        "rules": rules,
+                    }
+                },
+                "results": findings,
+            }
+        ],
+    }
+    return json.dumps(doc, indent=2)

authztrace/templating.py

@@ -0,0 +1,22 @@
+"""Small placeholder renderer used by contracts and generated checks."""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_PLACEHOLDER = re.compile(r"\{([A-Za-z_][A-Za-z0-9_]*)\}")
+_EXACT_PLACEHOLDER = re.compile(r"^\{([A-Za-z_][A-Za-z0-9_]*)\}$")
+
+
+def render(value: Any, context: dict[str, Any]) -> Any:
+    """Recursively replace ``{name}`` placeholders with context values."""
+    if isinstance(value, str):
+        exact = _EXACT_PLACEHOLDER.match(value)
+        if exact:
+            return context.get(exact.group(1), value)
+        return _PLACEHOLDER.sub(lambda m: str(context.get(m.group(1), m.group(0))), value)
+    if isinstance(value, dict):
+        return {k: render(v, context) for k, v in value.items()}
+    if isinstance(value, list):
+        return [render(item, context) for item in value]
+    return value