When a suspicious PDF lands on your desk, how do you decide if it's hostile or harmless? Opening it in Adobe Reader is a terrible idea. That's where peepdf comes in â a powerful Python tool built for analyzing PDF files at a structural level. Combined with pdfid, you can quickly identify dangerous elements before ever executing anything.
Why Manual PDF Analysis Matters
PDF is deceptively complex. The specification runs over 700 pages, and attackers exploit that complexity constantly. A malicious PDF might contain:
- Embedded JavaScript that executes upon opening
- Auto-run actions that launch external programs
- Object streams hiding encoded payloads
- Launch actions that execute shell commands
- Embedded files that extract to disk automatically
Antivirus doesn't catch everything. Advanced PDF malware often slips past signature-based detection, making manual analysis essential for security researchers and SOC analysts.
Installing peepdf and pdfid
Both tools are Python-based and run on Linux, macOS, and Windows. Install them via pip:
pip install peepdf
pip install pdfid
That's it. Both tools have minimal dependencies. On Kali Linux, they come pre-installed.
Quick Scan with pdfid
The pdfid tool gives you a fast overview of potentially dangerous elements in a PDF. Run it against any suspect file:
pdfid suspicious.pdf
Here's what the output means:
/JSâ JavaScript code present. Almost always suspicious in unexpected files./JavaScriptâ Same thing, different name. Flags embedded scripts./AAâ Additional Actions. Can trigger on page open, close, or other events./OpenActionâ Actions that execute automatically when the PDF opens./JBIG2Decodeâ Compression filter with a history of vulnerabilities./RichMediaâ Embedded Flash or video content./Launchâ Attempts to launch external programs./EmbeddedFilesâ Files packaged inside the PDF.
Any of these in an unsolicited PDF should raise red flags. A typical phishing PDF has zero of these â it's just text and images. A malicious one usually shows elevated counts in one or more of these categories.
Deep Dive with peepdf
When pdfid flags something concerning, peepdf lets you dig deeper. Launch it in interactive mode:
peepdf -i suspicious.pdf
This drops you into a shell where you can explore the PDF structure. Here are the commands you'll use most:
Basic Commands
infoâ Shows file metadata, version, encryption status, and object count.treeâ Displays the PDF object tree structure.objectsâ Lists all objects in the PDF.streamsâ Shows all streams (often where encoded data hides).
Examining Specific Objects
To look at a specific object, use the object number:
object 5
This shows you exactly what that object contains â raw text, encoded streams, references to other objects. If JavaScript is embedded, you'll see /JS and the actual script code here.
Decoding Streams
PDF streams are compressed with filters like FlateDecode. To decompress and view a stream:
stream 12
Peepdf automatically decodes common filters. For more complex analysis, you can dump streams to files for further inspection.
Searching for Scripts
To find all JavaScript in the file:
search JavaScript
This returns every occurrence of "JavaScript" across all objects. You'll often find script names like util.printf() or this.getIcon() that are commonly used in exploits.
Visualizing Object Relationships
The xref command shows cross-reference information â which objects reference which. This matters because exploit PDFs often chain together innocuous-looking objects that ultimately trigger malicious code.
Real-World Analysis Example
Let's walk through a typical malicious PDF scenario. You receive a file called invoice_updated.pdf from an unknown sender. First, run pdfid:
$ pdfid invoice_updated.pdf
PDFID 0.2.4
...
/JS 4 # Four JavaScript blocks
/JavaScript 3 # Three more
/OpenAction 1 # Runs automatically
/AA 2 # Additional triggers
/AcroForm 0
/URI 0
/Launch 0
/EmbeddedFiles 0
Four JavaScript blocks and an auto-run action. That's highly suspicious for what should be an invoice. Now let's open it in peepdf:
$ peepdf -i invoice_updated.pdf
...
Filesize: 245760 bytes
Version: 1.4
MD5: a1b2c3d4e5f6...
SHA256: ...
> objects
...
> search JS
Searching keyword 'JS' in the PDF content...
Object 5: contains '/JS /JavaScript'
Object 8: contains '/JS'
Object 12: contains '/JS'
> object 5
...
<< /Type /Action /S /JavaScript /JS 5 0 R >>
...
Object 5 contains a JavaScript action. That's your entry point. You can extract and examine that script:
set output file script.js
extract js 5
Now examine script.js in a text editor. Look for patterns like:
app.docorthisâ PDF-specific API callseval()â Dynamic code executionunescape()â Often used to decode shellcode- Long strings of
%uor hex-encoded data
Automated Analysis Tools
For high-volume analysis, combine peepdf with other tools:
- pdfid â Quick triage (covered above)
- peepdf â Deep structural analysis
- strings â Extract readable strings from the raw file
- xxd or hexdump â Manual hex inspection
- VBA Stream or olevba â For PDFs with embedded OLE objects
Key Indicators of Compromise
When analyzing PDFs professionally, watch for these patterns:
- Unexpected JavaScript â Invoices, contracts, and receipts don't need scripts
- High object count â Malware often creates dozens of objects for obfuscation
/URIlinks to suspicious domains- Encrypted streams that pdfid can't parse
- Metadata showing creation tools like "Python" or "Exploit Kit"
Building Your Workflow
For incident responders, here's a practical workflow:
- Isolate the sample in a sandboxed VM
- Run
pdfidfor quick triage - If flags appear, run
peepdf -ifor deeper analysis - Extract and review any JavaScript or shellcode
- Check objects for suspicious actions (Launch, URI, GoTo)
- Document findings and hash the sample for threat intelligence
The more PDFs you analyze, the faster you'll spot anomalies. Start with clean samples from legitimate sources to understand normal PDF structures, then move to malware samples from platforms like VirusShare or Contagio.
Conclusion
PDF malware isn't going away. The format's flexibility, widespread use, and historical vulnerabilities make it a favorite attack vector for threat actors. Tools like peepdf and pdfid give you the power to examine PDFs safely, identify malicious elements, and understand attacks before they execute.
Start small â analyze a few PDFs from your inbox. Build your baseline. The skills you develop here translate directly to malware analysis, incident response, and threat hunting.