sillybos¶

Decide before decoding. A σίλλυβος (sillybos; Latin sittybus) was the little parchment tag that hung from a rolled scroll in an ancient library, carrying its title and author, so that a reader could tell what a scroll was without unrolling it. Cicero had them made for his books. This library is that tag for the files a scanning or OCR pipeline is handed: it reads the tag, and says whether the scroll should be unrolled at all.

It answers one narrow question, before any image library or PDF renderer opens a file: is this one of the formats I mean to read, within the limits I expect, and if not, why? It names the format from the file's first bytes, whatever the file is called; reads the header of a JPEG, PNG or TIFF with a few dozen lines of its own, never a decoder's; asks poppler's pdfinfo, in a separate process with a time limit, how many pages a PDF has, how large they are and whether it carries JavaScript, a form, attached files or a launch action; and refuses, in a plain sentence, anything outside the policy you give it.

Status: alpha. The API is small and may still move. It is in use in Tetrak OCR, which is where it came from.

pip install sillybos            # the check; no dependencies
pip install 'sillybos[pillow]'  # plus open_checked(), which opens the file with Pillow

A PDF needs pdfinfo from poppler on the PATH (brew install poppler, apt install poppler-utils). Anything that renders PDFs in Python already has it.

Why¶

Every program that reads scans hands each file to a decoder: Pillow for images, poppler for PDFs, then an OCR engine. Decoders are large, old programs that read complicated formats, and they have flaws. In October 2026, Pillow 13.0.0 fixed four serious ones at once. One of them (CVE-2026-112900) ran commands on the computer when an EPS file was opened and Ghostscript was installed; and a file's extension was no protection, because Pillow decides what a file is from its contents, so a PostScript file named page.png went straight to the PostScript reader.

The fixes to Pillow arrived; the lesson stays. A pipeline that opens files it did not make should decide, from the file's own bytes and a policy of its own, whether a decoder may have it, and should do that deciding with code that is not itself a decoder.

Use¶

>>> from sillybos import check
>>> verdict = check("scans/page-012.png")
>>> verdict.ok
False
>>> verdict.reasons
('says PNG, is PostScript',)

>>> verdict = check("scans/register.tif")
>>> verdict.ok, verdict.format, verdict.facts
(True, 'tiff', Facts(bytes=48213990, width=4960, height=7016, pages=32, max_pixels=34799360, encrypted=False))

check never raises for anything found in the file. A lying name, a malformed header, a page too large and a thousand-page PDF are all reasons, not exceptions, and a verdict carries every reason it found. require is the same check for callers who would rather catch one exception:

from sillybos import require, Refused

try:
    require(path)
except Refused as refusal:
    quarantine(path, refusal.verdict.reasons)

The policy¶

from sillybos import Policy, DEFAULT, STRICT, check

check(path)  # DEFAULT: a trusted laptop, your own scanner
check(path, STRICT)  # files from outside: smaller and shorter
check(path, Policy(formats={"tiff", "pdf"}, max_pages=50))

The defaults were set from a real corpus of archival scans (largest page 39 million pixels at 600 dpi; longest book 166 pages) with room to spare. Set yours the same way: from the largest real file you have, times two or three.

With Pillow¶

from sillybos.pillow import open_checked

with open_checked(
    path
) as image:  # checked first; then Image.open(path, formats=["JPEG", "PNG", "TIFF"])
    ...

Image.open takes a formats list, and a file outside it is never handed to the other readers. open_checked runs the check, then opens with that list set from the policy. That one argument is the whole of the October fix for images, and it costs nothing; the check in front of it is what makes the limits bite before Pillow allocates a pixel.

Longer examples, each a complete programme, are in the tutorials: a thumbnailer, a PDF renderer and an inbox that quarantines what it refuses.

The command¶

