feat: experimental traffic analysis#2848
Conversation
🦋 Changeset detectedLatest commit: fdc6bc1 The changes in this PR will be included in the next version bump. This PR includes changesets to release 3 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
sobanieca-redocly
changed the title
Coverage Report
File Coverage
|
||||||||||||||||||||||||||||||||||||||||||||
Performance Benchmark (Lower is Faster)
|
|
@cursor review |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
|
@cursor review |
|
@cursor review |
|
@cursor review |
|
@cursor review |
|
@cursor review |
|
@cursor review |
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
There are 2 total unresolved issues (including 1 from previous review).
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 47e4b1e. Configure here.
|
|
||
| - Starts a reverse proxy that forwards every request to an upstream `--target` | ||
| and records each request/response exchange into a HAR file. | ||
| - The HAR file is written incrementally (after each exchange) and flushed on |
There was a problem hiding this comment.
As mentioned during demo - do we want to keep this behavior for the first release? (this means proxy will be usable only for short lived processes like e2e tests etc.). In future we can introduce chunking (and give drift command option to read whole folder of traffic files). Eventually we can switch to ndjson format and append line by line.
| - `--api <path>`: OpenAPI file or folder to validate against. Omit to generate. | ||
| - `--traffic-format <auto|har|kong|nginx-json|apache-json|ndjson>` (default: `auto`) | ||
| - `--format <pretty|json|csv|sarif>` (default: `pretty`) | ||
| - `--match-mode <strict-host|basepath>` (default: `strict-host`): how requests are located |
There was a problem hiding this comment.
Since we add server option which seems more flexible maybe we should get rid of match-mode param at all? That way we will always use strict-host so we validate against OAD, but user may also override server.
| Mutually exclusive with `--match-mode`: use `--match-mode` when the traffic URLs align | ||
| with the description `servers`, use `--server` to declare the actual server when they | ||
| do not. | ||
|
|
There was a problem hiding this comment.
As presented during demo - shall we include ignore option for the first release? To avoid messages about unknown headers like x-caddy-authtoken etc.
| 'packages/**/__tests__/**/*', | ||
| 'packages/cli/src/index.ts', | ||
| 'packages/cli/src/utils/assert-node-version.ts', | ||
| 'packages/cli/src/commands/drift/**', |
There was a problem hiding this comment.
Is it fine if we ignore coverage for experimental commands? I would expect that source code there may change significantly over time after getting feedback on usage....
| - missing required parameters/body, | ||
| - request/response schema mismatches, | ||
| - baseline security issues (opt-in OWASP API risk heuristics). | ||
| - When no spec is provided, infers an OpenAPI 3.1 description from the traffic. |
There was a problem hiding this comment.
Do we need to improve OAD generation option for the first release? Maybe we should explicitly require path to folder where OAD will be saved and implement more sophisticated schemas generation?
On the other hand - we may wait for feedback and do this in next iteration.
There was a problem hiding this comment.
As discussed in Slack - we will remove OAD generation in this PR.
1 participant
What/Why/How?
PoC for traffic analysis so we can check
driftbetween real traffic and specified OAD.Reference
Testing
Screenshots (optional)
Check yourself
Security
Note
Medium Risk
Large new CLI surface with dynamic plugin imports and a local reverse proxy that forwards real HTTP traffic; security rules are heuristic and experimental rather than core auth changes.
Overview
Adds two experimental CLI commands:
driftcompares recorded HTTP traffic to an OpenAPI description (or generates OpenAPI 3.1 from traffic when--apiis omitted), andproxyforwards live requests to an upstream while writing a HAR and optionally running the same checks in real time.driftingests HAR, Kong, Nginx/Apache JSON, and NDJSON (auto-detect or explicit format), normalizes exchanges, matches them to bundled OpenAPI operations, and runs pluggable rules—defaults cover undocumented routes, schema/parameter consistency (AJV), and security baselines;owasp-api-top10is opt-in. Reports can be pretty, json, csv, or sarif; error-level findings exit with code 1. External--plugin/--traffic-pluginmodules can extend rules and parsers.proxyreuses the shared in-memoryValidationSessionfrom drift, streams live findings, and prints a full drift report on shutdown.lintconfig output now skips mixing config-lint into csv/sarif single-document formats. E2E snapshots cover formats, generation, and validation scenarios.Reviewed by Cursor Bugbot for commit 47e4b1e. Bugbot is set up for automated code reviews on this repo. Configure here.