Security Defaults and Presets¶
Default protections¶
| Protection | Default | Why |
|---|---|---|
| Body logging | OFF |
Avoid leaking request/response secrets |
| Sensitive key masking | ON |
Protect fields like password, token, secret |
| Sensitive header masking | ON |
Protect authorization, cookie, x-api-key |
| Query string in logged path | Excluded | Prevent accidental token leakage |
| Request ID trust boundary | Trusted CIDRs only | Prevent spoofed correlation IDs |
What redaction covers¶
The default formatter and OTLP log handler sanitize structured mappings and
sequences by field and header name. Matching ignores case and treats
underscores as hyphens. For example, {"token": "example-secret"} is masked;
{"message": "token=example-secret"} keeps its text. Sensitive header rules
apply inside a mapping named headers. Values under other names remain visible.
A name is also masked when it holds a configured name as whole words, split at
_, -, ., capital letters and digits. password covers new_password,
passwordConfirmation and password2; token covers id_token, accessToken
and X-Auth-Token; api_key covers x_api_key. Part of a word does not match:
max_tokens, tokenizer, passwordless and secretary stay visible. This can
mask a harmless field such as token_type or password_changed_at; the names
you add with OBS_REDACTED_FIELDS match the same way.
URL user/password pairs such as postgresql://user:password@db/app are replaced
with postgresql://***:***@db/app in request exception summaries, JSON
error.message / error.stacktrace, and the library's OTLP exception attributes.
This is a specific credential pattern, not a general URL or secret scanner.
It does not remove query tokens, arbitrary API keys, email addresses, phone
numbers or card numbers from free text. Regular log messages, arbitrary string
values and exception text outside that URL pattern can still contain them.
The pci and gdpr presets extend the configured field names and masking rules.
They do not detect every occurrence of personal or payment data and do not
establish regulatory compliance. Keep body capture off unless you need it.
These protections cover the library's own output paths. Independently configured handlers and exporters require their own sanitizer.
Keep your own sanitizer¶
If your application already has a redaction filter, JSON formatter or shared
Python/TypeScript sanitization contract, retain it with
configure_logging=False. Request
diagnostics pass through those existing handlers and their filters, including
structured context and exception records. Keep the same test vectors in your
application's integration tests, checking messages, event, user_context,
rendered tracebacks and every intended output/export destination.
If you want the library's JSON schema in an application-owned handler,
StructuredJsonFormatter already accepts a sanitize_payload callback:
from fastapiobserver import StructuredJsonFormatter
from fastapiobserver.security import sanitize_record
from my_app.redaction import redact_payload # Your existing, tested implementation.
def sanitize_payload(payload, policy):
return redact_payload(sanitize_record(payload, policy))
handler.setFormatter(StructuredJsonFormatter(sanitize_payload=sanitize_payload))
This callback replaces the formatter's sanitization step; composing it with
sanitize_record retains the built-in field rules too. It covers that formatter's
output, not other handlers or direct OTel exports. The
runnable application example
demonstrates a custom filter instead, including traceback sanitization. Its
patterns are examples only.
Presets for regulated environments¶
from fastapiobserver import SecurityPolicy
# Strictest option: drop sensitive values and keep minimal safe headers
strict_policy = SecurityPolicy.from_preset("strict")
# PCI-focused redaction fields
pci_policy = SecurityPolicy.from_preset("pci")
# GDPR-focused hashed PII fields
gdpr_policy = SecurityPolicy.from_preset("gdpr")
The hash mode, used by gdpr, writes hmac-sha256:<hex>: an HMAC keyed with OBS_REDACTION_HASH_KEY (or SecurityPolicy(hash_key=...)). Keep the key secret. Without one, a random key is picked at startup, so hashes differ between processes and after a restart, and a warning says so.
Use a preset in installation:
install_observability(app, settings, security_policy=SecurityPolicy.from_preset("pci"))
Allowlist-only logging (audit-style)¶
If your compliance model is "log only approved fields", use allowlists:
from fastapiobserver import SecurityPolicy
policy = SecurityPolicy(
header_allowlist=("x-request-id", "content-type", "user-agent"),
event_key_allowlist=("method", "path", "status_code"),
)
Body capture¶
Captured bodies are cut at OBS_MAX_BODY_LENGTH bytes, then parsed as JSON or URL-encoded forms before sensitive keys are checked. JSON escapes and percent-encoded form names are decoded, and nested JSON values are redacted with the same policy as other structured fields. Repeated form fields are preserved.
Malformed or cut-off JSON, invalid forms and unsupported body formats (including free text and binary data) are masked as a whole. A cut-off form value can still be redacted when its key is complete. JSON and forms are re-encoded for the log; application traffic is unchanged. Values under keys outside the redacted fields remain visible. In drop mode, sensitive body values continue to be masked.
Body capture media-type guard¶
policy = SecurityPolicy(
log_request_body=True,
body_capture_media_types=("application/json",),
)