Skip to main content

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}