Skip to main content

Quick Start

Run your first shadowaudit scan in under 2 minutes.

Step 1: Have a project​

shadowaudit supports:

  • Express.js — any Node.js project with app.get(), router.post(), etc.
  • FastAPI — any Python project with @app.get() decorators
  • Django — any Django project with urls.py files

If you don't have a project handy, clone a real one:

git clone https://github.com/hagopj13/node-express-boilerplate.git --depth=1
cd node-express-boilerplate

Step 2: Have an OpenAPI spec​

shadowaudit needs an OpenAPI 3.x or Swagger 2.0 spec to compare against. If you already have one, skip to Step 3.

If you don't have one, create a minimal openapi.json:

{
  "openapi": "3.0.0",
  "info": { "title": "My API", "version": "1.0.0" },
  "paths": {
    "/users": { "get": {} },
    "/users/{id}": { "get": {}, "put": {}, "delete": {} }
  }
}

List only the routes you EXPECT to exist. shadowaudit will flag everything else as a shadow route.

Step 3: Run the scan​

shadowaudit --spec openapi.json --dir ./src

shadowaudit will auto-detect your framework. To force a specific framework:

# Express
shadowaudit --spec openapi.json --dir ./src --framework express

# FastAPI
shadowaudit --spec openapi.json --dir ./src --framework fastapi

# Django
shadowaudit --spec openapi.json --dir ./src --framework django

Step 4: Read the output​

[INFO] Running Express.js route scanner...
[✓] Found 18 routes in ./src
[INFO]   GET /api/users → routes/users.js:9 [auth]
[INFO]   POST /api/users → routes/users.js:14 [auth]
[INFO]   GET /api/debug/reset → routes/debug.js:3 [no auth]

┌──────────┬────────┬───────────────────┬──────┬──────┐
│ SEVERITY │ METHOD │ PATH              │ LINE │ AUTH │
├──────────┼────────┼───────────────────┼──────┼──────┤
│ CRITICAL │ GET    │ /api/debug/reset  │ 3    │ NO   │
└──────────┴────────┴───────────────────┴──────┴──────┘

⛔ Pipeline will FAIL — 1 critical shadow route(s) detected

Exit code: 1

What this means:

  • 18 routes found — shadowaudit detected 18 route definitions in your source code
  • [auth] / [no auth] — whether auth middleware was detected on each route
  • CRITICAL — /api/debug/reset is undocumented (not in your spec) AND has no auth middleware
  • Exit code 1 — the pipeline fails because --fail-on critical is the default

Next steps​

--diff mode (PR workflows)​

Show only new findings since the last scan — perfect for PR review:

# First run — full scan, cache saved
shadowaudit --dir ./src --spec ./openapi.json --diff

# Second run — only NEW findings shown, resolved findings shown as ✓
shadowaudit --dir ./src --spec ./openapi.json --diff

Exit code is based on new findings only — pre-existing findings won't fail your CI on every PR.

--generate-spec (no spec yet?)​

Don't have an OpenAPI spec? Generate one from your code:

shadowaudit --dir ./src --framework express --generate-spec > openapi.json