Building Ladon —
A Static Document Security Analyzer

Why This Tool Exists

The problem I kept running into while reading threat reports was a practical one. Someone receives a suspicious PDF. Their antivirus doesn't flag it. Their email gateway delivered it. They have no way to know if it's safe to open — not really. The advice is always "be careful with attachments" but there's no tool a non-technical person can use to actually check what's inside a file before they open it.

I decided to build one. I had no prior experience writing static file analysis tools. What I had was Python, a pile of file format specifications, and several months of reading threat reports that kept showing the same pattern: the threat was never where the existing defenses were looking. It was inside the attachment — inside the PDF, inside the image, inside the calendar invite — in places that email gateways don't reach and that users have no visibility into at all.

This lab documents how I built document_triage.py — the analysis engine at the core of Ladon. It's not a retrospective of a clean build. It's a record of the decisions made, the things that didn't work the first time, and what I learned from reading specifications that were never written with attackers in mind. The companion report The Document You Trusted covers the context and real-world validation. This lab covers the build.

Architecture — Three Layers,
One Design Principle

The first decision I made was the most important one: the tool must never execute anything it analyzes. Everything else followed from that. Reading bytes is safe. Interpreting them as a runnable program is not. If the tool executed a malicious file to figure out what it did, it would defeat the entire purpose of triage. So Ladon reads bytes — nothing more.

The build ended up with three distinct layers, each with a single responsibility. Separating them cleanly took a few iterations to get right.

The Detection Modules —
What Each One Looks For

Each module targets a specific attack surface independently. Their findings feed into a shared severity score. A file can trigger multiple modules at once — a malicious PDF with an embedded QR code pointing to a typosquatted domain would fire PDF structure, polyglot detection, barcode analysis, and URL analysis simultaneously. The modules were built one at a time with Claude — defining what each needed to detect, testing against synthetic samples, then adjusting until the output looked right.

Module 1 — PDF Structure Analysis

The PDF specification includes a rich set of actions that legitimate documents rarely use but that attackers routinely abuse. The module scans the raw PDF byte stream for dangerous keys and counts occurrences of each.

for key, description in PDF_DANGEROUS_KEYS.items():
    if key in data:
        count = data.count(key)
        results['dangerous_keys'].append({
            'key':         key.decode('latin-1'),
            'description': description,
            'count':       count,
        })

Module 2 — Polyglot Detection

A polyglot file is simultaneously valid in two different file formats. A PDF that also contains a Windows PE executable is the most common attack variant — the file passes type checks because it has a valid PDF header, but it carries a runnable executable in its body. Ladon scans the entire file for secondary magic byte signatures, not just the first few bytes.

secondary_checks = [
    (b'\x50\x4b\x03\x04', 'ZIP/PKPASS/DOCX',  50),
    (b'\x25\x50\x44\x46', 'PDF',               50),
    (b'\x4d\x5a',         'Windows PE (EXE)', 50),  # MZ header
    (b'\x7f\x45\x4c\x46', 'Linux ELF',         50),
]

for magic, description, min_offset in secondary_checks:
    idx = data.find(magic, min_offset)  # skip first 50 bytes
    if idx != -1:
        findings.append({
            'type':     'SECONDARY_SIGNATURE',
            'detail':   f"{description} signature found at offset {idx}",
            'severity': 'CRITICAL' if 'EXE' in description else 'HIGH',
        })

Module 3 — Image Steganography

Steganography hides data inside something that doesn't look like it contains data. Three sub-checks run on every image: appended data after the EOF marker, LSB (Least Significant Bit) distribution analysis, and Shannon entropy scoring. Legitimate images have slightly uneven LSB distributions. LSB steganography produces near-perfect 50/50 distribution — statistically detectable.

for pixel in sample:
    for channel in pixel:
        lsb = channel & 1  # extract least significant bit
        lsb_counts[lsb] += 1

deviation = abs(ratio_0 - 0.5)
# LSB steganography: deviation < 0.02
# Natural images: deviation > 0.05
suspicious = deviation < 0.02

Module 4 — Audio Steganography

WAV files have explicit chunk sizes declared in their RIFF header. Any bytes after the declared chunk boundary are appended data — not part of the audio. This is the exact delivery mechanism used in the TeamPCP/Telnyx supply chain attack, where malware was hidden inside a WAV file named ringtone.wav and extracted in memory.

if data[:4] == b'RIFF' and len(data) > 8:
    declared_size = struct.unpack('<I', data[4:8])[0] + 8
    actual_size   = len(data)
    if actual_size > declared_size:
        appended_bytes = actual_size - declared_size
        entropy        = shannon_entropy(data[declared_size:])
        # Flag as CRITICAL — data exists past audio boundary

Module 5 — URL Analysis

URLs extracted from any module feed into a shared analysis pipeline. Each URL is checked against a known-safe allowlist, URL shortener list, suspicious TLD list, and a Levenshtein distance typosquatting check against known legitimate domains. The typosquatting check computes edit distance — a domain two characters different from a known airline or travel service is flagged as a potential impersonation.

Module 6 — QR Code Analysis

QR codes inside images are decoded using pyzbar, which handles QR Code Model 1/2, Micro QR, PDF417, and DataMatrix. The decoded URL is fed into the URL analysis pipeline. This module exists because of a documented attack pattern: boarding passes with QR codes replaced by codes pointing to credential harvesting pages. The QR code looks identical visually. Only decoding and analyzing the destination reveals the substitution.

Module 7 — ICS Calendar Analysis

Calendar invites are a persistent delivery mechanism — they are auto-added to the recipient's calendar even if the email is quarantined. The ICS module extracts URLs from the LOCATION, DESCRIPTION, ATTACH, and COMMENT fields and checks for meeting platform spoofing: an invite that claims to be a Zoom or Teams meeting but embeds a URL pointing to a different domain.

