196 lines
7.0 KiB
Markdown
196 lines
7.0 KiB
Markdown
# Quick Start Guide
|
|
|
|
Get CorbelPurge built and running in under five minutes.
|
|
|
|
## Prerequisites
|
|
|
|
- **Rust** 1.70+ (install via [rustup](https://rustup.rs/))
|
|
- **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
|
|
|
|
```bash
|
|
tar xzf corbel-purge-0.4.2.tar.gz
|
|
cd corbel-purge-0.4.2
|
|
```
|
|
|
|
## Step 2: Build the CLI
|
|
|
|
```bash
|
|
cargo build --release
|
|
```
|
|
|
|
The binary lands at `target/release/corbel-purge`. Verify it works:
|
|
|
|
```bash
|
|
./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
|
|
|
|
```bash
|
|
# 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):
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
./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)
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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](README.md) for the full feature overview and security model
|
|
- Read [MANIFEST.md](MANIFEST.md) for the detailed technical specification
|
|
- Read [TODO.md](TODO.md) for the development roadmap
|
|
- Run `cargo test` to verify all 154 tests pass in your environment
|