Never commit secrets
Reqbook treats endpoint, pipeline, project markdown, and env.template.md as safe-to-commit artifacts. Generated env.md files are gitignored by default because environment values often drift by machine or deployment. Secrets belong in .env.local, CI environment variables, or a secret manager never in env markdown, endpoint files, pipeline files, or reqbook.md. The parser actively enforces this before any request is sent.
Secret detection
Reqbook scans env.template.md, env.md, endpoint files, pipeline files, and reqbook.md for common secret patterns during rqb validate and before every execution. If a match is found, the command exits with code 5 no network request is made.
Patterns that trigger exit code 5
| Pattern | Example | Reason |
|---|
Bearer eyJ... | Authorization: Bearer eyJhbGc... | JWT-like bearer token |
| Hex strings > 32 chars | a3f9c2d1b4e8... (33+ hex chars) | Typical API key encoding |
Prefix sk_ | sk_live_abc123 | Stripe-style secret key |
Prefix pk_live_ | pk_live_abc123 | Stripe-style live publishable key |
api-docs/_shared/env.md:12: possible secret detected
Fix: move this value to .env.local or RQB_* environment variables.
Allowed secret locations
| Location | When to use |
|---|
.env.local | Local development. Must be listed in .gitignore. Never committed. |
RQB_* OS env vars | CI/CD pipelines and shared environments. Set in your CI provider’s secret store. |
| Secret manager + env | RQB_AUTH_TOKEN=$(vault read secret/api-token) inject at runtime from HashiCorp Vault, AWS Secrets Manager, or similar. |
api-docs/_shared/env.md files are also listed in .gitignore by default, while api-docs/_shared/env.template.md is meant to be committed. Both are still for non-secret values only.
rqb doctor checks that .env.local and the generated api-docs/_shared/env.md path are listed in .gitignore and reports an error with a fix suggestion if either is missing. Run it after rqb init and before onboarding new contributors.
Output masking
Reqbook masks auth header values and known secret variable names in all output surfaces: CLI console, JSON reports, JUnit XML, markdown reports, and the web preview response history.
| Input | Masked output |
|---|
Authorization: Bearer abc123 | Authorization: Bearer **** |
Authorization: Basic dXNlcjpwYXNz | Authorization: Basic **** |
authToken=abc123 | authToken=**** |
Production confirmation
Running against a prod or production environment requires explicit confirmation in an interactive terminal. Reqbook prompts before sending any request when a production environment is selected.
rqb exec api-docs/apis/users/delete-user.md --env=prod
# Reqbook: You are about to execute endpoint against `prod`. Confirm? [y/N]
--yes is passed after deliberate review:
rqb exec api-docs/apis/users/get-users.md --env=prod --yes
Never pass --yes to destructive endpoints (DELETE, or POST to production data) in automated pipelines without deliberate human review of the entire workflow. Production confirmation exists to prevent accidental data loss from misconfigured CI jobs.
Localhost and desktop writes
rqb serve binds to loopback by default and rejects browser writes that clearly come from a cross-site origin. This protects the common case where a random website tries to submit a write request to your local Reqbook preview server.
Reqbook desktop adds an extra session check for unsafe methods (POST, PUT, PATCH, and DELETE). The embedded server issues an HttpOnly rqb_write_token cookie with SameSite=Strict when the desktop UI loads. Desktop write endpoints require that active session, so drive-by browser writes without the desktop session are rejected.
This is not a substitute for operating-system account security. A local process running as your user can still access files that your user can access. Treat Reqbook desktop as a local developer tool and avoid opening untrusted workspaces.
Run the desktop smoke test before release candidates to verify this guard:
cargo build --locked -p rqb-desktop
node scripts/desktop-smoke.mjs
Exit codes
Every Reqbook command exits with a stable, machine-readable code. CI pipelines can branch on these codes to distinguish test failures from spec errors.
| Code | Meaning |
|---|
0 | Passed |
1 | Test failed response did not match expected |
2 | Invalid spec missing field, unresolved variable, or malformed file |
3 | Engine error internal Reqbook error |
4 | Network error connection refused, timeout, or DNS failure |
5 | Secret detected a versioned file contains a possible credential |
