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.
//! Capture session lifecycle.
use crate::acq::{
enumerate_os_ifaces, open_live, CaptureBackend, CaptureError, LiveStubBackend, ReplayBackend,
};
use crate::file::{write_frames, CAPTURE_MAGIC};
use ghidrust_net_flow::{CaptureFilter, FlowTable, Frame};
use ghidrust_net_schema::{AttributedFlow, CaptureSessionInfo, Owner};
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::path::{Path, PathBuf};
use std::sync::Mutex;
use std::time::{SystemTime, UNIX_EPOCH};
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CaptureStartRequest {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub iface: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub filter: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub pid: Option<u32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub path_substr: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub out_dir: Option<String>,
/// Max bytes before LimitReached.
#[serde(default = "default_max_bytes")]
pub max_bytes: u64,
/// Optional replay capture file for CI.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub replay_path: Option<String>,
}
fn default_max_bytes() -> u64 {
32 * 1024 * 1024
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CaptureStartResult {
pub session_id: String,
pub out_path: String,
pub attr_path: String,
pub backend: String,
}
struct Session {
info: CaptureSessionInfo,
table: FlowTable,
frames: Vec<Frame>,
filter: CaptureFilter,
max_bytes: u64,
#[allow(dead_code)]
backend_name: String,
replay: Option<ReplayBackend>,
live: Option<Box<dyn CaptureBackend + Send>>,
finished: bool,
}
static SESSIONS: Mutex<Option<HashMap<String, Session>>> = Mutex::new(None);
fn with_sessions<R>(f: impl FnOnce(&mut HashMap<String, Session>) -> R) -> R {
let mut g = SESSIONS.lock().unwrap();
if g.is_none() {
*g = Some(HashMap::new());
}
f(g.as_mut().unwrap())
}
pub fn list_interfaces() -> Vec<serde_json::Value> {
let mut v: Vec<serde_json::Value> = enumerate_os_ifaces()
.into_iter()
.map(|i| {
serde_json::json!({
"name": i.name,
"description": i.description,
"ipv4": i.ipv4,
"guid": i.guid,
"kind": "os",
})
})
.collect();
v.push(serde_json::json!({
"name": "replay",
"description": "Fixture replay backend",
"kind": "replay",
}));
v
}
pub fn capture_start(req: CaptureStartRequest) -> Result<CaptureStartResult, CaptureError> {
let id = format!(
"cap-{}",
SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|d| d.as_millis())
.unwrap_or(0)
);
let out_dir = req
.out_dir
.as_deref()
.map(PathBuf::from)
.unwrap_or_else(|| std::env::temp_dir().join("ghidrust-net-capture"));
std::fs::create_dir_all(&out_dir).map_err(|e| CaptureError {
code: "io".into(),
message: e.to_string(),
})?;
let out_path = out_dir.join(format!("{id}.grncap"));
let attr_path = out_dir.join(format!("{id}.attr.json"));
let mut filter = req
.filter
.as_deref()
.map(CaptureFilter::parse)
.unwrap_or_default();
if filter.pid.is_none() {
filter.pid = req.pid;
}
let (replay, live, backend_name) = if let Some(rp) = &req.replay_path {
(
Some(ReplayBackend::from_paths(Path::new(rp), None)?),
None,
"replay".to_string(),
)
} else if req.iface.as_deref() == Some("replay") {
return Err(CaptureError::unavailable(
"replay iface requires replay_path",
));
} else if std::env::var("GHIDRUST_NET_LIVE_STUB").ok().as_deref() == Some("1") {
(
None,
Some(Box::new(LiveStubBackend::new()) as Box<dyn CaptureBackend + Send>),
"live_stub".to_string(),
)
} else {
let backend = open_live(req.iface.as_deref())?;
let name = backend.name().to_string();
(
None,
Some(Box::new(backend) as Box<dyn CaptureBackend + Send>),
name,
)
};
let info = CaptureSessionInfo {
session_id: id.clone(),
running: true,
iface: req.iface.clone(),
bytes_written: 0,
out_path: Some(out_path.display().to_string()),
attr_path: Some(attr_path.display().to_string()),
};
with_sessions(|m| {
m.insert(
id.clone(),
Session {
info,
table: FlowTable::new(),
frames: Vec::new(),
filter,
max_bytes: req.max_bytes,
backend_name: backend_name.clone(),
replay,
live,
finished: false,
},
);
});
// Eagerly drain replay so tests see flows immediately.
let _ = capture_pump(&id);
Ok(CaptureStartResult {
session_id: id,
out_path: out_path.display().to_string(),
attr_path: attr_path.display().to_string(),
backend: backend_name,
})
}
fn capture_pump(session_id: &str) -> Result<(), CaptureError> {
with_sessions(|m| {
let s = m.get_mut(session_id).ok_or_else(|| CaptureError {
code: "not_found".into(),
message: "unknown session".into(),
})?;
if s.finished {
return Ok(());
}
let frames = if let Some(b) = s.replay.as_mut() {
b.poll_frames()?
} else if let Some(b) = s.live.as_mut() {
b.poll_frames()?
} else {
Vec::new()
};
for f in frames {
if !s.filter.matches_frame(&f) {
continue;
}
let nbytes = f.payload.len() as u64 + 64;
if s.info.bytes_written + nbytes > s.max_bytes {
s.info.running = false;
s.finished = true;
return Err(CaptureError::limit());
}
s.info.bytes_written += nbytes;
s.table.ingest(&f);
s.frames.push(f);
}
Ok(())
})
}
pub fn capture_status(session_id: &str) -> Result<CaptureSessionInfo, CaptureError> {
let _ = capture_pump(session_id);
with_sessions(|m| {
m.get(session_id)
.map(|s| s.info.clone())
.ok_or_else(|| CaptureError {
code: "not_found".into(),
message: "unknown session".into(),
})
})
}
pub fn capture_stop(session_id: &str) -> Result<CaptureSessionInfo, CaptureError> {
let _ = capture_pump(session_id);
with_sessions(|m| {
let s = m.get_mut(session_id).ok_or_else(|| CaptureError {
code: "not_found".into(),
message: "unknown session".into(),
})?;
s.info.running = false;
s.finished = true;
if let Some(path) = &s.info.out_path {
write_frames(Path::new(path), &s.frames).map_err(|e| CaptureError {
code: "io".into(),
message: e,
})?;
}
if let Some(path) = &s.info.attr_path {
let owners: Vec<_> = s
.table
.attributed()
.into_iter()
.filter_map(|f| f.owner.map(|o| (f.flow_id.unwrap_or_default(), o)))
.collect::<Vec<(String, Owner)>>();
let _ = CAPTURE_MAGIC;
std::fs::write(
path,
serde_json::to_vec_pretty(&owners).unwrap_or_default(),
)
.map_err(|e| CaptureError {
code: "io".into(),
message: e.to_string(),
})?;
}
Ok(s.info.clone())
})
}
pub fn flows(session_id: &str, max: Option<usize>) -> Result<Vec<AttributedFlow>, CaptureError> {
let _ = capture_pump(session_id);
with_sessions(|m| {
let s = m.get(session_id).ok_or_else(|| CaptureError {
code: "not_found".into(),
message: "unknown session".into(),
})?;
let mut v = s.table.attributed();
if let Some(n) = max {
v.truncate(n);
}
Ok(v)
})
}
#[cfg(test)]
mod tests {
use super::*;
use ghidrust_net_schema::Confidence;
#[test]
fn replay_capture_produces_flows_and_files() {
let dir = std::env::temp_dir().join(format!(
"grn-test-{}",
SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap()
.as_nanos()
));
std::fs::create_dir_all(&dir).unwrap();
let replay = dir.join("in.grncap");
let frames = vec![Frame {
ts_ms: 1,
proto: "tcp".into(),
src: "10.0.0.1".into(),
dst: "10.0.0.2".into(),
src_port: 1234,
dst_port: 443,
payload: b"hello".to_vec(),
tcp_seq: None,
tcp_ack: None,
tcp_flags: None,
owner: Some(Owner {
pid: 99,
image_path: Some("C:\\demo\\app.exe".into()),
image_confidence: Confidence::Exact,
pid_confidence: Confidence::Exact,
}),
}];
write_frames(&replay, &frames).unwrap();
let start = capture_start(CaptureStartRequest {
iface: Some("replay".into()),
replay_path: Some(replay.display().to_string()),
out_dir: Some(dir.display().to_string()),
max_bytes: 1_000_000,
..Default::default()
})
.unwrap();
let fl = flows(&start.session_id, None).unwrap();
assert!(!fl.is_empty());
assert_eq!(fl[0].owner.as_ref().unwrap().pid, 99);
let info = capture_stop(&start.session_id).unwrap();
assert!(Path::new(info.out_path.as_ref().unwrap()).is_file());
assert!(std::fs::metadata(info.out_path.as_ref().unwrap()).unwrap().len() > 0);
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn list_interfaces_is_not_only_hardcoded_placeholders() {
let v = list_interfaces();
assert!(!v.is_empty());
let names: Vec<String> = v
.iter()
.filter_map(|x| x.get("name").and_then(|n| n.as_str()).map(|s| s.to_string()))
.collect();
assert!(names.iter().any(|n| n == "replay"), "replay stays listed");
let os_only: Vec<_> = names.iter().filter(|n| *n != "replay").cloned().collect();
if !os_only.is_empty() {
assert!(
os_only.iter().any(|n| n != "loopback"),
"OS enum must surface real adapters, got {os_only:?}"
);
} else {
// Enum failed — live open must be fail-closed, not live_stub success.
let err = crate::open_live(None).unwrap_err();
assert!(err.code == "privilege_required" || err.code == "backend_unavailable");
}
}
#[test]
fn live_capture_start_is_not_silent_stub() {
if std::env::var("GHIDRUST_NET_LIVE_STUB").ok().as_deref() == Some("1") {
return;
}
match capture_start(CaptureStartRequest {
iface: Some("no-such-ghidnetcap-iface-xyz".into()),
..Default::default()
}) {
Ok(s) => panic!("unknown iface must not start a session (backend={})", s.backend),
Err(e) => assert!(
e.code == "backend_unavailable" || e.code == "privilege_required",
"{}",
e.code
),
}
}
#[test]
fn limit_reached() {
let dir = std::env::temp_dir().join("grn-limit");
let _ = std::fs::create_dir_all(&dir);
let replay = dir.join("big.grncap");
let mut frames = Vec::new();
for i in 0..10 {
frames.push(Frame {
ts_ms: i,
proto: "tcp".into(),
src: "1.1.1.1".into(),
dst: "2.2.2.2".into(),
src_port: 1,
dst_port: 2,
payload: vec![0u8; 100],
tcp_seq: None,
tcp_ack: None,
tcp_flags: None,
owner: None,
});
}
write_frames(&replay, &frames).unwrap();
let res = capture_start(CaptureStartRequest {
replay_path: Some(replay.display().to_string()),
out_dir: Some(dir.display().to_string()),
max_bytes: 50,
..Default::default()
});
// pump during start may hit limit
match res {
Ok(s) => {
let err = capture_pump(&s.session_id);
assert!(err.is_err() || capture_status(&s.session_id).unwrap().bytes_written <= 200);
}
Err(e) => assert_eq!(e.code, "limit_reached"),
}
}
}
impl Default for CaptureStartRequest {
fn default() -> Self {
Self {
iface: None,
filter: None,
pid: None,
path_substr: None,
out_dir: None,
max_bytes: default_max_bytes(),
replay_path: None,
}
}
}