115 lines
3.8 KiB
Markdown
Executable File
115 lines
3.8 KiB
Markdown
Executable File
# 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`.
|