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.

âš ī¸ Warning: Never run pdfid on a file you suspect contains active exploits. These tools parse the structure safely, but the safest approach is analyzing in a VM with no network access.

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.doc or this — PDF-specific API calls
  • eval() — Dynamic code execution
  • unescape() — Often used to decode shellcode
  • Long strings of %u or 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
â„šī¸ Pro Tip: Always analyze suspicious PDFs in an isolated environment — a VM with no network, snapshots enabled, and no shared folders with the host. Even "safe-looking" analysis tools have had vulnerabilities.

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
  • /URI links 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:

  1. Isolate the sample in a sandboxed VM
  2. Run pdfid for quick triage
  3. If flags appear, run peepdf -i for deeper analysis
  4. Extract and review any JavaScript or shellcode
  5. Check objects for suspicious actions (Launch, URI, GoTo)
  6. 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.