Shadow audit

Static API security scanner — finds undocumented and unauthenticated routes before they reach production

Installation

Global CLI (recommended)

npm install -g shadowaudit

npx (no install needed)

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

GitHub Action

Add to .github/workflows/security.yml:

• uses: darkmaster0345/[email protected]
  with:
  dir: './src'
  spec: './openapi.json'
  fail-on: 'critical'
  The Problem
  Developers spin up quick test endpoints and forget to remove them. These shadow APIs bypass documentation, skip auth middleware, and get deployed to production silently — invisible to network scanners, invisible to your security team.

Shadowaudit solves this by statically analyzing your codebase, comparing every route definition against your OpenAPI/Swagger spec, and failing your CI pipeline before the PR merges if it finds undocumented or unauthenticated routes.

What Shadowaudit does

Scans your codebase for all actual route definitions (Express.js supported now; FastAPI & Django coming soon)

Compares them against your OpenAPI 3.x / Swagger 2.0 spec

Flags any route missing from the documentation

Detects whether auth middleware is applied to each route

Fails your CI/CD pipeline before the PR merges — with exit codes that respect configurable severity thresholds

Severity levels

Severity Condition CI behavior (--fail-on critical)

CRITICAL Undocumented route + no auth middleware Pipeline fails

HIGH Undocumented route + auth middleware present Pipeline passes (review recommended)

INFO Informational finding Pipeline passes

Supported Frameworks

Express.js ✅ (full support — AST-based route extraction via Babel)

FastAPI 🚧 (coming soon)

Django 🚧 (coming soon)

Installation

npm install -g shadowaudit

Or use it locally in your project:

npm install --save-dev shadowaudit

Quick Start

Scan your codebase against your OpenAPI spec

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

Force a specific framework

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

Output as JSON (pipe to jq for CI integrations)

shadowaudit --dir ./src --spec ./openapi.json --format json | jq '.findings | length'

Output as SARIF 2.1.0 (for GitHub Code Scanning)

shadowaudit --dir ./src --spec ./openapi.json --format sarif > results.sarif

CLI Options

Usage: shadowaudit [options]

Static API security scanner for undocumented routes

Options:

-V, --version output the version number

--dir Directory to scan (default: current directory)

--spec Path to OpenAPI/Swagger spec file

--format Output format: table, json, sarif (default: "table")

--fail-on Fail CI pipeline on: critical, high, info (default: "critical")

--framework Force framework: express, fastapi, django (default: "auto")

-h, --help display help for command

Exit codes

Condition Exit code

No findings 0

Findings below --fail-on threshold 0

Findings at or above --fail-on threshold 1

--fail-on value Fails when

critical (default) Any CRITICAL finding

high Any CRITICAL or HIGH finding

info Any finding at all

Configuration

shadowaudit loads config from two sources (CLI flags take priority):

CLI flags (highest priority)

.shadowaudit.yml or .shadowauditrc.yml in your project root

Example .shadowaudit.yml:

spec: ./openapi.json

dir: ./src

format: table

failOn: critical

authPatterns:

• myCustomAuth


• requireLogin
  ignore:


• node_modules


• dist


• build
  Default auth patterns (always detected)
  Even without custom config, shadowaudit detects these auth middleware patterns:

