corbel/BLOG.md

Announcing CorbelPurge v0.4.2

A defensive document research and cleaning tool for security analysts.

Why This Exists

Security researchers have a problem. When a suspicious PDF lands in your inbox or a weaponized DOCX turns up in a malware corpus, your options for safely inspecting it are limited. Open it in Adobe Reader and you might trigger the payload. Open it in LibreOffice and the macro runs. Send it to VirusTotal and you get a score but not an understanding.

CorbelPurge is built to fill that gap. It is a strict-Rust document sanitizer that never executes embedded scripts, macros, or active content -- but still gives you a full understanding of what is inside the file, then carves the malicious bits into a quarantine tarball with forensic reports and leaves behind a cleansed derivative you can actually read.

What CorbelPurge Does

• Parses PDF, EPUB, DOCX, and Markdown files into a unified intermediate representation (Document struct with TextNode and ExecutableVector items)
• Scans with a two-pass contextual engine: executable vectors go through heuristics::classify_vector() against file-signature, shellcode, phishing, and URI-allowlist tables; text nodes go through context_filter::evaluate() which distinguishes weaponized content from educational security literature (CVE writeups, code blocks, academic language)
• Tags known exploits automatically -- 11 entries in the built-in CVE table (CVE-2017-11882, CVE-2018-4990, CVE-2010-0188, CVE-2018-0802, CVE-2017-8570, CVE-2017-0199, CVE-2012-0158, CVE-2015-2545, CVE-2021-40444, CVE-2022-30190, and EPUB-SCRIPT-INJECTION)
• Quarantines extracted payloads into a compressed quarantine_<ts>_<sha>.tar.gz containing the original file, a JSON report, a Markdown report, and one .bin per carved payload -- each paired with a .hex annotated hex dump and a .info JSON metadata file
• Cleanses documents so you can read them safely, either as Markdown (default) or in the original format via --preserve-format (EPUB entries stripped from the ZIP, DOCX macros and embeddings removed, PDF objects deleted via lopdf)
• Studies documents in place via corbel-purge study <path>, which renders the original to a single annotated HTML file with malicious regions wrapped in inline <span> tags color-coded by classification
• Defends against zip-bomb attacks with streaming byte-counting (util::read_with_cap()) that counts actual decompressed bytes rather than trusting ZIP central-directory size headers, plus a cumulative total_archive_scan_cap (default 256 MiB) across all entries in a multi-entry archive

What Is New in v0.4.2

Glyphfix (carried from v0.4.1)

The iced 0.13 GUI previously rendered 11 Unicode glyphs as tofu boxes because iced's default embedded font (a subset of DejaVu Sans) does not cover them. Every problematic glyph was swapped for an ASCII equivalent that is guaranteed to render: shield emoji became [+], block characters became # and -, the warning sign became !, and so on. No new dependencies, no embedded fonts, no binary-size regression.

About / License overlay (carried from v0.4.1)

The ABOUT / LICENSE button in the GUI footer is now wired up. Clicking it opens a floating info panel anchored to the top-right corner -- dark panel, gold border, drop shadow, close button in the header, structured metadata (title, version, description, author, website, license, tech stack, copyright). A 55%-opacity black backdrop dims the underlying UI while the panel is open.

What else changed

• Version bumped to 0.4.2
• Docs (README.md, MANIFEST.md, TODO.md, FIX-NOTES-glyphfix.md, the pdf_parser.rs header comment) all updated to drop pdf-render references
• Test suite unchanged: 154 tests still pass (127 unit + 23 integration + 4 zip-bomb defense)

What Came Before

• v0.4.1: Glyphfix patch, About / License overlay wired up
• v0.3.0: Study mode (corbel-purge study), payload carving v2 (.hex + .info files alongside .bin), EPUB/Markdown cleansed-document viewer in the GUI, external threat-intel feeds (--rules and --cve-db flags + ExternalRulesData static storage), expanded CVE table (4 new entries: CVE-2012-0158, CVE-2015-2545, CVE-2021-40444, CVE-2022-30190), total-memory budget for multi-entry archives, PDF repackage dangling-reference cleanup, OPF manifest cleanup after EPUB repackage, GUI CVE badges parsed from Finding.context_notes
• v0.2.0: 4-format parsing (PDF via lopdf, EPUB via zip, Markdown via pulldown-cmark, DOCX via zip + XML regex), unified intermediate representation, layered contextual scanner, CVE tagging, quarantine packaging, document cleansing (Markdown + PreserveFormat modes), zip-bomb defense, iced 0.13 GUI dashboard

Who Is This For?

• Incident responders who need to safely inspect suspicious attachments
• Threat researchers studying document-based exploits from malware corpora
• Security teams who want CI/CD scanning for incoming documents (--abort-on-threat exits 2 on any malicious finding)
• Academics analyzing CVE write-ups and exploit techniques (the context filter whitelists educational content so a CVE writeup that quotes shellcode does not get flagged)
• Anyone who receives a document from an untrusted source and wants to read it without risking code execution

What CorbelPurge Is Not

CorbelPurge does not create, generate, weaponize, or distribute exploits. It does not execute embedded scripts, macros, or active content. It is not an offensive security tool. It is a defensive research instrument.

Get Started

tar xzf corbel-purge-0.4.2.tar.gz
cd corbel-purge-0.4.2
cargo build --release
./target/release/corbel-purge scan path/to/suspicious.pdf

See QUICKSTART.md for the full step-by-step guide, including the study subcommand, PreserveFormat mode, CI integration, external threat-intel feeds, and the optional iced GUI build.

Roadmap Preview

The highest-priority items currently on the deferred list:

• Bundled historical exploit corpus -- too risky to ship; would bloat the repo
• Sandbox hardening / fuzzing the tool itself -- the tool is not the target per the threat model
• Encrypted quarantine tarballs -- unnecessary for the research use case; disk encryption is the operator's responsibility
• Full OOXML schema validation -- the current coarse regex extraction in docx_parser.rs is sufficient for the threat model
• Magic-byte sniffing -- DocumentFormat::from_path() uses extension only; a mismatched extension causes a parse error (safe failure mode)
• Full syntect syntax highlighting -- the cleansed-document viewer uses a lightweight dark-panel approach; syntect would add a heavy dependency to a security-critical crate

See TODO.md for the full development roadmap.

License

GNU General Public License v3.0-or-later. Free software for research, security analysis, and academic study. See LICENSE for full terms.