Comprehensive security documentation for the cachekit Python SDK.

• Supported Versions
• Reporting a Vulnerability
• Architecture Overview
• Python SDK Security Features
• FFI Boundary Security
• Dependency Security
• CI/CD Security
• Known Limitations
• Security Roadmap

• Description of the vulnerability
• Steps to reproduce
• Affected versions
• Potential impact
• Suggested fix (if available)

┌─────────────────────────────────────────────────────────────────┐
│                     cachekit Python SDK                         │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────┐  │
│  │   @cache     │  │   @cache     │  │   Redis/CachekitIO    │  │
│  │  Decorator   │  │   .secure    │  │      Backend          │  │
│  └──────┬───────┘  └──────┬───────┘  └───────────┬───────────┘  │
│         │                 │                      │              │
│         └────────┬────────┴──────────────────────┘              │
│                  │                                              │
│         ┌────────▼────────┐                                     │
│         │   PyO3 FFI      │  ◄── This repo                      │
│         │   Wrapper       │                                     │
│         └────────┬────────┘                                     │
└──────────────────┼──────────────────────────────────────────────┘
                   │
         ┌─────────▼─────────┐
         │   cachekit-core   │  ◄── Separate crate
         │  ┌─────────────┐  │
         │  │ AES-256-GCM │  │
         │  │ LZ4 Compress│  │
         │  │ xxHash3     │  │
         │  │ HKDF        │  │
         │  └─────────────┘  │
         └───────────────────┘

This document focuses on Python SDK-specific security: FFI boundary, configuration, and Python-layer tooling.

We use MessagePack (safe binary serialization) with type preservation via schema metadata.

- import pickle  # NEVER - arbitrary code execution
+ import msgpack  # Safe binary serialization

When enabled via @cache.secure, client-side AES-256-GCM encryption ensures the server never sees plaintext:

All sensitive values are automatically masked:

Implementation: Uses pydantic-settings with SecretStr for automatic redaction.

When using @cache.io (CachekitIOBackend), the SDK includes built-in Server-Side Request Forgery (SSRF) protection. Custom API URLs are blocked by default - only api.cachekit.io and its subdomains are permitted.

See SSRF Protection for full details, including custom host configuration for development environments.

Cache keys can embed caller-supplied tenant/user identifiers, so the SDK's own loggers (cachekit.*) never emit them verbatim (CWE-532). Every cachekit log path — decorator error handling (structured and backwards-compat), cache-operation logs, and SWR/TTL-refresh debug logs — replaces the key with a fixed-length blake2b digest (<redacted:…>), keeping log lines correlatable without leaking the key. Error paths are covered centrally at the shared error sink (FeatureOrchestrator.handle_cache_error / log_cache_operation), so new call sites are redacted by construction. BackendError redacts the key in its formatted text (str(e) carries key=<redacted:…>), while the .key attribute keeps the raw caller-supplied key for programmatic use — never log e.key. Its free-form message is caller-supplied and third-party exception text (a redis ResponseError naming the key, a pymemcache illegal-input error echoing it) has unknown provenance — so no cachekit log line renders str(e). Every logging call that mentions an exception goes through redact_error_for_log, which emits only the exception type plus, for BackendError, its BackendErrorType classification; the full exception stays on the object (original_exception, .message) for programmatic access. Operators lose the provider's message text in the log line and keep it on the exception. An architecture test (tests/unit/test_log_redaction_architecture.py) walks every logging call in the package — logger.*(), get_logger().*(), getattr(logger, level)() — and fails CI if a key-shaped value reaches one unredacted in the message, %s arguments, or extra=; if an exception — any name bound by except ... as, a conventional name (e, exc, err, error, *_err), or an attribute of one — reaches one outside redact_error_for_log; or if a call emits a traceback (logger.exception, exc_info=). The guarantee does not depend on the next contributor remembering it. It is flow-insensitive: build log lines inline, not via a pre-formatted variable, and bind exceptions with except ... as or a conventional name (an Exception-typed parameter called failure is invisible to it), or the guard cannot see them.

