By Manny Fernandez

November 16, 2026

pdfid: Malicious PDF Triage and How to Read the Output

pdfid: Malicious PDF Triage and How to Read the Output

Objective: use pdfid for fast malicious PDF triage: run it against a suspect file, read every line of its output, and decide in under a minute whether the file goes back to the user, into a deeper pdf-parser session, or straight into the sandbox.

Target audience: SOC analysts, incident responders, and network engineers who get handed “is this attachment safe?” and want a fast, repeatable answer without opening the file.

Executive Summary

pdfid is Didier Stevens’ Python tool for malicious PDF triage. It scans a file for the PDF keywords that make a document do something (run JavaScript, act automatically when opened, launch a program, carry an attached file) and prints a count for each. It never renders the PDF, so it is safe to run on live samples inside an analysis VM.

The one thing to understand before you trust it: pdfid is a keyword counter, not a parser. Didier describes it as essentially a string search tool that does not parse the PDF structure. That makes it fast and hard to crash, but it also means compressed or encrypted content is invisible to it, and short keywords like /JS can show up by accident inside binary data. This post covers what each counter means, which combinations matter, the options most people never use, and the blind spots that bite.

Every output block in this post is real pdfid 0.2.10 output from lab samples built for this guide. The “malicious” samples only run app.alert(), and any lab link points at 198.18.10.50.

Prerequisites and Architecture

Assumed knowledge: basic shell use and a rough idea that a PDF is a set of numbered objects (5 0 obj ... endobj) tied together by a cross-reference table.

Lab requirements: a Linux or macOS analysis VM with Python 3, no PDF reader set as a default handler, and no shared clipboard or shared folders back to your workstation. Treat every sample as live.

Component Version used Role
pdfid.py 0.2.10 (2025-03-05) Keyword counter and triage front end
pdfid.ini ships with pdfid Extra keywords to count (default adds /URI)
plugin_triage.py DidierStevensSuite Scores each file 0.0 to 1.0 for bulk triage
pdf-parser.py DidierStevensSuite Next step: inspect the objects pdfid flagged
Python 3.x Runtime, no extra modules needed

Figure 1. pdfid triage decision flow

pdfid malicious PDF triage flow: active keywords, blind spots, links only, or low risk

Step-by-Step: Running pdfid

Step 1: Install pdfid

Goal: get Didier’s current script, not a fork.

Action: on Kali it is packaged as pdfid. Anywhere else, pull the script and its config straight from the DidierStevensSuite repository on GitHub.

# Kali Linux
sudo apt install pdfid

# Any Linux or macOS box
mkdir -p ~/tools/pdftools && cd ~/tools/pdftools
BASE=https://raw.githubusercontent.com/DidierStevens/DidierStevensSuite/master
for f in pdfid.py pdfid.ini plugin_triage.py pdf-parser.py; do
  curl -sSO "$BASE/$f"
done
chmod +x pdfid.py pdf-parser.py

Verify:

$ python3 pdfid.py --version
pdfid.py 0.2.10

Heads up: pip install pdfid gives you a library clone packaged for import into Python code, not the script you get from Didier. Use it if you are building a pipeline; use Didier’s script for hands-on triage.

Step 2: Baseline a known clean PDF

Goal: know what boring looks like before you hunt for interesting.

$ python3 pdfid.py clean-invoice.pdf
PDFiD 0.2.10 clean-invoice.pdf
 PDF Header: %PDF-1.7
 obj                    4
 endobj                 4
 stream                 1
 endstream              1
 xref                   1
 trailer                1
 startxref              1
 /Page                  1
 /Encrypt               0
 /ObjStm                0
 /JS                    0
 /JavaScript            0
 /AA                    0
 /OpenAction            0
 /AcroForm              0
 /JBIG2Decode           0
 /RichMedia             0
 /Launch                0
 /EmbeddedFile          0
 /XFA                   0
 /URI                   0
 /Colors > 2^24         0

