How aldaviva/fail2ban4win works
1. What this system is
Fail2Ban4Win is a .NET Framework Windows Service that sits in the background, watches Windows Event Log for authentication failures, and translates repeated failures into Windows Firewall inbound block rules. It is a local host security daemon, not a client/server app.
2. Top-level repository shape
The repo is split into three main production areas:
- Fail2Ban4Win: the service host and core logic
- Abstractions: shared contracts and parameter/data types used by the host and plugins
- SamplePlugin: example extension DLL
The Tests project mirrors the main subsystems, especially config parsing, event listening, and ban management.
3. Runtime entry and hosting
Execution begins in Fail2Ban4Win/Entry. MainClass and WindowsService provide both service-mode startup and foreground console execution for debugging. This is a classic Windows Service boundary: the process lifecycle is managed by SCM, but can also run interactively for diagnostics.
4. Configuration boundary
configuration.json is the primary runtime input. The Config subsystem deserializes it, including custom handling for regex and IP network types. This config controls:
- failure thresholds and time windows
- ban duration and repeat-offense scaling
- subnet aggregation size
- whitelist/never-ban ranges
- whether to clear bans on startup
- the set of event log selectors to monitor
5. Event ingestion
Services/EventLogListener is the event-facing subsystem. It listens to selected Windows Event Logs through Facades/EventLogWatcherFacade, which abstracts the Windows event subscription API. Its job is to react to matching event IDs/logs/sources and forward candidate events into the ban pipeline.
6. Event-to-IP extraction
Each configured selector defines how to find the client IP in the event payload:
- by event log name, event ID, and optional source
- by choosing a specific EventData field by name or index
- by optional regex filtering and capture of a named ipAddress group
This is the repository’s key parsing boundary: it turns heterogeneous Windows event formats into a normalized IP address.
7. Failure aggregation model
The Data layer tracks failures over time per subnet rather than per individual IP. SubnetFailureHistory and ArrayListSubnetFailureHistory store rolling failure timestamps so the service can decide whether a subnet has crossed the configured threshold within the configured window. The default behavior aggregates to a subnet prefix and counts cumulative failures across all matching selectors.
8. Ban decision and lifecycle
Services/BanManager is the core policy engine. It consumes failure observations, checks whitelist/reserved-subnet rules, applies repeated-offense scaling, and decides when to ban or unban. It also supports the startup behavior where previously created rules can be deleted to “fail open” unless configured otherwise.
9. Firewall side effect boundary
Facades/FirewallFacade isolates direct interaction with the Windows Firewall COM/API layer. This keeps firewall rule creation/deletion out of the policy engine. The visible artifact of a ban is a firewall rule group named for Fail2Ban4Win, with descriptions that include ban timing and offense count.
10. Extension/plugin model
The Abstractions/Plugins/IFail2Ban4WinPlugin contract defines the plugin boundary. Plugins are DLLs loaded from the installation’s plugins directory and can react to auth failures, bans, and unbans. The sample plugin demonstrates that the host exposes extension points without tying core ban logic to notifications or other custom behavior.
11. Dependency injection and modular composition
The Injection folder wires the application together in modules:
- configuration module
- facade modules
- service modules
This makes the service assembly a composition root that connects config, event watching, firewall access, and ban logic at startup.
12. Logging and observability
Logging is handled by NLog through Logging/NLog.config. Runtime logs go to a local file by default, and the code includes a custom formatter for cleaner output. Operationally, the service is monitored through Windows Service tools, log files, and the resulting firewall rules.
13. Packaging/build shape
The repo includes ILRepack.targets, indicating the release can be packaged as a single merged EXE or as an unpacked DLL-based distribution. That affects deployment architecture, not runtime behavior. The CI workflow is .NET Framework-oriented and runs the test suite on GitHub Actions.
14. Most important data flow to diagram
The central flow is:
configuration.json → event log subscription → event filter/regex/IP extraction → subnet failure history → ban decision → firewall rule create/delete
Plugins branch off from the core pipeline as optional notification/action handlers, while logging observes every stage.
Main entry points: BanManager.cs Ban Manager · ConfigurationModule.cs Composition Root · EventLogListener.cs Event Listener · Configuration.cs Config
Components 17
Production
Main runtime and core service subsystems
- Service Host · SCM/console startup and process lifecycle
Fail2Ban4Win/Entry/MainClass.cs - Config · Deserializes configuration.json and custom types
Fail2Ban4Win/Config/Configuration.cs - Event Listener · Watches selected Windows Event Logs and raises candidates
Fail2Ban4Win/Services/EventLogListener.cs - Event Facade · Wraps Windows event subscription/watch APIs
Fail2Ban4Win/Facades/EventLogWatcherFacade.cs - IP Extractor · Selects event fields and extracts client IPs from payloads
Fail2Ban4Win/Services/EventLogListener.cs - Failure History · Tracks rolling failures per subnet over time
Fail2Ban4Win/Data/SubnetFailureHistory.cs - Ban Manager · Applies thresholds, whitelists, scaling, and ban lifecycle
Fail2Ban4Win/Services/BanManager.cs - Firewall Facade · Creates and deletes Windows Firewall rules
Fail2Ban4Win/Facades/FirewallFacade.cs - Composition Root · Wires config, facades, and services together
Fail2Ban4Win/Injection/ConfigurationModule.cs - Logging · Runtime logging configuration and formatting
Fail2Ban4Win/Logging/NLog.config
Extensions
Plugin boundary and sample extension
- Plugin Contract · Defines callbacks for auth failures, bans, and unbans
Abstractions/Plugins/IFail2Ban4WinPlugin.cs - Sample Plugin · Demonstrates the plugin extension point
SamplePlugin/MyPlugin.cs - Shared Data · Ban and failure parameter types shared across projects
Abstractions/Data/BanParams.cs
Tests
Test coverage for core subsystems
- Config Tests · Covers config and custom deserializers
Tests/Config/ConfigurationTest.cs - Service Tests · Covers ban management and event listening
Tests/Services/BanManagerTest.cs - Entry Tests · Covers startup and host behavior
Tests/Entry/MainClassTest.cs
Delivery
Build and packaging pipeline
- CI Workflow · Builds and runs the .NET Framework test suite
.github/workflows/dotnetframework.yml
Connections 24
- Service Host → Composition Root: boots · Startup composes the service graph
- Composition Root → Config: loads · Configuration module binds runtime settings
- Composition Root → Event Facade: wires · Registers event subscription facade
- Composition Root → Firewall Facade: wires · Registers firewall access facade
- Composition Root → Event Listener: creates · Service module builds event ingestion pipeline
- Composition Root → Ban Manager: creates · Service module builds ban policy engine
- Ban Manager → Failure History: tracks · Records and queries subnet failure history
- Config → Event Listener: selects · Defines monitored logs, event IDs, and sources
- Event Listener → Event Facade: subscribes · Uses watcher facade to receive Windows events
- Event Listener → IP Extractor: parses · Normalizes event payloads into client IPs
- IP Extractor → Failure History: reports · Turns matched failures into subnet observations
- Failure History → Ban Manager: signals · Threshold crossings drive ban decisions
- Ban Manager → Firewall Facade: bans · Creates and removes firewall rules
- Ban Manager → Plugin Contract: notifies · Plugin callbacks receive failures and ban events
- Sample Plugin → Plugin Contract: implements · Example extension satisfies the contract
- Shared Data → Ban Manager: feeds · Shared ban/failure parameters shape policy inputs
- Config → Logging: configures · Runtime settings influence logging output
- Entry Tests → Service Host: covers · Verifies host startup behavior
- Config Tests → Config: covers · Verifies config loading and custom deserialization
- Service Tests → Ban Manager: covers · Verifies ban policy and lifecycle
- Service Tests → Event Listener: covers · Verifies event ingestion behavior
- CI Workflow → Config Tests: runs · Workflow executes test projects
- CI Workflow → Service Tests: runs · Workflow executes test projects
- CI Workflow → Entry Tests: runs · Workflow executes test projects