authztrace 0.6.0

How it works · Quickstart · Contract · CI guarantees · Roadmap

How it works

flowchart LR
    Contract["1. Contract<br/>actors + IDs + endpoint rules"]
    Matrix["2. Generate matrix<br/>endpoint x ID relationship x actor"]
    Safety["3. Safety gate<br/>record unsafe skips + preflight allow rows"]
    Replay["4. Live API<br/>replay executable deny rows"]
    Verdict{"Match contract?"}

    Setup["Exit 2<br/>invalid or untrustworthy setup"]
    Finding["Exit 1<br/>BOLA, leak, or strict warning"]
    Clean["Exit 0<br/>no failing executed checks<br/>warnings and skips stay visible"]

    Contract -->|valid| Matrix
    Contract -->|invalid| Setup
    Matrix --> Safety
    Safety -->|preflight fails| Setup
    Safety -->|passes| Replay
    Replay -->|request error| Setup
    Replay -->|response| Verdict
    Verdict -->|violation or strict warning| Finding
    Verdict -->|pass or non-strict warning| Clean

    classDef input fill:#161b22,stroke:#58a6ff,color:#f0f6fc,stroke-width:2px;
    classDef process fill:#1f2937,stroke:#8b949e,color:#f0f6fc;
    classDef decision fill:#221b2e,stroke:#d2a8ff,color:#f0f6fc,stroke-width:2px;
    classDef failure fill:#3d1519,stroke:#f85149,color:#ff7b72,stroke-width:2px;
    classDef success fill:#102a18,stroke:#3fb950,color:#56d364,stroke-width:2px;

    class Contract input;
    class Matrix,Safety,Replay process;
    class Verdict decision;
    class Setup,Finding failure;
    class Clean success;

What AuthzTrace does

AuthzTrace is an authorization contract test runner for REST APIs. You describe test identities, object ownership, and expected access once. AuthzTrace expands every endpoint across each owned object and declared actor, including anonymous actors you explicitly define.

GET /invoices/inv_A -> 200 means nothing by itself. When the contract says inv_A belongs to Alice, the same 200 for Bob is a proven BOLA.

Quickstart

Install the CLI:

pip install authztrace

For a FastAPI project, discover routes and authorization evidence directly from source. An OpenAPI document is optional, but gives AuthzTrace the authoritative public route paths and server URL:

authztrace init --from-source . --openapi openapi.yaml

AuthzTrace statically reads the code without importing the application. It confirms route and identifier facts, suggests owner only when it finds a supported ownership comparison, and asks you to review every remaining policy. It writes the executable contract to authztrace.yaml and provenance to authztrace.evidence.json.

For automation, probable owner policies can be accepted explicitly. If any endpoint is still unresolved, this exits 2 and does not write a contract:

authztrace init --from-source . --accept-probable --non-interactive

On later runs, preserve reviewed decisions by endpoint identity. New or renamed endpoints still require review:

authztrace init --from-source . \
  --decisions authztrace.evidence.json \
  --non-interactive --force

For other frameworks, scaffold from OpenAPI and review the generated ownership rules:

authztrace init --from openapi.yaml

See source inference for the supported FastAPI patterns and trust model.

Point base_url at a running non-production API, then add stable test-object IDs and actor credentials. Secrets can stay in environment variables:

export ALICE_TOKEN="..."
export BOB_TOKEN="..."

authztrace run -c authztrace.yaml --sarif authztrace.sarif

No OpenAPI document? Start from the working example.

permissions:
  contents: read
  actions: read
  security-events: write

steps:
  - uses: actions/checkout@v4

  # Start your API here, or point base_url at a reachable test environment.
  - uses: Asttr0/AuthzTrace@v0.6.0
    env:
      ALICE_TOKEN: ${{ secrets.ALICE_TOKEN }}
      BOB_TOKEN: ${{ secrets.BOB_TOKEN }}
    with:
      config: authztrace.yaml
      sarif: authztrace.sarif

  - uses: github/codeql-action/upload-sarif@v4
    if: ${{ always() && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) }}
    with:
      sarif_file: authztrace.sarif

The contract

This contract says Alice and Bob each own one invoice. Owners may read their own invoice; every other identity must be denied without receiving the owner's marker.

base_url: https://api.test.example.com

actors:
  alice: { auth: { type: bearer, token: "${ALICE_TOKEN}" } }
  bob:   { auth: { type: bearer, token: "${BOB_TOKEN}" } }
  anon:  { auth: { type: none } }

resources:
  invoice:
    ids:     { alice: inv_A, bob: inv_B }
    markers: { alice: "Alice private", bob: "Bob private" }
    endpoints:
      - request: GET /api/invoices/{id}
        allow: [owner]
        assertions:
          allow_contains: ["{marker}"]
          deny_not_contains: ["{marker}"]

policy:
  deny_status: [401, 403, 404]

That single endpoint becomes six checks: one endpoint x two owned objects x three declared actors. Alice and Bob must retrieve their own marker; the other user and anon must receive a deny status and never see it.

Object IDs can also live in query parameters, headers, JSON, or form bodies. Endpoint allow rules accept owner, named actors, authenticated, anonymous, all, or *.

resources:
  org_user:
    target_id: user_id
    ids:
      alice: { org_id: org_A, user_id: user_A }
      bob:   { org_id: org_B, user_id: user_B }
    endpoints:
      - request: GET /api/orgs/{org_id}/users/{user_id}
        allow: [owner]

Runtime login flows

Actors can acquire credentials from the API before preflight instead of receiving a static token. Each actor gets an isolated HTTP session, and a failed login or missing credential aborts the run as untrustworthy setup with exit code 2.

actors:
  alice:
    auth:
      type: login
      request: POST /api/login
      json:
        username: alice
        password: "${ALICE_PASSWORD}"
      extract: { from: json, path: session.access_token }
      credential: { type: bearer }

extract.from accepts json, header, or cookie. JSON extraction uses a dotted path; header and cookie extraction use name. The resulting credential can be applied as bearer, header, or cookie, and expect_status can override the default 2xx login expectation. OAuth-style form payloads, separate HTTP(S) identity-provider URLs, redirect control, and custom token schemes are supported.

Login requests are explicit setup operations and therefore run before the read-only endpoint safety gate, including POST logins. Keep targets pointed at controlled non-production environments. See the authentication guide and complete login-flow demo contract.

Built for trustworthy CI

Current scope

AuthzTrace is alpha software focused on REST authorization regression testing with stable fixtures and static or runtime login credentials. It supports scalar objects, nested parent/child ownership, OpenAPI scaffolding, and reviewed FastAPI source inference. Source inference currently recognizes static router declarations, path/query IDs, common SQLAlchemy lookups, and direct ownership comparisons; dynamic route registration, arbitrary service-layer policy, request-body inference, and other frameworks remain unsupported. Method-override, predictable-ID, mass-assignment, and GraphQL coverage remain planned. See the authorization test corpus for the full status.

_{Found AuthzTrace useful? Star the repository so more API teams can find it.
MIT © 2026 Mohamed Taha Slimani · @Asttr0 · Issues}