Why an API inventory is the foundation of every defense

Protection starts with visibility. What an organization doesn't know about, it can neither patch, nor monitor, nor shut down. NIST states in SP 800-228 that most organizations have gaps in their API inventory, even when the rest of their asset management is mature, and that without an accurate inventory, securing the estate cannot even begin. Security incidents can then play out at the API level without the security team ever learning of it.

This exact gap is what the OWASP API Security Project describes as Improper Inventory Management (API9:2023): old versions, forgotten hosts, and unvetted data flows to third parties enlarge the attack surface. Discovery and inventory are the defensive counterpart to this. They fall under the Identify function of the NIST Cybersecurity Framework: recognize what exists first, then protect it.

It's important to separate the terms. Discovery is the process of tracking down APIs. The inventory is the maintained register that results from it. An inventory, once created, becomes outdated again immediately, because new endpoints appear and old ones change. That's why both only make sense as a continuous process, not a one-time project.

TypeGuiding questionDetected via
ShadowRunning in production but unknown in the inventory?Traffic without a matching specification
ZombieOld version that was never shut down?Traffic on deprecated version paths in the gateway
OrphanNo responsible team left?Missing owner assignment in the inventory
PhantomNever planned in a spec, ticket or review?Pure runtime traffic with no planning source at all
Spec driftTraffic deviates from the specification?Fields, types or status codes in traffic with no counterpart in the spec

Notable endpoints and how discovery detects them

Correlating sources: where the inventory comes from

No single source knows about all APIs. A reliable inventory only emerges once several views are merged and cross-checked against each other. Every source has blind spots that another one closes.

  • Code and repositories: route definitions, controllers, annotations and specification files (e.g. openapi.yaml) show what teams have built. But they don't reveal whether an endpoint is actually reachable in production.
  • Infrastructure and gateways: API gateways, load balancers, ingress rules, DNS entries and service meshes show what is actually exposed and routed. However, endpoints that bypass the gateway are missing here.
  • Documentation and specifications: OpenAPI, gRPC or GraphQL definitions describe the intended state. NIST recommends in REC-API-1 that every API should have a specification at all, ideally in a machine-readable IDL.
  • Asset and CMDB registers: existing directories provide owner, business context and sensitivity, but are often incomplete for APIs.

Correlating these sources uncovers contradictions: an endpoint in the code without a gateway route, a host in DNS without an entry in the docs, a specification without a running service. These discrepancies are the actual findings.

Runtime discovery: real traffic against the specification

Static sources describe intentions. Only real traffic shows what's actually running. Runtime discovery observes the production data stream and derives from it the set of active endpoints, parameters and data types. NIST explicitly refers in REC-API-21.1 to semantic data discovery at runtime, which helps recognize the type of information flowing through a system (such as an email address) and build the initial inventory.

The decisive step is the comparison: observed traffic against the approved specification. Two kinds of deviations result from this:

  • Traffic without a specification: an endpoint receives requests but isn't captured in any spec. This is the typical sign of an interface that was never recorded, or built outside the process.
  • Specification without traffic: a documented endpoint receives no requests. This points to a dead route or an unused version.

On top of that there is spec drift: fields, status codes or parameters that appear in traffic but are missing from the specification or typed differently. NIST states in REC-API-3 and REC-API-5 that the request and response schema, including validation rules, should be part of the specification, so that runtime tools can automate exactly this comparison.

Recognizing shadow, zombie, orphan and phantom endpoints

The problematic endpoints are rarely new and correctly documented. They slip through the net because they're missing from at least one of the correlated sources. The industry names them inconsistently; what matters is not the label but along which question an endpoint stands out.

  • Shadow: runs in production but isn't captured in any inventory and is unknown to governance. Findable via traffic without a specification. NIST names such APIs, often built for debugging, testing or ad hoc fixes, that bypass security reviews.
  • Zombie: a superseded, technically outdated version that was never shut down and keeps receiving traffic. Findable via old version paths in gateway traffic alongside the current version.
  • Orphan: keeps running, but the responsible team no longer exists. Findable via a missing owner assignment in the inventory, not via a lack of visibility.
  • Phantom: an endpoint that never showed up in a spec, ticket or review, increasingly co-built by AI code generators. Findable only via runtime traffic, since it exists in no planning source.

NIST names organizational silos, high development velocity (the faster development goes, the faster inventories go stale), and zombie and deprecated APIs whose callers haven't migrated yet as drivers of these gaps.

Continuous, not one-off: inventory maintenance and lifecycle

An inventory is only as good as its update mechanism. NIST states in REC-API-4 that an organization-wide directory of all internal and external APIs should be maintained, and that each entry should include:

  • the API's specification (the inventory doesn't have to be the documentation itself),
  • owner information, to assign runtime issues to an organizational responsibility,
  • runtime information such as service instances, IP addresses, traffic volume, request and error rates, and the status of policy enforcement.

For the inventory not to go stale again, discovery needs to be embedded into the lifecycle. OWASP recommends generating documentation automatically via open standards and including the docs build in the CI/CD pipeline. A common governance lever is making an annotated specification a condition for deployment (the ticket to the platform approach described by NIST): whoever doesn't supply a spec doesn't get into production.

A dedicated standard exists for orderly retirement of old versions. RFC 8594 defines the Sunset HTTP header, which signals when a URI is expected to become unreachable. A documented deprecated status with a sunset date prevents a superseded version from turning into a zombie API. Runtime discovery meanwhile monitors whether traffic on the old version actually drops to zero before it's shut down.

Venedy's discovery core

Venedy maps exactly this comparison of real traffic against the approved specification as a core function. The platform correlates observed traffic with existing specifications and surfaces deviations: endpoints with traffic but no spec, documented routes with no traffic, and drift in fields, types and status codes. Shadow, zombie, orphan and phantom endpoints are thus named as concrete findings on your own interface, instead of remaining an abstract risk.

Because new endpoints keep appearing, discovery is built to be continuous: the inventory is checked against reality on an ongoing basis, not frozen in a one-time scan. Venedy is operated as a platform and not self-hosted; the conceptual discovery core is unaffected by this and follows the principles described here from OWASP API9 and NIST SP 800-228.

Sources

Keep reading
API9Improper Inventory Management FundamentalsAPI Gateways FundamentalsAPIs in Production