.authenticate( .authorize( requireAuth isAuthenticated

verifyToken checkAuth ensureLoggedIn passport.authenticate

jwt.verify bearerAuth apiKeyAuth basicAuth

Output Formats

Table (default)

Human-readable colored table with severity, method, path, file, line, and auth status. Includes a summary box and pipeline recommendation.

JSON

Structured JSON for CI dashboards and log aggregators:

{

"scanMeta": {

"tool": "shadowaudit",

"version": "0.1.0",

"timestamp": "2026-01-15T12:00:00.000Z",

"stats": { "total": 7, "documented": 5, "undocumented": 2, "critical": 2, "high": 0, "info": 0 }

},

"findings": [

{

"severity": "CRITICAL",

"method": "GET",

"path": "/api/debug/reset",

"file": "routes.js",

"line": 21,

"hasAuth": false,

"reason": "Undocumented route with no authentication middleware detected — publicly accessible shadow API"

}

],

"documentedRoutes": [...]

}

SARIF 2.1.0

Industry-standard format for GitHub Code Scanning, Azure DevOps, and other security dashboards. Maps findings to two rules:

Rule ID Severity Level

SHADOW001 CRITICAL error

SHADOW002 HIGH warning

SHADOW002 INFO note

Demo

Below is the actual terminal output from an end-to-end scan. The test project has 7 Express routes — 5 documented in the OpenAPI spec, 2 undocumented shadow routes with no auth middleware:

[INFO] No config file found, using defaults

╔════════════════════════════════╗

║ shadowaudit v0.1.0 ║

║ API Shadow Route Scanner ║

╚════════════════════════════════╝

[INFO] Directory : /tmp/auth-test

[INFO] Spec file : /tmp/auth-test/openapi.json

[INFO] Format : table

[INFO] Fail on : critical

[INFO] Framework : express

[INFO] Running Express.js route scanner...

[✓] Found 7 routes in /tmp/auth-test

[INFO] GET /public/health → routes.js:6 [auth]

[INFO] GET /public/products → routes.js:7 [auth]

[INFO] GET /api/users → routes.js:9 [auth]

[INFO] POST /api/users → routes.js:13 [auth]

[INFO] GET /api/admin/dashboard → routes.js:17 [auth]

[INFO] GET /api/debug/reset → routes.js:21 [no auth]

[INFO] POST /api/test/seed → routes.js:22 [no auth]

[INFO] Detected spec: OpenAPI 3.x

[INFO] Spec contains 5 documented routes

[INFO] ──────────────────────────────────────────────────

[INFO] Total routes scanned : 7

[INFO] Documented : 5

[INFO] Undocumented : 2

[INFO] ──────────────────────────────────────────────────

╔══════════════════════════════════════════════╗

║ shadowaudit — Scan Report ║

╚══════════════════════════════════════════════╝

┌──────────┬────────┬───────────────────────────────────┬───────────────────────────────────┬──────┬──────┐

│ SEVERITY │ METHOD │ PATH │ FILE │ LINE │ AUTH │

├──────────┼────────┼───────────────────────────────────┼───────────────────────────────────┼──────┼──────┤

│ CRITICAL │ GET │ /api/debug/reset │ routes.js │ 21 │ NO │

├──────────┼────────┼───────────────────────────────────┼───────────────────────────────────┼──────┼──────┤

│ CRITICAL │ POST │ /api/test/seed │ routes.js │ 22 │ NO │

└──────────┴────────┴───────────────────────────────────┴───────────────────────────────────┴──────┴──────┘

┌─────────────────────────────────────────────┐

│ SCAN SUMMARY │

│ Total routes scanned : 7 │

│ Documented : 5 │

│ Undocumented : 2 │

│ ───────────────────────────────────────── │

│ 🔴 CRITICAL : 2 │

│ 🟡 HIGH : 0 │

│ 🔵 INFO : 0 │

└─────────────────────────────────────────────┘

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

Exit code: 1

In the terminal, severity cells are color-coded:

CRITICAL → red bold

HIGH → yellow bold

INFO → blue

METHOD → cyan

AUTH YES → green / NO → red

How It Works

┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐

│ Express Scanner │ │ Spec Parser │ │ Delta Comparator│ │ Formatter │

│ (Babel AST) │ │ (OpenAPI/Swagger)│ │ (normalize + )│ │ (table/json/ )│

│ │ │ │ │ ( match routes )│ │ (sarif) )│

│ src//*.js │────▶│ openapi.json │────▶│ Route[] vs │────▶│ Findings[] │

│ src//*.ts │ │ swagger.yaml │ │ DocumentedRoute[]│ │ + stats │

│ │ │ │ │ │ │ │

│ + auth detector │ │ + basePath │ │ + severity │ │ + exit code │

│ (window scan) │ │ + serverPrefix │ │ scoring │ │ logic │

└──────────────────┘ └──────────────────┘ └──────────────────┘ └──────────────────┘

Express scanner uses @babel/parser + @babel/traverse to walk every .js/.ts file's AST and extract route definitions (app.get(), router.post(), router.route().get().post() chaining, etc.)

Auth detector scans a ±15-line window around each route for auth middleware patterns (inline or in surrounding scope), with sibling-route lines stripped to avoid false positives

Spec parser reads OpenAPI 3.x / Swagger 2.0 files (JSON or YAML), extracts documented routes, and normalizes path syntax ({id} → :id)

Delta comparator cross-references scanned routes against documented routes, reconciling Swagger basePath and OpenAPI servers[0].url prefixes, then scores each undocumented route as CRITICAL (no auth) or HIGH (has auth)

Formatter renders the report as a colored table, JSON, or SARIF 2.1.0

CI/CD Integration

GitHub Actions

name: Security Scan

on: [pull_request]

jobs:

shadowaudit:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v4

- uses: actions/setup-node@v4

with:

node-version: '20'

- run: npm ci

- run: npx shadowaudit --dir ./src --spec ./openapi.json --format sarif > shadowaudit.sarif

continue-on-error: true

- uses: github/codeql-action/upload-sarif@v3

with:

sarif_file: shadowaudit.sarif

- name: Fail on critical

run: npx shadowaudit --dir ./src --spec ./openapi.json --fail-on critical

Pre-commit hook

!/bin/bash

shadowaudit --dir ./src --spec ./openapi.json --fail-on critical

Project Structure

shadowaudit/

├── src/

│ ├── index.ts # CLI entry point

│ ├── config.ts # cosmiconfig loader (CLI flags + .shadowaudit.yml)

│ ├── comparator.ts # Delta comparator (route diffing + severity scoring)

│ ├── types.ts # Shared TypeScript interfaces

│ ├── scanners/

│ │ ├── express.ts # Express.js route extractor (Babel AST)

│ │ └── auth.ts # Auth middleware detector

│ ├── parsers/

│ │ └── spec.ts # OpenAPI 3.x / Swagger 2.0 parser

│ ├── formatters/

│ │ ├── table.ts # Colored terminal table

│ │ ├── json.ts # JSON output

│ │ ├── sarif.ts # SARIF 2.1.0 output

│ │ └── index.ts # Formatter dispatcher

│ └── utils/

│ └── logger.ts # Colored console output

├── tests/

│ ├── config.test.ts

│ ├── comparator.test.ts

│ ├── scanners/

│ │ ├── express.test.ts

│ │ └── auth.test.ts

│ ├── parsers/

│ │ └── spec.test.ts

│ └── formatters/

│ ├── table.test.ts

│ └── sarif.test.ts

├── .github/workflows/ci.yml

├── package.json

├── tsconfig.json

├── LICENSE

└── README.md

Development

Install dependencies

npm install

Build

npm run build

Run tests (45 tests across 8 test files)

npm test

Run in dev mode

npm run dev -- --dir ./src --spec ./openapi.json

Lint

npm run lint

Tech Stack

TypeScript — strict mode, ES2020 target, CommonJS modules

Babel (@babel/parser + @babel/traverse) — AST-based route extraction with error recovery

Commander.js — CLI argument parsing

chalk — terminal colors

cli-table3 — terminal table rendering

js-yaml — Swagger/OpenAPI YAML parsing

cosmiconfig — config file discovery

glob — recursive file scanning

Vitest — test runner

License

MIT © Ubaid ur Rehman 2026