Skip to content

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.

10.3 KB
Raw Blame
//! 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());
    }
}