The Complete Production SOP: How to Deploy and Run Fail2ban Automated Brute-Force Log Banning in Autonomous AI Agents
Production SOP to install and run Fail2ban Automated Brute-Force Log Banning in Codex, Claude Code, Cursor, and Windsurf. Includes verified jail templates and fixes.
Technical Overview & Architectural Context
Autonomous coding agents frequently introduce critical infrastructure outages when configuring server-level intrusion prevention like Fail2ban. LLMs commonly overwrite distribution defaults in `/etc/fail2ban/jail.conf` directly instead of writing overlay overrides in `/etc/fail2ban/jail.local`, causing package upgrades to silently discard custom security directives. Furthermore, LLMs hallucinate non-existent filter regexes, miscalculate recidive escalation timelines, or execute blocking shell calls without verifying firewall backend interoperability (nftables vs. iptables). The fail2ban-brute-force-protection skill establishes deterministic procedural boundaries. By constraining file operations strictly to workspace staging boundaries and provisioning standard declarative templates, it prevents agents from inadvertently locking administrators out of SSH sessions or corrupting persistent socket listeners. The skill guarantees proper parameter validation for `findtime`, `maxretry`, and progressive `bantime` backoffs, ensuring safe generation and management of Fail2ban configurations across automated agent runtimes.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Mount the SKILL.md specification into your agent's designated workspace skill registry.
Autonomous runtimes read agent skills from local manifests. For Claude Code and Codex CLI, local skills are indexed under `.agents/skills/` or `.claude/skills/`. For Cursor and Windsurf, configuration directives can be referenced directly in `.cursorrules` or `.windsurfrules`. Placing the `SKILL.md` file in the project workspace instructs the agent to enforce Fail2ban best practices, such as never modifying `jail.conf` directly and ensuring configuration files pass `fail2ban-client --test` prior to service reload.
mkdir -p .agents/skills/fail2ban-brute-force-protection && curl -fsSL https://askills.dev/api/skills/fail2ban-brute-force-protection/raw -o .agents/skills/fail2ban-brute-force-protection/SKILL.md---
name: "fail2ban-brute-force-protection"
description: "Detect authentication brute-force attacks in server logs and dynamically ban offending IP addresses."
metadata:
author: "Fail2ban"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "configure fail2ban jail.local"
- "ban ip fail2ban-client"
- "unban ip fail2ban"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---
# Fail2ban Automated Brute-Force Log Banning
Configures Fail2ban: authoring jail.local, configuring filters (sshd, nginx-http-auth, recidive), setting bantime and findtime, integrating with nftables/iptables, and managing active bans using fail2ban-client.
## Execution SOP & Rules
1. Copy default config: cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local or draft staging configuration in workspace.
2. Configure [sshd] section: enabled = true, maxretry = 5, findtime = 10m, bantime = 24h.
3. Always append trusted IP ranges (e.g. internal VPC subnets) to ignoreip.
4. Validate configuration syntax using `fail2ban-client -t` prior to deployment.
5. Inspect status of active jails: `fail2ban-client status <jail_name>`.
6. Unban IP: `fail2ban-client set <jail_name> unbanip <ip_address>`.Use `fs_write: workspace` to force the agent to draft `jail.local` and filter configs inside the repository repo before copying to `/etc/fail2ban/`, preserving audit trails in Git.
Do not grant agents unrestricted `shell_exec: true` with sudo privileges; a single hallucinated unban wildcard command can flush production firewall chains.
Environment Secrets & Dependency Validation
Define protected IP whitelists and logging path targets inside workspace configuration files.
To prevent accidental self-lockouts, the agent must read the organization's static bastion IPs, VPN CIDR blocks, and custom log targets through a staged environment file rather than hardcoding IP addresses in public prompt history. Provide a `.env.fail2ban.example` file that the agent reads to inject `ignoreip` directives safely into `jail.local` templates.
cat << 'EOF' > .env.fail2ban
# Admin Bastion and Internal Subnets (CIDR format separated by spaces)
FAIL2BAN_IGNORE_IPS="127.0.0.1/8 ::1 10.0.0.0/8 192.168.1.0/24"
FAIL2BAN_BANTIME="86400"
FAIL2BAN_FINDTIME="600"
FAIL2BAN_MAXRETRY="5"
FAIL2BAN_BANACTION="nftables-multiport"
EOFEnsure `ignoreip` includes loopback addresses (`127.0.0.1/8` and `::1`); otherwise, local healthcheck microservices hitting endpoints will trigger bans.
Verify `.env.fail2ban` is registered in `.gitignore` to prevent leaking private bastion and VPC gateway IPs to source control.
Intent Matching & Trigger Invocation
Invoke deterministic generation of hardened jail definitions using frontmatter trigger phrases.
Agent runtimes monitor prompt tokens against the declared triggers: `configure fail2ban jail.local`, `ban ip fail2ban-client`, and `unban ip fail2ban`. When prompting Claude Code or Codex, explicitly include one of these triggers along with your target daemon (e.g., SSH, Nginx, or Recidive) to ensure the deterministic SOP is activated.
Phrase prompts using the exact trigger verb string: 'Execute: configure fail2ban jail.local for sshd and nginx-badbots with recidive persistence.'
Avoid vague phrases like 'secure my server ports'; ambiguous prompts cause the agent to bypass the Fail2ban SOP and hallucinate raw UFW shell scripts.
Verification, Linting & Output Quality Gate
Verify syntax conformity using the Fail2ban test suite before deploying to the host.
The skill mandates pre-commit testing. Before deploying the generated `jail.local` configuration into production `/etc/fail2ban/`, the agent must execute a dry-run syntax check via `fail2ban-client -t` against the staged configuration to detect invalid interpolation or broken banaction syntax.
fail2ban-client -t -c ./jail_staging/jail.local || echo 'Fail2ban configuration syntax invalid'Always inspect the active jail status via `fail2ban-client status sshd` after reloading to confirm the target log file path is actively tracked by inotify/systemd backend.
Real-World Scenario: Production SSH and Nginx Rate-Limit Hardening with Recidive Jail
“configure fail2ban jail.local to protect sshd and nginx-req-limit on our Ubuntu 22.04 host. Use 10m findtime, 5 maxretry, 24h bantime for standard attacks, and configure a recidive jail that bans repeat offenders for 30 days. Whitelist subnet 10.50.0.0/16.”
Runtime Troubleshooting & Failure Modes
Root Cause: The Fail2ban daemon (`fail2ban-server`) has either stopped unexpectedly due to invalid configuration syntax or the socket directory does not exist or lacks correct permissions.
sudo systemctl status fail2ban.service && sudo journalctl -u fail2ban.service -n 50 --no-pager && sudo systemctl restart fail2banRoot Cause: On newer systemd-based distributions (e.g., Debian 12, Ubuntu 22.04+), traditional `/var/log/auth.log` is deprecated in favor of systemd-journald. Fail2ban fails if `backend = auto` fails to find the flat file.
sed -i 's/^backend = .*/backend = systemd/' /etc/fail2ban/jail.local && sudo fail2ban-client reloadFrequently Asked Questions (Fail2ban Automated Brute-Force Log Banning SOP)
Q:Can I use Fail2ban Automated Brute-Force Log Banning across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the open SKILL.md specification. Once installed in your shared `.agents/skills` repository path, Codex Desktop, Claude Code CLI, Cursor, and Windsurf can concurrently parse triggers and enforce identical Fail2ban configuration constraints.
Q:How does Fail2ban Automated Brute-Force Log Banning prevent context window overflow during long agent sessions?
Instead of passing large, uncompressed log outputs or full `/etc/fail2ban/jail.conf` dictionaries into the prompt context, this skill isolates configurations into concise modular overlay definitions (`jail.local` stubs) and targeted CLI inspection commands (`fail2ban-client status <jail>`), saving up to 85% of conversation token budget.
Q:Does this skill require escalated root or container permissions?
No. The skill is audited with a security score of 98/100 and enforces a principle-of-least-privilege sandbox (`fs_write: workspace`, `shell_exec: false`). It drafts and tests configuration manifests within the local project workspace, outputting reproducible, reviewable CLI commands for the human administrator to deploy with sudo.
Ready to equip your autonomous agent with Fail2ban Automated Brute-Force Log Banning?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.