Skip to content
Last updated

proxy

The proxy command captures live HTTP traffic through a reverse proxy into a HAR file, and optionally validates it against an OpenAPI description in real time.

Experimental

This is an experimental feature. Its behavior, command, flags, and output may change in future releases.

The proxy command supports OpenAPI 3.x descriptions only.

The proxy command:

  • Starts a reverse proxy that forwards every request to an upstream --target and records each request/response exchange into a HAR file.
  • Appends each exchange to a temporary file on disk as it is captured (nothing is held in memory), then assembles the final HAR document on shutdown.
  • When --api is provided, validates each captured exchange live against the description using the same engine as drift; findings are printed as they happen and a full report is rendered on shutdown.

The resulting HAR file can be replayed through drift later.

Spec loading reuses @redocly/openapi-core, schema validation reuses the bundled @redocly/ajv, and the upstream client uses undici (already shipped), so there are no extra runtime dependencies.

Clients must target the proxy directly; there is no forward/CONNECT mode and no inbound TLS termination. The accept-encoding header is stripped from forwarded requests so captured bodies are stored decoded; binary response bodies are stored base64-encoded in the HAR.

Captured exchanges are streamed to a temporary file (<har>.entries.tmp) and assembled into the final HAR only on shutdown. If the process is terminated before shutdown, the temporary file remains but the final HAR is not written.

Usage

redocly proxy --target <url> --har <path>
redocly proxy --target <url> --har <path> --api <api>
redocly proxy --target <url> --har <path> [--port=<number>] [--host=<string>]

Options

OptionTypeDescription
--targetstringREQUIRED. Upstream base URL to forward captured requests to.
--harstringREQUIRED. Path to the HAR file where captured traffic is written.
--portnumberPort the proxy listens on (0 picks a free port). Default value is 4040.
--hoststringHost the proxy binds to. Default value is 127.0.0.1.
--apistringOpenAPI description file or folder to validate captured traffic against (live).
--formatstringOutput format for the validation report printed on shutdown.
Possible values: pretty, json, csv, sarif. Default value is pretty.
--match-modestringEndpoint matching mode.
Possible values: strict-host, basepath. Default value is strict-host.
--ignore-cookiesbooleanIgnore cookie-based checks. Default value is false.
--ignore-headersstringComma-separated header names to skip in undocumented-header checks. A trailing * matches by prefix, for example x-consumer-*.
--max-findingsnumberMaximum findings shown in pretty output. Default value is 10.
--rulesstringComma-separated subset of built-in rules to run: undocumented-endpoint, schema-consistency, security-baseline, owasp-api-top10.
--configstringSpecify the path to the configuration file.
--lint-configstringSpecify the severity level for the configuration file.
Possible values: warn, error, off. Default value is warn.
--helpbooleanDisplay help.
--versionbooleanDisplay version number.

Examples

Capture only (no validation)

redocly proxy --target https://api.example.com --har ./capture.har
# point your client at http://127.0.0.1:4040, then press Ctrl+C to stop

Capture and validate live against a description

redocly proxy --target https://api.example.com --har ./capture.har --api ./openapi.yaml

Replay a captured HAR through drift

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

Exit codes

  • 0: no error-level findings (or capture-only mode).
  • 1: error-level drift detected in captured traffic.
  • drift replays a recorded HAR (or other traffic log) against an OpenAPI description.
  • generate-spec infers an OpenAPI description from a captured HAR.

push