PreFlight is a pre-install static risk-assessment scanner for Linux. Before you run
or install a downloaded artifact (an ELF binary, a .deb package, an AppImage, or a
shell script), PreFlight inspects it locally and reports what it is and whether it
looks dangerous to run — without executing a single byte of it.
It is explicitly not an anti-virus replacement. It is a fast, local, privacy-friendly "pre-flight check": a first layer of triage before you trust an unknown binary.
- Give a Linux user a fast, local verdict on an arbitrary file before execution.
- Surface concrete, explainable indicators (URLs, IPs, sensitive paths, dropper patterns, miner signatures, packed/obfuscated entropy) rather than a black-box score.
- Be a credible, resume-grade systems tool: written in Rust, with a real TUI and a networked companion service in Go.
- Never execute the target. Analysis is purely static.
- Not a full AV engine: no behavioral sandboxing, no dynamic execution.
- No package-manager interception hooks yet (
apt/dnf/pacmanpre-install hooks). - No signature database; reputation lookups are delegated to VirusTotal via the optional companion service.
- No automatic remediation (quarantine/delete) — PreFlight advises, it does not act.
| Feature | Description |
|---|---|
| File identification | Magic-byte detection for ELF, AppImage (Type 2), Debian .deb, zip, gzip/bzip2/xz, shell scripts (shebang), PE. |
| ELF introspection | Architecture (e_machine), ELF type (ET_EXEC / ET_DYN / ET_REL), entry point — via goblin. |
| String extraction | Printable ASCII runs (len ≥ 4), capped at 50,000 strings for performance. |
| Suspicious-indicator ruleset | 11 tuned regex rules across dropper, reverse-shell, miner, sensitive-path, persistence, obfuscation, and kernel-exploit categories. |
| Entropy analysis | Shannon entropy (0–8 bits) over the byte histogram; flags packed/obfuscated binaries (> 7.5 bits). |
| Hashing | SHA-256 of the entire file (streamed in 64 KiB chunks), independent of the analysis cap — always the real fingerprint for reputation lookup. |
| Risk scoring | Weighted severity sum + entropy bonus → verdict. |
| Verdict | LOW RISK / SUSPICIOUS — review before running / HIGH RISK — do not run. |
| Rule | Severity | What it catches |
|---|---|---|
EMBEDDED_URL |
low | Hard-coded http(s):// callbacks/beacons. |
IP_ADDRESS |
low | Hard-coded IPv4 (possible C2). |
DOWNLOAD_EXEC |
high | curl/wget … | sh dropper pattern. |
DOWNLOADER_TOOL |
medium | References to curl / wget / aria2c. |
SENSITIVE_PATH |
high | /etc/passwd, ~/.ssh, /proc/self/*, /dev/tcp. |
CRYPTOMINER |
high | stratum+tcp, xmrig, monero, cryptonight, nicehash, ethash. |
REVERSE_SHELL |
high | bash -i, nc -e, ncat -e, /dev/tcp/, socat … exec:, python -c … socket. |
PERSISTENCE_CRON |
medium | crontab, /etc/cron, .timer, systemctl enable. |
NETCAT_BIND |
high | nc … -l/-p … -e bind shell. |
OBFUSCATED_BASE64_EXEC |
high | base64 -d | sh style obfuscation. |
KERNEL_EXPLOIT_HINT |
medium | commit_creds, prepare_kernel_cred, /proc/kallsyms. |
- CLI —
preflight scan <file>prints a text report;--jsonemits a machine-readable report. - TUI —
preflight tui <file>opens a dark/neon dashboard (summary, color-coded verdict, findings table, hashes/entropy). Pressq/Escto quit. - Companion service —
preflight-rep(Go) exposes/health,/lookup/hash/{sha256},/lookup/url/{url}for online reputation; queries VirusTotal whenVT_API_KEYis set, otherwise returnsunknowncleanly.
| Layer | Technology | Why |
|---|---|---|
| Core analyzer + CLI + TUI | Rust (edition 2021) | Fast, memory-safe, the modern standard for Linux systems tooling (ripgrep, bottom, bat). |
| ELF/binary parsing | goblin |
Mature, pure-Rust object-format parsing. |
| CLI framework | clap (derive) |
Idiomatic, self-documenting --help. |
| TUI | ratatui + crossterm |
Modern retained-mode terminal UI with cross-platform backend. |
| Hashing | sha2, hex |
SHA-256 fingerprinting. |
| Pattern matching | regex |
The indicator ruleset. |
| Serialization | serde, serde_json |
--json report export. |
| Error handling | anyhow |
Ergonomic application error chaining. |
| Reputation service | Go 1.22 | Great for IO-bound networked services; complements the Rust core. |
| Release profile | opt-level=3, thin LTO, stripped |
Small, fast binaries. |
┌─────────────────────────── preflight (Rust) ───────────────────────────┐
file path ──►│ read (cap 64 MiB) │ detect type │ (ELF? goblin parse) │ strings+entropy │
│ │ rules::scan(strings) │ hash(SHA-256) │ assess → verdict │
│ Report { type, arch, entropy, sha256, findings[], risk_score, verdict }│
└───────────────┬───────────────────────────────────┬────────────────────┘
│ │
text / JSON ──► stdout (optional) HTTP GET
│
┌──────────────── preflight-rep (Go) ──────────────▼─┐
│ /health /lookup/hash/{sha256} │
│ /lookup/url/{url} │
│ VT_API_KEY set? ──► VirusTotal v3 lookup │
│ VT_API_KEY unset?──► { reputation: "unknown" } │
└────────────────────────────────────────────────────┘
Flow:
preflightreads up to 64 MiB of the target file (whole file if smaller).- Magic bytes determine
file_type; if ELF,goblinextracts arch/type/entry. - Printable strings are extracted and scored against the indicator ruleset.
- Shannon entropy is computed over the byte histogram.
- A SHA-256 of the entire file (streamed, independent of the analysis cap) is produced for reputation correlation.
- Severity-weighted findings + entropy bonus yield a
risk_scoreandverdict. - Result is rendered as text, JSON, or the TUI dashboard.
- (Optional) The SHA-256 can be sent to
preflight-rep, which returns VirusTotal reputation when an API key is configured.
preflight/
├── Cargo.toml # workspace root
├── SPEC.md # this document
├── README.md
├── crates/
│ └── preflight-cli/
│ ├── Cargo.toml
│ └── src/
│ ├── main.rs # clap CLI: scan / tui
│ ├── analyzer.rs # type detect, ELF parse, strings, entropy, hash, scoring
│ ├── rules.rs # indicator ruleset + finding type
│ └── tui.rs # ratatui dashboard
├── services/
│ └── preflight-rep/
│ ├── go.mod
│ └── main.go # reputation HTTP service
└── samples/
└── malicious.sh # demo sample
score = Σ(severity weight) # low=5, medium=15, high=30
+ 20 if entropy > 7.5
+ 10 if entropy > 7.85
verdict = "HIGH RISK — do not run" if score >= 60
= "SUSPICIOUS — review before running" if 25 <= score < 60
= "LOW RISK" if score < 25
The model is deliberately explainable: every point traces back to a named rule match or an entropy threshold the user can inspect in the findings table.
- False positives on real packages. Legitimate Debian
.debfiles often contain maintainer scripts (postinst, etc.) that reference/etc,curl, or cron — these commonly scoreSUSPICIOUS. This is by design (maintainer scripts can do anything), but it means "suspicious" should be read as "worth a manual look", not "malicious". - Benign binaries with embedded update URLs/IPs (e.g. a Rust-built
ls) may show low-severityEMBEDDED_URL/IP_ADDRESSfindings; these stay inLOW RISK. - String-only analysis. Packed binaries may hide their real strings; high entropy is the heuristic signal for this, not a definitive verdict.
- 64 MiB analysis cap. Larger files are scanned up to the cap (sufficient for the vast majority of binaries/packages).
- Reputation lookups require a VirusTotal API key in the companion service.
- Package-manager pre-install hooks (
aptDPkg::Pre-Install-Pkgs,dnf,pacman). - YARA rules integration for richer signature matching.
- Recursive archive scanning (
.deb→data.tar→ inner ELFs). - A unified
preflight daemonmode wrapping the Go reputation service in-process. - SARIF output for CI integration.