overstep 0.10.0__py3-none-any.whl

overstep/__init__.py

@@ -0,0 +1,39 @@
+"""overstep — a matrix-driven authorization testing tool for HTTP APIs.
+
+overstep takes a declarative *authorization matrix* (who is allowed to do what)
+and turns it into concrete positive and negative HTTP tests. Negative tests that
+unexpectedly succeed are reported as authorization vulnerabilities and classified
+as BOLA, BFLA or privilege escalation. Results can be snapshotted so that CI can
+fail on *authorization drift* between releases.
+
+The public API mirrors the pipeline stages, so an embedding application can do::
+
+    from overstep import load_matrix, run_pipeline, write_reports
+
+    matrix = load_matrix("matrix.yaml")
+    result = run_pipeline(matrix)
+    write_reports(result, "out")
+    if result.vulnerabilities:
+        raise SystemExit(1)
+"""
+
+__version__ = "0.10.0"
+
+from overstep.auth import authenticate
+from overstep.matrix import Matrix, load_matrix
+from overstep.models import Finding, RunResult, VulnClass
+from overstep.pipeline import run_pipeline, write_reports
+from overstep.planner import plan
+
+__all__ = [
+    "__version__",
+    "Matrix",
+    "load_matrix",
+    "plan",
+    "authenticate",
+    "run_pipeline",
+    "write_reports",
+    "RunResult",
+    "Finding",
+    "VulnClass",
+]

overstep/__main__.py

@@ -0,0 +1,4 @@
+from overstep.cli import main
+
+if __name__ == "__main__":
+    main()

overstep/auth.py

@@ -0,0 +1,135 @@
+"""Dynamic authentication: obtain subject tokens before a run.
+
+Real APIs don't accept a JWT pasted into a config file — it expires, and it
+shouldn't be committed anyway. A subject instead points at an auth provider and
+supplies its credentials via ``auth.vars``; before the run we perform the login,
+extract the token and set it on the subject as a header. Everything here happens
+once, up front, over a short-lived synchronous client kept separate from the
+async test executor.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+from urllib.parse import urljoin
+
+import httpx
+
+from overstep.jsonpath import extract
+from overstep.matrix import Matrix
+from overstep.models import AuthProvider, Subject
+from overstep.templating import render
+
+
+class AuthError(RuntimeError):
+    """Raised when a subject's login fails or no token can be extracted."""
+
+
+def extract_token(path: str, data: Any) -> Optional[str]:
+    """Pull a token string out of a JSON response by a dotted path."""
+    value = extract(path, data)
+    return value if value is None or isinstance(value, str) else str(value)
+
+
+def _login_call(provider: AuthProvider, variables: Dict[str, str], base_url: Optional[str]):
+    """Build (method, url, kwargs) for a provider's login request."""
+    provider_base = provider.base_url or base_url or ""
+
+    if provider.type == "http":
+        if provider.request is None:
+            raise AuthError(f"auth provider '{provider.name}' (http) needs a request")
+        req = provider.request
+        url = urljoin(_slash(provider_base), req.path.lstrip("/"))
+        kwargs: Dict[str, Any] = {
+            "params": render(req.query, variables) or None,
+            "json": render(req.body, variables),
+            "headers": render(req.headers, variables) or None,
+        }
+        return req.method, url, kwargs
+
+    # OAuth2 token endpoints: standard form-encoded body.
+    if not provider.token_url:
+        raise AuthError(f"auth provider '{provider.name}' needs a token_url")
+    url = urljoin(_slash(provider_base), provider.token_url.lstrip("/"))
+    form: Dict[str, str] = {}
+    if provider.type == "oauth2_client_credentials":
+        form["grant_type"] = "client_credentials"
+    elif provider.type == "oauth2_password":
+        form["grant_type"] = "password"
+        form["username"] = render(provider.username or "", variables)
+        form["password"] = render(provider.password or "", variables)
+    for key in ("client_id", "client_secret", "scope"):
+        val = render(getattr(provider, key) or "", variables)
+        if val:
+            form[key] = val
+    return "POST", url, {"data": form}
+
+
+def _slash(base: str) -> str:
+    return base if base.endswith("/") else base + "/"
+
+
+def _obtain_token(
+    client: httpx.Client,
+    provider: AuthProvider,
+    variables: Dict[str, str],
+    base_url: Optional[str],
+) -> str:
+    method, url, kwargs = _login_call(provider, variables, base_url)
+    try:
+        resp = client.request(method, url, **kwargs)
+    except httpx.HTTPError as exc:
+        raise AuthError(f"login via provider '{provider.name}' failed: {exc}") from exc
+
+    if resp.status_code >= 400:
+        raise AuthError(
+            f"login via provider '{provider.name}' returned {resp.status_code}"
+        )
+    try:
+        payload = resp.json()
+    except ValueError as exc:
+        raise AuthError(
+            f"login via provider '{provider.name}' did not return JSON"
+        ) from exc
+
+    token = extract_token(provider.token_path, payload)
+    if not token:
+        raise AuthError(
+            f"provider '{provider.name}' response had no token at "
+            f"'{provider.token_path}'"
+        )
+    return token
+
+
+def authenticate(
+    matrix: Matrix,
+    *,
+    base_url: Optional[str] = None,
+    verify_tls: bool = True,
+    client: Optional[httpx.Client] = None,
+) -> None:
+    """Resolve every subject that has an ``auth`` block, in place.
+
+    A no-op when the matrix declares no providers, so runs without dynamic auth
+    pay nothing and stay offline.
+    """
+    providers: Dict[str, AuthProvider] = {p.name: p for p in matrix.auth.providers}
+    subjects_with_auth: List[Subject] = [s for s in matrix.subjects if s.auth]
+    if not providers or not subjects_with_auth:
+        return
+
+    owns_client = client is None
+    client = client or httpx.Client(timeout=15.0, verify=verify_tls, follow_redirects=True)
+    try:
+        for subject in subjects_with_auth:
+            provider = providers.get(subject.auth.provider)
+            if provider is None:
+                raise AuthError(
+                    f"subject '{subject.name}' references unknown auth provider "
+                    f"'{subject.auth.provider}'"
+                )
+            token = _obtain_token(client, provider, subject.auth.vars, base_url)
+            header_value = provider.token_format.format(token=token)
+            subject.headers = {**subject.headers, provider.token_header: header_value}
+    finally:
+        if owns_client:
+            client.close()

