Skip to content

Commit ecef4fb

Browse files
aclark4lifeaclark4life
authored
Add STRIDE threat model to security docs (#9562)
2 parents 9f6a6a6 + 0cb00ac commit ecef4fb

3 files changed

Lines changed: 276 additions & 2 deletions

File tree

‎.github/SECURITY.md‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,21 @@
11
# Security policy
22

3+
## Reporting a vulnerability
4+
35
To report sensitive vulnerability information, report it [privately on GitHub](https://github.com/python-pillow/Pillow/security/advisories/new).
46

5-
If you cannot use GitHub, use the [Tidelift security contact](https://tidelift.com/security). Tidelift will coordinate the fix and disclosure.
7+
If you cannot use GitHub, use the [Tidelift security contact](https://tidelift.com/docs/security). Tidelift will coordinate the fix and disclosure.
8+
9+
**DO NOT report sensitive vulnerability information in public.**
10+
11+
## Threat model
12+
13+
Pillow's primary attack surface is parsing untrusted image data. A full STRIDE threat model covering spoofing, tampering, repudiation, information disclosure, denial of service, and elevation of privilege is maintained in the [Security handbook page](https://pillow.readthedocs.io/en/latest/handbook/security.html).
14+
15+
Key risks to be aware of when using Pillow to process untrusted images:
616

7-
DO NOT report sensitive vulnerability information in public.
17+
- **Decompression bombs** — do not set `Image.MAX_IMAGE_PIXELS = None` in production.
18+
- **EPS files invoke Ghostscript** — block EPS input at the application layer unless strictly required.
19+
- **`ImageMath.unsafe_eval()`** — never pass user-controlled strings to this function; use `lambda_eval` instead.
20+
- **C extension memory safety** — keep Pillow and its bundled C libraries (libjpeg, libpng, libtiff, libwebp, etc.) up to date.
21+
- **Sandboxing** — for high-risk deployments, run image processing in a sandboxed subprocess.

‎docs/handbook/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,4 @@ Handbook
88
tutorial
99
concepts
1010
appendices
11+
security

‎docs/handbook/security.rst‎

Lines changed: 259 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
Security
2+
========
3+
4+
Pillow's primary attack surface is **parsing untrusted image data**. This page
5+
documents the threat model for developers integrating Pillow into applications
6+
that handle images from untrusted sources, along with recommended mitigations.
7+
8+
To report a vulnerability see :ref:`security-reporting`.
9+
10+
.. _security-threat-model:
11+
12+
Threat model (STRIDE)
13+
---------------------
14+
15+
The analysis below follows the `STRIDE
16+
<https://en.wikipedia.org/wiki/STRIDE_model>`_ framework and covers the
17+
boundary between untrusted image input and the Pillow API.
18+
19+
.. code-block:: text
20+
21+
┌──────────────────────────────────────────┐
22+
Untrusted zone │ Pillow API │
23+
───────────── │ │
24+
Image files ────►│ Image.open() ──► Format plugins │
25+
Byte streams │ (40+ parsers) (Python + C FFI) │
26+
User metadata │ │
27+
│ ImageMath.unsafe_eval(expr) ───────────┼──► Python eval()
28+
│ ImageShow.show(image) ─────────────────┼──► os.system / subprocess
29+
│ EpsImagePlugin.open(eps) ──────────────┼──► Ghostscript (gs)
30+
└──────────────┬───────────────────────────┘
31+
│ C extensions:
32+
│ _imaging · _imagingft · _imagingcms
33+
│ _webp · _avif · _imagingtk
34+
│ _imagingmath · _imagingmorph
35+
▼
36+
┌──────────────────────────────────────────┐
37+
│ C libraries (bundled or system) │
38+
│ libjpeg · libpng · libtiff · libwebp │
39+
│ openjpeg · freetype · littlecms2 │
40+
└──────────────────────────────────────────┘
41+
42+
Spoofing
43+
^^^^^^^^
44+
45+
**S-1 — Format sniffing bypass**
46+
47+
``Image.open()`` detects format by magic bytes, not file extension or MIME
48+
type. An attacker can name a file ``safe.png`` while its content is TIFF, JPEG
49+
2000, or EPS, causing a different — potentially more dangerous — parser to run.
50+
51+
*Mitigations:* validate MIME type and magic bytes independently before calling
52+
``Image.open()``; pass the ``formats`` argument with an allowlist of accepted
53+
formats.
54+
55+
**S-2 — Plugin registry spoofing**
56+
57+
Pillow's format registry is a global mutable dictionary. A malicious package
58+
installed in the same environment could register a replacement parser for a
59+
well-known format.
60+
61+
*Mitigations:* use isolated virtual environments with pinned, hash-verified
62+
dependencies; audit ``Image.registered_extensions()`` at startup.
63+
64+
Tampering
65+
^^^^^^^^^
66+
67+
**T-1 — Malicious metadata propagation**
68+
69+
Pillow preserves EXIF, XMP, IPTC, ICC profiles, and comments when
70+
round-tripping images. Applications that store or render metadata without
71+
sanitisation are vulnerable to second-order injection (SQLi, XSS, command
72+
injection).
73+
74+
*Mitigations:* treat all values from ``image.info``, ``image._getexif()``,
75+
``image.getexif()``, and ``image.text`` as untrusted; sanitise before storing
76+
or rendering; strip metadata when it is not required.
77+
78+
**T-2 — Covert data channel (steganography)**
79+
80+
Pillow does not remove hidden data (JPEG comments, PNG text chunks) when
81+
re-saving. An attacker can embed data that survives the
82+
encode-decode cycle invisibly.
83+
84+
*Mitigations:* to guarantee a clean output when saving, create a new image instance via
85+
``image.copy()`` and delete the ``image.info`` contents.
86+
87+
**T-3 — Supply chain tampering**
88+
89+
Pre-compiled wheels bundle libjpeg-turbo, libpng, libtiff, libwebp, openjpeg,
90+
freetype, littlecms2, and other libraries. A compromised PyPI release or build pipeline
91+
could ship malicious binaries.
92+
93+
*Mitigations:* pin with hash verification
94+
(``python3 -m pip install --require-hashes``); monitor `Pillow security advisories
95+
<https://github.com/python-pillow/Pillow/security/advisories>`_; use
96+
Dependabot or OSV-Scanner for bundled C library CVEs.
97+
98+
Repudiation
99+
^^^^^^^^^^^
100+
101+
**R-1 — No structured audit trail**
102+
103+
Without application-level logging there is no record of which images were
104+
opened, what formats were detected, or what operations were performed, making
105+
forensic investigation harder after an incident.
106+
107+
*Mitigations:* log the filename/hash, detected format, and dimensions of every
108+
image processed; log and alert on ``Image.DecompressionBombWarning``,
109+
``Image.DecompressionBombError``, and ``PIL.UnidentifiedImageError``.
110+
111+
Information disclosure
112+
^^^^^^^^^^^^^^^^^^^^^^
113+
114+
**I-1 — Metadata in saved images**
115+
116+
GPS coordinates, author names, software version strings, and ICC profiles can
117+
be inadvertently included in output images served publicly.
118+
119+
*Mitigations:* explicitly strip EXIF and XMP on save (set ``exif=b""``,
120+
``icc_profile=None``, omit ``pnginfo``); verify output with ``exiftool`` in CI.
121+
122+
**I-2 — Temporary file exposure**
123+
124+
Several code paths write pixel data to temporary files via
125+
``tempfile.mkstemp()``. Exception paths can leave these files behind on shared
126+
filesystems.
127+
128+
*Mitigations:* files are created with mode ``0o600``; mount ``/tmp`` as a
129+
per-container ``tmpfs``; ensure ``try/finally`` cleanup is in place.
130+
131+
Denial of service
132+
^^^^^^^^^^^^^^^^^
133+
134+
**D-1 — Decompression bomb**
135+
136+
A small compressed image can expand to gigabytes in memory.
137+
:py:data:`PIL.Image.MAX_IMAGE_PIXELS` raises
138+
``Image.DecompressionBombError`` at 2× the limit and
139+
``Image.DecompressionBombWarning`` at 1×. PNG text chunks are
140+
separately capped by ``PngImagePlugin.MAX_TEXT_CHUNK`` and
141+
``MAX_TEXT_MEMORY``. Check the values in your installed Pillow version at
142+
runtime or in the reference/source for the current defaults.
143+
144+
*Mitigations:* **never** set ``Image.MAX_IMAGE_PIXELS = None`` in production;
145+
treat ``Image.DecompressionBombWarning`` as an error; set OS/container memory limits
146+
per worker.
147+
148+
**D-2 — CPU exhaustion**
149+
150+
Large-but-legal images (within ``MAX_IMAGE_PIXELS``) can still saturate CPU
151+
through high-quality resampling, convolution filters, or complex draw
152+
operations.
153+
154+
*Mitigations:* apply per-request CPU time limits; set a practical dimension
155+
ceiling below ``MAX_IMAGE_PIXELS``; rate-limit processing requests.
156+
157+
**D-3 — Algorithmic complexity in parsers**
158+
159+
Formats such as TIFF (nested IFD chains), animated GIF/WebP (many frames), and
160+
PNG (many text chunks) can exhaust CPU or memory before pixel data is decoded.
161+
162+
*Mitigations:* restrict accepted formats to the minimum required; enforce a
163+
file-size limit before passing data to Pillow; use per-request timeouts.
164+
165+
Elevation of privilege
166+
^^^^^^^^^^^^^^^^^^^^^^
167+
168+
**E-1 — C extension memory corruption (RCE)**
169+
170+
Pillow's ~87 C source files and its bundled C libraries process
171+
attacker-controlled bytes. Historical CVEs include buffer overflows, integer
172+
overflows, and use-after-free vulnerabilities that allow arbitrary code
173+
execution.
174+
175+
*Mitigations:* keep Pillow and all C libraries up to date; compile with
176+
hardening flags (ASLR, stack canaries, PIE, ``_FORTIFY_SOURCE=2``); run image
177+
processing in a sandboxed subprocess (seccomp-bpf, AppArmor, or a restricted
178+
container).
179+
180+
**E-2 — Ghostscript exploitation via EPS (RCE)**
181+
182+
Opening an EPS file invokes the system Ghostscript binary (``gs``) via
183+
``subprocess``. Ghostscript has a long history of sandbox-escape CVEs
184+
permitting arbitrary code execution from malicious PostScript.
185+
186+
*Mitigations:* **block EPS files** at the application input layer before
187+
passing files to Pillow; if EPS must be supported, run Ghostscript in a fully
188+
isolated sandbox with no network and no sensitive mounts. Pillow does not
189+
provide a stable public API for unregistering individual format plugins, so do
190+
not rely on mutating internal registries such as ``Image.OPEN`` as a security
191+
control.
192+
193+
194+
**E-3 — ImageMath.unsafe_eval() code injection**
195+
196+
:py:meth:`~PIL.ImageMath.unsafe_eval` calls Python's built-in ``eval()`` with
197+
only a minimal ``__builtins__`` restriction, which can be bypassed via
198+
introspection. Any user-controlled string passed to this function results in
199+
arbitrary code execution.
200+
201+
*Mitigations:* **never** pass user-controlled strings to
202+
``ImageMath.unsafe_eval()``; use :py:meth:`~PIL.ImageMath.lambda_eval` instead,
203+
which accepts a Python callable and never calls ``eval``.
204+
205+
**E-4 — Font path traversal via ImageFont**
206+
207+
``ImageFont.truetype(font, size)`` passes the filename to the FreeType C
208+
library. If font paths are constructed from user input without
209+
canonicalisation, an attacker may supply a path like
210+
``../../../../etc/passwd``.
211+
212+
*Mitigations:* never construct font paths from user input; if font selection
213+
must be user-driven, resolve names against an explicit allowlist of
214+
pre-validated absolute paths.
215+
216+
.. _security-recommendations:
217+
218+
Recommendations
219+
---------------
220+
221+
The following mitigations are listed in priority order.
222+
223+
1. **Sandbox image processing** — run Pillow workers in a seccomp/AppArmor
224+
restricted subprocess, isolated from the main application process.
225+
2. **Block or sandbox EPS** — reject EPS at the application boundary, or run
226+
Ghostscript in an isolated container.
227+
3. **Never use** ``ImageMath.unsafe_eval()`` **with user input** — migrate all
228+
callers to :py:meth:`~PIL.ImageMath.lambda_eval`.
229+
4. **Keep all dependencies current** — Pillow and its C library dependencies
230+
(including libjpeg, libpng, libtiff, libwebp, openjpeg, freetype,
231+
littlecms2, Ghostscript, and others). Subscribe to `Pillow security
232+
advisories <https://github.com/python-pillow/Pillow/security/advisories>`_.
233+
5. **Enforce** ``MAX_IMAGE_PIXELS`` — never set it to ``None``; treat
234+
``Image.DecompressionBombWarning`` as an error.
235+
6. **Allowlist image formats** — restrict accepted formats when opening
236+
images, for example with ``Image.open(..., formats=...)``, and isolate
237+
installs/environments if you need to minimise supported formats.
238+
7. **Strip metadata on output** — never pass through EXIF/XMP/ICC from user
239+
uploads to publicly served images.
240+
8. **Sanitise all metadata** returned by Pillow before using it downstream.
241+
9. **Pin dependencies with hash verification** — use
242+
``pip install --require-hashes`` and lockfiles.
243+
10. **Log and alert** on ``Image.DecompressionBombWarning``,
244+
``Image.DecompressionBombError``, ``PIL.UnidentifiedImageError``,
245+
and all exceptions from ``Image.open()``.
246+
247+
.. _security-reporting:
248+
249+
Reporting a vulnerability
250+
-------------------------
251+
252+
To report sensitive vulnerability information, report it `privately on GitHub
253+
<https://github.com/python-pillow/Pillow/security/advisories/new>`_.
254+
255+
If you cannot use GitHub, use the `Tidelift security contact
256+
<https://tidelift.com/docs/security>`_. Tidelift will coordinate the fix and
257+
disclosure.
258+
259+
**Do not report sensitive vulnerability information in public.**

0 commit comments

Comments
 (0)