# 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