Shadow APIs: finding the endpoints nobody is tracking
A shadow API is an API that runs and takes requests but is missing from the organisation's inventory, so nobody reviews, patches or monitors it. A zombie API is one that was supposed to be retired and still answers. Neither term comes from OWASP, which files the underlying problem under API9, improper inventory management, in the OWASP API Security Top 10 2023. This guide covers how forgotten endpoints appear, how to inventory them and how to switch them off. It belongs to API security.
Quick facts
- Named by
- OWASP API9:2023, improper inventory management, in the 2023 edition of the OWASP API Security Top 10
- The gap
- Missing or outdated documentation, hosts with an unclear purpose, and no retirement plan for old versions (OWASP's description of API9)
- Typical finds
- Old versions left running, beta and test hosts, undocumented endpoints, unmonitored data flows to third parties
- Record per host
- Environment, intended network audience and API version, according to the API9 prevention list
- Machine-readable format
- The OpenAPI Specification, a language-agnostic interface description for HTTP APIs
- Retirement signals
- The Deprecation header (RFC 9745) and the Sunset header (RFC 8594)
- Does a WAF keep your API inventory?
- No. It sees only the traffic routed through it, and it cannot know about a host that traffic never reaches
Sources: the OWASP API9:2023 chapter, the OWASP API Security Project, the OpenAPI Specification, RFC 9745, RFC 8594 and RFC 9110 for status codes.
Shadow, zombie, deprecated
The vocabulary is loose, and vendors use the words in slightly different ways. For a working team the useful split is by what is wrong with the record, not by what the API does.
| Term | What it is | Usual cause |
|---|---|---|
| Shadow API | Live, in use, and never recorded | A team shipped it without review, or the owner left |
| Zombie API | Recorded as retired, still answering | Shutdown was planned but never carried out |
| Deprecated API | Known, marked for removal, still supported for now | A newer version exists; clients have not moved |
| Undocumented endpoint | A route on a documented host that the spec omits | Code added after the documentation was written |
A deprecated API is the healthy case: someone knows it exists and has a date. The other three are the ones API9 is about, because nobody is accountable for them. The security problem is the same in each. The endpoint accepts requests, yet it gets none of the review the main API gets.
Where forgotten endpoints come from
OWASP describes two blind spots. The documentation blind spot covers old versions, hosts whose purpose nobody remembers and endpoints missing from the docs. The data flow blind spot covers data passed to third parties without anyone watching it. In practice the sources look like this.
- Old versions left running. A new version ships, the old one stays up for a few clients, and then no one removes it. API9 lists running several versions as a wider attack surface and names old versions left unpatched as the usual way in.
- Beta, test and debug hosts. A host created for a launch or a test keeps its DNS record and its route to the same data. It is easy to forget because nothing links to it.
- Routes added in code only. A developer adds an endpoint for a one-off job. The code is merged, the spec is not updated, and the route is live.
- Copies of production data. API9 advises against putting production data in non-production environments, and says that if it cannot be avoided, those environments need the same protection as the real one.
- Third-party integrations. OWASP asks for an inventory of integrated services too: what role each plays, what data it receives and how sensitive that data is.
OWASP's first example scenario shows why one forgotten host matters. A social network limited password-reset attempts outside the API code. A beta host running the same API did not have that limit, and a researcher used it to take over accounts. The weakness was never in the main API. It was in a copy nobody had counted. Missing limits on such a copy are what per-route endpoint security is meant to catch, and the general method for finding them is under API security testing.
Building an API inventory
An inventory is a list you maintain. Discovery is the process that finds what the list is missing. You need both, and the second one never ends, because new endpoints keep appearing.
- List every host. For each, write the environment, who is meant to reach it (internet, partners, internal only) and the API version. These three are the fields OWASP names.
- Describe each API in OpenAPI. The specification gives people and tools a standard way to understand an HTTP API without reading its source. OWASP advises generating the documentation automatically from open standards and building it into the CI/CD pipeline, so it changes when the code changes.
- Record what each endpoint needs. API9 asks for authentication, errors, redirects, rate limiting, CORS policy, and the parameters, requests and responses of each endpoint.
- Compare declared with observed. Take the paths and hosts that appear in access logs and DNS, and subtract those in the specification. The remainder is your list of candidates.
- Give every entry an owner and a review date. An entry with no owner is how a zombie is made.
- Restrict who can read the documentation. OWASP says to limit API documentation to authorized users, since a full spec is also a map for an attacker.
| Source | What it finds | What it misses |
|---|---|---|
| OpenAPI documents | What the team intended to publish | Anything nobody wrote down |
| Gateway or router configuration | Routes that are wired to a backend | Hosts that bypass the gateway |
| DNS zone records | Host names that still resolve | Paths, and what runs behind a name |
| Cloud load balancer and service lists | Running services and their addresses | Which of them serve an API |
| Access logs at the origin | Paths and versions that really receive requests | Endpoints that nobody has called yet |
| Source code and route tables | Endpoints that exist in the build | Services deployed from older builds |
declared (OpenAPI) observed (origin access log)
GET /v2/orders GET /v2/orders
POST /v2/orders POST /v2/orders
GET /v1/orders <- version not in the spec
GET /internal/ping <- route not in the spec
host: api.example.com host: beta-api.example.com <- host not in the list
Every line marked on the right is a question for an owner, not yet a finding. Some will be legitimate and simply unrecorded; add them to the inventory. Others should be closed. Methods that appear in the log but not in the spec deserve a look as well, which is where HTTP methods comes in.
Retiring an API
Switching an API off without warning breaks clients, so the usual path has stages. OWASP also frames the decision: when a newer version adds security improvements, assess the risk and choose between backporting the fix to the old version or retiring it quickly.
- Mark it deprecated. In OpenAPI, an operation can carry
deprecated: true; the specification says consumers should refrain from using such an operation. - Tell callers in the response. RFC 9745 defines a Deprecation response header that signals a resource is or will be deprecated. RFC 8594 defines Sunset, which signals when it is likely to stop responding. RFC 9745 states that the Sunset date must not be earlier than the Deprecation date. Both are hints to clients and change nothing on their own.
- Watch who still calls it. Count requests per version and per client in the origin log. A flat line means you can go ahead; a steady caller means a conversation.
- Switch it off. Return a clear status instead of a silent timeout. RFC 9110 defines 410 Gone for a resource that is no longer available and is likely to stay that way.
- Clean up. Remove the route, the DNS record, the credentials and any data copies that only the old version used, then close the entry in the inventory.
paths:
/v1/orders:
get:
deprecated: true
summary: Superseded by GET /v2/orders
Retirement is a change to the application and its hosting. Nothing in front of the API can complete it for you, though a filter can help during the wait, as the next section explains.
Where a WAF helps and where it does not
A WAF filters requests that reach it. A forgotten host that resolves directly to an origin never sends it a single request, so the filter has nothing to inspect there. This is the first limit and the most important one: coverage depends on routing, and the inventory is what tells you whether the routing is complete.
The second limit is the log. The activity log records requests that were flagged, not every request, so it cannot list the paths your API serves. Treat it as one more clue. A flagged request for an old version on a known host is worth a look, but a quiet log proves nothing about what exists.
Where traffic does pass through the filter, API9 asks for protection on every exposed version, not only the current one. For a deprecated version that still has clients, that means keeping the same rules and per-domain rate limits in front of it while you wait for the Sunset date. A WAF cannot give an old version the authorisation checks it lacks. Those remain code, which is the ground covered by BOLA and API authentication.
Start in monitor mode when you first route a newly found host through the filter. Matches are logged while every request is still served, so you can read the monitor-mode log before choosing block. The three modes are in the box below.
Questions
What is a shadow API?
A shadow API is an API that is running and taking requests but is missing from the organisation's inventory, so nobody reviews, patches or monitors it. OWASP does not use the term; it files the underlying problem under API9:2023, improper inventory management.
What is a zombie API?
A zombie API is an old API, version or host that was meant to be retired but still answers requests. It often keeps old code and weaker checks than the current version, which is why OWASP API9 asks for a retirement plan for every version.
How do you find shadow APIs?
Compare what you have declared with what you can observe. Declared means OpenAPI documents, gateway configuration and a list of hosts; observed means access logs, DNS records and cloud load balancer listings. Anything seen but not declared is a candidate.
How do you retire an old API version?
Mark it deprecated in the specification, announce a date, send the Deprecation and Sunset headers, watch the logs for callers still using it, then switch it off and remove its host name. After shutdown, a 410 status signals that the resource is gone.
Can a WAF find shadow APIs?
Only partly. A WAF sees the traffic that passes through it, so a host that resolves straight to an origin is invisible to it. Its log records flagged requests, not every request, which makes it a weak inventory source.