7.0 KiB

Raw Permalink Blame History

Quick Start Guide

Get CorbelPurge built and running in under five minutes.

Prerequisites

Rust 1.70+ (install via rustup)
Python 3 (only needed if you want to regenerate test fixtures)

That is it. The headless CLI has zero GUI dependencies and no native libraries.

Step 1: Get the Source

tar xzf corbel-purge-0.4.2.tar.gz
cd corbel-purge-0.4.2

Step 2: Build the CLI

cargo build --release

The binary lands at target/release/corbel-purge. Verify it works:

./target/release/corbel-purge --help

You should see the usage banner listing scan, scan-dir, study, and the supported flags (--workspace, --abort-on-threat, --quiet, --recursive, --preserve-format, --rules, --cve-db).

Step 3: Scan Your First File

# Scan a suspicious PDF you received
./target/release/corbel-purge scan suspicious_document.pdf

If the file contains threats, you will see a summary block printed to your terminal (findings count, classification, SHA-256, output paths), and the pipeline will write:

A quarantine tarball in ./corbel_quarantine/ (quarantine_<ts>_<sha>.tar.gz) containing original.<ext>, report.json, report.md, and one .bin per carved payload (plus paired .hex and .info files for each payload)
A cleansed Markdown derivative in ./corbel_clean/
Standalone report_<timestamp>_<sha>.json and .md for programmatic access

If the file is clean, the summary block simply reports zero findings and no quarantine output is written.

Step 4: Try PreserveFormat Mode

If you want a cleaned version that keeps the original format (e.g. a cleaned .epub you can actually read in an e-reader):

./target/release/corbel-purge scan research_paper.epub --preserve-format

This produces a cleansed_<ts>_<sha>.epub with malicious entries stripped from the ZIP container but chapter text preserved. Works for PDF and DOCX too.

Step 5: Study a Document In Place

The study subcommand renders the original document to a single annotated HTML file with malicious regions wrapped in inline <span> tags, color-coded by classification. Use it when you want to see exactly where the exploit sits in context, without leaving the source format:

./target/release/corbel-purge study suspicious.epub

Output lands at study_<ts>_<sha>.html in the workspace. Quiet mode (-q) prints just the path.

Step 6: Scan a Directory (Optional)

# Recursively scan an inbox directory
./target/release/corbel-purge scan-dir /path/to/inbox --recursive --workspace /tmp/corbel

The directory walker picks up .pdf, .epub, .md, .markdown, and .docx files. Each file is logged with a [OK], [MALICIOUS], or [ERROR] tag.

Step 7: CI Integration (Optional)

Use --abort-on-threat to make CorbelPurge a CI gate. Exit code 2 means threats were found:

# In your CI pipeline
./target/release/corbel-purge scan incoming_document.pdf --abort-on-threat --quiet
# exit 0: clean
# exit 2: has threats -> fail the build
# exit 1: hard error (parse failure, IO, etc.)

--quiet suppresses the summary block and prints only the JSON report path, which is handy for piping into downstream tooling.

Step 8: Plug In External Threat-Intel Feeds (Optional)

The built-in signature tables and CVE database are static, but you can layer your own on top at runtime:

# Load additional YARA-style signature rules
./target/release/corbel-purge scan suspicious.pdf --rules my_rules.json

# Load additional CVE signature entries
./target/release/corbel-purge scan suspicious.docx --cve-db my_cve_db.json

# Or set them via environment variables
export CORBEL_EXTERNAL_RULES=/etc/corbel/rules.json
export CORBEL_EXTERNAL_CVE_DB=/etc/corbel/cve_db.json
./target/release/corbel-purge scan suspicious.pdf

External rules are matched alongside the built-in tables; nothing is overridden. See MANIFEST.md for the JSON schema.

Step 9: Build the GUI (Optional)

The iced 0.13 dashboard GUI is behind the gui feature flag:

cargo build --release --features gui --bin corbel-purge-gui
./target/release/corbel-purge-gui

The GUI provides file pickers, toggle switches for preserve-format / abort-on-threat / recursive, a timestamped console log, a sidebar with a Unicode progress gauge and per-file stats, and a cleansed-document viewer. All scanning runs through the same Pipeline the CLI uses, via tokio::spawn_blocking.

What You Should See

Clean file output:

────────────────────────────────────────────────────────
scan complete: PDF
  source:      benign.pdf
  sha256:      9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
  text nodes:  12
  vectors:     0
  findings:    0 malicious, 0 educational, 0 total
────────────────────────────────────────────────────────

Threat found output:

────────────────────────────────────────────────────────
scan complete: PDF
  source:      suspicious.pdf
  sha256:      a1b2c3...
  text nodes:  8
  vectors:     1
  findings:    1 malicious, 0 educational, 1 total
  quarantine:  ./corbel_quarantine/quarantine_20260801T120000_abc12345.tar.gz
  cleansed:    ./corbel_clean/cleansed_20260801T120000_abc12345.md
  json report: ./corbel_quarantine/report_20260801T120000_abc12345.json
  md report:   ./corbel_quarantine/report_20260801T120000_abc12345.md
────────────────────────────────────────────────────────

Exit code is 2 when any malicious finding is produced.

Key Environment Variables

Variable	Default	When to Change It
`CORBEL_QUARANTINE_DIR`	`./corbel_quarantine`	Point at a shared quarantine volume
`CORBEL_CLEANSE_DIR`	`./corbel_clean`	Point at an output directory for cleaned files
`CORBEL_ABORT_ON_THREAT`	`false`	Set to `true` in CI pipelines
`CORBEL_EMIT_SUSPICIOUS`	`true`	Set to `false` to only report Malicious (not Suspicious)
`CORBEL_EMIT_MARKDOWN_REPORT`	`true`	Set to `false` if you only need JSON
`CORBEL_TOTAL_ARCHIVE_SCAN_CAP`	`268435456` (256 MiB)	Cumulative cap across all entries in a multi-entry archive
`CORBEL_EXTERNAL_RULES`	(unset)	Path to an external signature-rules JSON file
`CORBEL_EXTERNAL_CVE_DB`	(unset)	Path to an external CVE database JSON file

Next Steps

Read README.md for the full feature overview and security model
Read MANIFEST.md for the detailed technical specification
Read TODO.md for the development roadmap
Run cargo test to verify all 154 tests pass in your environment

7.0 KiB Raw Permalink Blame History