What the module does
Automatic IP blocking
Tracks qualifying 404 requests and automatically adds an IP to the blocked list once it exceeds the configured threshold.
Request-time enforcement
Rejects requests from blocked IP addresses with a 403 response before they continue through the application pipeline.
Recent 404 visibility
Gives administrators a dashboard view of recent 404 attempts, including IP address, requested URL, and attempt time.
Manual admin control
Supports manual blocking, unblocking, editing, deleting by IP, and moving an IP directly from recent 404 attempts into the blocked list.
Why this matters
Not every bad request is dangerous, but repeated 404 activity often reveals automated reconnaissance. Attackers and bots commonly scan for well-known endpoints, old CMS paths, plugin folders, admin URLs, or framework-specific routes that do not exist on the current site.
Instead of just logging those misses and moving on, IPGuard turns them into a signal. When the same IP keeps generating suspicious 404 traffic inside the configured time window, the module can block it automatically and reduce future noise.
Key features
- Configurable 404 threshold for automatic blocking
- Configurable block window in hours
- Support for allowed IP addresses that should never be blocked
- Optional exclusion of reserved and internal Oqtane routes
- Built-in handling for framework paths such as
/_blazor,/_framework, and/_content - Automatic country lookup for blocked IPs
- A diagnostic mode for troubleshooting threshold and concurrency behavior
- Safe behavior during tenant initialization and install-time gaps
Administrator experience
The module includes a clean admin dashboard with two primary views:
Blocked IP Addresses
Administrators can view:
- IP address
- Country lookup
- Error count
- Blocked date
- Reason
Recent 404 Attempts
Administrators can review:
- IP address
- Requested URL
- Attempt date
- One-click block action
A useful workflow improvement is the ability to take an IP from the recent 404 list and add it
directly to the blocked list. When that happens, the module performs a country lookup, sets the
block reason to Administrator manual block., uses the recorded attempt count as the
error count, and removes that IP’s rows from the recent 404 attempt table.
Built for real-world hosting
Oqtane environments are often multi-tenant, and runtime behavior matters. IPGuard is designed with that in mind. It prefers host settings, supports fallback behavior for transition scenarios, and stores blocked IPs and 404 attempts at the tenant database level rather than per site instance.
The module also includes defensive handling for initialization timing issues. If tenant persistence is not yet ready during installation or startup, IPGuard safely no-ops instead of breaking the request pipeline.
Performance notes
Runtime enforcement is efficient because blocked lookups are exact IP matches backed by a unique index. In practice, the blocked-IP table can grow to a substantial size before request-time lookup becomes a concern.
Operationally, the recent 404 attempt table is usually the area that deserves more attention over time, especially on busy public sites. IPGuard helps manage that by allowing administrators to delete all attempts, delete by IP, or convert suspicious IPs directly into blocked records.
When to use it
- Public Oqtane sites that receive bot traffic
- Sites seeing repeated requests for missing admin or framework paths
- Environments where administrators want both automated blocking and manual control
- Multi-tenant installations that need lightweight request filtering based on repeated 404 behavior
Final thoughts
GIBS.Module.IPGuard is a focused security-hardening module for Oqtane. It does not try to replace a full WAF or upstream firewall, but it does provide a practical application-level defense against repeated 404 probing and suspicious request patterns.
For teams running Oqtane in production, it offers a useful balance of automation, visibility, and control with a simple administrative experience.