# ardayesilcayir/authdiff architecture

> Architecture diagram of the GitHub repository ardayesilcayir/authdiff, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ardayesilcayir/authdiff
- Repository: https://github.com/ardayesilcayir/authdiff

## Overview

authdiff is a Go CLI and library for differential REST API authorization testing; vuln-lab is its intentionally vulnerable demo target. The main workflow loads configuration and an OpenAPI inventory, probes endpoints with multiple identity profiles and rules, compares responses into findings, then writes reports. Source excerpts show the CLI, orchestration, transport, and lab wiring; several scan internals are unsampled, so their detailed call relationships are not asserted.

Main entry points: [`pkg/authdiff/authdiff.go`](https://github.com/ardayesilcayir/authdiff/blob/main/pkg/authdiff/authdiff.go) (Public orchestration), [`internal/engine/engine.go`](https://github.com/ardayesilcayir/authdiff/blob/main/internal/engine/engine.go) (Scan engine), [`vuln-lab/app/db.py`](https://github.com/ardayesilcayir/authdiff/blob/main/vuln-lab/app/db.py) (Lab database), [`internal/finding/finding.go`](https://github.com/ardayesilcayir/authdiff/blob/main/internal/finding/finding.go) (Finding records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and API"]
  node_command["Command entry<br/>[main.go]"]
  node_cli_scan["Scan command<br/>[scan.go]"]
  node_public_api["Public orchestration<br/>[authdiff.go]"]
end

subgraph group_scan["Scan pipeline"]
  node_configuration["Config validation<br/>[config.go]"]
  node_openapi["Spec inventory<br/>[loader.go]"]
  node_identities["Identity profiles<br/>[profile.go]"]
  node_ownership["Ownership data<br/>[ownership.go]"]
  node_planner["Request planner<br/>[planner.go]"]
  node_rule_loader["Rule loader<br/>[loader.go]"]
  node_rule_eval["Rule evaluation<br/>[eval.go]"]
  node_engine["Scan engine<br/>[engine.go]"]
  node_template_checks["Template checks<br/>[template.go]"]
  node_special_checks["Specialized checks"]
  node_transport["Scoped transport<br/>[client.go]"]
end

subgraph group_results["Findings and reports"]
  node_comparison["Response comparison<br/>[structural.go]"]
  node_findings["Finding records<br/>[finding.go]"]
  node_baseline["Ignore baseline<br/>[baseline.go]"]
  node_reporting["Report formats<br/>[write.go]"]
end

subgraph group_lab["Vulnerable demo API"]
  node_lab_app["Lab app and routes<br/>[main.py]"]
  node_lab_auth["Lab authentication<br/>[auth.py]"]
  node_lab_data["Lab data models<br/>[models.py]"]
  node_lab_db[("Lab database<br/>[db.py]")]
  node_lab_seed["Lab seed data<br/>[seed.py]"]
  node_lab_tokens["Lab tokens<br/>[tokens.py]"]
end

node_user(("Operator"))
node_target_api(("Target REST API"))

node_user -->|"runs"| node_command
node_command -->|"dispatches"| node_cli_scan
node_cli_scan -->|"starts scan"| node_public_api
node_cli_scan -->|"writes reports"| node_reporting
node_public_api -->|"loads config"| node_configuration
node_public_api -->|"loads inventory"| node_openapi
node_public_api -->|"loads rules"| node_rule_loader
node_public_api -->|"builds client"| node_transport
node_public_api -->|"runs scan"| node_engine
node_engine -->|"creates profiles"| node_identities
node_engine -->|"builds requests"| node_planner
node_engine -.->|"evaluates rules"| node_rule_eval
node_template_checks -->|"compares responses"| node_comparison
node_template_checks -->|"creates findings"| node_findings
node_template_checks -->|"sends probes"| node_transport
node_ownership -->|"uses config"| node_configuration
node_planner -->|"uses profiles"| node_identities
node_rule_eval -->|"evaluates against"| node_findings
node_findings -->|"suppressed by"| node_baseline
node_reporting -->|"renders"| node_findings
node_transport -->|"sends requests"| node_target_api
node_lab_app -->|"initializes"| node_lab_db
node_lab_app -->|"serves routes"| node_target_api
node_lab_auth -->|"gets sessions"| node_lab_db
node_lab_auth -->|"decodes tokens"| node_lab_tokens
node_lab_auth -->|"loads users"| node_lab_data
node_lab_db -->|"stores models"| node_lab_data
node_lab_db -->|"seeds database"| node_lab_seed

click node_command "https://github.com/ardayesilcayir/authdiff/blob/main/cmd/authdiff/main.go"
click node_cli_scan "https://github.com/ardayesilcayir/authdiff/blob/main/internal/cli/scan.go"
click node_public_api "https://github.com/ardayesilcayir/authdiff/blob/main/pkg/authdiff/authdiff.go"
click node_configuration "https://github.com/ardayesilcayir/authdiff/blob/main/internal/config/config.go"
click node_openapi "https://github.com/ardayesilcayir/authdiff/blob/main/internal/spec/loader.go"
click node_identities "https://github.com/ardayesilcayir/authdiff/blob/main/internal/identity/profile.go"
click node_ownership "https://github.com/ardayesilcayir/authdiff/blob/main/internal/identity/ownership.go"
click node_planner "https://github.com/ardayesilcayir/authdiff/blob/main/internal/planner/planner.go"
click node_rule_loader "https://github.com/ardayesilcayir/authdiff/blob/main/internal/rules/loader.go"
click node_rule_eval "https://github.com/ardayesilcayir/authdiff/blob/main/internal/rules/eval.go"
click node_engine "https://github.com/ardayesilcayir/authdiff/blob/main/internal/engine/engine.go"
click node_template_checks "https://github.com/ardayesilcayir/authdiff/blob/main/internal/engine/template.go"
click node_special_checks "https://github.com/ardayesilcayir/authdiff/tree/main/internal/engine"
click node_transport "https://github.com/ardayesilcayir/authdiff/blob/main/internal/transport/client.go"
click node_comparison "https://github.com/ardayesilcayir/authdiff/blob/main/internal/compare/structural.go"
click node_findings "https://github.com/ardayesilcayir/authdiff/blob/main/internal/finding/finding.go"
click node_baseline "https://github.com/ardayesilcayir/authdiff/blob/main/internal/finding/baseline.go"
click node_reporting "https://github.com/ardayesilcayir/authdiff/blob/main/internal/report/write.go"
click node_lab_app "https://github.com/ardayesilcayir/authdiff/blob/main/vuln-lab/app/main.py"
click node_lab_auth "https://github.com/ardayesilcayir/authdiff/blob/main/vuln-lab/app/auth.py"
click node_lab_data "https://github.com/ardayesilcayir/authdiff/blob/main/vuln-lab/app/models.py"
click node_lab_db "https://github.com/ardayesilcayir/authdiff/blob/main/vuln-lab/app/db.py"
click node_lab_seed "https://github.com/ardayesilcayir/authdiff/blob/main/vuln-lab/app/seed.py"
click node_lab_tokens "https://github.com/ardayesilcayir/authdiff/blob/main/vuln-lab/app/tokens.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_command,node_cli_scan,node_public_api toneBlue
class node_configuration,node_openapi,node_identities,node_ownership,node_planner,node_rule_loader,node_rule_eval,node_engine,node_template_checks,node_special_checks,node_transport toneAmber
class node_comparison,node_findings,node_baseline,node_reporting,node_target_api toneMint
class node_lab_app,node_lab_auth,node_lab_data,node_lab_db,node_lab_seed,node_lab_tokens toneRose
class node_user toneIndigo
```

## Components

### CLI and API

- [Command entry](https://github.com/ardayesilcayir/authdiff/blob/main/cmd/authdiff/main.go): `cmd/authdiff/main.go`
- [Scan command](https://github.com/ardayesilcayir/authdiff/blob/main/internal/cli/scan.go): `internal/cli/scan.go`
- [Public orchestration](https://github.com/ardayesilcayir/authdiff/blob/main/pkg/authdiff/authdiff.go): `pkg/authdiff/authdiff.go`

### Scan pipeline

- [Config validation](https://github.com/ardayesilcayir/authdiff/blob/main/internal/config/config.go): `internal/config/config.go`
- [Spec inventory](https://github.com/ardayesilcayir/authdiff/blob/main/internal/spec/loader.go): `internal/spec/loader.go`
- [Identity profiles](https://github.com/ardayesilcayir/authdiff/blob/main/internal/identity/profile.go): `internal/identity/profile.go`
- [Ownership data](https://github.com/ardayesilcayir/authdiff/blob/main/internal/identity/ownership.go): `internal/identity/ownership.go`
- [Request planner](https://github.com/ardayesilcayir/authdiff/blob/main/internal/planner/planner.go): `internal/planner/planner.go`
- [Rule loader](https://github.com/ardayesilcayir/authdiff/blob/main/internal/rules/loader.go): `internal/rules/loader.go`
- [Rule evaluation](https://github.com/ardayesilcayir/authdiff/blob/main/internal/rules/eval.go): `internal/rules/eval.go`
- [Scan engine](https://github.com/ardayesilcayir/authdiff/blob/main/internal/engine/engine.go): `internal/engine/engine.go`
- [Template checks](https://github.com/ardayesilcayir/authdiff/blob/main/internal/engine/template.go): `internal/engine/template.go`
- [Specialized checks](https://github.com/ardayesilcayir/authdiff/tree/main/internal/engine): `internal/engine`
- [Scoped transport](https://github.com/ardayesilcayir/authdiff/blob/main/internal/transport/client.go): `internal/transport/client.go`

### Findings and reports

- [Response comparison](https://github.com/ardayesilcayir/authdiff/blob/main/internal/compare/structural.go): `internal/compare/structural.go`
- [Finding records](https://github.com/ardayesilcayir/authdiff/blob/main/internal/finding/finding.go): `internal/finding/finding.go`
- [Ignore baseline](https://github.com/ardayesilcayir/authdiff/blob/main/internal/finding/baseline.go): `internal/finding/baseline.go`
- [Report formats](https://github.com/ardayesilcayir/authdiff/blob/main/internal/report/write.go): `internal/report/write.go`

### Vulnerable demo API

- [Lab app and routes](https://github.com/ardayesilcayir/authdiff/blob/main/vuln-lab/app/main.py): `vuln-lab/app/main.py`
- [Lab authentication](https://github.com/ardayesilcayir/authdiff/blob/main/vuln-lab/app/auth.py): `vuln-lab/app/auth.py`
- [Lab data models](https://github.com/ardayesilcayir/authdiff/blob/main/vuln-lab/app/models.py): `vuln-lab/app/models.py`
- [Lab database](https://github.com/ardayesilcayir/authdiff/blob/main/vuln-lab/app/db.py): `vuln-lab/app/db.py`
- [Lab seed data](https://github.com/ardayesilcayir/authdiff/blob/main/vuln-lab/app/seed.py): `vuln-lab/app/seed.py`
- [Lab tokens](https://github.com/ardayesilcayir/authdiff/blob/main/vuln-lab/app/tokens.py): `vuln-lab/app/tokens.py`

### Other components

- **Operator**
- **Target REST API**

## Connections

- Operator → Command entry: runs
- Command entry → Scan command: dispatches (evidence: `cmd/authdiff/main.go`)
- Scan command → Public orchestration: starts scan (evidence: `internal/cli/scan.go`)
- Scan command → Report formats: writes reports (evidence: `internal/cli/scan.go`)
- Public orchestration → Config validation: loads config (evidence: `pkg/authdiff/authdiff.go`)
- Public orchestration → Spec inventory: loads inventory (evidence: `pkg/authdiff/authdiff.go`)
- Public orchestration → Rule loader: loads rules (evidence: `pkg/authdiff/authdiff.go`)
- Public orchestration → Scoped transport: builds client (evidence: `pkg/authdiff/authdiff.go`)
- Public orchestration → Scan engine: runs scan (evidence: `pkg/authdiff/authdiff.go`)
- Scan engine → Identity profiles: creates profiles (evidence: `internal/engine/engine.go`)
- Scan engine → Request planner: builds requests (evidence: `internal/engine/engine.go`)
- Scan engine → Rule evaluation: evaluates rules
- Template checks → Response comparison: compares responses (evidence: `internal/engine/template.go`)
- Template checks → Finding records: creates findings (evidence: `internal/engine/template.go`)
- Template checks → Scoped transport: sends probes (evidence: `internal/engine/template.go`)
- Ownership data → Config validation: uses config (evidence: `internal/identity/ownership.go`)
- Request planner → Identity profiles: uses profiles (evidence: `internal/planner/planner.go`)
- Rule evaluation → Finding records: evaluates against (evidence: `internal/rules/eval.go`)
- Finding records → Ignore baseline: suppressed by
- Report formats → Finding records: renders
- Scoped transport → Target REST API: sends requests
- Lab app and routes → Lab database: initializes (evidence: `vuln-lab/app/main.py`)
- Lab app and routes → Target REST API: serves routes (evidence: `vuln-lab/app/main.py`)
- Lab authentication → Lab database: gets sessions (evidence: `vuln-lab/app/auth.py`)
- Lab authentication → Lab tokens: decodes tokens (evidence: `vuln-lab/app/auth.py`)
- Lab authentication → Lab data models: loads users (evidence: `vuln-lab/app/auth.py`)
- Lab database → Lab data models: stores models (evidence: `vuln-lab/app/db.py`)
- Lab database → Lab seed data: seeds database (evidence: `vuln-lab/app/db.py`)