Verify: obj equals endobj, stream equals endstream, one each of xref, trailer and startxref, and zeros everywhere below /Page. That is a single-revision PDF with no active content.

Step 3: Run it on the suspect

Goal: cut the noise and see only what is present.

Action: add -n to hide zero counts. On a real sample this is the first command you type.

$ python3 pdfid.py -n openaction-js.pdf
PDFiD 0.2.10 openaction-js.pdf
 PDF Header: %PDF-1.7
 obj                    5
 endobj                 5
 stream                 1
 endstream              1
 xref                   1
 trailer                1
 startxref              1
 /Page                  1
 /JS                    1
 /JavaScript            1
 /OpenAction            1

Verify: /OpenAction plus /JS and /JavaScript is the classic pattern: JavaScript that runs the moment the document opens, no click required. Didier notes that every malicious JavaScript PDF he had seen in the wild used an automatic action to launch it. This one goes to Step 9 and pdf-parser.

Interpreting pdfid output for malicious PDF triage

Read the output top to bottom in three bands: structure (header through /Page), blind spots (/Encrypt, /ObjStm), and active content (everything from /JS down).

Line What it counts How to read it
PDF Header %PDF-x.y in the first 1024 bytes Missing means “Not a PDF document”. Junk before the header still parses.
obj / endobj Object open and close Should match. A mismatch means a malformed or hand-crafted file.
stream / endstream Stream open and close Should match. Streams hold page content, images, fonts, and scripts.
xref / trailer / startxref Cross-reference sections More than one means incremental updates: edits, form saves, signatures.
/Page Page objects 0 pages with active content is a lure that exists only to run code.
/Encrypt Encryption dictionary Over 0 means strings and streams are encrypted and keywords may be hidden.
/ObjStm Object streams Objects compressed inside a stream. Keywords inside are invisible to pdfid.
/JS, /JavaScript JavaScript High risk, especially with /OpenAction or /AA.
/AA Additional actions Actions fired on events like page open, close, or field focus.
/OpenAction Action on document open Runs automatically. Common in benign files to set the zoom or first page.
/AcroForm Interactive form Normal on fillable forms. Worth a look combined with /JS or /XFA.
/JBIG2Decode JBIG2 image filter Historic exploit vector. Rare in normal office documents.
/RichMedia Embedded Flash or media Legacy attack surface. Almost never legitimate today.
/Launch Launch action Starts an external program or file. Treat as high risk.
/EmbeddedFile Attached file Could be a harmless spreadsheet or an EXE. Extract and identify it.
/XFA XML Forms Architecture Complex form engine, large attack surface.
/URI Link actions (from pdfid.ini) Phishing indicator. Counts about two per link.
/Colors > 2^24 Absurd color counts Used to trigger image parsing bugs. Should always be 0.

Combinations that matter

  • /OpenAction or /AA with /JS or /JavaScript: auto-executing script. Escalate.
  • /OpenAction with /Launch and /EmbeddedFile: drop an attachment and try to run it on open. Escalate.
  • /URI only, low page count: credential phishing lure. Pull the links, no sandbox needed.
  • /AcroForm alone on a multi-page file: almost always a normal fillable form.
  • Everything zero but /ObjStm or /Encrypt over 0: you have not seen the file yet. See the tips below.

Step 4: Spot name obfuscation

Goal: catch keywords written in hex to dodge naive scanners.

Action: PDF names may encode any character as #xx, so /J#61vaScript is still /JavaScript to a reader. pdfid decodes these and shows how many hits were obfuscated in parentheses.

$ python3 pdfid.py -n obfuscated-js.pdf
...
 /JS                    1(1)
 /JavaScript            1(1)
 /OpenAction            1

Verify: 1(1) reads as “one hit, and one of them was hex encoded”. Legitimate PDF producers have no reason to do this. Any number in parentheses is a strong malicious signal on its own.

Step 5: Pull the extra data with -e

Goal: find data hiding outside the document and spot packed content.

