Ghidrust provides a hyper fast, AI native reverse engineering platform built in Rust, inspired by Ghidra. Includes experimental GPU kernels to rapidly decompile large files, a decryption suite, and network monitor for packet to binary reverse engineering.
//! Dig playbook compilation and offline / closed-loop execution.
use ghidrust_core::{
envelope_or_spill, extract_iocs, filter_imports, load_path, run_analyzers, xrefs_to_string_filter,
DEFAULT_PREVIEW_LIMIT,
};
use ghidrust_net_schema::{
Alert, ClosedLoopConfig, DigFinding, DigJob, DigPlan, DigResult, DigStep, NetHint,
};
use serde_json::{json, Value};
use std::path::Path;
use std::time::{SystemTime, UNIX_EPOCH};
const NETWORK_IMPORT_HINTS: &[&str] = &[
"ws2_32",
"winhttp",
"wininet",
"wsock32",
"dnsapi",
"crypt32",
"schannel",
"ncrypt",
"connect",
"send",
"recv",
"getaddrinfo",
"internet",
];
/// Compile a dig playbook from a hint. Empty hints error.
pub fn compile_playbook(hint: &NetHint) -> Result<DigPlan, String> {
if hint.is_empty() {
return Err("empty hint: provide path, pid, host, ioc, alert_id, or flow_ref".into());
}
let mut steps = Vec::new();
let mut next_steps = Vec::new();
let mut rationale_parts = Vec::new();
if let Some(path) = &hint.path {
steps.push(DigStep {
tool: "load".into(),
args: json!({ "path": path }),
note: Some("load image for analysis".into()),
});
steps.push(DigStep {
tool: "analyze".into(),
args: json!({ "path": path }),
note: Some("auto analysis".into()),
});
rationale_parts.push(format!("load+analyze {path}"));
} else if hint.pid.is_some() {
next_steps.push("process_list".into());
next_steps.push("resolve image path from pid".into());
next_steps.push("net_dig with path".into());
rationale_parts.push("pid present without path; resolve path before offline dig".into());
}
let needle = hint.host.clone().or_else(|| hint.ioc.clone());
if let (Some(path), Some(n)) = (&hint.path, &needle) {
steps.push(DigStep {
tool: "search_strings".into(),
args: json!({ "path": path, "query": n }),
note: Some("locate host/ioc string evidence".into()),
});
steps.push(DigStep {
tool: "get_string_xrefs".into(),
args: json!({ "path": path, "query": n }),
note: Some("xref host/ioc".into()),
});
rationale_parts.push(format!("string/ioc search for {n}"));
}
if let Some(path) = &hint.path {
steps.push(DigStep {
tool: "list_imports".into(),
args: json!({ "path": path }),
note: Some("highlight network-related imports".into()),
});
steps.push(DigStep {
tool: "decompile".into(),
args: json!({ "path": path }),
note: Some("decompile at import/string xref sites (bounded)".into()),
});
}
if hint.pid.is_some() {
next_steps.extend([
"process_attach".into(),
"process_modules".into(),
"process_export_snapshot".into(),
"process_detach".into(),
]);
}
if steps.is_empty() && next_steps.is_empty() {
return Err("hint did not produce any dig steps".into());
}
Ok(DigPlan {
steps,
rationale: rationale_parts.join("; "),
next_steps,
hint: hint.clone(),
})
}
/// MCP/CLI-friendly chain view of a plan.
pub fn playbook_to_mcp_chain(plan: &DigPlan) -> Value {
json!({
"rationale": plan.rationale,
"steps": plan.steps,
"next_steps": plan.next_steps,
})
}
/// Run offline steps that need only a filesystem image.
pub fn execute_playbook_offline(plan: &DigPlan) -> Result<DigResult, String> {
let path = plan
.hint
.path
.as_deref()
.ok_or_else(|| "offline execute requires hint.path".to_string())?;
let path = Path::new(path);
if !path.is_file() {
return Err(format!("path not found: {}", path.display()));
}
let mut prog = load_path(path).map_err(|e| e.to_string())?;
let _ = run_analyzers(&mut prog, &[]).map_err(|e| e.to_string())?;
let mut findings = Vec::new();
let needle = plan
.hint
.host
.clone()
.or_else(|| plan.hint.ioc.clone())
.unwrap_or_default();
if !needle.is_empty() {
let xrefs = xrefs_to_string_filter(&prog, &needle);
if !xrefs.is_empty() {
findings.push(DigFinding {
kind: "string_xref".into(),
detail: format!("{} xref(s) for '{needle}'", xrefs.len()),
evidence: Some(format!("{:x}", xrefs[0].from)),
});
}
let iocs = extract_iocs(&prog.file_bytes);
let hit = iocs.iter().any(|i| i.contains(&needle));
if hit {
findings.push(DigFinding {
kind: "ioc".into(),
detail: format!("ioc match for '{needle}'"),
evidence: Some(needle.clone()),
});
}
}
let net_imports: Vec<_> = filter_imports(&prog.imports, None, None)
.into_iter()
.filter(|im| {
let name = im.name.as_deref().unwrap_or("");
let blob = format!("{}!{}", im.dll, name).to_ascii_lowercase();
NETWORK_IMPORT_HINTS.iter().any(|h| blob.contains(h))
})
.collect();
if !net_imports.is_empty() {
let im0 = net_imports[0];
findings.push(DigFinding {
kind: "import".into(),
detail: format!("{} network-related import(s)", net_imports.len()),
evidence: Some(format!(
"{}!{}",
im0.dll,
im0.name.as_deref().unwrap_or("?")
)),
});
}
// Always record a path finding so closed-loop digs are non-empty on honest PE loads.
findings.push(DigFinding {
kind: "image".into(),
detail: format!("loaded {}", path.display()),
evidence: Some(format!("base={:#x}", prog.image_base)),
});
let envelope = envelope_or_spill(
"net_dig",
json!([{
"path": path.display().to_string(),
"findings": findings,
"plan": plan,
}]),
64,
DEFAULT_PREVIEW_LIMIT,
Some(&path.display().to_string()),
)
.map_err(|e| e.to_string())?;
let mut artifact_ids = Vec::new();
if let Some(id) = envelope.artifact_id.clone() {
artifact_ids.push(id);
}
Ok(DigResult {
artifact_ids,
findings,
plan: Some(plan.clone()),
status: "ok".into(),
})
}
/// Closed-loop dig from an alert (or hint derived from alert).
pub fn execute_closed_loop(
alert: &Alert,
path: &Path,
cfg: &ClosedLoopConfig,
) -> Result<DigJob, String> {
let mut hint = NetHint {
path: Some(path.display().to_string()),
host: alert.host.clone(),
ioc: alert.ioc.clone(),
alert_id: Some(alert.id.clone()),
..Default::default()
};
if hint.host.is_none() && hint.ioc.is_none() {
if let Some(fk) = &alert.flow_key {
hint.ioc = Some(fk.dst.clone());
}
}
let plan = compile_playbook(&hint)?;
let mut result = if cfg.auto_analyze {
execute_playbook_offline(&plan)?
} else {
DigResult {
plan: Some(plan.clone()),
status: "planned".into(),
..Default::default()
}
};
// Bound decompile-oriented findings to configured limit.
if result.findings.len() > cfg.auto_decompile_limit.saturating_add(8) {
result.findings.truncate(cfg.auto_decompile_limit.saturating_add(8));
}
let job_id = format!(
"dig-{}-{}",
alert.id,
SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|d| d.as_millis())
.unwrap_or(0)
);
Ok(DigJob {
job_id,
source: format!("alert:{}", alert.id),
plan,
result: DigResult {
status: "ok".into(),
..result
},
status: "ok".into(),
})
}
#[cfg(test)]
mod tests {
use super::*;
use std::path::PathBuf;
fn fixture_pe() -> PathBuf {
PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../fixtures/tiny_x64.pe")
}
#[test]
fn empty_hint_errors() {
assert!(compile_playbook(&NetHint::default()).is_err());
}
#[test]
fn compile_playbook_includes_load_analyze_and_search() {
let hint = NetHint {
path: Some(fixture_pe().display().to_string()),
host: Some("example.test".into()),
..Default::default()
};
let plan = compile_playbook(&hint).unwrap();
let tools: Vec<_> = plan.steps.iter().map(|s| s.tool.as_str()).collect();
assert!(tools.contains(&"load"));
assert!(tools.contains(&"analyze"));
assert!(tools.iter().any(|t| t.contains("string") || *t == "search_strings"));
assert!(plan.steps.len() >= 3);
let golden = serde_json::to_value(&plan).unwrap();
assert!(golden["steps"].as_array().unwrap().len() >= 3);
}
#[test]
fn offline_execute_on_fixture() {
let pe = fixture_pe();
if !pe.is_file() {
return;
}
let hint = NetHint {
path: Some(pe.display().to_string()),
host: Some("example.test".into()),
..Default::default()
};
let plan = compile_playbook(&hint).unwrap();
let result = execute_playbook_offline(&plan).unwrap();
assert_eq!(result.status, "ok");
// imports finding should generally appear on PE with imports
assert!(!result.findings.is_empty() || result.plan.is_some());
}
#[test]
fn closed_loop_respects_decompile_limit_field() {
let pe = fixture_pe();
if !pe.is_file() {
return;
}
let alert = Alert {
id: "a1".into(),
sid: 1000001,
msg: "test".into(),
severity: 2,
action: "alert".into(),
flow_key: None,
owner: None,
timestamp_ms: 0,
host: Some("example.test".into()),
ioc: None,
};
let cfg = ClosedLoopConfig {
auto_analyze: true,
auto_decompile_limit: 3,
attach_live: false,
};
let job = execute_closed_loop(&alert, &pe, &cfg).unwrap();
assert_eq!(job.status, "ok");
assert!(!job.job_id.is_empty());
}
}