Delete INSTALL.md
This commit is contained in:
parent
6db02ed324
commit
01140683a6
114
INSTALL.md
114
INSTALL.md
|
|
@ -1,114 +0,0 @@
|
||||||
# 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`.
|
|
||||||
Loading…
Reference in New Issue