MEETING_PLATFORMS = {
    'zoom':        'zoom.us',
    'teams':       'teams.microsoft.com',
    'meet':        'meet.google.com',
    'webex':       'webex.com',
    'gotomeeting': 'gotomeeting.com',
}

for platform, legit_domain in MEETING_PLATFORMS.items():
    if re.search(rf'\b{platform}\b', domain_part) \
       and legit_domain not in url_lower:
        findings.append({'type': 'MEETING_PLATFORM_SPOOF', 'severity': 'CRITICAL'})

Severity Scoring —
How Findings Become a Verdict

Each finding contributes points to a composite severity score. The score determines the final verdict — CRITICAL, HIGH, MEDIUM, or LOW. The thresholds are deliberately conservative: a single CRITICAL finding from polyglot detection (score += 5) puts a file over the HIGH threshold immediately.

if   score >= 8:  return 'CRITICAL'
elif score >= 4:  return 'HIGH'
elif score >= 1:  return 'MEDIUM'
else:            return 'LOW'

The Flask Backend —
Serving Analysis as an API

The Flask layer is intentionally thin. Its job is to accept a file, call the engine, and return JSON. All the intelligence lives in document_triage.py. This separation means the analysis engine can be used directly from the command line, called from other scripts, or exposed through a different interface entirely — the web layer is not load-bearing for the detection logic.

@app.route('/analyze', methods=['POST'])
def analyze():
    file = request.files.get('file')
    if not file:
        return jsonify({'error': 'No file uploaded'}), 400

    # Save to temp file — analyze — discard
    with tempfile.NamedTemporaryFile(
        suffix=Path(file.filename).suffix,
        delete=False
    ) as tmp:
        file.save(tmp.name)
        try:
            results = analyze_file(tmp.name)
            return jsonify(results)
        finally:
            os.unlink(tmp.name)  # always delete — no persistence

The finally block is not an afterthought. It guarantees the uploaded file is deleted regardless of whether analysis succeeds or throws an exception. A malicious file that crashes the parser is still deleted. The server never accumulates files.

Decisions Made Along the Way

Some of the most useful things to document are the decisions that aren't visible in the final code — the things I considered and rejected, and why. These came up repeatedly during the build.

Why not send files to VirusTotal?

The obvious first thought was to integrate VirusTotal. Then I thought about who the tool is for. A defense contractor submitting a suspicious vendor PDF to VirusTotal might inadvertently tip off the attacker that their document was analyzed — VirusTotal results are visible to subscribers. That disclosure risk is real, and it's the kind of thing that came from reading how analysts actually work rather than from writing code. Static local analysis means the file goes nowhere. Ladon reads it and discards it. Nothing leaves the system.

Why not use a sandbox for dynamic analysis?

Sandboxing is the professional answer for malware analysis. But sandboxing requires executing the file — which means you need an isolated environment, you need to know what you're doing, and you need to accept that something is going to run. The question Ladon is trying to answer is "is this safe to open?" Executing it to find out defeats the purpose. Static analysis answers the structural question without triggering anything.

Why Python and not a compiled language?

Python was Claude's recommendation for this use case and it turned out to be the right one. Speed wasn't the concern — documents are small files and analysis is fast regardless. Python's standard library handles binary parsing, Pillow and pyzbar handle images and barcodes, and the code is readable enough that I can follow what it's doing, spot when something looks wrong, and describe the fix I want clearly. That last part matters — I'm not writing the code independently, but I need to be able to evaluate whether what was written actually does what I intended.

Why a single HTML file for the frontend?

Simplicity. A single HTML file can be opened locally in a browser without a server, deployed anywhere, and inspected by anyone. No build pipeline, no bundler, no dependencies to audit. The frontend is not the interesting part of Ladon — the analysis engine is. Keeping the frontend simple keeps the focus where it belongs.

What Was Learned

Reading file format specifications to understand what was designed to be there — and then reading threat reports to understand what attackers put there instead — is where most of the build time went. The PDF spec is 756 pages. WAV chunk boundaries come from a 1991 IBM/Microsoft document. ICS is RFC 5545. None of them were written with attackers in mind, which is exactly why they're useful attack surfaces.

The typosquatting check took the most iterations to get right. The first version Claude wrote flagged too many legitimate domains — a travel booking site with a domain two characters different from "booking.com" is not necessarily a typosquat. I kept testing it against real URLs, flagging what looked wrong, and describing the adjustment needed. Tuning the edit distance threshold and minimum domain length down to something that caught real typosquats without flagging legitimate sites took several rounds of that back-and-forth.

The ICS meeting platform detection had the same problem. The first version checked if a platform keyword appeared anywhere in the URL string — which immediately broke on real-world cases I tested. A Proofpoint-wrapped Zoom URL has "zoom" buried in the destination but the actual domain is Proofpoint. A Calendly-scheduled Teams meeting says "teams" in the description but "calendly.com" in the URL. I found these by testing edge cases, described what was going wrong, and Claude rewrote the check to look at the domain portion only with word boundary matching. That's the pattern throughout the build — I find what's broken, describe what correct behavior looks like, and iterate until the output matches my expectation.

The most useful thing about building this way: the tool is only as good as the edge cases you think to test. Synthetic test files tell you the code runs. Real malware tells you the detection logic actually works. That validation is documented in Lab Log 011.

Ladon is a static analysis tool — it reads file structure and content without executing anything. All analysis runs server-side on Railway infrastructure. No files are stored after analysis. The tool is currently in private testing. SiteWave Studio LLC · Built by Yana Ivanov · April 2026