Scope — transport logs are not covered. The CachekitIO backend addresses entries by key in the request path (GET /v1/cache/{key}), and httpx logs every request line — method, full URL, status — at INFO on its own httpx logger. An application that enables INFO globally (logging.basicConfig(level=logging.INFO)) will therefore see raw keys in httpx's output on every operation, exactly as it would see any REST resource path. cachekit does not mute a third-party logger on your behalf; if your keys carry identifiers, silence or raise the level of that logger in your logging config:

import logging

logging.getLogger("httpx").setLevel(logging.WARNING)

The same applies to any HTTP-layer capture between the SDK and api.cachekit.io — see the lock-token paragraph below for why path/query content is treated as logged.

Digest strength. The redaction digest is unkeyed blake2b, so it is exactly as hard to reverse as the key material is to guess — and the key material is deterministic from the call: [ns:{ns}:]func:{mod.fn}:args:{blake2b(args)} for generated keys, or whatever you return from @cache(key=...). Namespace and function name are static application config, so a cache on get_user(user_id) is enumerable from its digest by iterating plausible IDs, whether the key was generated (hash the candidate args) or hand-built (default:user:1234). A per-installation secret was considered and rejected for a public library (unset it is theatre; set it breaks cross-process log correlation, the property the digest exists for). Treat the digest as a correlation ID, never as a secret: if a log reader must not be able to confirm which user an entry belongs to, do not grant that reader the logs.

The distributed-lock capability token (lock_id) is sent in the X-CacheKit-Lock-Id request header when releasing a lock (DELETE /v1/cache/{key}/lock), never in the URL query string. Query strings are routinely captured by access logs, proxy/CDN logs, and OpenTelemetry http.url spans (CWE-532); a leaked token could be replayed to release a lock within its short TTL. The CacheKit SaaS backend dual-reads the header and the legacy ?lock_id= query during migration, preferring the header (removed in protocol 2.0).

Custom @cache(key=...) values are percent-encoded before they reach the CachekitIO request path, so a key can only ever address /v1/cache/{key} and never a different api.cachekit.io endpoint. Without encoding, ?/# would be split into a query/fragment and a /-bearing key would introduce extra path segments, both escaping the cache namespace with the application's bearer token; httpx normalizes these client-side before the request leaves the process (CWE-22), so the SaaS-side key validator never sees them. quote(key, safe="") encodes every reserved character (/ → %2F, ? → %3F, # → %23, % → %25), collapsing the whole key into one inert path segment.

RFC-3986 marks . as unreserved, so quote (like cachekit-ts encodeURIComponent and cachekit-rs urlencoding::encode) leaves it raw — but a key of exactly . or .. is still a live dot-segment that httpx collapses: .. → GET /v1, and on the sub-resource routes ../ttl → GET /v1/ttl, ../lock → GET /v1/lock, reaching a different route with the bearer token. The encoder special-cases an all-dot segment (.. → %2E%2E) so it can no longer collapse; only a segment that is entirely dots is affected (a:.. is untouched), so canonical keys are unchanged.

Encode-once matches the SaaS validator's single decode, so a canonical key round-trips byte-for-byte. Python's quote(key, safe="") is byte-identical to cachekit-rs urlencoding::encode, and resolves to the same server-side key as cachekit-ts encodeURIComponent after that single decode, so cross-SDK cache lookups still coincide.

# One-time setup
make security-install

# Quick checks (< 3 min)
make security-fast

# Comprehensive (< 15 min)
make security-medium

# Python dependencies
make security-audit

# Generate report
make security-report

Reports are archived in reports/security/ for compliance and audit trails.

SDK Responsibilities:

• Safely calling cachekit-core via FFI
• Protecting master keys in memory (SecretStr)
• Preventing key leakage in logs/errors
• Validating inputs before FFI calls

For cryptographic guarantees, see:

• cachekit-core Cryptographic Security
• cachekit-core Kani Verification

Security patches are backported to the latest supported version.

We appreciate responsible disclosure from the security community. Security researchers who report valid vulnerabilities will be acknowledged in release notes (with permission).