fsfilter_rs/lib.rs
1//! # minifilter-rs
2//!
3//! Checkout the [README](https://github.com/SubconsciousCompute/fsfilter-rs/blob/master/README.md) too at github.
4//!
5//! **Use `cargo doc --no-deps --document-private-items --open` to read Documentation**
6//!
7//! ## Table of Contents
8//!
9//! <details>
10//! <summary>Table of Contents</summary>
11//!
12//! - [Minifilter Driver](https://!github.com/SubconsciousCompute/fsfilter-rs#minifilter-driver)
13//! - [Building Driver](https://!github.com/SubconsciousCompute/fsfilter-rs#building-driver)
14//! - [Installing Driver](https://!github.com/SubconsciousCompute/fsfilter-rs#building-driver)
15//! - [Loading/Removing Driver](https://!github.com/SubconsciousCompute/fsfilter-rs#loadingremoving-driver)
16//! - [Rust Application](https://!github.com/SubconsciousCompute/fsfilter-rs#rust-application)
17//! - [Building Rust App](https://!github.com/SubconsciousCompute/fsfilter-rs#building-rust-app)
18//! - [Running Rust App](https://!github.com/SubconsciousCompute/fsfilter-rs#running-rust-app)
19//! - [What and the How](https://!github.com/SubconsciousCompute/fsfilter-rs#what-and-the-how)
20//!
21//! </details>
22//!
23//! ## Minifilter Driver
24//!
25//! ### Building Driver
26//!
27//! 1. Open `VS 2022`
28//! 2. Goto `minifilter-rs -> minifilter -> RWatch.sln`
29//! 3. Build solution in `Release` mode with `x64`
30//!
31//! **NOTE: Enable Loading of Test Signed Drivers by executing `Bcdedit.exe -set TESTSIGNING ON` in administrative cmd**
32//!
33//! ### Installing Driver
34//!
35//! 1. Open Powershell or command prompt as Administrator
36//! 2. `RUNDLL32.EXE SETUPAPI.DLL,InstallHinfSection DefaultInstall 132 <path-to>\minifilter-rs\minifilter\x64\Debug\snFilter.inf`
37//!
38//! You should be able to see the driver at `"C:\Windows\System32\drivers\snFilter.sys"`
39//!
40//! ### Loading/Removing Driver
41//!
42//! 1. Open Powershell or command prompt as Administrator
43//! 2. Start the driver using `sc start snFilter`, expected output:
44//! ```ignore
45//! SERVICE_NAME: snFilter
46//! TYPE : 2 FILE_SYSTEM_DRIVER
47//! STATE : 4 RUNNING
48//! (STOPPABLE, NOT_PAUSABLE, IGNORES_SHUTDOWN)
49//! WIN32_EXIT_CODE : 0 (0x0)
50//! SERVICE_EXIT_CODE : 0 (0x0)
51//! CHECKPOINT : 0x0
52//! WAIT_HINT : 0x0
53//! PID : 0
54//! FLAGS :
55//! ```
56//! 3. Stop the driver using `sc stop snFilter`, should give the following output:
57//! ```ignore
58//! SERVICE_NAME: snFilter
59//! TYPE : 2 FILE_SYSTEM_DRIVER
60//! STATE : 1 STOPPED
61//! WIN32_EXIT_CODE : 0 (0x0)
62//! SERVICE_EXIT_CODE : 0 (0x0)
63//! CHECKPOINT : 0x0
64//! WAIT_HINT : 0x0
65//! ```
66//! 4. Remove it by `sc delete snFilter`, should give the following output:
67//! ```ignore
68//! [SC] DeleteService SUCCESS
69//! ```
70//!
71//! You can also run `Fltmc.exe` to see the currently loaded drivers:
72//!
73//! ```ignore
74//! Filter Name Num Instances Altitude Frame
75//! ------------------------------ ------------- ------------ -----
76//! bindflt 1 409800 0
77//! snFilter 4 378781 0 //our minifilter driver
78//! WdFilter 5 328010 0
79//! storqosflt 0 244000 0
80//! wcifs 0 189900 0
81//! CldFlt 0 180451 0
82//! FileCrypt 0 141100 0
83//! luafv 1 135000 0
84//! npsvctrig 1 46000 0
85//! Wof 3 40700 0
86//! FileInfo 5 40500 0
87//! ```
88//!
89//! ## Rust Application
90//!
91//! ### Building Rust App
92//!
93//! Simply use `cargo build --release` to build the application
94//!
95//! ### Running Rust App
96//!
97//! Use `cargo run --bin minifilter --release` to run the application
98//!
99//! The program starts to print the `IOMessage` which is defined like:
100//!
101//! ```ignore
102//! #[repr(C)]
103//! pub struct IOMessage {
104//! pub extension: [wchar_t; 12],
105//! pub file_id_vsn: c_ulonglong,
106//! pub file_id_id: [u8; 16],
107//! pub mem_sized_used: c_ulonglong,
108//! pub entropy: f64,
109//! pub pid: c_ulong,
110//! pub irp_op: c_uchar,
111//! pub is_entropy_calc: u8,
112//! pub file_change: c_uchar,
113//! pub file_location_info: c_uchar,
114//! pub filepathstr: String,
115//! pub gid: c_ulonglong,
116//! pub runtime_features: RuntimeFeatures,
117//! pub file_size: i64,
118//! }
119//! ```
120//!
121//! We end the process using `ctrl + c` in the example video:
122//! 
123//!
124//! #### NOTE:
125//!
126//! - Might fail if not ran with administrative privileges
127//! - You need to [load and start the driver]((https://!github.com/SubconsciousCompute/fsfilter-rs#loadingremoving-driver)) before running
128//! the program or else it will error out
129//!
130//! ## What and the How
131//!
132//! We basically share definition between the mini-filter and Rust using `#[repr(C)]`
133//!
134//! 
135//!
136//! We use [channels](https://!doc.rust-lang.org/std/sync/mpsc/fn.channel.html) to process
137//! all [IRPs](https://!docs.microsoft.com/en-us/windows-hardware/drivers/ifs/irps-are-different-from-fast-i-o).
138
139pub mod driver_comm;
140pub mod shared_def;