SPB Git forge
spboucher.ai ↗

spb/doc-api

Public
2commits 1branches 0releases
15.7 MBsize
maindefault branch
13 days agolast push
Python 88.3% TypeScript 7.6% Shell 4.1%
9.1 KB
View source Raw Blame History

# File uploads and SSRF

Status: DOCUMENTED (xAI Files API and Gemini resumable/multipart/raw uploads LIVE_VERIFIED 2026-09-18/19 by the provider agents; the shared adapters implement both upload protocols offline-tested) Sources: https://platform.claude.com/docs/en/api/errors#request-size-limits · https://platform.claude.com/docs/en/build-with-claude/files · https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool · OpenAI OpenAPI spec (POST /v1/files, input_file/input_image, /v1/uploads) · https://developers.openai.com/api/docs/guides/safety-best-practices · xAI: https://docs.x.ai/developers/rest-api-reference/files/upload (multipart file, purpose ignored, expires_after 1 h–30 d, 50 MB spec / 512 MB guide), https://docs.x.ai/developers/files/public-urls (eligible types png/jpeg/gif/webp/mp4/webm/pdf, ≤ 50 MiB, ≤ 1,000 active URLs/team, anonymous GET), https://docs.x.ai/developers/model-capabilities/files/chat-with-files (input_file {file_id | file_url | file_data}, attachment search $10/1k, Responses only), https://docs.x.ai/developers/model-capabilities/images/image-understanding (input_image.image_url https or data URL) · Gemini: https://ai.google.dev/api/files (resumable protocol X-Goog-Upload-*, 2 GB/file, 20 GB/project, 48 h retention, files:register for GCS), https://ai.google.dev/gemini-api/docs/files, https://ai.google.dev/gemini-api/docs/file-input-methods (fileData.fileUri = Files URI, public YouTube URL or public/pre-signed HTTPS media URL ≤ 100 MB fetched by Google per request), https://ai.google.dev/gemini-api/docs/file-search (stores persist until deleted) Last verified: 2026-09-19

# Two attack surfaces

  1. The file itself — user-controlled bytes that your service stores, parses, and feeds to a model (or to a hosted sandbox). Risks: parser exploits, decompression bombs, hidden text (white-on-white PDF instructions = prompt injection), malware later served to other users.
  2. URLs you fetch on the model's or user's behalf — SSRF: an attacker makes your server request http://169.254.169.254/latest/meta-data/, http://localhost:6379/, or an internal admin panel. Provider-hosted fetch tools (Anthropic web_fetch, OpenAI web_search) run on the provider's network, so they are not an SSRF vector into your network; your own fetchers are.

# Uploading to the providers

OpenAI Files Anthropic Files xAI Files Gemini Files
Endpoint POST /v1/files (multipart file, purpose required) — large files via /v1/uploads POST /v1/files (multipart; anthropic-beta: files-api-2025-04-14) POST /v1/files (multipart file; purpose accepted, ignored, echoed ""; expires_after 3600–2592000 s must precede file); chunked files:initialize/files:uploadChunks (SDK) Resumable protocol: POST /upload/v1beta/files with X-Goog-Upload-Protocol: resumable, X-Goog-Upload-Command: start, X-Goog-Upload-Header-Content-Length/-Type + JSON metadata → x-goog-upload-url; then POST <url> with X-Goog-Upload-Offset: 0, X-Goog-Upload-Command: upload, finalize + raw bytes (also ?uploadType=multipart / media); files:register {uris: ["gs://…"]} for GCS objects
Reference in prompt {type:"input_file", file_id} / {type:"input_image", file_id}; also file_url / image_url (provider fetches the URL) {type:"document", source:{type:"file", file_id}} Responses only: {type:"input_file", file_id | file_url | file_data} — turns the request into an agentic attachment search ($10/1k calls); input_image.image_url accepts https URLs or data URLs (xAI fetches the URL); Chat Completions → 400 {fileData:{fileUri: File.uri, mimeType?}} — the same field also accepts public YouTube URLs and public/pre-signed HTTPS media URLs (≤ 100 MB), fetched by Google on every request; inlineData (base64, ≤ 20 MB request)
Scope project — any project key can read organization/workspace team — any team key with the right ACL can list/download (GET /v1/files/{id}/content); AIP-160 filter on listings project — any key of the project can use the files/… name; GET /v1beta/files/{id} on a foreign/deleted file → 403 (not 404); user uploads cannot be downloaded (metadata only)
Limits per purpose 500 MB/file, 32 MB Messages request 50 MB (spec) / 512 MB (guide) per file; text-based formats + images/PDF; storage $0.025/GiB/day, download $0.20/GiB 2 GB/file, 20 GB/project, free; video/audio need state: ACTIVE polling
Retention until you delete until deleted permanent unless expires_after; DELETE /v1/files/{id} → later GET 404 48 h then auto-deleted (expirationTime); registered GCS objects up to 30 days
Public exposure — — POST /v1/files/{id}/public-url → anonymous files-cdn.x.ai URL (images/video/PDF only, ≤ 50 MiB, ≤ 1,000 active per team, TTL ≤ file lifetime, idempotent); …/public-url/revoke; deleting the file revokes it generated files via downloadUri; no public-URL feature for uploads