$ python3 pdfid.py -e -n appended.pdf
...
 %%EOF                  1
 After last %%EOF      38
 Total entropy:           4.997501 (       497 bytes)
 Entropy inside streams:  4.118454 (        40 bytes)
 Entropy outside streams: 4.937389 (       457 bytes)

Verify: After last %%EOF is the number of bytes after the final end-of-file marker. A few bytes (a trailing newline) is normal. Dozens or thousands means something was appended: a second payload, a ZIP, or a polyglot. Entropy near 8.0 inside streams is normal for compressed images; high entropy outside streams is not.

Step 6: Triage a whole folder

Goal: sort a pile of quarantined attachments by risk.

Action: the triage plugin scores each file. -c makes it CSV, so it pipes into a spreadsheet or your SIEM.

$ python3 pdfid.py -c -p plugin_triage *.pdf
Filename;Plugin-name;Score
clean-invoice.pdf;Triage plugin;0.00
embedded-file.pdf;Triage plugin;1.00
obfuscated-js.pdf;Triage plugin;1.00
openaction-js.pdf;Triage plugin;1.00
phish-link.pdf;Triage plugin;0.60
Score Meaning (from plugin_triage.py)
1.00 Any of /JS, /JavaScript, /AA, /OpenAction, /AcroForm, /JBIG2Decode, /RichMedia, /Launch, /EmbeddedFile, /XFA, /Colors > 2^24
0.75 /ObjStm present: expand the object streams and rescan
0.60 /URI present: check the links
0.50 obj/endobj or stream/endstream mismatch: malformed
0.00 None of the above

Note that a benign fillable form scores 1.00 because of /AcroForm. The plugin tells you what to look at first, not what is malicious.

Step 7: Select only what you care about with -S

Goal: print full reports only for files matching a condition.

python3 pdfid.py -S "pdf.javascript.count > 0" *.pdf
python3 pdfid.py -S "pdf.javascript.count > 0 or pdf.launch.count > 0" *.pdf

Verify: only the matching files print. Field names are lowercase keywords without the slash, with .count for the total and .hexcode for the obfuscated hits, so pdf.javascript.hexcode > 0 finds every hex-obfuscated JavaScript sample in a folder.

Step 8: Disarm a copy with -d

Goal: produce a copy that a reader will not auto-execute, for when someone insists on seeing the content.

$ python3 pdfid.py -d -n suspect.pdf
/OpenAction -> /oPENaCTION
/JavaScript -> /jAVAsCRIPT
/JS -> /js
...
$ ls
suspect.disarmed.pdf  suspect.pdf

Verify: rerun pdfid on the .disarmed.pdf file and the active keywords drop to zero. Disarm only flips the case of the trigger names, so readers ignore them. The script itself is still in the file, and nothing inside compressed or encrypted streams is touched. It is a convenience, not a sanitizer.

Step 9: Hand off to pdf-parser

Goal: confirm what pdfid counted and read the actual payload.

python3 pdf-parser.py --search openaction suspect.pdf
python3 pdf-parser.py --search javascript suspect.pdf
python3 pdf-parser.py -o 5 -f -d obj5.bin suspect.pdf
python3 pdf-parser.py -a suspect.pdf

Verify: the search shows the object holding /OpenAction and the object it references. -o 5 -f -d decompresses object 5 and dumps its stream to a file for reading. -a prints keyword statistics, which is how you prove a pdfid hit was a false positive.

Verification and Validation

Before you trust pdfid on real mail, prove your install catches what it should. Keep a small folder of known samples (a clean PDF, one with an auto-run alert, one with a link) and run the triage plugin over it after every update.

cd ~/samples/pdf-known
python3 ~/tools/pdftools/pdfid.py -c -p plugin_triage *.pdf

Expected success output: the clean file scores 0.00, the link-only file 0.60, and every file with an auto action or JavaScript 1.00. If a known-bad sample scores 0.00, check that you are running Didier’s pdfid.py and that pdfid.ini sits next to it.

