When you open a PDF file, what you see is just the surface. Underneath that clean document layout lies a complex structure of objects, and one of the most abused components is the stream object. Attackers have figured out that streams are perfect for smuggling malicious code past security filters, and understanding how they work is essential for anyone doing PDF malware analysis or forensic investigations.
What Are PDF Stream Objects?
In PDF terminology, a stream object is a sequence of bytes that can contain arbitrary data—images, fonts, JavaScript, encrypted content, or anything else the PDF spec allows. Streams are defined with the stream and endstream keywords, and they're preceded by a dictionary that describes the stream's properties, including compression filters.
Here's what a typical stream object looks like:
12 0 obj
<<
/Type /XObject
/Subtype /Image
/Filter /DCTDecode
/Width 800
/Height 600
>>
stream
[compressed image data here]
endstream
endobj
The /Filter entry is where things get interesting. PDF supports dozens of compression filters—/FlateDecode, /DCTDecode, /LZWDecode, /ASCII85Decode, and more. Each of these can be chained together, creating layers of encoding that make analysis progressively harder.
Why Attackers Love Stream Objects
Stream objects give attackers several advantages when crafting malicious PDFs:
- Compression obfuscation: Compressed streams are harder for naive scanners to inspect. Many security products only check the raw PDF structure without decompressing streams first.
- Multiple filter chains: Stacking filters like
/Filter [/FlateDecode /ASCII85Decode]creates nested encoding that breaks automated analysis. - Legitimate-looking objects: Streams are used for perfectly valid purposes (images, fonts, content streams). Malicious streams blend in with benign ones.
- JavaScript hiding: The most common attack vector involves embedding JavaScript inside streams, often compressed with FlateDecode.
Real-World Attack Scenario
An attacker embeds a JavaScript payload inside a stream object marked as image data. The script uses util.printf() or this.getIcon() to execute arbitrary code when the PDF opens. Traditional signature-based detection fails because the malicious code only exists in compressed form within the stream.
Analyzing Stream Objects
Let's walk through how to inspect streams safely. You'll want to use tools designed for PDF forensic analysis rather than trying to parse raw files manually.
Using pdfid.py
The pdfid.py tool (from Didier Stevens) gives you a quick overview of the PDF structure, including stream counts:
pdfid.py suspicious.pdf
Look for anomalies like excessive stream objects, unusual filter combinations, or streams without the expected dictionary entries.
Extracting Streams with pdf-parser.py
The pdf-parser.py tool lets you dive into individual objects and extract stream content:
pdf-parser.py -o 12 suspicious.pdf
This dumps object 12 and its stream content. You can also use -f to automatically decompress FlateDecode streams:
pdf-parser.py -f -o 12 suspicious.pdf
Manual Stream Extraction
For deeper investigation, you can extract streams manually. Here's a Python snippet using the pdfminer library:
from pdfminer.high_level import extract_pages
from pdfminer.pdfparser import PDFParser
from pdfminer.pdfdocument import PDFDocument
with open('suspicious.pdf', 'rb') as f:
parser = PDFParser(f)
doc = PDFDocument(parser)
for obj in doc.objects:
if hasattr(obj, 'stream') and obj.stream is not None:
print(f"Object {obj.objid}: {len(obj.stream.get_data())} bytes")
print(f"Filter: {obj.get('Filter')}")
Detecting Malicious Streams
When analyzing streams for potential threats, watch for these red flags:
- Unexpected JavaScript: Streams containing
eval(),app.alert,this.getIcon(), orutil.printf() - Filter abuse: Unusual filter combinations, especially involving
/Noneor missing filters where expected - Large unnamed streams: Streams without clear /Type or /Subtype that contain substantial data
- Obfuscated content: Streams with excessive encoding layers that serve no apparent purpose
- Action streams: Streams containing
/AA(additional actions) or/OpenActionentries
Practical Example: Finding Hidden JavaScript
Let's say you're analyzing a suspicious PDF and want to find JavaScript hidden in streams. A quick grep approach:
grep -a "JavaScript" suspicious.pdf
This searches the decompressed PDF for JavaScript references. But remember—compressed streams won't show up this way. For thorough analysis, you need to decompress streams first or use a dedicated tool.
Here's a more robust approach using peepdf, a Python tool specifically designed for PDF analysis:
peepdf -f suspicious.pdf
This will parse the PDF, decompress streams automatically, and show you the contents in a readable format. Look for /JS and /JavaScript entries in the PDF structure.
Defending Against Stream-Based Attacks
For organizations, the key is ensuring your PDF security tools actually decompress and inspect stream contents. This means:
- Use modern PDF parsers: Ensure your security tools recursively decompress all streams before analysis
- Enable JavaScript blocking: Disable PDF JavaScript execution at the endpoint level
- Sanitize incoming PDFs: Run all incoming PDFs through a PDF sanitization process that strips unnecessary objects and scripts
- Monitor for anomalies: Track metrics like stream count, filter complexity, and object ratios as part of your threat detection
Key Takeaways
Stream objects are a legitimate part of the PDF specification, but they're also one of the primary vehicles for PDF malware delivery. Understanding how streams work, how they're compressed, and where attackers hide malicious code is fundamental to PDF security and forensic analysis.
The key skills every security professional should have:
- Reading PDF structure and identifying stream objects
- Using tools like pdfid, pdf-parser, and peepdf for analysis
- Recognizing common attack patterns in stream content
- Implementing proper sanitization workflows
When in doubt, treat any PDF with unexpected streams—especially those containing JavaScript or unusual filter chains—as suspicious. Run it through a sandboxed analysis environment before allowing it into your network.