pdf-inspector
pdf-inspector Security and Operations: Handle PDFs as Untrusted Input
Protect local documents, OCR runtimes, hosted fallbacks, output provenance, and service boundaries.
What you will learn
- Trace detection and layout stages
- Run native extraction and OCR safely
- Design provenance checks
Before you start
- Basic Git and command-line usage
- Comfort reading a project README
You can explain the project, run its documented first step, and decide what to verify before adopting it.
Key takeaways
- A PDF parser needs resource limits and isolation.
- Derived Markdown must retain page provenance.
- OCR fallback is an external data boundary.
Input isolation
PDFs can contain malformed objects, links, forms, huge pages, and hostile content. Process them in a sandbox with size, page, time, memory, and recursion limits; never trust embedded URLs or scripts.
Use the pinned source evidence, record versions and assumptions, and ask a qualified reviewer to validate the result before adopting it.
OCR and fallback
Keep PDFium/ONNX workers separated, restrict model caches and outbound traffic, and make hosted fallback explicit. Store per-page source and confidence so downstream users can see uncertainty.
Retention and response
Encrypt originals and extracted text, redact logs, define deletion windows, and rehearse cancellation, quarantine, cleanup, and restore. Treat Markdown as derived data, not a replacement for the original evidence.
Use the pinned source evidence, record versions and assumptions, and ask a qualified reviewer to validate the result before adopting it.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Define input, output, and retention policy.
- 2
Sandbox parser and OCR workers.
- 3
Restrict links, egress, and caches.
- 4
Monitor, quarantine, delete, and restore.
Copy-ready example
untrusted PDF -> sandbox limits -> parser
page evidence + confidence -> redacted Markdown
OCR/fallback -> approved egress + retention
incident -> stop/quarantine/delete/restoreFrequently asked questions
Can pdf-inspector safely fetch links inside a PDF?
The parser should extract links as data; fetching them requires a separate, authorized component with allow-lists.
Should extracted text be kept forever?
No. Match retention to purpose and preserve only the evidence needed for the workflow.
Sources
- pdf-inspector README (captured 2026-08-31)Source checked 2026-08-31
- pdf-inspector repositorySource checked 2026-08-31