windows_wfp/
lib.rs

1//! # windows-wfp — Windows Filtering Platform (WFP) Wrapper
2//!
3//! Safe Rust wrapper around Windows Filtering Platform APIs.
4//!
5//! This crate provides a high-level, memory-safe interface to the Windows Filtering Platform (WFP),
6//! the kernel-level firewall API in Windows. It handles all the complex FFI interactions, memory
7//! management, and path conversions required for WFP to work correctly.
8//!
9//! ## Features
10//!
11//! - **WFP Engine Management** - RAII-based session lifecycle with automatic cleanup
12//! - **Provider & Sublayer** - Registration of custom firewall provider with high priority
13//! - **Filter Creation** - Builder-pattern filter rules with automatic DOS-to-NT path conversion
14//! - **Event Subscription** - Real-time monitoring of network events (learning mode)
15//! - **Memory Safety** - All Windows handles managed with RAII, minimal unsafe code
16//!
17//! ## Quick Start
18//!
19//! ```no_run
20//! use windows_wfp::{WfpEngine, FilterBuilder, FilterRule, Direction, Action, FilterWeight, initialize_wfp};
21//!
22//! // Open WFP engine (requires Administrator)
23//! let engine = WfpEngine::new()?;
24//!
25//! // Register provider and sublayer
26//! initialize_wfp(&engine)?;
27//!
28//! // Block an application
29//! let rule = FilterRule::new("Block curl", Direction::Outbound, Action::Block)
30//!     .with_weight(FilterWeight::UserBlock)
31//!     .with_app_path(r"C:\Windows\System32\curl.exe");
32//!
33//! let filter_id = FilterBuilder::add_filter(&engine, &rule)?;
34//!
35//! // curl.exe is now blocked at kernel level!
36//!
37//! // Clean up
38//! FilterBuilder::delete_filter(&engine, filter_id)?;
39//! # Ok::<(), windows_wfp::WfpError>(())
40//! ```
41//!
42//! ## Path Conversion
43//!
44//! **CRITICAL**: WFP operates at the Windows kernel level and requires NT kernel paths.
45//! This crate automatically converts DOS paths to NT kernel format:
46//!
47//! - **DOS path**: `C:\Windows\System32\curl.exe` (what you provide)
48//! - **NT kernel path**: `\device\harddiskvolume4\windows\system32\curl.exe` (what WFP needs)
49//!
50//! Without this conversion, filters would be added successfully but would **never match**
51//! any traffic. This crate handles the conversion automatically using `FwpmGetAppIdFromFileName0`.
52//!
53//! ## Event Monitoring
54//!
55//! Subscribe to network events for learning mode:
56//!
57//! ```no_run
58//! use windows_wfp::{WfpEngine, WfpEventSubscription};
59//!
60//! let engine = WfpEngine::new()?;
61//! let subscription = WfpEventSubscription::new(&engine)?;
62//!
63//! loop {
64//!     match subscription.try_recv() {
65//!         Ok(event) => {
66//!             println!("Event: {:?}", event.event_type);
67//!             println!("App: {:?}", event.app_path);
68//!         }
69//!         Err(std::sync::mpsc::TryRecvError::Empty) => {
70//!             std::thread::sleep(std::time::Duration::from_millis(100));
71//!         }
72//!         Err(_) => break,
73//!     }
74//! }
75//! # Ok::<(), windows_wfp::WfpError>(())
76//! ```
77
78pub mod condition;
79pub mod constants;
80pub mod engine;
81pub mod errors;
82pub mod events;
83pub mod filter;
84pub mod filter_builder;
85pub mod layer;
86pub mod provider;
87pub mod transaction;
88
89// Re-exports
90pub use condition::{IpAddrMask, Protocol};
91pub use constants::*;
92pub use engine::WfpEngine;
93pub use errors::{WfpError, WfpResult};
94pub use events::{NetworkEvent, NetworkEventType, WfpEventSubscription};
95pub use filter::{Action, Direction, FilterRule};
96pub use filter_builder::FilterBuilder;
97pub use layer::FilterWeight;
98pub use provider::{initialize_wfp, WfpProvider, WfpSublayer};
99pub use transaction::WfpTransaction;
windows_wfp/lib.rs

windows_wfp/
lib.rs
