use std::fs;
use std::io::{Read, Write};
use std::os::unix::process::CommandExt;
use std::path::Path;
use std::process::{Command, Stdio};
use std::time::Duration;
use anyhow::{bail, Context, Result};
use clap::{Parser, Subcommand};
use fnprint_core::{
dump_traces, eval, index_bytes, match_by_name, query_corpus, source_str, triage, warm_pool,
EffectTrace, IndexedFunc, Verdict, MIN_COMPLEXITY,
};
use fnprint_db::{Db, FuncRec, MemCorpus};
use fnprint_emu::Config;
use fnprint_loader::FuncSource;
use serde::{Deserialize, Serialize};
const MAX_INPUT: u64 = 512 << 20; const MAX_REPLY: u64 = 128 << 20;
const WORKER_TOKEN: &str = "__worker";
fn worker_deadline() -> Duration {
let threads = std::thread::available_parallelism()
.map(|n| n.get() as u64)
.unwrap_or(8);
Duration::from_secs(120u64.saturating_mul(threads).saturating_add(300))
}
const POST_REPLY_GRACE: Duration = Duration::from_secs(30);
fn reap_bounded(
child: &mut std::process::Child,
pgid: Option<rustix::process::Pid>,
grace: Duration,
) -> std::io::Result<std::process::ExitStatus> {
let until = std::time::Instant::now() + grace;
loop {
if let Some(st) = child.try_wait()? {
return Ok(st);
}
if std::time::Instant::now() >= until {
if let Some(pgid) = pgid {
let _ = rustix::process::kill_process_group(pgid, rustix::process::Signal::Kill);
}
return child.wait();
}
std::thread::sleep(Duration::from_millis(20));
}
}
#[derive(Serialize, Deserialize)]
enum WorkerReply {
IndexOk(Vec<IndexedFunc>),
DumpOk(Vec<String>),
DbOk(Vec<FuncRec>),
Err(String),
}
#[derive(Parser)]
#[command(
name = "fnprint",
version,
about = "behavioral function fingerprinting"
)]
struct Cli {
#[arg(long, global = true)]
no_sandbox: bool,
#[command(subcommand)]
cmd: Cmd,
}
#[derive(Subcommand)]
enum Cmd {
Index {
binary: String,
#[arg(short, long)]
out: Option<String>,
},
Match { a: String, b: String },
Query {
target: String,
#[arg(long)]
corpus: String,
#[arg(long, default_value_t = 0.7)]
threshold: f64,
},
Eval { a: String, b: String },
Triage {
target: String,
#[arg(long)]
vuln: String,
#[arg(long)]
patched: String,
#[arg(long, default_value_t = 0.6)]
min_sim: f64,
#[arg(long, default_value_t = 0.08)]
margin: f64,
},
Dump { binary: String, func: String },
}
fn main() -> Result<()> {
let mut raw = std::env::args();
let _bin = raw.next();
if raw.next().as_deref() == Some(WORKER_TOKEN) {
let op = raw.next().unwrap_or_default();
let func = raw.next();
return worker_main(&op, func.as_deref());
}
let cli = Cli::parse();
let ns = cli.no_sandbox;
match cli.cmd {
Cmd::Index { binary, out } => cmd_index(&binary, out.as_deref(), ns),
Cmd::Match { a, b } => cmd_match(&a, &b, ns),
Cmd::Query {
target,
corpus,
threshold,
} => cmd_query(&target, &corpus, threshold, ns),
Cmd::Eval { a, b } => cmd_eval(&a, &b, ns),
Cmd::Triage {
target,
vuln,
patched,
min_sim,
margin,
} => cmd_triage(&target, &vuln, &patched, min_sim, margin, ns),
Cmd::Dump { binary, func } => cmd_dump(&binary, &func, ns),
}
}
fn worker_main(op: &str, func: Option<&str>) -> Result<()> {
warm_thread_pool();
fnprint_sandbox::lock_down_worker().context("worker could not enter sandbox")?;
let mut input = Vec::new();
let n = std::io::stdin()
.lock()
.take(MAX_INPUT + 1)
.read_to_end(&mut input)
.context("worker reading stdin")?;
if n as u64 > MAX_INPUT {
return emit(&WorkerReply::Err("input over size cap".into()));
}
let reply = match op {
"index" => match index_bytes(&input, Config::default()) {
Ok(funcs) => WorkerReply::IndexOk(funcs),
Err(e) => WorkerReply::Err(format!("{e:#}")),
},
"dump" => {
let name = func.unwrap_or_default();
match dump_traces(&input, name, Config::default()) {
Ok(traces) => WorkerReply::DumpOk(render_traces(&traces)),
Err(e) => WorkerReply::Err(format!("{e:#}")),
}
}
"dbload" => match Db::open_image(&input).and_then(|db| db.all()) {
Ok(recs) => WorkerReply::DbOk(recs),
Err(e) => WorkerReply::Err(format!("{e:#}")),
},
other => WorkerReply::Err(format!("unknown worker op: {other}")),
};
emit(&reply)
}
fn warm_thread_pool() {
warm_pool();
}
fn render_traces(traces: &[EffectTrace]) -> Vec<String> {
let mut out = Vec::new();
for (i, t) in traces.iter().enumerate() {
out.push(format!(
"-- path {} ({} effects, instret {}, capped {}, coverage {:.2}) --",
i,
t.effects.len(),
t.instret,
t.capped,
t.coverage
));
for e in &t.effects {
out.push(format!(" {e:?}"));
}
}
out
}
fn emit(reply: &WorkerReply) -> Result<()> {
let buf = postcard::to_allocvec(reply).context("serializing worker reply")?;
std::io::stdout()
.lock()
.write_all(&buf)
.context("worker writing reply")?;
Ok(())
}
fn run_worker(op: &str, func: Option<&str>, input: &[u8]) -> Result<WorkerReply> {
let exe = std::env::current_exe().context("locating self for worker re-exec")?;
let mut cmd = Command::new(exe);
cmd.arg(WORKER_TOKEN).arg(op);
if let Some(f) = func {
cmd.arg(f);
}
cmd.stdin(Stdio::piped())
.stdout(Stdio::piped())
.stderr(Stdio::piped());
cmd.process_group(0);
let mut child = cmd.spawn().context("spawning jailed worker")?;
let wpgid = rustix::process::Pid::from_raw(child.id() as i32);
let mut stdin = child.stdin.take().context("worker stdin")?;
let payload = input.to_vec();
let writer = std::thread::spawn(move || {
let _ = stdin.write_all(&payload);
drop(stdin);
});
let mut errpipe = child.stderr.take().context("worker stderr")?;
let errdrain = std::thread::spawn(move || {
let mut buf = Vec::new();
let _ = errpipe.by_ref().take(8 * 1024).read_to_end(&mut buf);
let _ = std::io::copy(&mut errpipe, &mut std::io::sink());
buf
});
let mut stdout = child.stdout.take().context("worker stdout")?;
let (reply_tx, reply_rx) = std::sync::mpsc::channel::<std::io::Result<Vec<u8>>>();
let reader = std::thread::spawn(move || {
let mut out = Vec::new();
let r = stdout.by_ref().take(MAX_REPLY + 1).read_to_end(&mut out);
let _ = reply_tx.send(r.map(|_| out));
});
let deadline = worker_deadline();
let out = match reply_rx.recv_timeout(deadline) {
Ok(Ok(out)) => out,
Ok(Err(e)) => {
let _ = child.wait();
let _ = writer.join();
let _ = reader.join();
return Err(anyhow::Error::new(e).context("reading worker reply"));
}
Err(std::sync::mpsc::RecvTimeoutError::Timeout) => {
if let Some(pgid) = wpgid {
let _ = rustix::process::kill_process_group(pgid, rustix::process::Signal::Kill);
}
let _ = child.wait();
bail!(
"jailed worker exceeded the {}s time budget and was killed",
deadline.as_secs()
);
}
Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => {
let _ = child.wait();
bail!("jailed worker reply reader failed");
}
};
let status = reap_bounded(&mut child, wpgid, POST_REPLY_GRACE).context("waiting on worker")?;
let _ = writer.join();
let _ = reader.join();
let errtail = errdrain.join().unwrap_or_default();
if !status.success() {
let tail = String::from_utf8_lossy(&errtail);
let tail = tail.trim();
if tail.is_empty() {
bail!("jailed worker exited abnormally ({status}) - likely killed by the sandbox or a crash in the emulator");
}
bail!(
"jailed worker exited abnormally ({status}) - likely killed by the sandbox or a crash in the emulator; stderr: {}",
esc(tail)
);
}
if out.len() as u64 > MAX_REPLY {
bail!("jailed worker reply over size cap");
}
let reply: WorkerReply = postcard::from_bytes(&out).context("decoding worker reply")?;
Ok(reply)
}
fn run_index(bytes: &[u8], no_sandbox: bool) -> Result<Vec<IndexedFunc>> {
if no_sandbox {
eprintln!("warning: --no-sandbox, running the emulator without the jail");
return index_bytes(bytes, Config::default());
}
match run_worker("index", None, bytes)? {
WorkerReply::IndexOk(mut funcs) => {
validate_reply_fps(&funcs)?;
for f in &mut funcs {
f.coverage = if f.coverage.is_finite() {
f.coverage.clamp(0.0, 1.0)
} else {
1.0
};
}
Ok(funcs)
}
WorkerReply::Err(e) => bail!("{}", esc(&e)),
_ => bail!("worker returned the wrong reply kind for index"),
}
}
fn validate_reply_fps(funcs: &[IndexedFunc]) -> Result<()> {
for f in funcs {
if f.fp.sig.len() != fnprint_core::SIG_LEN {
bail!("jailed worker returned a fingerprint with an invalid signature length");
}
}
Ok(())
}
fn run_dump(bytes: &[u8], func: &str, no_sandbox: bool) -> Result<Vec<String>> {
if no_sandbox {
eprintln!("warning: --no-sandbox, running the emulator without the jail");
return Ok(render_traces(&dump_traces(bytes, func, Config::default())?));
}
match run_worker("dump", Some(func), bytes)? {
WorkerReply::DumpOk(lines) => Ok(lines),
WorkerReply::Err(e) => bail!("{}", esc(&e)),
_ => bail!("worker returned the wrong reply kind for dump"),
}
}
fn is_db(p: &str) -> bool {
Path::new(p).extension().map(|e| e == "db").unwrap_or(false)
}
fn esc(s: &str) -> String {
let mut out = String::with_capacity(s.len());
for b in s.bytes() {
if b == b' ' || b.is_ascii_graphic() {
out.push(b as char);
} else {
out.push_str(&format!("\\x{b:02x}"));
}
}
out
}
fn validate_corpus_records(recs: &[FuncRec]) -> Result<()> {
for r in recs {
if r.fp.sig.len() != fnprint_core::SIG_LEN {
bail!("jailed db worker returned a record with an invalid signature length");
}
}
Ok(())
}
fn load_corpus_records(path: &str, no_sandbox: bool) -> Result<Vec<FuncRec>> {
if no_sandbox {
eprintln!("warning: --no-sandbox, parsing corpus with in-process sqlite (unjailed)");
return Db::open(path)
.with_context(|| format!("opening corpus {path}"))?
.all();
}
let bytes = read_input(path)?;
match run_worker("dbload", None, &bytes)? {
WorkerReply::DbOk(recs) => {
validate_corpus_records(&recs)?;
Ok(recs)
}
WorkerReply::Err(e) => bail!("{}", esc(&e)),
_ => bail!("worker returned the wrong reply kind for dbload"),
}
}
fn load_corpus(path: &str, no_sandbox: bool) -> Result<MemCorpus> {
Ok(MemCorpus::from_records(load_corpus_records(
path, no_sandbox,
)?))
}
fn read_input(path: &str) -> Result<Vec<u8>> {
if let Ok(md) = fs::metadata(path) {
if md.len() > MAX_INPUT {
bail!(
"{path} is {} bytes, over the {MAX_INPUT} byte cap",
md.len()
);
}
}
let bytes = fs::read(path).with_context(|| format!("reading {path}"))?;
if bytes.len() as u64 > MAX_INPUT {
bail!("{path} over the {MAX_INPUT} byte cap");
}
Ok(bytes)
}
fn load_index(path: &str, no_sandbox: bool) -> Result<Vec<IndexedFunc>> {
if is_db(path) {
Ok(load_corpus_records(path, no_sandbox)?
.into_iter()
.map(|r| IndexedFunc {
name: r.name,
entry: r.entry,
source: FuncSource::Symtab,
fp: r.fp,
coverage: 1.0,
})
.collect())
} else {
let bytes = read_input(path)?;
run_index(&bytes, no_sandbox)
}
}
fn cmd_index(binary: &str, out: Option<&str>, no_sandbox: bool) -> Result<()> {
let bytes = read_input(binary)?;
let funcs = run_index(&bytes, no_sandbox)?;
let label = Path::new(binary)
.file_name()
.and_then(|s| s.to_str())
.unwrap_or(binary);
let named = funcs.iter().filter(|f| f.name.is_some()).count();
let usable = funcs
.iter()
.filter(|f| f.fp.complexity >= MIN_COMPLEXITY)
.count();
println!(
"{}: {} functions, {} named, {} with enough signal",
esc(label),
funcs.len(),
named,
usable
);
if let Some(path) = out {
let db = Db::open(path)?;
for f in &funcs {
db.insert(
label,
f.name.as_deref(),
f.entry,
source_str(f.source),
&f.fp,
)?;
}
println!("wrote {} prints -> {}", funcs.len(), path);
}
Ok(())
}
fn cmd_match(a: &str, b: &str, no_sandbox: bool) -> Result<()> {
let ia = load_index(a, no_sandbox)?;
let ib = load_index(b, no_sandbox)?;
let rep = match_by_name(&ia, &ib);
println!("compared {} functions present in both", rep.compared);
println!(" unchanged: {}", rep.same);
println!(" changed: {}", rep.changed.len());
println!(" low-signal: {} (too small to judge)", rep.low_signal);
println!(" only in {}: {}", a, rep.only_a.len());
println!(" only in {}: {}", b, rep.only_b.len());
if !rep.changed.is_empty() {
println!("\nchanged behavior (lowest similarity first):");
for c in rep.changed.iter().take(40) {
println!(" {:>5.1}% {}", c.similarity * 100.0, esc(&c.name));
}
}
Ok(())
}
fn cmd_query(target: &str, corpus: &str, threshold: f64, no_sandbox: bool) -> Result<()> {
let it = load_index(target, no_sandbox)?;
let db = load_corpus(corpus, no_sandbox)?;
let named = query_corpus(&it, &db, threshold)?;
if named.is_empty() {
println!(
"no matches above {:.0}% (try a lower --threshold)",
threshold * 100.0
);
return Ok(());
}
println!("named {} function(s):", named.len());
for n in &named {
println!(
" {:#010x} {:>5.1}% {} ({})",
n.entry,
n.similarity * 100.0,
esc(&n.guess),
esc(&n.from_binary)
);
}
Ok(())
}
fn cmd_eval(a: &str, b: &str, no_sandbox: bool) -> Result<()> {
let ia = load_index(a, no_sandbox)?;
let ib = load_index(b, no_sandbox)?;
let r = eval(&ia, &ib);
println!("scored {} functions (had signal + a twin in B)", r.scored);
println!(" rank-1 accuracy: {:.1}%", r.rank1_acc() * 100.0);
println!(" recall@3: {:.1}%", r.recall_at(3) * 100.0);
println!(" recall@5: {:.1}%", r.recall_at(5) * 100.0);
println!(" MRR: {:.3}", r.mrr());
println!(
" precision@same: {:.1}% ({} tp / {} fp)",
r.precision() * 100.0,
r.tp,
r.fp
);
println!(" recall@same: {:.1}%", r.recall() * 100.0);
println!(
" abstained: {:.1}% ({} of {} below same-threshold)",
r.abstain_rate() * 100.0,
r.abstained,
r.scored
);
Ok(())
}
fn cmd_triage(
target: &str,
vuln: &str,
patched: &str,
min_sim: f64,
margin: f64,
no_sandbox: bool,
) -> Result<()> {
let it = load_index(target, no_sandbox)?;
let vdb = load_corpus(vuln, no_sandbox)?;
let pdb = load_corpus(patched, no_sandbox)?;
let hits = triage(&it, &vdb, &pdb, min_sim, margin)?;
let vulns: Vec<_> = hits
.iter()
.filter(|h| h.verdict == Verdict::Vulnerable)
.collect();
println!(
"{} functions triaged: {} look vulnerable, {} patched, {} inconclusive",
hits.len(),
vulns.len(),
hits.iter()
.filter(|h| h.verdict == Verdict::Patched)
.count(),
hits.iter()
.filter(|h| h.verdict == Verdict::Inconclusive)
.count(),
);
if vulns.is_empty() {
println!("\nno function leans vulnerable above the margin. nothing to review.");
return Ok(());
}
println!("\nreview queue (vuln-leaning, strongest first):");
println!(" addr vuln% patched% margin cov matches");
for h in vulns {
let cov_flag = if h.coverage <= fnprint_core::LOW_COVERAGE_ADVISORY {
"!"
} else {
" "
};
println!(
" {:#010x} {:>5.1} {:>6.1} {:>+5.1} {:>3.0}%{} {} vs {}",
h.entry,
h.vuln_sim * 100.0,
h.patched_sim * 100.0,
h.margin() * 100.0,
h.coverage * 100.0,
cov_flag,
esc(&h.vuln_name),
esc(&h.patched_name),
);
}
println!("\ncov = fraction of the target function body microexecution observed.");
println!(
"a low cov (flagged !) means the verdict rests on little behavior; give it a second look."
);
Ok(())
}
fn cmd_dump(binary: &str, func: &str, no_sandbox: bool) -> Result<()> {
let bytes = read_input(binary)?;
let lines = run_dump(&bytes, func, no_sandbox)?;
for line in &lines {
println!("{}", esc(line));
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::esc;
#[test]
fn esc_defangs_terminal_escapes() {
assert_eq!(esc("foo\x1b[31mbar"), "foo\\x1b[31mbar");
assert_eq!(esc("a\nb\r"), "a\\x0ab\\x0d");
assert_eq!(esc("adler32_z"), "adler32_z");
assert_eq!(esc("é"), "\\xc3\\xa9");
}
}