Overview

IPBan Pro consists of two primary applications that work together to provide centralized IP ban management across one or more machines:

In the Server Edition, these run as two separate services — typically one central Web Admin and many datacenter clients, each on its own machine, reporting in over WebSocket. In the Personal Edition, the Web Admin and datacenter client are bundled together and run on a single machine: there is no remote connectivity, no multi-machine dashboard, and everything (bans, whitelist, monitoring) is scoped to that one, local install. See Editions for the full feature comparison.

Web Admin Application

Installation

The Web Admin is installed as a system service. The installer supports both Windows and Linux:

Installer command-line arguments:

The installer creates a desktop URL shortcut on Windows and registers an uninstaller entry.

Database Configuration

The Web Admin supports four database providers, configured in appsettings.json:

The DatabaseProvider key in appsettings.json selects the provider, and the corresponding connection string is read from the ConnectionStrings section. The default SQLite database file is IPBanProWebAdmin.sqlite.

Authentication

The Web Admin supports two authentication schemes:

• Basic Authentication — Username and password credentials stored in a local credentials file.
• OpenID Connect — Configured via the OpenId section in appsettings.json for integration with providers such as Microsoft Entra ID (Azure AD). Server Edition only — Personal Edition always uses Basic Authentication.

These schemes can be used independently or together. Successful logins via either scheme (including OpenID Connect) are recorded to the recent activity / logs feed, the same as a datacenter client login. The application supports the following roles:

