Plugin Authoring

Fail2Ban4Win allows its functionality to be extended with plugins.

These Fail2Ban4Win plugins take the form of .NET DLLs that implement an interface from a shared library and are located in the <installation directory>\plugins\ directory.

Prerequisites

• .NET development environment, such as any one of
  • Visual Studio Community Edition with .NET Desktop Development workload
  • Visual Studio Code with the C# Dev Kit extension
  • JetBrains Rider
  • .NET SDK and a text editor

Sample plugin

The SamplePlugin is a skeleton project that shows how to structure a library to act as a plugin.

Creating a plugin

1. Create a new C# library project, targeting .NET Framework 4.7.2.
2. Declare a dependency on the Fail2Ban4Win.Abstractions package.

Warning

Make sure to set the ExcludeAssets attribute of the Fail2Ban4Win.Abstractions PackageReference to runtime, otherwise Fail2Ban4Win could load two different copies of that library, which would prevent it from discovering or loading your plugin.

📄 MyPlugin.csproj

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFramework>net472</TargetFramework>
        <AssemblyName>Fail2Ban4Win.Plugins.$(MSBuildProjectName)</AssemblyName>
        <RootNamespace>$(AssemblyName)</RootNamespace>
        <Nullable>enable</Nullable>
        <ImplicitUsings>enable</ImplicitUsings>
        <LangVersion>latest</LangVersion>
        <Authors>My Name</Authors>
        <Copyright>© 2026 $(Authors)</Copyright>
        <Company>$(Authors)</Company>
        <DebugType>embedded</DebugType>
        <EnableDynamicLoading>true</EnableDynamicLoading>
    </PropertyGroup>

    <ItemGroup>
        <PackageReference Include="Fail2Ban4Win.Abstractions" Version="0.0.1" ExcludeAssets="runtime" />
    </ItemGroup>

</Project>

3. Create a class that implements the IFail2Ban4WinPlugin interface.
4. Provide your custom logic to run when an IP address fails to authenticate in the OnAuthFailureDetected(FailureParams) method, or when a subnet is banned or unbanned in the OnSubnetBanned(BanParams) or OnBanLifted(BanParams) methods.
5. Optionally provide process-lifetime initialization and cleanup logic in the class' constructor and IDisposable.Dispose methods, respectively.

📄 MyPlugin.cs

using Fail2Ban4Win.Data;

namespace Fail2Ban4Win.Plugins.SamplePlugin;

public class MyPlugin: IFail2Ban4WinPlugin, IDisposable {

    public MyPlugin() {
        // optional initialization logic when Fail2Ban4Win launches
    }

    public void OnAuthFailureDetected(FailureParams failure) {
        // logic when an IP address fails to authenticate once
    }

    public void OnSubnetBanned(BanParams ban) {
        // logic when a subnet failed enough times to get banned in the firewall
    }

    public void OnBanLifted(BanParams ban) {
        // logic when a subnet was banned long enough for the ban to expire and be deleted from the firewall
    }

    public void Dispose() {
        // optional cleanup logic when Fail2Ban4Win exits
    }

}

Deploying a plugin

1. Compile the project.

   dotnet publish

2. Stop Fail2Ban4Win.
3. Copy the DLLs (such as Fail2Ban4Win.Plugins.MyPlugin.dll) and other required files from bin\Debug\net472\publish\ to <Fail2Ban4Win installation directory>\plugins\, which you will have to create if it doesn't already exist.
4. Start Fail2Ban4Win.

Debugging a plugin

You can debug Fail2Ban4Win and its plugins in Visual Studio by clicking Debug › Attach to Process… and choosing Fail2Ban4Win.exe.