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.

9.6 KB
Raw Blame
//! Address → Function resolution (containing-function layer).
//!
//! Shared by CLI, MCP, GPU decompile, and GUI. On executable orphans: re-run FSS
//! once, heal from pdata when possible, otherwise synthesize `SYNTH_{addr}`.

use crate::analyzers::run_analyzers;
use crate::error::Result;
use crate::pe_functions::{create_function_with_kind, runtime_function_containing};
use crate::program::{FunctionInfo, FunctionSeedKind, Program};
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ResolveStatus {
    ExactEntry,
    Containing,
    Ambiguous,
    NoContainingFunction,
    NotExecutable,
    Unmapped,
    /// Orphan executable VA healed via pdata or freshly synthesized.
    Synthesized,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ResolveResult {
    pub ok: bool,
    pub resolve_status: ResolveStatus,
    pub requested_addr: u64,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub resolved_entry: Option<u64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub function_name: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub function_end: Option<u64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub offset_in_function: Option<u64>,
    #[serde(default)]
    pub ambiguous: bool,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub candidates: Vec<ResolveCandidate>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reason: Option<String>,
    /// Present when status is `synthesized` (pdata heal or orphan synth).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub synthesized_range: Option<SynthesizedRange>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SynthesizedRange {
    pub start: u64,
    pub end: u64,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ResolveCandidate {
    pub entry: u64,
    pub end: u64,
    pub name: String,
}

fn fail(addr: u64, status: ResolveStatus, reason: &str) -> ResolveResult {
    ResolveResult {
        ok: false,
        resolve_status: status,
        requested_addr: addr,
        resolved_entry: None,
        function_name: None,
        function_end: None,
        offset_in_function: None,
        ambiguous: false,
        candidates: vec![],
        reason: Some(reason.into()),
        synthesized_range: None,
    }
}

fn ok_from(
    addr: u64,
    f: &FunctionInfo,
    status: ResolveStatus,
    ambiguous: bool,
    candidates: Vec<ResolveCandidate>,
) -> ResolveResult {
    let synthesized_range = if status == ResolveStatus::Synthesized {
        Some(SynthesizedRange {
            start: f.entry,
            end: f.end,
        })
    } else {
        None
    };
    ResolveResult {
        ok: true,
        resolve_status: status,
        requested_addr: addr,
        resolved_entry: Some(f.entry),
        function_name: Some(f.name.clone()),
        function_end: Some(f.end),
        offset_in_function: Some(addr.saturating_sub(f.entry)),
        ambiguous,
        candidates,
        reason: None,
        synthesized_range,
    }
}

fn try_resolve_covering(prog: &Program, addr: u64) -> Option<ResolveResult> {
    if let Some(f) = prog.function_at(addr) {
        return Some(ok_from(addr, f, ResolveStatus::ExactEntry, false, vec![]));
    }
    let covering: Vec<&FunctionInfo> = prog
        .analysis
        .functions
        .iter()
        .filter(|f| addr >= f.entry && addr < f.end.max(f.entry.saturating_add(1)))
        .collect();
    if covering.is_empty() {
        return None;
    }
    let primary = covering
        .iter()
        .copied()
        .min_by_key(|f| {
            let span = f.end.saturating_sub(f.entry);
            (span, u64::MAX - f.entry)
        })
        .expect("non-empty");
    let ambiguous = covering.len() > 1;
    let candidates: Vec<ResolveCandidate> = covering
        .iter()
        .map(|f| ResolveCandidate {
            entry: f.entry,
            end: f.end,
            name: f.name.clone(),
        })
        .collect();
    let status = if ambiguous {
        ResolveStatus::Ambiguous
    } else {
        ResolveStatus::Containing
    };
    Some(ok_from(addr, primary, status, ambiguous, candidates))
}

/// Resolve `addr` to a function entry. Auto-runs Function Start Search when empty;
/// on executable orphans, re-runs FSS once then pdata-heals or synthesizes.
pub fn resolve_function(prog: &mut Program, addr: u64) -> Result<ResolveResult> {
    if !prog.contains_va(addr) {
        return Ok(fail(addr, ResolveStatus::Unmapped, "unmapped"));
    }
    let in_exec = prog
        .blocks
        .iter()
        .any(|b| b.executable && addr >= b.va && addr < b.va.saturating_add(b.size));
    if !in_exec {
        if prog.function_at(addr).is_none() {
            return Ok(fail(addr, ResolveStatus::NotExecutable, "not_executable"));
        }
    }

    if prog.analysis.functions.is_empty() {
        let _ = run_analyzers(prog, &["Function Start Search"])?;
    }

    if let Some(r) = try_resolve_covering(prog, addr) {
        return Ok(r);
    }

    if !in_exec {
        return Ok(fail(
            addr,
            ResolveStatus::NoContainingFunction,
            "no_containing_function",
        ));
    }

    // Orphan executable VA: re-run FSS/PE once, then pdata-heal or synthesize.
    let _ = run_analyzers(prog, &["Function Start Search"])?;
    if let Some(r) = try_resolve_covering(prog, addr) {
        return Ok(r);
    }

    if let Some(rf) = runtime_function_containing(prog, addr) {
        let f = create_function_with_kind(
            prog,
            rf.begin_va,
            Some(rf.end_va),
            FunctionSeedKind::Pdata,
            Some(format!("FUN_{:08x}", rf.begin_va)),
        );
        return Ok(ok_from(addr, &f, ResolveStatus::Synthesized, false, vec![]));
    }

    let f = create_function_with_kind(
        prog,
        addr,
        None,
        FunctionSeedKind::Synthesized,
        Some(format!("SYNTH_{addr:08x}")),
    );
    Ok(ok_from(addr, &f, ResolveStatus::Synthesized, false, vec![]))
}

/// JSON-friendly hex fields for agent responses.
pub fn resolve_result_json(r: &ResolveResult) -> serde_json::Value {
    serde_json::json!({
        "ok": r.ok,
        "resolve_status": r.resolve_status,
        "requested_addr": format!("{:#x}", r.requested_addr),
        "resolved_entry": r.resolved_entry.map(|e| format!("{e:#x}")),
        "function_name": r.function_name,
        "function_end": r.function_end.map(|e| format!("{e:#x}")),
        "offset_in_function": r.offset_in_function,
        "ambiguous": r.ambiguous,
        "candidates": r.candidates.iter().map(|c| serde_json::json!({
            "entry": format!("{:#x}", c.entry),
            "end": format!("{:#x}", c.end),
            "name": c.name,
        })).collect::<Vec<_>>(),
        "reason": r.reason,
        "synthesized_range": r.synthesized_range.as_ref().map(|s| serde_json::json!({
            "start": format!("{:#x}", s.start),
            "end": format!("{:#x}", s.end),
        })),
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::program::{FunctionInfo, MemoryBlock, Program};

    fn prog_with_fn(entry: u64, end: u64) -> Program {
        let mut prog = Program::new("t".into(), "PE32+");
        prog.blocks.push(MemoryBlock {
            name: ".text".into(),
            va: entry,
            size: end - entry,
            bytes: vec![0x90; (end - entry) as usize],
            readable: true,
            writable: false,
            executable: true,
        });
        prog.analysis
            .functions
            .push(FunctionInfo::new(entry, end, "f").with_seed_kind(FunctionSeedKind::Manual));
        prog
    }

    #[test]
    fn mid_body_resolves_containing() {
        let mut prog = prog_with_fn(0x1000, 0x1100);
        let r = resolve_function(&mut prog, 0x1050).unwrap();
        assert!(r.ok);
        assert_eq!(r.resolved_entry, Some(0x1000));
        assert_eq!(r.offset_in_function, Some(0x50));
        assert_eq!(r.resolve_status, ResolveStatus::Containing);
    }

    #[test]
    fn unmapped_is_honest() {
        let mut prog = prog_with_fn(0x1000, 0x1100);
        let r = resolve_function(&mut prog, 0x9999).unwrap();
        assert!(!r.ok);
        assert_eq!(r.resolve_status, ResolveStatus::Unmapped);
    }

    #[test]
    fn orphan_executable_synthesizes() {
        let mut prog = Program::new("t".into(), "PE32+");
        // ret; int3; int3 so grow terminates cleanly
        let mut bytes = vec![0x90; 0x100];
        bytes[0x50] = 0xC3;
        bytes[0x51] = 0xCC;
        bytes[0x52] = 0xCC;
        prog.blocks.push(MemoryBlock {
            name: ".text".into(),
            va: 0x1000,
            size: 0x100,
            bytes,
            readable: true,
            writable: false,
            executable: true,
        });
        // Non-empty functions list so first path does not only rely on empty-FSS.
        prog.analysis
            .functions
            .push(FunctionInfo::new(0x2000, 0x2100, "elsewhere"));
        let r = resolve_function(&mut prog, 0x1050).unwrap();
        assert!(r.ok);
        assert_eq!(r.resolve_status, ResolveStatus::Synthesized);
        assert_eq!(r.resolved_entry, Some(0x1050));
        assert_eq!(r.function_name.as_deref(), Some("SYNTH_00001050"));
        assert!(r.synthesized_range.is_some());
        let syn = r.synthesized_range.unwrap();
        assert_eq!(syn.start, 0x1050);
        assert!(syn.end > syn.start);
        assert!(prog.function_at(0x1050).is_some());
        assert_eq!(
            prog.function_at(0x1050).unwrap().seed_kind,
            Some(FunctionSeedKind::Synthesized)
        );
    }
}