drift

The drift command detects drift between recorded HTTP traffic and an OpenAPI description. The command reads a traffic log (or a folder of logs), matches each request/response exchange to a documented operation, and reports the discrepancies it finds.

The drift command reports:

• undocumented endpoints
• undocumented request parameters and headers
• missing required parameters or request bodies
• request and response schema mismatches
• baseline security issues (opt-in OWASP API risk heuristics)

Spec loading reuses the same engine as the other commands (@redocly/openapi-core), and schema validation reuses the bundled @redocly/ajv, so there are no extra runtime dependencies.

The traffic input can be provided in any of the following formats. By default the format is detected automatically from the file contents:

• HAR
• Kong
• Nginx JSON
• Apache JSON
• NDJSON

JSON-array traffic files (HAR, Kong, and webserver JSON) are read fully into memory. For very large captures, prefer the NDJSON format, which is streamed.

redocly drift <traffic> --api <api>
redocly drift <traffic> --api <api> [--traffic-format=<option>]
redocly drift <traffic> --api <api> [--format=<option>] [--output=<file>]
redocly drift <traffic> --api <api> [--server=<url>]
redocly drift <traffic> --api <api> [--match-mode=<option>]
redocly drift <traffic> --api <api> [--coverage] [--coverage-output=<file>]

The owasp-api-top10 rule is opt-in and only runs when included in --rules.

redocly drift ./traffic.har --api ./openapi.yaml

redocly drift ./traffic-logs/ --api ./openapi/ --format json

When the captured traffic does not carry the documented host or base path (for example, behind a gateway that adds /api), use --server to declare the actual server. Only requests under it are considered, and the remaining path is matched against the description paths directly:

redocly drift ./traffic.har --api ./openapi.yaml --server localhost:9000

A gateway such as Caddy often injects headers that are not part of the API contract (for example authentication or consumer-identity headers). Skip them so they don't show up as undocumented headers. Use a trailing * to match a family of headers by prefix:

redocly drift ./traffic.har --api ./openapi.yaml --ignore-headers "x-caddy-auth-token,x-auth-intent,x-consumer-*"

redocly drift ./traffic.har --api ./openapi.yaml --format json -o ./drift-report.json

redocly drift ./traffic.har --api ./openapi.yaml --coverage --coverage-output ./coverage.json

Drift tells you where the traffic disagrees with the description. Coverage tells you how much of the description the traffic exercised at all, so you know how far the drift findings can be trusted. Coverage is measured the same way test runners measure code coverage: each documented item is either covered by at least one exchange or missing.

With --coverage, the command prints an overview after the drift report:

API coverage
  operations         ███████████████░░░░░   75%      3/4
  parameters         ██████████░░░░░░░░░░   50%      2/4
  schema properties  ████████░░░░░░░░░░░░   41%    16/39
  response codes     ███████████░░░░░░░░░   57%      4/7

Schema properties are collected from properties, items, allOf, oneOf, and anyOf. Properties marked readOnly are not expected in requests and properties marked writeOnly are not expected in responses, so they are not counted on that side. A property declared in several oneOf or anyOf branches is counted once, and a body covers it whenever it carries that field, whichever branch declares it.

If the report on stdout is machine-readable (--format json, csv, or sarif without --output), the overview is printed to stderr so the report stays parseable.

With --coverage-output, the command writes a JSON report that lists, for every operation, the items the traffic covered and the items it never exercised:

{
  "version": 1,
  "meta": {
    "spec": "./openapi.yaml",
    "traffic": "./traffic.har",
    "matchMode": "strict-host",
    "exchanges": { "total": 4, "matched": 4, "withBody": 4 }
  },
  "totals": {
    "operations": { "covered": 3, "total": 4 },
    "parameters": { "covered": 2, "total": 4 },
    "properties": { "covered": 16, "total": 39 },
    "responses": { "covered": 4, "total": 7 }
  },
  "operations": [
    {
      "method": "GET",
      "path": "/items",
      "operationId": "listItems",
      "missing": [
        { "kind": "parameter", "name": "limit", "in": "query" },
        { "kind": "property", "target": "response", "status": "200", "path": "[].tags" },
        { "kind": "response", "status": "400" }
      ],
      "covered": [
        { "kind": "operation" },
        { "kind": "parameter", "name": "category", "in": "query" },
        { "kind": "response", "status": "200" },
        { "kind": "property", "target": "response", "status": "200", "path": "[].name" }
      ]
    }
  ]
}

• meta.exchanges.withBody counts the matched exchanges that carried a JSON request or response body.
• A property path is relative to the body: [] marks array items, so [].price.amount is the amount of the price of each element.

The coverage output is experimental and its shape may change. Coverage does not affect the exit code.

• 0: no error-level findings.
• 1: error-level drift detected.

• proxy captures live HTTP traffic into a HAR file that can be replayed through drift.
• generate-spec infers an OpenAPI description from the same traffic formats.