SHADOWAUDIT
Static API security scanner that finds undocumented shadow routes — code endpoints attackers find but QA misses.
npm i -g shadowaudit$ shadowaudit scan ./src --spec ./openapi.yaml --format table shadowaudit v0.6.1 — scanning 142 files (Express + FastAPI detected)─────────────────────────────────────────────────────────────── FOUND 7 undocumented routes (3 HIGH, 4 MEDIUM) HIGH DELETE /api/users/:id src/routes/users.js:42 HIGH POST /api/admin/wipe src/routes/admin.js:88 [no auth] MEDIUM GET /api/internal/health src/server.js:15 ─────────────────────────────────────────────────────────────── → Add to CI: npx shadowaudit scan --diff --fail-on HIGH
ORIGIN STORY
Why I Built It
“Every bug bounty I did — PriceOye, EC-Council, Waqar Electronics — had the same root cause: an API endpoint that existed in code but wasn’t in the spec, wasn’t in tests, and wasn’t in the WAF ruleset. ShadowAudit turns that class of bug into a CI failure.”
PHILOSOPHY
Zero tolerance for security theater.
API documentation is only as reliable as the build script that verifies it. When development cycles move quickly, manual spec drafting fails first. Attackers bypass modern firewalls and testing pipelines simply by fuzzing the routes developers forgot to document. ShadowAudit solves this systematically by introducing source code verification into your CI/CD.
Advanced Auditing Capabilities
Engineered for robust extraction, accurate diffs, and rapid deployment.
AST-Based Extraction
Babel parser extracts routes directly from Express.js abstract syntax trees (ASTs) rather than relying on brittle regex matching.
Regex Framework Scanners
High-speed scanners for Python (FastAPI, Django, Flask) and NestJS (v0.7.0) support zero-config route extraction.
Auth/Middleware Detection
Recognizes authorization guards and middleware chains to auto-classify endpoints as "auth required" vs "publicly open".
Prefix Reconciliation
Recursively resolves mounted route prefixes (e.g. app.use("/api/v1", router)) ensuring precise matching against documentation.
CI-Friendly Diff Mode
Runs with --diff to compare against local JSON caching, surfacing only the NEW shadow routes introduced in current branches.
Auto OpenAPI Gen
Auto-generates complete, fully compliant OpenAPI 3.0.3 specifications straight from extracted routes for instant documentation.
SARIF 2.1.0 Output
Outputs in native SARIF format, allowing seamless ingestion into GitHub Advanced Security Code Scanning dashboards.
GitHub Action Published
Available on the Marketplace with a comment bot that flags undocumented routes directly inside pull requests.
Framework Support Matrix
| FRAMEWORK | LANGUAGE | VERSION / STATUS |
|---|---|---|
| Express.js(Babel AST Parser) | Node.js | ✓ Active |
| FastAPI(Regex Pydantic AST) | Python | ✓ Active |
| Django / DRF(CBV/Viewset Resolver) | Python | ✓ Active |
| Flask(Blueprint Decorator Scraper) | Python | ✓ Active |
| NestJS(TypeScript AST compiler) | Node.js | v0.7.0 Dev |
Project Roadmap
- TypeScript AST compiler for NestJS
- Parallel multi-threading scanning
- --watch mode for instant local scans
- Enterprise-grade SaaS integrations
- Custom policy rulesets (.shadowauditrc)
- Integrations with Slack & Discord
Real-World Scan Benchmarks
Tested against high-volume production projects and FOSS codebases to verify extraction and false positive handling.
| TEST TARGET / REPO | TOTAL ROUTES | UNDOCUMENTED (SHADOW) | FALSE POSITIVE RATE |
|---|---|---|---|
| Ghost CMS v5.x | 269 | 42 | 88% (via AST Auth) |
| expressjs/express | 38 | 0 | 100% (Auto-spec verified) |
| tiangolo/fastapi | 54 | 3 | 0% False Positive |
| node-express-realworld | 28 | 0 | 100% (Match) |
Audit Your Pipeline Today
Add ShadowAudit to your CI loop and capture leaks before QA signs off. Available on major distribution channels.