SECURITY & PRIVACY

Security & Secret Sanitization

Accidentally persisting secrets into Git fixtures is the biggest risk of HTTP recording. VEXFOX implements in-memory redaction pipelines that scrub credentials before fixtures are ever serialized to disk.

1. The Security Threat Model

When recording interactions with external services (Stripe, OpenAI, OAuth providers, internal microservices), requests inevitably contain live authorization tokens, cookies, or secrets. If a tool writes raw wire traffic directly to disk, those credentials risk being committed to public or shared Git repositories.

Core Guarantee: Pre-Persistence Scrubbing

VEXFOX redacts sensitive data in memory before writing to the temporary cassette file. Raw credentials never touch disk, even momentarily.

2. Default Scrubbed Targets

Out of the box, VEXFOX scrubs five layers of sensitive data:

1. Sensitive Headers (Case-Insensitive)

Header values matching any of the following keys are replaced with `[REDACTED]`:

AuthorizationProxy-AuthorizationCookieSet-CookieX-Api-KeyX-Auth-TokenApiKey

2. Sensitive Query Parameters

URL query string values are sanitized in the recorded URI:

api_keytokensecretpasswordaccess_tokenauthclient_secret

3. Recursive JSON Body Keys

Traverses nested dictionaries and lists in JSON request and response bodies, redacting:

passwordsecretapi_keytokenclient_secretprivate_keyaccess_token

4. High-Entropy Pattern Scanners

Regular expression scanners detect common third-party token signatures regardless of where they appear:

Bearer tokens (`Bearer eyJ...`)
OpenAI API keys (`sk-...`)
Stripe live secrets (`sk_live_...` and `rk_live_...`)
JSON Web Tokens (JWT `eyJ...`)
AWS Access Key IDs (`AKIA[0-9A-Z]{16}`)
Basic Auth credentials in URLs (`https://user:pass@host/` -> `https://user:[REDACTED]@host/`)

3. Secret-Safe Mismatch Diagnostics

When an unrecorded request is made during replay mode, VEXFOX raises `RequestMismatchError`. Crucially, the diagnostic diff printed in the test traceback passes through the sanitizer first. Tokens in the incoming request are redacted in the diagnostic error message to prevent accidental leaks into CI build logs.

4. Defining Custom Redaction Rules

tests/test_custom_security.py

36 lines

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
from vexfox import VexfoxConfig, use_cassette
import httpx

# Configure specialized domain-specific redaction rules
strict_security_config = VexfoxConfig(
    sensitive_headers={
        "authorization",
        "proxy-authorization",
        "cookie",
        "x-api-key",
        "x-company-secret",
    },
    sensitive_query_params={
        "token",
        "session_id",
        "auth_sig",
    },
    sensitive_body_keys={
        "password",
        "secret",
        "client_secret",
        "private_key",
        "access_token",
        "social_security_number",
        "pan",
    },
    redaction_marker="[REDACTED]",
)

with use_cassette("fixtures/banking_api.json", config=strict_security_config):
    response = httpx.post(
        "https://api.bank.example.com/transfer",
        headers={"X-Company-Secret": "ultra_secret_key_881"},
        json={"account": "12345", "pan": "4111222233334444"},
    )
    assert response.status_code == 200

5. Operational Boundaries & Realistic Limits

What VEXFOX Cannot Automatically Guarantee

Opaque Binary Payloads: Protobuf, Avro, MessagePack, or encrypted binary streams cannot be parsed by default. They are preserved verbatim using base64.
Arbitrary Proprietary Formats: Custom secret formats not matching known patterns or configured keys must be added to `sensitive_body_keys` or `sensitive_headers`.
Engineering Rule: Always perform a code-review diff on new cassette JSON files before committing them to version control.

Configuration & Modes

Troubleshooting & Diagnostics