Shadow API endpoint

Two ways to find them, and they disagree

Most security tooling discovers shadow endpoints from runtime traffic: watch the gateway, record what gets called, compare against the documented inventory. It works, and it has one structural blind spot — an endpoint nobody has called yet is invisible to it. The endpoints most likely to be forgotten are also the least likely to appear in a traffic sample.

The other method reads the code. Enumerate every route the application defines, then compare that list against what the documentation describes. This finds endpoints before anyone calls them, including the ones left behind by a migration that was never finished.

The two methods surface different sets, and neither is a superset of the other.

Where they come from

Shadow endpoints are rarely created deliberately. They accumulate:

• Debug and admin routes added during an incident and never removed
• Deprecated versions left running because something might still depend on them
• Partner-specific endpoints built for one integration, documented in an email
• Framework-generated routes nobody chose — health checks, introspection, defaults
• Endpoints that outlived their documentation, where the docs were removed and the route was not

Why they matter beyond tidiness

An undocumented endpoint is not merely untidy. It is unreviewed.

It sits outside the inventory that security review, threat modelling and penetration testing work from. It is not covered by the rate limits someone configured for the documented surface. Its authentication behaviour has not been checked against the policy, because nobody knew to check it. OWASP tracks this under improper inventory management, and it is consistently among the most-exploited API weaknesses — not because the endpoints are badly written, but because nothing is watching them.

Coding agents raise the cost further. An agent writing client code works from whatever inventory it can reach. An endpoint outside that inventory never gets used correctly; an endpoint inside it but documented wrongly gets used incorrectly at scale.

The inverse problem

Shadow endpoints have a mirror image: documented endpoints that do not exist. The documentation describes a route the code no longer serves — removed in a refactor, renamed, or never shipped.

These fail differently and more visibly. A developer writes against the documentation and gets a 404. An agent does the same and reports a bug that is not in the code. Both sets need finding, and the same comparison finds them: enumerate the code, enumerate the docs, look at the difference in both directions.

What reduces them

• Derive the inventory from the code, not from a spreadsheet someone maintains. Any inventory kept by hand drifts from the system it describes.
• Make the comparison run on every change, so a new undocumented route is visible at the merge rather than at the next audit.
• Treat the finding as a security item with an owner, not a documentation backlog ticket. An endpoint outside the inventory is an unreviewed attack surface regardless of which team's board it lands on.