corbel/INSTALL.md

CorbelPurge v0.3.0 — Quick Start

Author: Jeremy Anderson Repo: https://git.dcos.net/dcosnet/corbel License: GPL-3.0-or-later

Option A: Build from source

Requires Rust 1.70+ (stable). No C compiler needed — all dependencies are pure Rust.

# Headless CLI (default — no GUI deps pulled in)
cargo build --release

# With iced GUI (pulls in iced, rfd, tokio)
cargo build --release --features gui --bin corbel-purge-gui

The headless CLI binary is target/release/corbel-purge. The GUI binary is target/release/corbel-purge-gui (only built when the gui feature is enabled).

Release profile

Cargo.toml uses opt-level = 3, lto = "thin", codegen-units = 1, strip = "symbols" for the release profile. This produces a small, optimized binary.

What you get

CLI (corbel-purge)

Two subcommands:

• corbel-purge scan <path> — scan a single file. Produces a ScanReport with per-finding classifications (Benign, Suspicious, EducationalContent, Malicious). If malicious findings exist, writes a quarantine tarball (original + report + extracted payloads) and a cleansed document.
• corbel-purge scan-dir <dir> — scan all supported files in a directory. With --recursive, descends into subdirectories. Supported extensions: .pdf, .epub, .md, .markdown, .docx.

Flags: --workspace <dir>, --abort-on-threat, --quiet, --recursive, --preserve-format.

Output files

When threats are found, the pipeline writes to the workspace:

<workspace>/
├── corbel_quarantine/
│   ├── quarantine_20260731T120000_abcdef01.tar.gz
│   ├── report_20260731T120000_abcdef01.json
│   └── report_20260731T120000_abcdef01.md
└── corbel_clean/
    └── cleansed_20260731T120000_abcdef01.md

With --preserve-format, the cleansed file keeps its original extension (.pdf, .epub, .docx). Markdown always produces .md.

GUI (corbel-purge-gui)

The iced 0.13 dashboard provides:

• File/folder pickers (via rfd::AsyncFileDialog)
• Toggle switches for preserve-format, abort-on-threat, recursive
• A timestamped console log showing scan progress and results
• A sidebar with a Unicode progress gauge and stats

The GUI spawns the pipeline via tokio::spawn_blocking — the UI stays responsive during long scans.

Try it on the bundled fixtures

# Regenerate fixtures first (requires pypdf, reportlab, python-docx)
pip install pypdf reportlab python-docx
python3 scripts/gen_fixtures.py
python3 scripts/gen_md_epub_fixtures.py
python3 scripts/gen_docx_fixtures.py
python3 scripts/gen_zip_bomb_fixtures.py

# Benign — should report 0 threats
corbel-purge scan tests/fixtures/benign.pdf --workspace /tmp/demo

# Malicious PDF with embedded JavaScript — should quarantine + cleanse
corbel-purge scan tests/fixtures/malicious_js.pdf --workspace /tmp/demo

# Malicious PDF with /Launch action — should quarantine
corbel-purge scan tests/fixtures/malicious_launch.pdf --workspace /tmp/demo

# Malicious EPUB with <script> tag — format-preserving repackage
corbel-purge scan tests/fixtures/malicious.epub --workspace /tmp/demo --preserve-format

# Malicious DOCX with VBA macro — format-preserving repackage
corbel-purge scan tests/fixtures/malicious_macro.docx --workspace /tmp/demo --preserve-format

# CVE writeup — should whitelist as educational, 0 malicious findings
corbel-purge scan tests/fixtures/cve_writeup.md --workspace /tmp/demo

# Scan the whole fixtures directory
corbel-purge scan-dir tests/fixtures --workspace /tmp/demo --recursive

Run the test suite

cargo test

The suite includes unit tests in every module, 22 integration tests in tests/pipeline_integration.rs (benign/malicious PDF, EPUB, DOCX, Markdown; PreserveFormat repackage; abort-on-threat; educational whitelisting), and 4 zip-bomb defense tests in tests/zip_bomb_defense.rs.