1. [Visual Studio 2019 version 16.11.7 or later](https://www.techspot.com/downloads/downloadnow/7241/?evp=70f51271955e6392571f575e301cd9a3&file=9642),
including the "Desktop development with C++" workload, and the "*MSVC v142 - VS 2019 C++ x64/x86 Spectre-mitigated libs (latest)*", which must be selected
from the "*Individual components*" tab of the *Visual Studio Installer*.
1. [Visual Studio Build Tools 2019](https://aka.ms/vs/16/release/vs_buildtools.exe)
1. [Windows SDK for Windows 11 (version 10.0.22000.x)](https://go.microsoft.com/fwlink/?linkid=2173743)
1. [Windows WDK for Windows 11 21H2 (version 10.0.22000.x)](https://go.microsoft.com/fwlink/?linkid=2166289), including the
"*Windows Driver Kit Visual Studio extension*" (make sure the check box is checked before completing the installer).
1. [Clang for Windows 64-bit version 11.0.1](https://github.com/llvm/llvm-project/releases/download/llvmorg-11.0.1/LLVM-11.0.1-win64.exe).
Note: clang versions 12 and higher are NOT yet supported, as they perform program optimizations that are incompatible with the PREVAIL verifier.
1. [NuGet Package Installer (nuget.exe - recommended latest version)](https://www.nuget.org/downloads) installed to a location such as `C:\Program Files (x86)\NuGet\`.
You should add the paths to `git.exe`, `cmake.exe` and `nuget.exe` to the Windows PATH environment variable after the software packages above have been installed.
#### Exclusion of PE parse directory from Windows Defender Antivirus
PE parse directory includes some malformed PE images as a part of the test suite for PE image parser and Windows Defender flags these files as viruses. Please note that similar exclusions have to be done for other Antivirus products as needed. The following steps are needed to exempt PE directory from Windows Defender Antivirus:
1. Select *Start*, then open *Settings*. Under *Privacy & Security*, select *Virus & threat protection*.
2. Under *Virus & threat protection* settings, select *Manage settings*, and then under *Exclusions*, select *Add or remove exclusions*.
3. Select *Add an exclusion*, and then select from files, folders, file types, or processes. Choose the following directory ```ebpf-for-windows/external/pe-parse``` to exclude the folder and subfolders to get flagged by the antivirus.
The following steps need to be executed _once_ before the first build on a new clone.
1. Launch `Developer Command Prompt for VS 2019` by running `"C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\Common7\Tools\VsDevCmd.bat"`.
2. Change directory to where the project is cloned, e.g. ```cd ebpf-for-windows```.
1. Driver is signed using a certificate that chains up to the Microsoft code signing root (aka a production signed driver).
2. The OS is booted with a kernel debugger attached.
3. The OS is running in [test-signing mode](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/the-testsigning-boot-configuration-option), the [driver is test signed](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/test-signing-a-driver-through-an-embedded-signature) and the [test certificate is installed](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/installing-test-certificates).
This section shows how to use eBPF for Windows in a demo that lets us control a UDP port leak by attaching an eBPF program to the socket `bind()` call via the `EBPF_ATTACH_TYPE_BIND` hook.
1. Build the ``port_leak`` and ``port_quota`` applications from under the tools project.
2. Copy both the exe's to a machine that has eBPF installed. See
[Installing eBPF for Windows](#installing-ebpf-for-windows)
#### Demo
1. At a command prompt running as Administrator, run ``port_quota.exe load`` to load the port quota eBPF program attached to the bind hook.
2. Set a limit to a threshold number of ports you want to permit an application to bind to by doing ``port_quota.exe limit 5000``
3. Run ``port_leak.exe`` in another command prompt. This will just leak UDP ports. Observe the output that bind starts to fail after this app binds 5000 ports.
4. Running ```port_quota.exe stats``` will dump how many ports are taken up by an application. Under the covers, the eBPF program communicates this information up to the user mode application via an eBPF map.
This uses `bpf_xdp_adjust_head` helper function to encapsulate an outer IP header to a packet.
1. On the first host:
1. [Install eBPF for Windows](https://github.com/microsoft/ebpf-for-windows/blob/main/docs/InstallEbpf.md).
2. Load the test eBPF program by running the following command: `netsh ebpf add program encap_reflect_packet.o xdp` and note the ID. See **Note 3** below.
2. On the second host:
1. Allow inbound traffic for `xdp_tests.exe` through Windows Defender Firewall. See **Note 1** below.
This uses `bpf_xdp_adjust_head` helper function to decapsulate an outer IP header from a packet.
1. On *both* the hosts, [install eBPF for Windows](https://github.com/microsoft/ebpf-for-windows/blob/main/docs/InstallEbpf.md).
2. On the first host load the first test eBPF program by running the following command: `netsh ebpf add program encap_reflect_packet.o xdp` and note the ID. See **Note 3** below.
3. On the second host:
1. Load the second test eBPF program by running the following command: `netsh ebpf add program decap_permit_packet.o xdp` and note the ID. See **Note 3** below.
2. Allow inbound traffic for `xdp_tests.exe` through Windows Defender Firewall. See **Note 1** below.
**Note 1:** To allow inbound traffic to `xdp_tests.exe`, in a Windows Powershell with administrative privilege, run `New-NetFirewallRule -DisplayName "XDP_Test" -Program "<Full path to xdp_tests.exe>" -Direction Inbound -Action Allow`.<br>
**Note 2:** For the `--remote-ip` parameter to `xdp_tests.exe` program that is run on the second host, pass an IPv4 or IPv6 address of an Ethernet-like interface on the first host in string format.<br>
**Note 3:** After completion of each test variation, unload the eBPF programs from both host machines by running `delete program <id>` on the netsh prompt, where `<id>` is the ID noted when the eBPF programs were loaded.<br>
***Advanced:*** The eBPF program can be attached to a specific interface by passing `interface=<IfIndex>` parameter either to the netsh `add program` or `set program` commands.
This application loads the `cgroup_sock_addr.o` eBPF program and attaches to hooks to handle various socket operations. Currently it tests authorizing ingress and egress connections based on entries in a map passed to the program.
1) Start tracing: ```wpr.exe -start "%ProgramFiles%\ebpf-for-windows\ebpfforwindows.wprp" -filemode```. This will capture traces from eBPF execution context and the network eBPF extension drivers. (The path `%ProgramFiles%\ebpf-for-windows` assumes you installed eBPF for Windows via the MSI file. If you installed it via some other method, [ebpfforwindows.wprp](../scripts/ebpfforwindows.wprp) may be in some other location.)
2) View the session in real-time on stdout: ```tracefmt -rt MyTrace -displayonly -jsonMeta 0```. This will
continue until you break out of the executable with Ctrl-C.
3) Close the trace session: ```tracelog -stop MyTrace```
Often when tracing eBPF programs, it is useful to only view output generated by the [bpf_printk](https://microsoft.github.io/ebpf-for-windows/bpf__helper__defs_8h.html#aae337e68db96b4b9470f8c519386cbec) helper.
To do so, use `ebpf-printk.guid` instead of `ebpf-all.guid` when creating a trace session. That is:
where `[3]` is the CPU ID, `1760` is the Process ID in hex, and `1910` is the Thread ID in hex.
If you want the prefix to look closer to Linux output, set the following [environment variable](https://docs.microsoft.com/en-us/windows-hardware/drivers/devtest/trace-message-prefix):
If you are using WinDbg to work on the EbpfCore or the NetEbpfExt drivers, you may find the WinDbg command ```.kdfiles``` to be useful. This
command allows the replacement of a driver binary on the target machine with another binary from the machine WinDbg is running
on (typically the development machine) at driver load time.
This eliminates the need for repeated manual copy of the modified driver binary and saves considerable time during the
development cycle. See the [Windows Hardware Developer documentation](https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/-kdfiles--set-driver-replacement-map-) for more details.