Rules: set purpose to the narrowest value where it exists; delete files when the job is done (Gemini deletes for you after 48 h — but a 48-hour window is still a window); never put tenant secrets in filenames or displayName (they appear in listings and logs); treat file ids/URIs and xAI public URLs as capabilities — do not expose raw ids to end users if that lets them read other users' files through your proxy, and revoke xAI public URLs as soon as the consumer has fetched them. xAI: set expires_after on every upload unless permanence is a requirement.

# Validating uploads before they reach a model

  • Enforce size caps below provider limits (a 32 MB PDF is also a token bomb); reject nested archives and decompression ratios > ~100×.
  • Sniff content type (magic bytes), do not trust the Content-Type header or extension; convert risky formats to safe ones (images → re-encoded PNG; office docs → PDF/text) in a sandbox.
  • Extract text yourself when you want control: strip invisible text layers, tiny fonts, off-page content — common carriers of injected instructions. Then label it as untrusted (prompt-injection.md).
  • Scan with AV/YARA before storing; store outside the web root; serve with Content-Disposition: attachment and a separate origin.
  • Quotas per user/tenant; log file ids with request ids for traceability.

# Provider-fetched URLs (file_url, image_url, fileData.fileUri, urlContext)

OpenAI (file_url/image_url), xAI (input_image.image_url, input_file.file_url) and Gemini (fileData.fileUri with an HTTPS/YouTube URL; urlContext tool) fetch URLs from the provider's network, so they are not an SSRF vector into yours — but they are a way for a user to make the provider fetch an attacker-controlled document (indirect injection) or to probe whether a URL exists/renders. Validate the URL against your allowlist before passing it, prefer uploading bytes you have inspected, and remember Gemini re-fetches media URLs on every request (cost + freshness + a signal to the URL's owner). Gemini's urlContext refuses private/localhost/tunnel hosts and paywalled/login pages by design.

# SSRF defences for your own URL fetchers

  1. Allow only http/https; deny file:, gopher:, ftp:, data:.
  2. Resolve DNS yourself, reject private/loopback/link-local/multicast/ULA ranges (IPv4 10/8, 172.16/12, 192.168/16, 127/8, 169.254/16, 0/8, IPv6 ::1, fc00::/7, fe80::/10, IPv4-mapped IPv6), then connect to the resolved IP (pin it) to defeat DNS rebinding.
  3. Follow redirects manually (max 3) and re-validate every hop.
  4. Strip credentials from URLs; never forward your own cookies/authorization; use a dedicated egress identity.
  5. Cap response size and time; stream to disk with a limit; only accept expected content types.
  6. Prefer an allowlist of domains (domain-allowlists.md); Anthropic's web_fetch gets this for free via allowed_domains plus the URL-in-context rule — reuse the same list for your own fetcher.
  7. Run fetchers in a network segment with no route to internal services or cloud metadata.

# Checklist

  • Size/type/AV checks before upload; archives and nested containers rejected or unpacked with limits.
  • Narrowest purpose (OpenAI); files deleted after use (xAI: expires_after on upload, public URLs revoked; Gemini: 48 h auto-delete acknowledged); per-tenant isolation (projects/workspaces/teams or ACL).
  • Extracted document text treated as untrusted; hidden-text stripping where feasible (xAI attachment search and Gemini fileData read the whole document).
  • Own fetchers: scheme allowlist, DNS pinning, private-range denial after redirects, size/time caps, egress-isolated network.
  • No cookies/keys forwarded by fetchers; file_url/image_url/fileData.fileUri/urlContext URLs validated before you pass them to any provider.
  • Gemini resumable upload URLs (x-goog-upload-url, contain upload_id) and xAI public CDN URLs kept out of logs; file ids/URIs and request ids logged; user-facing download paths never expose raw provider file ids.