Skip to content

Latest commit

 

History

History
180 lines (149 loc) · 9.55 KB

SPEC.md

File metadata and controls

180 lines (149 loc) · 9.55 KB

PreFlight — Specification

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.


1. Goals & non-goals

Goals

  • 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.

Non-goals (v1)

  • Not a full AV engine: no behavioral sandboxing, no dynamic execution.
  • No package-manager interception hooks yet (apt/dnf/pacman pre-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.

2. Features

Core analysis

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.

Indicator rules (v1)

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.

Interfaces

  • CLI — preflight scan <file> prints a text report; --json emits a machine-readable report.
  • TUI — preflight tui <file> opens a dark/neon dashboard (summary, color-coded verdict, findings table, hashes/entropy). Press q / Esc to quit.
  • Companion service — preflight-rep (Go) exposes /health, /lookup/hash/{sha256}, /lookup/url/{url} for online reputation; queries VirusTotal when VT_API_KEY is set, otherwise returns unknown cleanly.

3. Technology stack

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.

4. Architecture & data flow

                ┌─────────────────────────── 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:

  1. preflight reads up to 64 MiB of the target file (whole file if smaller).
  2. Magic bytes determine file_type; if ELF, goblin extracts arch/type/entry.
  3. Printable strings are extracted and scored against the indicator ruleset.
  4. Shannon entropy is computed over the byte histogram.
  5. A SHA-256 of the entire file (streamed, independent of the analysis cap) is produced for reputation correlation.
  6. Severity-weighted findings + entropy bonus yield a risk_score and verdict.
  7. Result is rendered as text, JSON, or the TUI dashboard.
  8. (Optional) The SHA-256 can be sent to preflight-rep, which returns VirusTotal reputation when an API key is configured.

5. Project layout

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

6. Risk-scoring model

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.


7. Known limitations & tuning notes

  • False positives on real packages. Legitimate Debian .deb files often contain maintainer scripts (postinst, etc.) that reference /etc, curl, or cron — these commonly score SUSPICIOUS. 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-severity EMBEDDED_URL / IP_ADDRESS findings; these stay in LOW 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.

8. Roadmap (post-v1)

  • Package-manager pre-install hooks (apt DPkg::Pre-Install-Pkgs, dnf, pacman).
  • YARA rules integration for richer signature matching.
  • Recursive archive scanning (.deb → data.tar → inner ELFs).
  • A unified preflight daemon mode wrapping the Go reputation service in-process.
  • SARIF output for CI integration.