[Docs][Security] Document multimodal media UUID security implications (#53582)
Signed-off-by: jperezde <jperezde@redhat.com>
Juan Pérez de Algaba committed
Aug 24, 2026 at 16:19 UTC
9f295fe8cee4cbd2b21a5ce3066cec026e4bd2af
1 file changed
+31
docs/usage/security.md
+31
@@ -587,6 +587,37 @@ Scope the salt to the isolation boundary you need:
587
- **Single-tenant deployments**: Cache salting is unnecessary and can be omitted to maximize cache hit rates.
588
- Salting reduces cache efficiency, since cached blocks are only reusable by requests with the same salt. Choose the granularity of your salt values to balance privacy against performance.
589
590
+## Multimodal Media UUID Security
591
+
592
+### Background
593
+
594
+Multimodal content parts (`image_url`, `input_audio`, `video`, `image_embeds`, `audio_embeds`, `vision_chunk`) accept an optional `uuid` field. When provided, vLLM uses this value as the cache identity for the media item instead of hashing the raw media bytes. This avoids re-hashing large media payloads on repeated requests and is the primary mechanism for client-side cache control of multimodal inputs.
595
+
596
+### Client Responsibility
597
+
598
+**It is the client's responsibility to generate UUIDs that cannot be guessed by others.** Use cryptographically random values — for example, UUIDv4 via Python's `uuid.uuid4()` — rather than sequential counters, short strings, or predictable identifiers such as filenames or user IDs.
599
+
600
+### Multi-Tenant Risk
601
+
602
+In multi-tenant deployments where multiple callers share the same vLLM server, two callers who present the same `uuid` for different media will share a single cache entry. The media from whichever request arrives first is served to both, which means:
603
+
604
+- **Integrity**: A later caller's media is silently discarded and replaced by the earlier caller's cached output.
605
+- **Confidentiality**: A caller who deliberately reuses another caller's UUID receives output derived from that caller's media.
606
+
607
+This applies to the multimodal processor cache, the encoder output cache, and the prefix cache block hashes. Clients must ensure UUID uniqueness across all callers on the same server.
608
+
609
+### Extra Protection with `cache_salt`
610
+
611
+For additional cross-tenant isolation, set `cache_salt` on each request (see [Prefix Cache Timing Side-Channel Mitigation](#prefix-cache-timing-side-channel-mitigation-cache-salting) above). The salt is mixed into the prefix cache block hashes, so requests with different salts cannot share cached prefix blocks even if UUIDs collide.
612
+
613
+`cache_salt` is opt-in and not passed by default.
614
+
615
+### Recommendations
616
+
617
+- **Multi-tenant deployments**: Always generate cryptographically random UUIDs per media item. Additionally, set `cache_salt` to a per-tenant secret for defense in depth.
618
+- **Single-tenant deployments**: Ensure UUIDs are unique per distinct media content. `cache_salt` is unnecessary when there is no cross-tenant threat.
619
+- **Default behavior**: Omitting `uuid` entirely preserves the default content-hash-based identity, which is safe against this class of collision but requires hashing the media bytes on every request.
620
+
621
## Reporting Security Vulnerabilities
622
623
If you believe you have found a security vulnerability in vLLM, please report it following the project's security policy. For more information on how to report security issues and the project's security policy, please see the [vLLM Security Policy](https://github.com/vllm-project/vllm/blob/main/SECURITY.md).