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.

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