Form-based admin actions (credential changes, ban/unban, settings, licenses, plugins, etc.) are protected against cross-site request forgery (CSRF) with anti-forgery tokens. The JSON /api/* surface is unaffected, since it is called directly (Basic Auth, no browser form) rather than via a submitted HTML form.

Dashboard & Recent Activity

Route: / or /recentactivity

The home page displays recent activity including:

• Recently banned IP addresses
• Recent failed login attempts
• Recent successful login attempts

Features:

• Filter by connected machine
• Configurable max result count
• Optional server-side paging with per-column filtering and sorting
• Export to ZIP (/IPBanProRecentActivity.zip)

Machines

Route: /machines

Manage all datacenter client machines connected to the Web Admin:

• View all registered machines with FQDN, IP address, alias, OS, version, and status
• View and edit individual machine details (/machine/{id})
• Delete machines
• Override country blacklist settings per machine (/machine-countryblacklistoverride)
• View connected clients in real time (/connectedclients)

Settings

Route: /settings

The centralized settings page is organized into several sections:

Whitelist & Blacklist

• Whitelist — IP addresses, ranges, or CIDR blocks that are never banned.
• Blacklist — IP addresses, ranges, or CIDR blocks that are always banned.
• Country Blacklist — Block all traffic from selected countries. Options include:
  • Allowed ports (exceptions for country blocking)
  • First-failed-login mode (block on first failed login from a country)
  • Invert mode (block all countries except those listed)
  • Precise mode for more accurate geo-blocking
• ASN Blacklist — Block traffic by Autonomous System Number.

Notifications

• Notification Flags — Choose which events trigger notifications (bans, failed logins, successful logins, etc.).
• Duplicate Filter Window — Suppress duplicate notifications within a time window.
• SMTP Email — Configure outgoing email notifications:
  • Server, port, SSL, credentials
  • From/To addresses
  • Subject and body templates (with WHOIS variants)
• Webhook — Send notification payloads to an HTTP endpoint.

Client Settings

• Configuration pushed to connected datacenter clients.

Event Viewer / Log Parsing

• Custom event log and log file parsing rules.

IPBan Shield

• Additional security hardening settings.
• Aggregate Ban User Names — Bans every source IP attempting to log in as a given username once that username has failed login from at least N distinct IP addresses, even if no single IP crosses the normal per-IP ban threshold (defends against distributed/low-and-slow username-spray attacks). Available on both Personal and Server Edition.

XML Configuration

• Direct XML editing for advanced IPBan configuration.

Monitoring

Route: /monitor

Real-time monitoring dashboard for connected machines:

• Toggle monitoring on/off per machine
• Live data streamed via WebSocket to the browser
• Filter by machine name
• Restrict to IPBan Pro events — When enabled (the default), only packet events tied to IPBan Pro’s own firewall rules are shown. Disable it to also see the platform’s default block rule events (e.g. baseline Windows Filtering Platform blocks) for broader packet-level visibility.

Logs

Route: /logs

View aggregated log entries from datacenter clients:

• Filter by machine, log level, and timestamp
• Configurable max result count
• Refresh and clear log database functionality

License Management

Route: /licenses

Manage IPBan Pro license keys:

• View current license keys with usage and status
• Add, update, or remove license keys
• View the count of connected clients
• Personal edition accepts a single license key; server edition accepts multiple

Blacklist Export

Export the current blacklist as a downloadable file:

Whitelist URLs

Route: /whitelist-urls

(Server edition only)

Manage URL-based whitelists that are periodically fetched and synchronized to connected datacenter clients. IP addresses resolved from configured URLs are automatically added to the client whitelists.

IP Address Events

Route: /ipaddressevents/{id}

Look up detailed event history for a specific IP address, including all recorded failed logins, successful logins, and ban events with geo-lookup information.

Tools

Route: /tools

A collection of administrative utilities:

Plugins

Route: /plugins

The Web Admin has a plugin system that extends functionality. Each plugin can be enabled/disabled and configured through the UI or API.

Cloudflare

Synchronizes banned IP addresses to Cloudflare firewall rules.

Azure NSG

Updates Azure Network Security Group deny rules with banned IP addresses.

Azure Sign-In Events

Monitors Azure AD sign-in activity logs and processes failed/successful login events.

Syslog

Forwards ban events, failed logins, and successful logins to a syslog server.

Run Process

Executes an external process with recently banned IP addresses as a command-line argument.

Domain Whitelister

Allows authenticated users whose username matches configured domains to whitelist their own IP address. Requires OpenID Connect authentication.

Users visit /whitelistme or /plugins/domainwhitelister/entry to self-whitelist.

Geo Notification

Detects impossible travel (same user logging in from distant locations) and abnormal login locations.

REST API

Base Route: /api

The Web Admin exposes a JSON REST API for programmatic access. All API endpoints require authentication.

Full Swagger/OpenAPI documentation is available at the /swagger endpoint when the application is running.

MCP Server (Model Context Protocol)

Route: /mcp

The Web Admin includes a built-in MCP server so an LLM-based client (Claude Desktop, Claude Code, or any other MCP-compatible tool) can investigate bans, logins, and machine status, and take a small set of safe actions, directly in conversation — without writing scripts against the REST API.

• Transport: Streamable HTTP, mounted at /mcp.
• Authentication: The same credentials as the Web Admin UI (Basic Authentication or OpenID Connect). Every call requires the Administrator role — no other role, including Guest or Event Reader, can reach MCP tools.
• Implementation: Each tool is a thin wrapper around the same controller action the REST API or web UI already uses, so results and permissions match exactly what an administrator sees in the browser — no separate business logic or data path.

To connect a client, point it at https://<your-webadmin-host>/mcp using Streamable HTTP transport and supply Web Admin administrator credentials.

Read / query tools:

Safe mutation tools:

Destructive or secret-bearing operations — resetting all bans, deleting machines, overwriting settings, credential changes, raw SQL, and reads of secret-bearing config such as SMTP credentials or whitelist URLs — are intentionally not exposed as MCP tools.

Software Updates

Route: /autoupdate

Trigger a self-update of the Web Admin application. The update is downloaded from api.ipban.com and installed automatically. The appropriate download is selected based on the current operating system and CPU architecture.

Datacenter Client Application

Datacenter Installation

The datacenter client is installed as a system service on each machine to be protected.

Installer command-line arguments:

During installation, you are prompted for the Web Admin server URL and credentials. The client connects to the Web Admin via WebSocket to send events and receive configuration updates.

Version check:

IPBanProDatacenter --version

Firewall Types

The datacenter client supports multiple firewall implementations:

WebSocket Communication

The datacenter client maintains a persistent WebSocket connection to the Web Admin for:

• Reporting events — Failed logins, successful logins, bans, and unbans.
• Receiving configuration — Settings changes, whitelist/blacklist updates, country block lists, and ASN block lists are pushed from the Web Admin in real time.
• Remote commands — Firewall rule queries, software update triggers, and credential changes.
• Log forwarding — Client log entries are sent to the Web Admin for centralized viewing.
• Packet monitoring — Blocked packet events can be forwarded for analysis.

Credential Management

Credentials are stored in a local creds.txt file on the datacenter client. The file contains username/password pairs with associated roles. Credentials can be changed remotely from the Web Admin.

The datacenter client also maintains a machine_guid.txt file that uniquely identifies the machine. This GUID can be reset during installation or via the installer.

Migration

The datacenter client supports database migration via the command line:

IPBanProDatacenter migrate [args]

This is used when upgrading from previous versions or changing database schemas.

Editions

The Personal Edition runs the Web Admin and IPBan service on the same machine. The Datacenter Edition runs the Web Admin centrally with multiple datacenter clients connecting remotely.