$ sillybos scans/*
ok       scans/page-001.tif  (TIFF, 4960x7016, 1 page, 1.6 MB)
refused  scans/page-002.png  says PNG, is PostScript
refused  scans/poster.jpg    a page of 1,200,000,000 pixels; the limit is 89,478,485
refused  scans/report.pdf    1,412 pages; the limit is 500
refused  scans/form.pdf      a PDF with JavaScript and a form; the policy allows none of the features a PDF can carry

Exit status 0 when every file passed, 1 when any was refused, 2 when the command could not do its job. --strict, --formats, --max-pages, --max-pixels, --max-bytes, --max-metadata-bytes, --jpeg-frames, --tiff-compressions, --tiff-photometrics, --tiff-subsamplings, --no-tiled-tiff, --png-colour-types, --max-png-bit-depth, --interlaced-png, --pdf-features and --any-name adjust the policy; --json prints one object per line for a pipeline; -q prints only refusals.

What it does, exactly¶

1. Size, from the file system. Over the limit, nothing reads the file but the next step.
2. Format, from the first bytes. JPEG, PNG, TIFF and PDF are the four it can pass. It also knows PostScript, GIF, BMP, WebP, HEIF, JPEG 2000, BigTIFF, Photoshop, OLE (FlashPix, old Office), zip, gzip, icons and XML, so that a refusal can say what the file is. Anything else is "an unknown format". Refused by name, and no reader of ours runs on it.
3. Name against contents. says PNG, is JPEG.
4. The header, with a reader of its own for each raster format: the dimensions, coding and component count from a JPEG's frame header, the size of its colour profile, and every picture of a multi-picture (MPF) JPEG, each read the same way and required to match the first; a PNG's whole IHDR (bit depth, colour type, interlacing, and the methods the specification fixes), its acTL frame count, and the size of every other chunk, before and after the image data; and every directory in a TIFF's chain, each with its dimensions, its compression scheme, which must be one the policy names, and its pixel layout (photometric interpretation and, for YCbCr, chroma subsampling, both of which the policy names; samples per pixel; bits per sample), all of which must be the same in every frame, since the decoder sizes its buffers from the first, its tile size if it is tiled, and every tag's data checked to lie inside the file; the chain is walked with a limit and a memory of where it has been, so that one that loops or points off the end of the file is a refusal, not a hang. Every read is bounded and every offset is checked against the file's size. For a PDF, pdfinfo reports the page count, whether it is encrypted, whether it carries JavaScript or a form and, if the count is within the limit, every page's size; pdfdetach reports attached files; and a bounded scan of the bytes finds the name of a launch action, and of JavaScript that an older poppler does not report, with the #xx escapes a name may hide behind undone.
5. The limits, against what the header said.

What it does not do¶

Say this plainly, because a security library carries an implied promise.

• It does not protect against a flaw in the readers you do allow. A crafted JPEG that exploits a bug in your JPEG decoder passes this check, because it is a JPEG of a sensible size. What this library removes is the attack surface of every format you did not mean to read, the whole class of files that are too big to be safe, and, where the header shows them, the rare codings a scanner never writes. For the readers you keep: update them, and run them in a boxed process with memory and time limits (a recipe for that is planned; it is deliberately not a dependency).
• It does not scan for malware. ClamAV does that, for malware that has been seen before.
• It does not repair, re-encode or "sanitise" a file. That needs a decoder, and the moment this library decoded anything it would become the kind of code it exists to keep away from untrusted files.
• It does not look inside a PDF beyond what pdfinfo reports. A PDF's structure cannot be read from a fixed header; it has to be parsed, and the parser this library trusts is poppler's, in its own process, with a timeout. Checks for JavaScript, launch actions, embedded files and forms (things a scanned book never has) are the next step.
• It does not validate uploads. File names, path traversal and zip bombs belong to a web framework's upload handling. This library starts after the file is on disk and asks only whether a decoder may open it.
• It does not read formats beyond the four. WebP, JPEG 2000, HEIC and the rest are refused by name until someone shows a scan in one. Each format added is attack surface added.