# implant fail2ban

Controle granular sobre o Fail2Ban — habilita/desabilita o serviço, lista jails e IPs banidos, banir/desbanir IPs sob demanda, ler o log recente. As operações de ban/consulta usam fail2ban-client; só o enable escreve configuração.

# Uso

implant fail2ban <subcomando> [OPTIONS]

# Subcomandos

# Ações de serviço

• enable — instala o Fail2Ban se necessário, escreve a configuração de jail e inicia o serviço. Um jail.local existente que não foi criado pelo implant não é sobrescrito: nesse caso a configuração vai para /etc/fail2ban/jail.d/implant.conf (a configuração do operador continua valendo)
• disable — para e desabilita o serviço (sem desinstalar)
• status — status atual do serviço. Desde a v2.59.0 inclui o bloco ipset_action (ver use-ipset-action abaixo)

# `list-jails`

Lista todos os jails configurados com contadores.

# `list-banned [--jail ]`

Lista IPs banidos — em todos os jails, ou só no especificado.

# `ban [--jail ]`

Bane um IP (v4 ou v6) manualmente. O endereço é validado antes de qualquer execução. Sem --jail, aplica em todos os jails.

# `unban [--jail ]`

Remove o ban de um IP. Sem --jail, remove de todos os jails.

# `clear [--jail ]`

Limpa todos os bans de um jail — ou de todos, se --jail for omitido.

# `tail-log [--lines ]`

Mostra as últimas N linhas de /var/log/fail2ban.log (default 50).

# `use-ipset-action --enable | --disable`

Opt-in (v2.59.0+). O fail2ban passa a gravar os bans direto na blocklist central do implant (IMPLANT_RL_BLOCKLIST / IMPLANT_RL_BLOCKLIST6), a mesma do `ban` e do auto-ban. Os ganchos da INPUT e da DOCKER-USER já leem esse set: o IP banido pelo fail2ban fica fora do host e dos containers, sem as chains f2b-* paralelas.

sudo implant fail2ban use-ipset-action --enable
sudo implant fail2ban --dry-run use-ipset-action --enable   # só o plano
implant fail2ban status                                     # vínculo
sudo implant fail2ban use-ipset-action --disable            # volta ao anterior

• Arquivos: o --enable cria só dois arquivos, com a marca do implant: /etc/fail2ban/action.d/ipset-implant.conf (a action) e /etc/fail2ban/jail.d/zz-implant-ipset.local (liga a action como banaction). Nenhum arquivo existente é editado. Arquivo de terceiro com um desses nomes faz o --enable recusar, e o --disable não o toca.
• Só nas jails do implant: as seções do jail.local escrito pelo implant ou do jail.d/implant.conf (na prática, sshd). Jails de terceiros continuam com a action delas. Jail com action = explícito não usa a banaction; o status mostra isso em live_jails.
• Pré-requisito: o gancho da blocklist na INPUT (e na DOCKER-USER, havendo Docker), instalado pelo `rate-limit apply`. Sem ele, o --enable recusa, porque o ban não teria efeito. --force liga mesmo assim, com aviso.
• Validação: depois de gravar, roda fail2ban-client -t. Se a configuração for reprovada, os arquivos voltam ao que eram. Em seguida, systemctl try-restart fail2ban: os bans vigentes migram da action antiga para o set. Rodar de novo sem mudança não reinicia o fail2ban.
• --disable: apaga os dois arquivos; as jails voltam exatamente à action que tinham antes.
• Prazo: o timeout da entrada no set é o bantime do ban. bantime = -1 (permanente) vira entrada sem timeout. Acima do teto do ipset (~24 dias), vale o teto.
• Precedência: IP na whitelist do implant não entra no set (e o gancho da whitelist vem antes do da blocklist). IP que já está na blocklist (ban manual, auto-ban ou faixa mais ampla) não tem o timeout regravado: um ban não encurta outro.
• Unban: no fim do ban, a action só tira o IP do set se ele não tiver outro ban vigente do implant (ban manual ou auto-ban). Para tirar o IP de todos os mecanismos de uma vez, use implant unban <IP>.
• Set compartilhado: a action não cria regra de iptables, não esvazia nem destrói o set e não roda ipset save. Depois de um reboot, quem repõe os bans do fail2ban é o próprio fail2ban, a partir do banco dele.
• Emergency-mode: é a feature fail2ban-ipset do emergency-mode. Durante a emergência o fail2ban volta à action própria e o SSH continua protegido.
• Reset: implant reset --fail2ban também apaga os dois arquivos, se forem do implant.

# `ipset_action` no `status`

Os sets não têm a extensão comment, então a origem (ips_from_fail2ban) sai do cruzamento com a lista de banidos das jails. Um IP que o fail2ban baniu e o auto-ban estendeu conta como vindo do fail2ban.

# Divisão de papéis: SSH no fail2ban, HTTP no auto-ban

A detecção de abuso HTTP fica no auto-ban (sinal traefik_http, que lê o access log JSON do Traefik com TTL progressivo). O fail2ban fica para o SSH. Jails de HTTP no fail2ban duplicariam a detecção com regex frágil sobre JSON. A use-ipset-action serve só para o fail2ban do SSH gravar no mesmo set que o resto do implant.

# Saída JSON

Envelope por subcomando — o schema varia (lista de jails, lista de IPs, ack de ban, etc.).

O use-ipset-action responde fail2ban.use-ipset-action com action, dry_run, jails, files (path + action: created, updated, unchanged, removed, absent, foreign_kept, ou would_* em dry-run), config_test, restarted, warnings e status (o mesmo objeto ipset_action do status).

# Exemplos

# Status geral
implant --output json fail2ban status

# Quem está banido no jail sshd
implant --output json fail2ban list-banned --jail sshd | jq '.data'

# Banir IP manualmente no jail sshd
sudo implant fail2ban ban 203.0.113.4 --jail sshd

# Desbanir de todos os jails
sudo implant fail2ban unban 203.0.113.4

# Investigação rápida
sudo implant fail2ban tail-log --lines 200

Para desfazer um ban em todos os mecanismos de uma vez (ipset, fail2ban e UFW), use implant unban <IP>.

# Veja também

• ban — ban unificado na mesma blocklist
• auto-ban — detecção HTTP
• rate-limit — ganchos da blocklist
• emergency-mode — feature fail2ban-ipset