overstep/classifier.py

@@ -0,0 +1,254 @@
+"""Compare expectations with observations and classify the mismatches.
+
+There are two kinds of mismatch:
+
+* A negative test (expected deny) that was **allowed** is a real authorization
+  weakness. We label it BOLA, BFLA or privilege escalation depending on the
+  resource type and the subject's role relative to what the policy requires.
+* A positive test (expected allow) that was **denied** is an over-restriction —
+  not a security hole, but a functional regression worth surfacing.
+"""
+from __future__ import annotations
+
+import json
+from typing import Dict, List, Set
+
+from overstep.matrix import Matrix
+from overstep.models import (
+    Effect,
+    Finding,
+    Observation,
+    ResourceType,
+    TestCase,
+    Variant,
+    VulnClass,
+)
+from overstep.repro import request_record, to_curl
+
+
+def _min_required_rank(matrix: Matrix, case: TestCase) -> int:
+    ranks = [matrix.role_rank(r) for r in case.required_roles]
+    ranks = [r for r in ranks if r >= 0]
+    return min(ranks) if ranks else -1
+
+
+def _classify_violation(matrix: Matrix, case: TestCase) -> VulnClass:
+    """A negative test slipped through — decide which flavour of broken authz."""
+    subject_rank = matrix.role_rank(case.role)
+    required_rank = _min_required_rank(matrix, case)
+
+    # Vertical escalation: the subject reached something only a strictly more
+    # privileged role should be able to reach.
+    if subject_rank >= 0 and required_rank >= 0 and subject_rank < required_rank:
+        return VulnClass.PRIVILEGE_ESCALATION
+
+    if case.resource_type == ResourceType.OBJECT and case.variant == Variant.OTHER:
+        return VulnClass.BOLA
+    return VulnClass.BFLA
+
+
+def _json_keys(body: str) -> Set[str]:
+    """Every object key that appears anywhere in a JSON body (recursively).
+
+    Returns an empty set when the body is not valid JSON, so BOPLA checks match
+    real property *keys* rather than substrings of arbitrary text.
+    """
+    try:
+        data = json.loads(body)
+    except (ValueError, TypeError):
+        return set()
+
+    keys: Set[str] = set()
+
+    def _walk(node) -> None:
+        if isinstance(node, dict):
+            for key, value in node.items():
+                keys.add(key)
+                _walk(value)
+        elif isinstance(node, list):
+            for item in node:
+                _walk(item)
+
+    _walk(data)
+    return keys
+
+
+def _leaked_fields(resource, obs: Observation) -> Set[str]:
+    """Forbidden JSON keys present in an allowed response (BOPLA surface)."""
+    if resource is None or not resource.forbidden_fields:
+        return set()
+    present = _json_keys(obs.body_snippet)
+    return {f for f in resource.forbidden_fields if f in present}
+
+
+def _grade(vuln: VulnClass, case: TestCase, obs: Observation):
+    """Assign (severity, confidence) using the content-aware oracle.
+
+    Only object-level probes (BOLA) can be content-verified: we know the victim's
+    marker. When it shows up in the body the leak is *confirmed*; when a marker was
+    configured but never appeared the grant is *suspected* (possibly an empty
+    result) and downgraded; with no marker at all we fall back to status alone and
+    label the finding *unverified*.
+    """
+    if vuln != VulnClass.BOLA:
+        return "high", "confirmed"
+    if not case.expect_markers:
+        return "high", "unverified"
+    if obs.matched_markers:
+        return "high", "confirmed"
+    return "medium", "suspected"
+
+
+def _detail(case: TestCase, obs: Observation, vuln: VulnClass, confidence: str = "confirmed") -> str:
+    if vuln == VulnClass.BOLA:
+        if confidence == "confirmed":
+            leaked = ", ".join(obs.matched_markers)
+            proof = (
+                f" and the response exposed the owner's data ({leaked})"
+                if leaked
+                else ""
+            )
+            return (
+                f"{case.subject} ({case.role}) read another subject's object via "
+                f"{case.method} {case.path} and got {obs.status}{proof}; the matrix "
+                f"only allows owners here."
+            )
+        if confidence == "suspected":
+            return (
+                f"{case.subject} ({case.role}) was granted {case.method} {case.path} "
+                f"(status {obs.status}) on another subject's object, but the expected "
+                f"owner data did not appear — suspected BOLA, verify manually."
+            )
+        return (
+            f"{case.subject} ({case.role}) read another subject's object via "
+            f"{case.method} {case.path} and got {obs.status}; the matrix only "
+            f"allows owners here (no content marker configured to confirm the leak)."
+        )
+    if vuln == VulnClass.PRIVILEGE_ESCALATION:
+        allowed = ", ".join(case.required_roles) or "a higher-privileged role"
+        return (
+            f"{case.subject} ({case.role}) reached {case.method} {case.path} "
+            f"(status {obs.status}) which the matrix reserves for {allowed}."
+        )
+    return (
+        f"{case.subject} ({case.role}) invoked {case.method} {case.path} "
+        f"(status {obs.status}) but has no allow rule for it."
+    )
+
+
+def classify(
+    matrix: Matrix,
+    cases: List[TestCase],
+    observations: List[Observation],
+    *,
+    base_url: str = "",
+) -> List[Finding]:
+    """Produce findings from expectations vs. observations.
+
+    ``base_url`` (defaulting to the matrix's own) is used to render a
+    reproduction (``curl`` + a masked request record) onto every finding.
+    """
+    by_id: Dict[str, TestCase] = {c.id: c for c in cases}
+    by_case: Dict[str, TestCase] = by_id
+    subjects = {s.name: s for s in matrix.subjects}
+    resources = matrix.resource_map()
+    repro_base = base_url or matrix.base_url or ""
+    findings: List[Finding] = []
+
+    for obs in observations:
+        case = by_id.get(obs.test_id)
+        if case is None:
+            continue
+        # A deliberately skipped request (read-only) is not evidence either way.
+        if obs.skipped:
+            continue
+
+        if case.expected == Effect.ALLOW:
+            if obs.effect == Effect.DENY:
+                findings.append(
+                    Finding(
+                        test_id=case.id,
+                        vuln_class=VulnClass.UNEXPECTED_DENY,
+                        severity="low",
+                        resource=case.resource,
+                        subject=case.subject,
+                        role=case.role,
+                        method=case.method,
+                        path=case.path,
+                        expected=case.expected,
+                        observed=obs.effect,
+                        status=obs.status,
+                        variant=case.variant,
+                        detail=(
+                            f"{case.subject} ({case.role}) should be allowed "
+                            f"{case.method} {case.path} but was denied "
+                            f"(status {obs.status})."
+                        ),
+                        evidence=obs,
+                    )
+                )
+            elif obs.effect == Effect.ALLOW:
+                # BOPLA: an allowed read that over-shares forbidden properties.
+                leaked = _leaked_fields(resources.get(case.resource), obs)
+                if leaked:
+                    fields = ", ".join(sorted(leaked))
+                    findings.append(
+                        Finding(
+                            test_id=case.id,
+                            vuln_class=VulnClass.BOPLA,
+                            severity="high",
+                            resource=case.resource,
+                            subject=case.subject,
+                            role=case.role,
+                            method=case.method,
+                            path=case.path,
+                            expected=case.expected,
+                            observed=obs.effect,
+                            status=obs.status,
+                            variant=case.variant,
+                            detail=(
+                                f"{case.subject} ({case.role}) was allowed "
+                                f"{case.method} {case.path} but the response exposed "
+                                f"forbidden field(s): {fields}."
+                            ),
+                            evidence=obs,
+                        )
+                    )
+            continue
+
+        # Negative test.
+        if obs.effect == Effect.ALLOW:
+            vuln = _classify_violation(matrix, case)
+            severity, confidence = _grade(vuln, case, obs)
+            findings.append(
+                Finding(
+                    test_id=case.id,
+                    vuln_class=vuln,
+                    severity=severity,
+                    resource=case.resource,
+                    subject=case.subject,
+                    role=case.role,
+                    method=case.method,
+                    path=case.path,
+                    expected=case.expected,
+                    observed=obs.effect,
+                    status=obs.status,
+                    variant=case.variant,
+                    detail=_detail(case, obs, vuln, confidence),
+                    evidence=obs,
+                    confidence=confidence,
+                )
+            )
+
+    # Attach a copy-pasteable reproduction to every finding.
+    for f in findings:
+        case = by_case.get(f.test_id)
+        subject = subjects.get(f.subject)
+        if case is not None and subject is not None:
+            f.curl = to_curl(repro_base, subject, case)
+            f.request = request_record(repro_base, subject, case)
+
+    # Highest severity, then stable by test id, so reports read consistently.
+    order = {"high": 0, "medium": 1, "low": 2}
+    findings.sort(key=lambda f: (order[f.severity], f.test_id))
+    return findings