# aldaviva/fail2ban4win architecture

> Architecture diagram of the GitHub repository aldaviva/fail2ban4win, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aldaviva/fail2ban4win
- Repository: https://github.com/aldaviva/fail2ban4win

## Overview

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: [`Fail2Ban4Win/Services/BanManager.cs`](https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Services/BanManager.cs) (Ban Manager), [`Fail2Ban4Win/Injection/ConfigurationModule.cs`](https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Injection/ConfigurationModule.cs) (Composition Root), [`Fail2Ban4Win/Services/EventLogListener.cs`](https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Services/EventLogListener.cs) (Event Listener), [`Fail2Ban4Win/Config/Configuration.cs`](https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Config/Configuration.cs) (Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_production["Production"]
  node_entry["Service Host<br/>windows service entry<br/>[MainClass.cs]"]
  node_config["Config<br/>[Configuration.cs]"]
  node_event_listener(("Event Listener<br/>event ingestion"))
  node_event_facade["Event Facade<br/>event API facade"]
  node_extractor["IP Extractor<br/>event parsing"]
  node_history[("Failure History<br/>subnet aggregation")]
  node_ban_manager{{"Ban Manager<br/>policy engine<br/>[BanManager.cs]"}}
  node_firewall_facade["Firewall Facade<br/>firewall API facade<br/>[FirewallFacade.cs]"]
  node_di["Composition Root<br/>dependency injection"]
  node_logging["Logging<br/>nlog setup<br/>[NLog.config]"]
end

subgraph group_extensions["Extensions"]
  node_plugin_contract["Plugin Contract<br/>extension interface"]
  node_sample_plugin["Sample Plugin<br/>example dll<br/>[MyPlugin.cs]"]
  node_abstractions_data["Shared Data<br/>contracts<br/>[BanParams.cs]"]
end

subgraph group_tests["Tests"]
  node_config_tests["Config Tests<br/>test suite"]
  node_service_tests["Service Tests<br/>test suite<br/>[BanManagerTest.cs]"]
  node_entry_tests["Entry Tests<br/>test suite<br/>[MainClassTest.cs]"]
end

subgraph group_delivery["Delivery"]
  node_ci["CI Workflow<br/>github actions"]
end

node_entry -->|"boots"| node_di
node_di -->|"loads"| node_config
node_di -->|"wires"| node_event_facade
node_di -->|"wires"| node_firewall_facade
node_di -->|"creates"| node_event_listener
node_di -->|"creates"| node_ban_manager
node_ban_manager -->|"tracks"| node_history
node_config -->|"selects"| node_event_listener
node_event_listener -->|"subscribes"| node_event_facade
node_event_listener -->|"parses"| node_extractor
node_extractor -->|"reports"| node_history
node_history -->|"signals"| node_ban_manager
node_ban_manager -->|"bans"| node_firewall_facade
node_ban_manager -->|"notifies"| node_plugin_contract
node_sample_plugin -->|"implements"| node_plugin_contract
node_abstractions_data -->|"feeds"| node_ban_manager
node_config -.->|"configures"| node_logging
node_entry_tests -.->|"covers"| node_entry
node_config_tests -.->|"covers"| node_config
node_service_tests -.->|"covers"| node_ban_manager
node_service_tests -.->|"covers"| node_event_listener
node_ci -->|"runs"| node_config_tests
node_ci -->|"runs"| node_service_tests
node_ci -->|"runs"| node_entry_tests

click node_entry "https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Entry/MainClass.cs"
click node_config "https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Config/Configuration.cs"
click node_event_listener "https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Services/EventLogListener.cs"
click node_event_facade "https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Facades/EventLogWatcherFacade.cs"
click node_extractor "https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Services/EventLogListener.cs"
click node_history "https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Data/SubnetFailureHistory.cs"
click node_ban_manager "https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Services/BanManager.cs"
click node_firewall_facade "https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Facades/FirewallFacade.cs"
click node_di "https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Injection/ConfigurationModule.cs"
click node_logging "https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Logging/NLog.config"
click node_plugin_contract "https://github.com/aldaviva/fail2ban4win/blob/master/Abstractions/Plugins/IFail2Ban4WinPlugin.cs"
click node_sample_plugin "https://github.com/aldaviva/fail2ban4win/blob/master/SamplePlugin/MyPlugin.cs"
click node_abstractions_data "https://github.com/aldaviva/fail2ban4win/blob/master/Abstractions/Data/BanParams.cs"
click node_config_tests "https://github.com/aldaviva/fail2ban4win/blob/master/Tests/Config/ConfigurationTest.cs"
click node_service_tests "https://github.com/aldaviva/fail2ban4win/blob/master/Tests/Services/BanManagerTest.cs"
click node_entry_tests "https://github.com/aldaviva/fail2ban4win/blob/master/Tests/Entry/MainClassTest.cs"
click node_ci "https://github.com/aldaviva/fail2ban4win/blob/master/.github/workflows/dotnetframework.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_config,node_event_listener,node_event_facade,node_extractor,node_history,node_ban_manager,node_firewall_facade,node_di,node_logging toneBlue
class node_plugin_contract,node_sample_plugin,node_abstractions_data toneAmber
class node_config_tests,node_service_tests,node_entry_tests toneMint
class node_ci toneRose
```

## Components

### Production

Main runtime and core service subsystems

- [Service Host](https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Entry/MainClass.cs): windows service entry · SCM/console startup and process lifecycle · `Fail2Ban4Win/Entry/MainClass.cs`
- [Config](https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Config/Configuration.cs): runtime config · Deserializes configuration.json and custom types · `Fail2Ban4Win/Config/Configuration.cs`
- [Event Listener](https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Services/EventLogListener.cs): event ingestion · Watches selected Windows Event Logs and raises candidates · `Fail2Ban4Win/Services/EventLogListener.cs`
- [Event Facade](https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Facades/EventLogWatcherFacade.cs): event API facade · Wraps Windows event subscription/watch APIs · `Fail2Ban4Win/Facades/EventLogWatcherFacade.cs`
- [IP Extractor](https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Services/EventLogListener.cs): event parsing · Selects event fields and extracts client IPs from payloads · `Fail2Ban4Win/Services/EventLogListener.cs`
- [Failure History](https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Data/SubnetFailureHistory.cs): subnet aggregation · Tracks rolling failures per subnet over time · `Fail2Ban4Win/Data/SubnetFailureHistory.cs`
- [Ban Manager](https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Services/BanManager.cs): policy engine · Applies thresholds, whitelists, scaling, and ban lifecycle · `Fail2Ban4Win/Services/BanManager.cs`
- [Firewall Facade](https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Facades/FirewallFacade.cs): firewall API facade · Creates and deletes Windows Firewall rules · `Fail2Ban4Win/Facades/FirewallFacade.cs`
- [Composition Root](https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Injection/ConfigurationModule.cs): dependency injection · Wires config, facades, and services together · `Fail2Ban4Win/Injection/ConfigurationModule.cs`
- [Logging](https://github.com/aldaviva/fail2ban4win/blob/master/Fail2Ban4Win/Logging/NLog.config): nlog setup · Runtime logging configuration and formatting · `Fail2Ban4Win/Logging/NLog.config`

### Extensions

Plugin boundary and sample extension

- [Plugin Contract](https://github.com/aldaviva/fail2ban4win/blob/master/Abstractions/Plugins/IFail2Ban4WinPlugin.cs): extension interface · Defines callbacks for auth failures, bans, and unbans · `Abstractions/Plugins/IFail2Ban4WinPlugin.cs`
- [Sample Plugin](https://github.com/aldaviva/fail2ban4win/blob/master/SamplePlugin/MyPlugin.cs): example dll · Demonstrates the plugin extension point · `SamplePlugin/MyPlugin.cs`
- [Shared Data](https://github.com/aldaviva/fail2ban4win/blob/master/Abstractions/Data/BanParams.cs): contracts · Ban and failure parameter types shared across projects · `Abstractions/Data/BanParams.cs`

### Tests

Test coverage for core subsystems

- [Config Tests](https://github.com/aldaviva/fail2ban4win/blob/master/Tests/Config/ConfigurationTest.cs): test suite · Covers config and custom deserializers · `Tests/Config/ConfigurationTest.cs`
- [Service Tests](https://github.com/aldaviva/fail2ban4win/blob/master/Tests/Services/BanManagerTest.cs): test suite · Covers ban management and event listening · `Tests/Services/BanManagerTest.cs`
- [Entry Tests](https://github.com/aldaviva/fail2ban4win/blob/master/Tests/Entry/MainClassTest.cs): test suite · Covers startup and host behavior · `Tests/Entry/MainClassTest.cs`

### Delivery

Build and packaging pipeline

- [CI Workflow](https://github.com/aldaviva/fail2ban4win/blob/master/.github/workflows/dotnetframework.yml): github actions · Builds and runs the .NET Framework test suite · `.github/workflows/dotnetframework.yml`

## Connections

- 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