Tips and Tricks

  • Alias it. Add alias pdfid='python3 ~/tools/pdftools/pdfid.py -n' to your shell profile so zero counts are hidden by default.
  • Scan ZIPs without extracting. pdfid opens ZIP files directly, including archives protected with the malware-sharing password infected, so the PDF never touches the disk in the clear: pdfid.py -n sample.zip.
  • Scan from a list or a folder. pdfid.py -n @todo.txt reads one path per line. pdfid.py -s -n /quarantine scans a directory, and --recursedir walks subfolders.
  • Log it. -o triage.log writes the report to a file for the ticket.
  • /URI counts double. A single link annotation shows /URI 2 because the action type /S /URI and the /URI key both match. Divide by two for a rough link count.
  • Watch the xref count. Two or more xref, trailer, and %%EOF markers mean the file was saved incrementally. Normal for signed contracts and saved forms, but also how an attacker appends a malicious revision to a clean document.
  • Add your own keywords. pdfid counts anything listed under [keywords] in pdfid.ini. Adding /GoToE, /GoToR, /SubmitForm and /ImportData catches remote go-to and form-submit actions, which have been used to leak NTLM credentials.
  • Zero is not clean when /ObjStm or /Encrypt is over 0. Run pdf-parser.py -O to expand object streams, or qpdf --decrypt in.pdf out.pdf for files encrypted with an empty user password, then rerun pdfid on the result.
  • Never double-click to check. pdfid exists so nobody has to open the file. If the answer is not clear from pdfid and pdf-parser, send it to a sandbox, not to a reader.

Troubleshooting and Gotchas

1. A /JS hit that pdf-parser cannot find

Short keywords such as /JS or /AA occasionally appear by chance inside compressed or binary data. pdfid counts the bytes, not the structure, so it reports them. Didier has written up this exact false positive twice.

python3 pdf-parser.py --search /JS suspect.pdf
python3 pdf-parser.py -a suspect.pdf

Fix: if no object dictionary holds the keyword and -a shows no JavaScript, it is a false positive. If /OpenAction or /AA is also present, assume it is real until proven otherwise.

2. “Not a PDF document” on a file that opens fine

pdfid looks for %PDF in the first 1024 bytes. Readers are more forgiving, and attackers know it. Polyglots and files with a large junk prefix fall through.

python3 pdfid.py -f -n weird.pdf
xxd weird.pdf | head -5

Fix: -f forces the scan without a valid header. A file that a reader opens but pdfid calls “Not a PDF” deserves extra suspicion.

3. “Error instantiating plugin”

With pdfid 0.2.10, the plugin_nameobfuscation and plugin_embeddedfile files currently in the repository fail with a constructor TypeError. plugin_triage works.

python3 pdfid.py -v -p plugin_nameobfuscation -n suspect.pdf

Fix: stick with plugin_triage. You do not lose anything: the parentheses in the counts already flag name obfuscation, and /EmbeddedFile is in the default report. Plugins load from pdfid’s own folder, so a bare name like -p plugin_triage works from any directory.

Sources

No fluff. Just the config that works.

How SSDs Work, How They Perform, and Why SSD Secure Erase Overwrites Are Obsolete

How SSDs Work, How They Perform, and Why SSD Secure Erase Overwrites Are Obsolete

Learn SSD secure erase internals, FTL mechanics, and crypto erase. Stop using slow overwrites. Sanitize drives correctly with CLI tools in this guide.

Read More
Windows Event Types for Forensic Investigations

Windows Event Types for Forensic Investigations

Map critical Windows event IDs for forensics. Configure audit policies, parse Security logs, and deploy Sysmon to capture attacker activity and build timelines.

Read More
auditd on Linux: Install, Configure, and Actually Use the Linux Audit Framework

auditd on Linux: Install, Configure, and Actually Use the Linux Audit Framework

Configure auditd on Linux to capture kernel events. Install the daemon, build a layered ruleset for forensics, and query logs with ausearch and aureport.

Read More