> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markapidown.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Security

> Reqbook prevents secrets from being committed to version control. Learn about secret detection, allowed secret locations, and output masking.

## 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 |

### Error format

```
api-docs/_shared/env.md:12: possible secret detected
Fix: move this value to .env.local or RQB_* environment variables.
```

The error includes the file path and line number so you can find and move the offending value immediately.

***

## 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. |

Generated `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.

<Tip>
  `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.
</Tip>

***

## 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=****`             |

Masking is applied before writing to any file, stream, or storage. Unmasked values are never written to disk by Reqbook.

***

## 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.

```bash theme={null}
rqb exec api-docs/apis/users/delete-user.md --env=prod
# Reqbook: You are about to execute endpoint against `prod`. Confirm? [y/N]
```

In non-interactive shells, Reqbook refuses to send production requests unless `--yes` is passed after deliberate review:

```bash theme={null}
rqb exec api-docs/apis/users/get-users.md --env=prod --yes
```

<Warning>
  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.
</Warning>

***

## 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:

```bash theme={null}
cargo build --locked -p rqb-desktop
node scripts/desktop-smoke.mjs
```

***

## Anonymous active usage

Anonymous active-usage reporting in the web and desktop UI is **off by default**. Users can enable or disable it from the **Feedback and support** popup.

When enabled, Reqbook sends a heartbeat containing:

* a random identifier stored in browser-local storage,
* the surface: `desktop` or `web`,
* the Reqbook version.

Reqbook does not include workspace paths, API URLs, request or response data, headers, variables, environment values, filenames, or source content. Disabling anonymous usage stops heartbeats and removes the local identifier.

The server retains each active-presence key for five minutes. Counts therefore represent opted-in users active within the last five minutes and can be delayed by Cloudflare KV propagation.

***

## 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    |