Find shadow APIs in Express.js before they become production threats

Developers frequently spin up temporary endpoints during debugging or prototyping only to forget removing them later. These undocumented routes—often called shadow APIs—bypass authentication layers and slip into production unnoticed. Traditional network scanners miss them entirely, leaving security teams unaware of potential attack vectors.

Enter Shadowaudit, a static analysis CLI that compares every route in an Express.js codebase against an OpenAPI/Swagger specification. By integrating directly into CI/CD pipelines, it blocks problematic routes before pull requests merge, ensuring only documented and authenticated endpoints reach production.

How Shadowaudit uncovers hidden risks

Shadowaudit scans JavaScript files for route definitions using AST-based analysis powered by Babel. It then cross-references each discovered route with an OpenAPI 3.x or Swagger 2.0 specification. Any mismatch triggers a failure in the CI pipeline, preventing undocumented or insecure endpoints from deploying.

The tool currently supports Express.js with planned expansions to FastAPI and Django. Its detection logic focuses on two critical gaps:

• Undocumented routes: Endpoints defined in code but missing from API documentation
• Missing authentication: Routes that lack security middleware despite being exposed to the internet

When a shadow API is detected, the CI pipeline fails immediately if the issue meets the configured severity threshold.

Configurable severity levels that fit your risk appetite

Shadowaudit assigns findings to three severity levels, each with distinct CI pipeline behaviors:

• Critical: Undocumented route without authentication middleware → Pipeline fails immediately
• High: Undocumented route with authentication present → Pipeline passes but flags for review
• Info: General informational finding → Pipeline passes

Teams can adjust the --fail-on threshold to match their security policies. A default of critical ensures only the highest-risk issues halt deployments, while high or info settings allow flexible enforcement.

Seamless integration into existing workflows

Installation takes seconds. Run Shadowaudit globally for quick checks:

npm install -g shadowaudit

Or add it as a dev dependency for project-specific scans:

npm install --save-dev shadowaudit

Execute a scan with minimal configuration:

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

For framework-specific analysis, specify the environment:

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

Output flexibility supports various pipeline needs:

• Table format: Human-readable output with colored severity indicators
• JSON: Structured data for log aggregation and dashboard integration
• SARIF 2.1.0: Standardized format compatible with GitHub Code Scanning and Azure DevOps

Beyond defaults: Advanced configuration options

Shadowaudit loads settings from a .shadowaudit.yml file in the project root, with CLI flags taking precedence. A typical configuration might look like:

spec: ./openapi.json
dir: ./src
format: table
failOn: critical
authPatterns:
  - myCustomAuth
  - requireLogin
ignore:
  - node_modules
  - dist
  - build

Even without custom patterns, the tool automatically detects common authentication middleware signatures such as:

• authenticate(
• authorize(
• requireAuth
• jwt.verify
• passport.authenticate

Ignored paths can be customized to exclude build artifacts and third-party dependencies, reducing noise in scan results.

Looking ahead: A stronger API security foundation

Shadow APIs represent a persistent blind spot in many codebases. By catching undocumented and unauthenticated routes during development, Shadowaudit shifts security left without disrupting existing workflows. As frameworks like FastAPI and Django gain support, the tool’s utility will expand across more backend ecosystems. For teams serious about API security, integrating Shadowaudit into CI pipelines is a straightforward step toward reducing exposure and maintaining cleaner, more reliable code.