I'm building internal APIs and need to catch shadow endpoints

To catch shadow endpoints in internal APIs, you want a process that detects routes or services that exist but aren’t officially documented, reviewed, or expected by your gateway/router.

What to look for

Shadow endpoints usually show up as:

• Undocumented routes in your API framework or service code
• Old versions still reachable, like /v1/... after /v2/... is live
• Admin/debug/test endpoints left enabled
• Direct-to-service routes bypassing the gateway
• Endpoints exposed by config drift across environments
• Hidden handlers in serverless or microservice deployments

Practical ways to detect them

1. Compare runtime routes against the API spec

If you have OpenAPI/Swagger, generate a route inventory from running services and compare:

• documented paths vs
• actual registered paths

Any route in runtime but not in spec is a candidate shadow endpoint.

2. Scan service frameworks directly

Most frameworks can enumerate routes:

• Express / Fastify / NestJS
• Spring Boot
• Django / DRF
• Flask / Falcon
• ASP.NET Core
• Go routers like chi, gin, echo

Build a CI job or startup check that exports the live route table.

3. Inspect gateway and load balancer config

Shadow endpoints often exist because:

• a service is reachable through a misconfigured ingress
• a path is forwarded that shouldn’t be
• a stale route remains in an API gateway plugin or route table

Compare:

• gateway routes
• service routes
• DNS/service discovery entries

4. Use traffic-based discovery

Look at logs, traces, and APM:

• requests hitting paths not in your registry
• low-volume endpoints
• unusual HTTP methods
• endpoints used only by one client

This is especially useful for finding “forgotten” internal endpoints.

5. Active probing in a controlled environment

In staging or a test tenant:

• crawl known route prefixes
• fuzz with safe methods like OPTIONS or HEAD
• compare response patterns
• look for unexpected 200, 401, 403, or 405 responses on unlisted routes

Avoid broad probing in production unless your policy allows it.

Good controls to prevent them

• Single source of truth for routes, ideally API spec + generated router
• CI checks that fail if undocumented routes exist
• Gateway allowlists so only approved paths are exposed
• Route deprecation policy with explicit sunset dates
• Periodic route audits in every environment
• Access logging with alerts for unknown paths
• Disable debug/admin endpoints in production builds

A simple detection workflow

1. Export all live routes from services
2. Export all exposed routes from gateway/ingress
3. Compare both against OpenAPI
4. Review any mismatches:
   • undocumented
   • deprecated but still reachable
   • environment-specific
   • admin/debug
5. Remove, document, or explicitly approve them

Useful output format

A good internal report might include:

• route path
• HTTP method
• service owner
• environment
• exposed by gateway? yes/no
• documented? yes/no
• risk level
• action required

If you want, I can help you build:

• a shadow endpoint detection checklist
• a CI script to compare OpenAPI vs live routes
• or a framework-specific detector for Express, Spring Boot, FastAPI, etc.