Technical note · Active development
Building shadowaudit: Turning Route Inventory into Reviewable API-Security Context
A technical note on an open-source CLI that inventories API routes, compares code with an OpenAPI specification, and produces reviewable security context for development workflows.
Modern APIs often have a documentation problem before they have a production incident. Routes can be added in code, mounted conditionally, or protected in a shared middleware layer while the OpenAPI specification remains incomplete. These gaps make it harder to review the actual attack surface and easier to miss ownership questions during development.
I built shadowaudit as an open-source static-analysis CLI to make that inventory work more visible. The tool scans supported application codebases for routes, can compare discovered routes with an OpenAPI specification, maps findings to OWASP API Security Top 10 context, and presents the result in formats suited to local review and CI workflows.
| Capability | Practical purpose |
|---|---|
| Route discovery | Creates an inventory from supported framework source code instead of relying only on maintained documentation. |
| OpenAPI comparison | Highlights routes that appear in code but not in the supplied specification. |
| Authentication context | Distinguishes route-level, upstream, controller, environment-only, and no-auth conditions. |
| OWASP API mapping | Gives reviewers common vocabulary for discussing an observation without treating the mapping as proof of exploitation. |
| Risk score and filters | Provides a review signal and lets intentional routes be excluded through .shadowauditignore. |
| Table, JSON, SARIF, and Markdown output | Makes results usable in terminals, reports, and CI/security integrations. |
One design priority is false-positive control. A route without inline middleware is not automatically unauthenticated. It may inherit an authentication layer upstream, check identity inside a controller, or exist only in a test environment. The public implementation documents five auth statuses so that only the documented no auth condition contributes to critical-risk logic; the other contexts remain visible without being promoted to the same severity.
This is a review aid, not an autonomous verdict. Static analysis can reveal inventory gaps and give developers an actionable place to start, but a flagged route still needs human review. Configuration, deployed infrastructure, gateway enforcement, and business authorization logic may live outside the source pattern that a CLI can observe.
shadowaudit is in active public development. Its public README documents support for Express, FastAPI, Django, Flask, NestJS, Rails, Grape, and Spring Boot, alongside work on authentication-context detection and false-positive reduction. These are documented product capabilities, not a guarantee that the tool will find every issue in every application.
Route inventory is security context. The more clearly a team can compare what its code exposes with what its API contract declares, the earlier it can ask the right review questions.