ms_even6/lib.rs
1//! MS-EVEN6 — the EventLog Remoting Protocol v6, the Vista-era replacement for MS-EVEN.
2//! Speaks over MS-RPCE (SMB named pipe `\pipe\eventlog`, interface UUID
3//! `F6BEAFF7-1E19-4FBB-9F8F-B89E2018337C` v1.0). Lets a remote caller open a channel by
4//! name, register an XPath query against it, pull matching event records, and read the
5//! payload as BinXml (MS-EVEN6 §2.2.17) — the same wire form the local Vista+ EventLog
6//! service hands to `EvtRender`.
7//!
8//! **Status: pre-alpha / 0.1.0-dev.** The wire encoders for the core opnums exist and
9//! round-trip against hand-crafted golden bytes; the BinXml decoder recognises the
10//! commonly-used token subset (element open/close, attribute, value UTF-16LE, template
11//! reference, EOF) and produces a structured `Event`. Full spec conformance and live-DC
12//! iteration are deferred to a later revision.
13//!
14//! # Layout
15//! - [`transport`] — a small `Transport` trait so the client can be driven by dcerpc's
16//! `SmbPipe` (real DC) or a byte-scripted mock (tests). The dcerpc adapter is `todo`
17//! for 0.2.0 — it needs async plumbing that the sync-facing API doesn't offer yet.
18//! - [`opnums`] — opnum wire encoders/decoders (EvtRpcOpenLogHandle, RegisterLogQuery,
19//! QueryNext, Close).
20//! - [`binxml`] — the BinXml token-stream decoder (channel, provider, event id,
21//! record id, time_created, and a rendered XML string).
22//! - [`gaps`] — record-id gap detection over a set of pulled events.
23//!
24//! The public API on this crate ([`EvenClient`], [`open_log_handle`](EvenClient::open_log_handle),
25//! [`register_log_query`](EvenClient::register_log_query),
26//! [`query_next`](EvenClient::query_next), [`decode_binxml`], [`detect_gaps`]) is sync —
27//! the transport trait is sync too. A DC-real caller wraps their `SmbPipe` (async) via a
28//! `tokio::runtime::Handle::block_on` shim; see `examples/` (TBD) for the pattern.
29
30pub mod binxml;
31pub mod gaps;
32pub mod opnums;
33pub mod transport;
34
35use ms_ndr::NdrError;
36
37pub use binxml::{decode_binxml, Event};
38pub use gaps::{detect_gaps, RecordIdGap};
39pub use transport::Transport;
40
41/// A DCE/RPC abstract syntax (UUID + interface version) — the tiny local stand-in
42/// for `dcerpc::Syntax` while the dcerpc integration is deferred. Wire byte layout
43/// matches DCE (little-endian UUID, u16 major, u16 minor).
44#[derive(Clone, Copy, Debug, PartialEq, Eq)]
45pub struct Syntax {
46 pub uuid: [u8; 16],
47 pub ver_major: u16,
48 pub ver_minor: u16,
49}
50
51/// The MS-EVEN6 interface: UUID F6BEAFF7-1E19-4FBB-9F8F-B89E2018337C, v1.0.
52pub fn even6_syntax() -> Syntax {
53 // Canonical UUID → DCE on-wire byte order:
54 // time_low (u32 LE), time_mid (u16 LE), time_hi_and_version (u16 LE),
55 // clock_seq_hi_reserved (u8), clock_seq_low (u8), node (6 bytes).
56 let uuid = [
57 0xF7, 0xAF, 0xBE, 0xF6, // f6beaff7 LE
58 0x19, 0x1E, // 1e19 LE
59 0xBB, 0x4F, // 4fbb LE
60 0x9F, 0x8F, // 9f 8f (clock_seq)
61 0xB8, 0x9E, 0x20, 0x18, 0x33, 0x7C, // node
62 ];
63 Syntax {
64 uuid,
65 ver_major: 1,
66 ver_minor: 0,
67 }
68}
69
70/// Only way anything in this crate fails.
71#[derive(Debug, thiserror::Error)]
72pub enum EvenError {
73 #[error("transport: {0}")]
74 Transport(String),
75 #[error("event log server returned Win32 status {0:#010x}")]
76 Server(u32),
77 #[error("ndr underrun at pos {pos}, need {need}")]
78 Underrun { need: usize, pos: usize },
79 #[error("binxml: {0}")]
80 BinXml(String),
81 #[error("unexpected token {tok:#04x} at pos {pos}")]
82 UnexpectedToken { tok: u8, pos: usize },
83 #[error("short input, need {need} at {pos}")]
84 Short { need: usize, pos: usize },
85 #[error("protocol: {0}")]
86 Protocol(String),
87}
88
89impl From<NdrError> for EvenError {
90 fn from(e: NdrError) -> Self {
91 match e {
92 NdrError::Underrun { need, pos } => EvenError::Underrun { need, pos },
93 }
94 }
95}
96
97pub type Result<T> = std::result::Result<T, EvenError>;
98
99/// A remote MS-EVEN6 CONTEXT_HANDLE (20 bytes: attributes u32 + 16-byte UUID).
100/// Returned by EvtRpcOpenLogHandle; passed back to Read/Clear/QueryChannel calls.
101#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
102pub struct ContextHandle(pub [u8; 20]);
103
104impl ContextHandle {
105 pub const NULL: ContextHandle = ContextHandle([0u8; 20]);
106 pub fn is_null(&self) -> bool {
107 self.0 == [0u8; 20]
108 }
109}
110
111/// The handle a caller keeps for pulling records after RegisterLogQuery.
112#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
113pub struct QueryHandle(pub [u8; 20]);
114
115impl QueryHandle {
116 pub const NULL: QueryHandle = QueryHandle([0u8; 20]);
117 pub fn is_null(&self) -> bool {
118 self.0 == [0u8; 20]
119 }
120}
121
122/// The high-level MS-EVEN6 client.
123///
124/// Owns a `Transport` (bound to the remote `\pipe\eventlog`, RPC bound to
125/// [`even6_syntax`]) and tracks the caller's open handles. Split across trait/impl so
126/// live-DC and test-mock transports plug into the same code path.
127pub struct EvenClient<T: Transport> {
128 pub transport: T,
129}
130
131impl<T: Transport> EvenClient<T> {
132 pub fn new(transport: T) -> Self {
133 Self { transport }
134 }
135
136 /// EvtRpcOpenLogHandle (opnum 0): open a channel by name (e.g. `"Security"`,
137 /// `"Application"`) for reading. Returns the CONTEXT_HANDLE the server will accept
138 /// on read/clear calls.
139 ///
140 /// Wire (MS-EVEN6 §3.1.4.19): `[in,string] wchar_t* Channel, [in] DWORD Flags,
141 /// [out] CONTEXT_HANDLE_LOG_HANDLE* Handle, [out] RpcInfo* Error`.
142 pub fn open_log_handle(&mut self, channel: &str, flags: u32) -> Result<ContextHandle> {
143 let stub = opnums::encode_open_log_handle(channel, flags);
144 let resp = self
145 .transport
146 .call(opnums::OPNUM_OPEN_LOG_HANDLE, &stub)
147 .map_err(EvenError::Transport)?;
148 opnums::decode_open_log_handle(&resp)
149 }
150
151 /// EvtRpcRegisterLogQuery (opnum 5): register an XPath / structured-XML query and
152 /// receive a query handle for pulling matching events.
153 pub fn register_log_query(&mut self, xpath: &str, flags: u32) -> Result<QueryHandle> {
154 let stub = opnums::encode_register_log_query(xpath, flags);
155 let resp = self
156 .transport
157 .call(opnums::OPNUM_REGISTER_LOG_QUERY, &stub)
158 .map_err(EvenError::Transport)?;
159 opnums::decode_register_log_query(&resp)
160 }
161
162 /// EvtRpcQueryNext (opnum 11): pull up to `n` events from a registered query,
163 /// blocking on the server for at most `timeout_ms`. Empty result means the query
164 /// has drained. Each BinXml fragment is decoded into an [`Event`].
165 pub fn query_next(&mut self, h: &QueryHandle, n: u32, timeout_ms: u32) -> Result<Vec<Event>> {
166 let stub = opnums::encode_query_next(h, n, timeout_ms);
167 let resp = self
168 .transport
169 .call(opnums::OPNUM_QUERY_NEXT, &stub)
170 .map_err(EvenError::Transport)?;
171 let frags = opnums::decode_query_next(&resp)?;
172 let mut out = Vec::with_capacity(frags.len());
173 for f in frags {
174 out.push(decode_binxml(&f)?);
175 }
176 Ok(out)
177 }
178
179 /// EvtRpcClose (opnum 13): release either a log handle or a query handle.
180 pub fn close(&mut self, handle: &[u8; 20]) -> Result<()> {
181 let stub = opnums::encode_close(handle);
182 let resp = self
183 .transport
184 .call(opnums::OPNUM_CLOSE, &stub)
185 .map_err(EvenError::Transport)?;
186 opnums::decode_close(&resp)
187 }
188}