pdf-toolkit

PDF Toolkit

Audit .pdf files for metadata, page count, encryption status, embedded JavaScript, embedded files, and PDF version — using the standard library only.

Table of Contents

• [Keywords](#keywords)
• [Quick Start](#quick-start)
• [Core Workflows](#core-workflows)
• [Tools](#tools)
• [Reference Guides](#reference-guides)
• [Templates](#templates)
• [Best Practices](#best-practices)

Keywords

pdf, pdf audit, pdf metadata, pdf review, pdf leakage, pdf security, redaction, document handoff

Quick Start

python scripts/pdf_auditor.py contract.pdf

Outputs: PDF version, page count, file size, metadata (Author, Title, Producer, Creator, dates), encryption status, embedded JavaScript indicators, embedded file indicators.

Core Workflows

Workflow 1: Pre-Handoff PDF Metadata Audit

Goal: Stop leaking author identity, prior client names, or document history when handing a PDF to an external party.

Steps:

1. Run: python scripts/pdf_auditor.py document.pdf
2. Review metadata fields:
3. Author matches the sender (not "Bob's intern" from a prior project)
4. Title matches the document, not a leftover working title
5. Producer doesn't reveal an internal-only PDF tool
6. CreationDate and ModDate are reasonable for the deal
7. If metadata leaks, re-export from source with cleaned properties (or use a redaction tool)

Time Estimate: 2-3 minutes per document.

Workflow 2: PDF Security Triage

Goal: Decide whether a received PDF can be opened safely on a managed laptop.

Steps:

1. Run audit
2. JavaScript indicator present → quarantine; review in a sandbox
3. Embedded files indicator present → list of file types; quarantine if unexpected
4. Encrypted with non-empty owner password → request password from sender via separate channel
5. Decision: open / quarantine / reject

Time Estimate: 1-2 minutes per inbound document.

Workflow 3: Bulk Audit of an Outbound Document Set

Goal: Audit every PDF in a folder before zipping for a customer or partner.

Steps:

1. Loop: for f in *.pdf; do python scripts/pdf_auditor.py "$f" --json; done > audit.jsonl
2. Parse the JSON Lines for any metadata leakage or anomalies
3. Re-export problem files from source
4. Re-run audit until clean

Time Estimate: 1-2 minutes per file.

Tools

pdf_auditor.py

Reads a PDF using stdlib parsing — no pypdf or pdfplumber required. Detects:

• PDF version (from header)
• Page count (via /Type /Page object scan)
• File size
• Document Info / XMP metadata (Title, Author, Subject, Keywords, Producer, Creator, CreationDate, ModDate)
• Encryption status (/Encrypt reference present)
• JavaScript indicators (/JS, /JavaScript, /AA keys)
• Embedded files indicator (/EmbeddedFiles)

python scripts/pdf_auditor.py document.pdf
python scripts/pdf_auditor.py document.pdf --json

Limits:

• Does not extract text content — pure PDF text extraction with stdlib is unreliable. For text extraction install pdfplumber or pypdf separately.
• Cannot decrypt encrypted files.
• Detects only the presence of JavaScript/embedded files, not their behavior.

Reference Guides

• references/pdf_handoff_guide.md — What to scrub from PDFs before external send; PDF/A and PDF/UA basics; common leakage patterns

Templates

• assets/pdf_handoff_checklist.md — Pre-send PDF sign-off checklist

Best Practices

• Re-export rather than redact. Redaction tools that "remove" content can leave it recoverable. The safest path is regenerating the PDF from the source document with sensitive fields removed.
• Scrub document properties at the source. In Word: File → Inspect Document → Document Inspector. In Pages: File → Properties. Then export to PDF.
• Don't trust filenames. A file named Public-Report.pdf can carry private metadata indistinguishable to the human eye.
• Use PDF/A for archival. PDF/A removes JavaScript and external dependencies, making documents safe for long-term archive.

Integration Points

• Pairs with legal/ for redacted contract handoffs
• Pairs with c-level-advisor/board-deck-builder for board pack handoff
• Used by marketing/ for whitepaper / case-study handoff