docs: update security documentation and installation instructions to address CVE-2025-69872 and clarify usage of optional disk backend

SirStig · SirStig · commit 9f7b5fc565bd · 2026-03-23T21:32:13.000-06:00
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -7,6 +7,8 @@ assignees: ''
 
 ---
 
+Do **not** use this template for undisclosed security issues—use **[Security advisories](https://github.com/sirstig/yokedcache/security/advisories/new)** instead. Known third-party notes (e.g. optional **diskcache** / **CVE-2025-69872**) are summarized in [`SECURITY.md`](https://github.com/sirstig/yokedcache/blob/main/SECURITY.md).
+
 **Describe the bug**
 A clear and concise description of what the bug is.
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Documentation
+
+- Documented the optional **diskcache** advisory (**CVE-2025-69872** / [GHSA-w8v5-vhqr-4h9v](https://github.com/advisories/GHSA-w8v5-vhqr-4h9v)) in `SECURITY.md`, the README Security section, the docs site *Security* page, `CONTRIBUTING.md`, and the GitHub bug report template (no patched upstream wheel at the time of writing; trust boundaries and mitigations).
+
 ## [1.0.0] - 2026-03-23
 
 First stable 1.x release. Published as **1.0.0** (not a PEP 440 pre-release) so a plain `pip install yokedcache` resolves to this line ahead of 0.x. Focus: security hardening, safer Redis usage, and clearer HTTP cache semantics.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -219,6 +219,10 @@ yokedcache/
 - **Discussions:** Use GitHub Discussions for questions
 - **Chat:** Join our community chat (link TBD)
 
+## Security
+
+Report vulnerabilities through [GitHub Security Advisories](https://github.com/sirstig/yokedcache/security/advisories/new). Maintainer-facing notes on trust boundaries, optional backends, and known third-party advisories (including **diskcache** / **CVE-2025-69872** for the optional `disk` extra) live in **[SECURITY.md](SECURITY.md)** in the repository root.
+
 ## Code of Conduct
 
 By participating in this project, you agree to abide by our Code of Conduct:
diff --git a/README.md b/README.md
@@ -24,13 +24,13 @@ Async-first Python caching for FastAPI and other asyncio services: Redis-oriente
 
 ## Installation
 
-Current stable line: **1.0.0** (default on PyPI).
+Install the latest **1.x** from PyPI; you do not need to pin an exact version unless your policy requires it.
 
 ```bash
 pip install yokedcache
 ```
 
-To require 1.x or newer:
+To require 1.x or newer explicitly:
 
 ```bash
 pip install "yokedcache>=1.0.0"
@@ -86,7 +86,9 @@ Other backends impose their own dependencies when you install the matching extra
 
 ## Security
 
-Treat Redis and Memcached as **trusted** stores: anyone who can write arbitrary keys can affect deserialization. From **1.0.0**, new values are written with a typed envelope; set `allow_legacy_insecure_deserialization=False` on `CacheConfig` once legacy entries are migrated. Do not use `HTTPCacheMiddleware` on authenticated routes without a `key_builder` that varies the key per user or session. See the changelog for details. The **[SECURITY.md](SECURITY.md)** file covers the optional disk backend (pickle / `diskcache`) and how we pin vulnerable transitive deps in `uv.lock`.
+Treat Redis and Memcached as **trusted** stores: anyone who can write arbitrary keys can affect deserialization. From **1.0.0**, new values are written with a typed envelope; set `allow_legacy_insecure_deserialization=False` on `CacheConfig` once legacy entries are migrated. Do not use `HTTPCacheMiddleware` on authenticated routes without a `key_builder` that varies the key per user or session. See the changelog for details.
+
+**Optional `disk` extra:** installs **diskcache**, which uses **pickle** by default. **[CVE-2025-69872](https://github.com/advisories/GHSA-w8v5-vhqr-4h9v)** (GHSA-w8v5-vhqr-4h9v) documents unsafe pickle deserialization when an attacker can write the cache directory; **there is no patched diskcache release on PyPI yet**, so dependency scanners may still alert. Use a non-world-writable cache path and skip `yokedcache[disk]` if you do not need disk persistence. Full write-up: **[SECURITY.md](SECURITY.md)** (also covers how we pin transitive deps in `uv.lock`).
 
 ## Development
 
diff --git a/SECURITY.md b/SECURITY.md
@@ -5,7 +5,27 @@ Report vulnerabilities via [GitHub Security Advisories](https://github.com/sirst
 ## Trust boundaries
 
 - **Redis / Memcached**: Treat as trusted stores. Anyone who can write arbitrary keys can influence what your app deserializes. Use `CacheConfig.allow_legacy_insecure_deserialization=False` once legacy blobs are gone (see changelog).
-- **Disk backend (`yokedcache[disk]`)**: The optional `diskcache` library persists values with **pickle** by default. There is **no patched diskcache release** yet for [CVE-2025-69872](https://github.com/advisories/GHSA-w8v5-vhqr-4h9v) (unsafe pickle deserialization if an attacker can write the cache directory). Only use the disk extra when the cache directory is **not writable by untrusted users**; prefer JSON/msgpack serialization at the application layer where feasible.
+
+## Optional disk backend (`diskcache`)
+
+The **`yokedcache[disk]`** extra pulls in **[diskcache](https://pypi.org/project/diskcache/)** (python-diskcache). That library persists values with **pickle** by default.
+
+| | |
+| --- | --- |
+| **Advisory** | [GHSA-w8v5-vhqr-4h9v](https://github.com/advisories/GHSA-w8v5-vhqr-4h9v) (**CVE-2025-69872**) |
+| **Affected** | diskcache **through 5.6.3** (current PyPI line as of this writing) |
+| **Patched PyPI version** | **None** yet; automated scanners may flag the dependency until upstream ships a release |
+
+**Threat model:** someone who can **write or replace files under the cache directory** can supply a malicious pickle payload; when your process reads that entry, that can lead to **arbitrary code execution**.
+
+**What we recommend**
+
+- Do **not** install the disk extra unless you need a filesystem-backed cache.
+- Keep the cache directory **writable only by the application user** (no shared multi-tenant paths, no world-writable directories, careful with network mounts).
+- Prefer **Redis, SQLite, or memory** backends when untrusted parties could influence the filesystem.
+- At the application layer, only cache payloads you could treat as **trusted after deserialization**; JSON or msgpack at the boundary does not remove the pickle risk inside diskcache until you stop using pickle-backed storage for those keys.
+
+**Upstream note:** diskcache also provides **`JSONDisk`** (JSON + zlib instead of pickle). **YokedCache’s `DiskCacheBackend`** currently constructs `diskcache.Cache` with the default disk (pickle). Callers who require disk without pickle need a custom integration or another backend until this project exposes a supported switch.
 
 ## Dependency scanning
 
diff --git a/site-src/pages/cli.md b/site-src/pages/cli.md
@@ -8,7 +8,7 @@ The CLI is automatically available after installing YokedCache:
 
 ```bash
 # Install YokedCache
-pip install "yokedcache==1.0.0"
+pip install yokedcache
 
 # Verify CLI installation
 yokedcache --version
diff --git a/site-src/pages/getting-started.md b/site-src/pages/getting-started.md
@@ -14,7 +14,13 @@ This guide will walk you through installing YokedCache and setting up your first
 
 ```bash
 # Install the core YokedCache package for Python FastAPI Redis caching
-pip install "yokedcache==1.0.0"
+pip install yokedcache
+```
+
+If you want an explicit 1.x floor (optional):
+
+```bash
+pip install "yokedcache>=1.0.0"
 ```
 
 ### Recommended Installation for Production FastAPI Applications
@@ -23,7 +29,7 @@ For production FastAPI applications, install YokedCache with all Redis caching f
 
 ```bash
 # Install with all Redis caching features (recommended for FastAPI)
-pip install "yokedcache[full]==1.0.0"
+pip install "yokedcache[full]"
 ```
 
 ### Feature-Specific Installation for Custom Python Setups
@@ -32,19 +38,19 @@ Install only the Redis caching features you need for your Python application:
 
 ```bash
 # Vector similarity search caching
-pip install "yokedcache[vector]==1.0.0"
+pip install "yokedcache[vector]"
 
 # Production monitoring for Redis cache (Prometheus, StatsD)
-pip install "yokedcache[monitoring]==1.0.0"
+pip install "yokedcache[monitoring]"
 
 # Memcached backend support
-pip install "yokedcache[memcached]==1.0.0"
+pip install "yokedcache[memcached]"
 
 # Fuzzy search capabilities for cached data
-pip install "yokedcache[fuzzy]==1.0.0"
+pip install "yokedcache[fuzzy]"
 
 # Combine multiple caching features
-pip install "yokedcache[vector,monitoring,fuzzy]==1.0.0"
+pip install "yokedcache[vector,monitoring,fuzzy]"
 ```
 
 ## Python versions
@@ -510,7 +516,7 @@ pip list | grep yokedcache
 
 # Reinstall if needed
 pip uninstall yokedcache
-pip install "yokedcache[full]==1.0.0"
+pip install "yokedcache[full]"
 ```
 
 ### Performance Issues
diff --git a/site-src/pages/monitoring.md b/site-src/pages/monitoring.md
@@ -143,7 +143,7 @@ The NoOpCollector allows you to disable metrics collection without changing your
 
 ```bash
 # Install Prometheus dependencies
-pip install "yokedcache[monitoring]==1.0.0"
+pip install "yokedcache[monitoring]"
 
 # Or install manually
 pip install prometheus_client
@@ -221,7 +221,7 @@ collector = PrometheusCollector(
 
 ```bash
 # Install StatsD dependencies
-pip install "yokedcache[monitoring]==1.0.0"
+pip install "yokedcache[monitoring]"
 
 # Or install manually
 pip install statsd
diff --git a/site-src/pages/security.md b/site-src/pages/security.md
@@ -1,6 +1,7 @@
 # Security
 
 - **Versions:** 1.x targets **Python 3.10+** (CI covers through **3.14**). On **Python 3.9**, use **`yokedcache==0.3.0`** (or `yokedcache<1`) only as a stopgap—that branch does **not** receive the same security fixes as 1.x; upgrade when you can. Details: [SECURITY.md](https://github.com/sirstig/yokedcache/blob/main/SECURITY.md) in the repo.
+- **Optional disk extra (`diskcache`):** the `yokedcache[disk]` extra depends on **diskcache**, which serializes with **pickle** by default. **[CVE-2025-69872](https://github.com/advisories/GHSA-w8v5-vhqr-4h9v)** describes arbitrary code execution if an attacker can write under the cache directory. **No patched PyPI release** is available yet; scanners may flag the package. Prefer strict filesystem permissions, avoid the extra if you do not need disk caching, and read the **Disk / diskcache** section in [SECURITY.md](https://github.com/sirstig/yokedcache/blob/main/SECURITY.md).
 - Use `rediss://` and TLS-enabled Redis in production.
 - Limit Redis access to your VPC/private network; avoid public endpoints.
 - For multi-tenant apps, include tenant namespace in keys and enforce isolation.
diff --git a/site-src/pages/tutorials/fastapi-redis-caching.md b/site-src/pages/tutorials/fastapi-redis-caching.md
@@ -28,7 +28,7 @@ This comprehensive tutorial shows you how to implement high-performance caching
 Install YokedCache with full features for your FastAPI application:
 
 ```bash
-pip install "yokedcache[full]==1.0.0"
+pip install "yokedcache[full]"
 ```
 
 This includes:
diff --git a/site-src/pages/tutorials/fastapi.md b/site-src/pages/tutorials/fastapi.md
@@ -14,7 +14,7 @@ By the end of this tutorial, you'll have a FastAPI application with:
 
 ```bash
 # Install dependencies
-pip install "yokedcache[full]==1.0.0" fastapi uvicorn sqlalchemy psycopg2-binary
+pip install "yokedcache[full]" fastapi uvicorn sqlalchemy psycopg2-binary
 
 # Start Redis (using Docker)
 docker run -d --name redis -p 6379:6379 redis:7
diff --git a/site-src/pages/tutorials/sqlalchemy.md b/site-src/pages/tutorials/sqlalchemy.md
@@ -14,7 +14,7 @@ Learn how to integrate YokedCache with SQLAlchemy for high-performance database
 
 ```bash
 # Install dependencies
-pip install "yokedcache[full]==1.0.0" sqlalchemy psycopg2-binary
+pip install "yokedcache[full]" sqlalchemy psycopg2-binary
 
 # Start Redis
 docker run -d --name redis -p 6379:6379 redis:7
diff --git a/site-src/pages/usage-patterns.md b/site-src/pages/usage-patterns.md
@@ -303,7 +303,7 @@ Find approximate matches across cached keys and optionally search within cached
 
 ```python
 # Install the fuzzy search dependencies
-# pip install "yokedcache[fuzzy]==1.0.0"
+# pip install "yokedcache[fuzzy]"
 
 from yokedcache import YokedCache, CacheConfig
 
diff --git a/site-src/pages/vector-search.md b/site-src/pages/vector-search.md
@@ -125,7 +125,7 @@ Vector search requires additional dependencies:
 
 ```bash
 # Install vector search dependencies
-pip install "yokedcache[vector]==1.0.0"
+pip install "yokedcache[vector]"
 
 # Or install manually
 pip install numpy scipy scikit-learn
diff --git a/site-src/static/llms.txt b/site-src/static/llms.txt
@@ -4,7 +4,7 @@
 
 ## Summary
 
-- Package: yokedcache (PyPI), current version **1.0.0**; **Python 3.10+** (CI: 3.10–3.14). Python **3.9**: legacy **`yokedcache==0.3.0`** only—no 1.x security backports; upgrade recommended.
+- Package: yokedcache (PyPI), latest **1.x** via `pip install yokedcache` (pin only if your policy requires it); **Python 3.10+** (CI: 3.10–3.14). Python **3.9**: legacy **`yokedcache==0.3.0`** or **`yokedcache<1`** only—no 1.x security backports; upgrade recommended.
 - Docs: https://sirstig.github.io/yokedcache/
 - API (HTML): https://sirstig.github.io/yokedcache/api/
 - Changelog: https://sirstig.github.io/yokedcache/changelog.html
diff --git a/src/yokedcache/vector_search.py b/src/yokedcache/vector_search.py
@@ -114,7 +114,7 @@ def __init__(
         if not VECTOR_DEPS_AVAILABLE:
             raise ImportError(
                 "Vector dependencies not available. Install with: "
-                'pip install "yokedcache[vector]==1.0.0"'
+                'pip install "yokedcache[vector]"'
             )
 
         self.similarity_method = similarity_method
