diff --git a/.github/Invoke-VisualStudio.ps1 b/.github/Invoke-VisualStudio.ps1 index 13c9d8f..bfe7637 100644 --- a/.github/Invoke-VisualStudio.ps1 +++ b/.github/Invoke-VisualStudio.ps1 @@ -12,7 +12,7 @@ Function Invoke-CmdScript { } -Function Invoke-VisualStudio2019x86 { +Function Invoke-VisualStudio2019win32 { Invoke-CmdScript "C:/Program Files (x86)/Microsoft Visual Studio/2019/Enterprise/VC/Auxiliary/Build/vcvars32.bat" } @@ -25,7 +25,7 @@ Function Invoke-VisualStudio2019arm64 { Invoke-CmdScript "C:/Program Files (x86)/Microsoft Visual Studio/2019/Enterprise/VC/Auxiliary/Build/vcvarsamd64_arm64.bat" } -Function Invoke-VisualStudio2022x86 { +Function Invoke-VisualStudio2022win32 { Invoke-CmdScript "C:/Program Files/Microsoft Visual Studio/2022/Enterprise/VC/Auxiliary/Build/vcvars32.bat" } diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index e69de29..0000000 diff --git a/Docs/README.md b/Docs/README.md index a0fa945..830c601 100644 --- a/Docs/README.md +++ b/Docs/README.md @@ -12,43 +12,11 @@ ## Idea -Furious Beaver is a distributed tool for capturing IRPs sent to any Windows driver. It operates in 2 parts: +**Canadian Furious Beaver** is a distributed tool for capturing IRPs sent to any Windows driver. It operates in 2 parts: -1. the "Broker" combines both a user-land agent and a self-extractable driver (`IrpDumper.sys`) that will install itself on the targeted system. Once running it will expose (depending on the compilation options) a remote named pipe (reachable from `\\target.ip.address\pipe\cfb`), or a TCP port listening on TCP/1337. The communication protocol was made to be simple by design (i.e. not secure) allowing any [3rd party tool](https://github.com/hugsy/cfb-cli) to dump the driver IRPs from the same Broker easily (via simple JSON messages). - -2. the GUI is a Windows 10 UWP app made in a `ProcMon`-style: it will connect to wherever the broker is, and provide a convienent GUI for manipulating the broker (driver enumeration, hooking and IRP capturing). It also offers facililties for forging/replaying IRPs, auto-fuzzing (i.e. apply specific fuzzing policies on *each* IRP captured), or extract IRP in various formats (raw, as a Python script, as a PowerShell script) for further analysis. The captured data can be saved on disk in an easily parsable format (`*.cfb` = SQLite) for further analysis, and/or reload afterwards in the GUI. - -Although the GUI obviously requires a Windows 10 environment (UWP App), the Broker itself can be deployed on any Windows 7+ host (x86 or x64). The target host must have `testsigning` BCD policy enabled, as the self-extracting driver is not WHQL friendly. - - -## Screenshots - -### Intercepted IRP view - -![Intercepted IRP view](https://i.imgur.com/xMOIIhC.png) - -### IRP details - -![IRP Metadata](https://i.imgur.com/zmh2QAw.png) -![IRP InputBuffer](https://i.imgur.com/j0W9ljL.png) - - -### IRP replay - -![IRP Replay](https://i.imgur.com/9Ybq27G.png) - - -## Concept - -`IrpDumper.sys` is the driver part of the CFB Broker that will auto-extract and install when launched. The driver will be responsible for hooking the IRP Major Function table of -the driver that is requested to be hooked, via an IOCTL passed from the Broker. -Upon success, the IRP table of the driver will then be pointing to `IrpDumper.sys` interception routine, as we can easily see with a debugger or tools like [`WinObjEx64`](https://github.com/hfiref0x/WinObjEx64). - -![img](https://i.imgur.com/dYqHE6q.png) - -`IrpDumper.sys` in itself then acts a rootkit, proxy-ing all calls to the targeted driver(s). When a `DeviceIoControl` is sent to a hooked driver, `IrpDumper` will simply capture the data if any, and push a message to the user-land agent (`Broker`), and yield the execution back to the legitimate drivers, allowing the intended code to continue as expected. -The `Broker` stores all this data in user-land waiting for a event to ask for them. +1. the "Broker" combines both a user-land agent and a self-extractable driver (`IrpMonitor.sys`) that will install itself on the targeted system. After installing the driver, the broker will expose a TCP port listening (by default, on TCP/1337) and start collecting IRP from hooked drivers. The communication protocol was made to be simple by design (i.e. not secure) allowing any [3rd party tool](https://github.com/hugsy/cfb-cli) to dump the driver IRPs from the same Broker easily (via simple JSON messages). +2. the clients can connect to the broker, and will receive IRPs as a JSON message making it easy to view, or convert to another format. ## Why the name? diff --git a/Docs/_sidebar.md b/Docs/_sidebar.md index da8415b..e595c2c 100644 --- a/Docs/_sidebar.md +++ b/Docs/_sidebar.md @@ -1,8 +1,10 @@ * CFB * [Overview](/) + * [Concept](/concept.md) * [Setup](/setup.md) + * [Usage](/usage.md) * [Debugging](/debugging.md) * [Fuzzing](/fuzzing-vm-setup.md) * [Crash Analysis](/crash-analysis.md) + * [Gallery](/gallery.md) * [FAQ](/faq.md) - diff --git a/Docs/concept.md b/Docs/concept.md new file mode 100644 index 0000000..9ad51e8 --- /dev/null +++ b/Docs/concept.md @@ -0,0 +1,10 @@ +# Concept + +`IrpDumper.sys` is the driver part of the CFB Broker that will auto-extract and install when launched. The driver will be responsible for hooking the IRP Major Function table of +the driver that is requested to be hooked, via an IOCTL passed from the Broker. +Upon success, the IRP table of the driver will then be pointing to `IrpDumper.sys` interception routine, as we can easily see with a debugger or tools like [`WinObjEx64`](https://github.com/hfiref0x/WinObjEx64). + +![img](https://i.imgur.com/dYqHE6q.png) + +`IrpDumper.sys` in itself then acts a rootkit, proxy-ing all calls to the targeted driver(s). When a `DeviceIoControl` is sent to a hooked driver, `IrpDumper` will simply capture the data if any, and push a message to the user-land agent (`Broker`), and yield the execution back to the legitimate drivers, allowing the intended code to continue as expected. +The `Broker` stores all this data in user-land waiting for a event to ask for them. diff --git a/Docs/FAQ.md b/Docs/faq.md similarity index 100% rename from Docs/FAQ.md rename to Docs/faq.md diff --git a/Docs/gallery.md b/Docs/gallery.md new file mode 100644 index 0000000..005155d --- /dev/null +++ b/Docs/gallery.md @@ -0,0 +1,22 @@ +# Screenshots + +## Boker + +## ImGUI Client + +## UWP Client + +### Intercepted IRP view + +![Intercepted IRP view](https://i.imgur.com/xMOIIhC.png) + +### IRP details + +![IRP Metadata](https://i.imgur.com/zmh2QAw.png) + +![IRP InputBuffer](https://i.imgur.com/j0W9ljL.png) + +### IRP replay + +![IRP Replay](https://i.imgur.com/9Ybq27G.png) + diff --git a/Docs/setup.md b/Docs/setup.md index 998acf1..8c66fae 100644 --- a/Docs/setup.md +++ b/Docs/setup.md @@ -1,4 +1,4 @@ -# Setting up CFB +# Build CFB ## Pre-Build @@ -6,22 +6,31 @@ The easiest and fastest way to get started is simply to download the artifacts f ## Build -Building CFB requires only [`cmake`](), and the Windows [SDK]() and [WDK](). In a developer prompt: +Building CFB requires only [`cmake`](https://cmake.org), and the Windows [SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/) and [WDK](https://learn.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk). In a developer prompt: +### To compile ```powershell cd \path\to\CFB.git -mkdir build; cd build -cmake .. -DCFB_BUILD_TOOLS:BOOL=ON -cmake --build . --verbose --parallel $env:NUMBER_OF_PROCESSORS --config $config -cd .. +mkdir build +cmake -S . -B ./build -D CFB_BUILD_TOOLS:BOOL=ON -D CFB_BUILD_GUI:BOOL=ON -A $platform +cmake --build ./build --verbose --parallel $env:NUMBER_OF_PROCESSORS --config $config ``` -Where `$config` can be either `RelWithDebInfo` (normal use) or `Debug` for debugging. +Where `$platform` can be: + - `x64` + - `arm64` -To isolate only the useful binaries produced from the compilation stage into a single folder, the optional next step is to run `cmake install`. +`win32` may work to build the broker. However, ImGUI doesn't compile on 32-bit. + +### To install + +After building: ```powershell -mkdir bins; cd build -cmake --install . --config $config --prefix ../bins --verbose -cd .. +mkdir artifact +cmake --install ./build --config $config --prefix ./artifact --verbose ``` + +Where `$config` can be: + - `RelWithDebInfo` (you probably want this one) + - `Debug` for debugging (very verbose outputs) diff --git a/Docs/usage.md b/Docs/usage.md new file mode 100644 index 0000000..e955e08 --- /dev/null +++ b/Docs/usage.md @@ -0,0 +1,24 @@ +# Usage + +A Windows 7+ machine ([Windows 10 SDK VM](https://developer.microsoft.com/en-us/windows/downloads/virtual-machines) is recommended) + +On this target machine, simply enable BCD test signing flag (in `cmd.exe` as Admin): + +``` +bcdedit.exe /set {whatever-profile} testsigning on +``` + +If using in Debug mode, `IrpDumper.sys` will provide a lot more valuable information as to what's being hooked (the price of performance). All those info can be visible via tools like `DebugView.exe` or a kernel debugger like WinDbg. In either case, you must enable kernel debug BCD flag (in `cmd.exe` as Admin): + +``` +bcdedit.exe /set {whatever-profile} debug on +``` + +It is also recommended to edit the KD verbosity level, via: + - the registry for a permanent effect (`reg add "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Debug Print Filter" /v DEFAULT /t REG_DWORD /d 0xf`) + - directly from WinDbg for only the current session (`ed nt!Kd_Default_Mask 0xf`) + + +If you plan on (re-)compiling any of the tools, you must install VS (2019 preferred). If using the Release binaries, you only need VS C++ Redist installed(x86 or x64 depending on your VM architecture). + +Follow the indications in the `Docs/` folder to improve your setup. \ No newline at end of file diff --git a/README.md b/README.md index 8ef5dc0..ce21280 100644 --- a/README.md +++ b/README.md @@ -9,95 +9,13 @@ Discord

+## What is it? -## Idea +**Canadian Furious Beaver** is a distributed tool for capturing IRPs sent to any Windows driver. It operates in 2 parts: -Furious Beaver is a distributed tool for capturing IRPs sent to any Windows driver. It operates in 2 parts: +1. the "Broker" combines both a user-land agent and a self-extractable driver (`IrpMonitor.sys`) that will install itself on the targeted system. After installing the driver, the broker will expose a TCP port listening (by default, on TCP/1337) and start collecting IRP from hooked drivers. The communication protocol was made to be simple by design (i.e. not secure) allowing any [3rd party tool](https://github.com/hugsy/cfb-cli) to dump the driver IRPs from the same Broker easily (via simple JSON messages). -1. the "Broker" combines both a user-land agent and a self-extractable driver (`IrpDumper.sys`) that will install itself on the targeted system. Once running it will expose (depending on the compilation options) a remote named pipe (reachable from `\\target.ip.address\pipe\cfb`), or a TCP port listening on TCP/1337. The communication protocol was made to be simple by design (i.e. not secure) allowing any [3rd party tool](https://github.com/hugsy/cfb-cli) to dump the driver IRPs from the same Broker easily (via simple JSON messages). - -2. the GUI is a Windows 10 UWP app made in a `ProcMon`-style: it will connect to wherever the broker is, and provide a convienent GUI for manipulating the broker (driver enumeration, hooking and IRP capturing). It also offers facililties for forging/replaying IRPs, auto-fuzzing (i.e. apply specific fuzzing policies on *each* IRP captured), or extract IRP in various formats (raw, as a Python script, as a PowerShell script) for further analysis. The captured data can be saved on disk in an easily parsable format (`*.cfb` = SQLite) for further analysis, and/or reload afterwards in the GUI. - -Although the GUI obviously requires a Windows 10 environment (UWP App), the Broker itself can be deployed on any Windows 7+ host (x86 or x64). The target host must have `testsigning` BCD policy enabled, as the self-extracting driver is not WHQL friendly. - - -## Screenshots - -### Intercepted IRP view - -![Intercepted IRP view](https://i.imgur.com/xMOIIhC.png) - -### IRP details - -![IRP Metadata](https://i.imgur.com/zmh2QAw.png) -![IRP InputBuffer](https://i.imgur.com/j0W9ljL.png) - - -### IRP replay - -![IRP Replay](https://i.imgur.com/9Ybq27G.png) - - -## Concept - -`IrpDumper.sys` is the driver part of the CFB Broker that will auto-extract and install when launched. The driver will be responsible for hooking the IRP Major Function table of -the driver that is requested to be hooked, via an IOCTL passed from the Broker. -Upon success, the IRP table of the driver will then be pointing to `IrpDumper.sys` interception routine, as we can easily see with a debugger or tools like [`WinObjEx64`](https://github.com/hfiref0x/WinObjEx64). - -![img](https://i.imgur.com/dYqHE6q.png) - -`IrpDumper.sys` in itself then acts a rootkit, proxy-ing all calls to the targeted driver(s). When a `DeviceIoControl` is sent to a hooked driver, `IrpDumper` will simply capture the data if any, and push a message to the user-land agent (`Broker`), and yield the execution back to the legitimate drivers, allowing the intended code to continue as expected. -The `Broker` stores all this data in user-land waiting for a event to ask for them. - - -## Build - -### GUI - -Clone the repository, and build the `Broker` in the solution `CFB.sln` at the project root with Visual Studio (Debug - very verbose - or Release). Additionally, you can build the App GUI by building the `GUI (Universal Windows)` project. - - - -### Command line - -Clone the repository and in a VS prompt run - -``` -C:\cfb\> msbuild CFB.sln /p:Configuration=$Conf -``` - -Where `$Conf` can be set to `Release` to `Debug`. - - -## Setup - -A Windows 7+ machine ([Windows 10 SDK VM](https://developer.microsoft.com/en-us/windows/downloads/virtual-machines) is recommended) - -On this target machine, simply enable BCD test signing flag (in `cmd.exe` as Admin): - -``` -C:\> bcdedit.exe /set {whatever-profile} testsigning on -``` - -If using in Debug mode, `IrpDumper.sys` will provide a lot more valuable information as to what's being hooked (the price of performance). All those info can be visible via tools like `DebugView.exe` or a kernel debugger like WinDbg. In either case, you must enable kernel debug BCD flag (in `cmd.exe` as Admin): - -``` -C:\> bcdedit.exe /set {whatever-profile} debug on -``` - -It is also recommended to edit the KD verbosity level, via: - - the registry for a permanent effect (`reg add "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Debug Print Filter" /v DEFAULT /t REG_DWORD /d 0xf`) - - directly from WinDbg for only the current session (`ed nt!Kd_Default_Mask 0xf`) - - -If you plan on (re-)compiling any of the tools, you must install VS (2019 preferred). If using the Release binaries, you only need VS C++ Redist installed(x86 or x64 depending on your VM architecture). - -Follow the indications in the `Docs/` folder to improve your setup. - - -## Command-line client - -Several command line tools (such as dumping all data to SQLite database, fuzzing IRP, etc.) can be found in the external repository [CFB-cli](https://github.com/hugsy/CFB-cli). +2. the clients can connect to the broker, and will receive IRPs as a JSON message making it easy to view, or convert to another format. ## Why the name?