# 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.

```bash
# 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

```bash
# 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

```bash
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`.