pdf-parser: A tool for parsing and analyzing PDF files to extract data or metadata

Once PDFiD flags a suspicious PDF (as I covered in that article), pdf-parser is the tool I turn to next. Also written by Didier Stevens, it’s a proper object-level parser that lets me walk through every object in a PDF file, dump its raw or decompressed content, and extract embedded JavaScript or other suspicious payloads for manual review — all without ever rendering the document in a real PDF viewer.

What pdf-parser Does and How It Works

Unlike PDFiD’s shallow keyword counting, pdf-parser actually parses the PDF’s object structure: it identifies each numbered object, its dictionary entries, and any associated stream data. It can:

• List all objects and their types
• Search for objects containing specific keywords (/JS, /JavaScript, /OpenAction, etc.)
• Decompress and display stream content (many malicious payloads are hidden inside FlateDecode-compressed streams)
• Follow object references so you can trace, for example, which object an /OpenAction points to and see exactly what code will run

Because it’s written in pure Python with no PDF-rendering engine involved, it can safely inspect a malicious PDF’s content without any risk of the document actually executing.

Installing pdf-parser

On Kali, it’s typically available directly:

which pdf-parser.py

If missing:

sudo apt update
sudo apt install -y pdf-parser

Or from source:

git clone https://github.com/DidierStevens/DidierStevensSuite.git
cd DidierStevensSuite
python3 pdf-parser.py --help

Basic Syntax

python3 pdf-parser.py [options] <file.pdf>

Options I use regularly:

python3 pdf-parser.py suspicious.pdf                     # list all objects
python3 pdf-parser.py -a suspicious.pdf                    # show statistics summary
python3 pdf-parser.py -o 12 suspicious.pdf                  # show a specific object number
python3 pdf-parser.py -s /JavaScript suspicious.pdf         # search objects containing a keyword
python3 pdf-parser.py -o 12 -f suspicious.pdf               # decompress/filter stream content of object 12
python3 pdf-parser.py --object 7 --raw suspicious.pdf       # dump raw stream bytes

Real Example

Starting with a statistics overview:

$ python3 pdf-parser.py -a suspicious.pdf
PDF Comment '%PDF-1.7'
PDF Comment '%¥±ë'

Type                        Count
----                        -----
obj                            42
endobj                          42
stream                          5
endstream                       5
xref                            1
trailer                         1
startxref                       1
/Page                           3
/JS                             1
/JavaScript                     1
/OpenAction                     1

Following the OpenAction reference:

$ python3 pdf-parser.py -o 1 suspicious.pdf
obj 1 0
 Type: /Catalog
 Referencing: 2 0 R, 5 0 R
 <<
  /Type /Catalog
  /Pages 2 0 R
  /OpenAction 5 0 R
 >>

Then dumping the actual JavaScript object it points to:

$ python3 pdf-parser.py -o 5 -f suspicious.pdf
obj 5 0
 Type: /Action
 <<
  /Type /Action
  /S /JavaScript
  /JS (this.exportDataObject({cName:"payload.exe", nLaunch:2});)
 >>

That output right there — an auto-triggered JavaScript action attempting to launch an embedded executable — is a textbook malicious PDF pattern, and I can read the full logic without any risk of it actually executing.

Real-World Use Cases

Malware analysis and reverse engineering — extracting and reading obfuscated JavaScript inside a malicious PDF to understand its payload delivery mechanism.

Phishing/incident response investigation — confirming exactly what an email attachment does before deciding on containment and remediation scope.

PDF exploit research (in an authorized lab) — studying how specific CVEs abuse PDF object structures by examining proof-of-concept files object by object.

Integration with Other Tools

• pdfid — I always run pdfid first for a fast triage pass, then escalate to pdf-parser for full object-level extraction.
• peepdf — an alternative/complementary parser with an interactive shell, useful for cross-verifying findings.
• CyberChef — I often paste extracted, obfuscated JavaScript strings into CyberChef for deobfuscation (base64 decode, string reverse, etc.) since pdf-parser itself doesn’t deobfuscate JS logic.

Performance and Troubleshooting

• Some malicious PDFs deliberately corrupt their cross-reference table to confuse parsers; use the -f (force) style options or pdf-parser’s error-tolerant parsing mode to still extract objects despite structural damage.
• If a stream doesn’t decompress cleanly with -f, check the object’s /Filter entry — some PDFs stack multiple filters (e.g., FlateDecode then ASCII85Decode) that need to be unwound in the correct order.
• A mistake I’ve made: forgetting that object numbers can be reused/updated across incremental PDF revisions — always check the /Prev trailer entries for older object versions that might hide the real payload.

Best Practices

• Always work inside an isolated analysis VM with networking disabled when examining anything you suspect is malicious.
• Document every object you examine and its content directly in your case notes for reproducibility.
• Cross-reference suspicious JavaScript logic against known exploit kits or malware family signatures before concluding it’s a novel threat.

FAQ

Can pdf-parser execute the JavaScript it finds? No — it only extracts and displays the code as text; it never executes it.

Does it handle encrypted PDFs? It has support for decrypting PDFs when the password or standard security handler is known/empty; heavily protected PDFs may need additional tooling.

Is pdf-parser a replacement for a full PDF library like PyPDF2? No — it’s purpose-built for security analysis and forensic extraction, not for general-purpose PDF editing or rendering.

Summary

pdf-parser gives me the object-level x-ray view of a PDF file that PDFiD’s keyword scan can only hint at. Between the two tools, I can go from “this file looks suspicious” to “here is the exact malicious code it contains” in just a few commands, entirely without opening the file in a vulnerable reader.

References

• Official tool page: https://blog.didierstevens.com/programs/pdf-tools/
• GitHub repository (DidierStevensSuite): https://github.com/DidierStevens/DidierStevensSuite