Implant Documentação 8de3f8d

implant auto-ban

Daemon + CLI que lê 4 sinais de tráfego ofensivo e banha IPs via blocklist ipset com TTL progressivo por reincidência.

Setup 

sudo implant auto-ban service install     # cria unit + config + ipsets, start
sudo implant auto-ban service status      # verifica

Sinais detectados

Sinal Source TTL base Threshold
fail2ban fail2ban-client status por jail 24h qualquer ban
log_auth /var/log/auth.log 6h ≥10 falhas SSH em 5min
iptables_drops /var/log/kern.log (sem ele, journalctl -k) 12h ≥30 drops em 10min
traefik_http /var/log/traefik/access.log 1h pontuação ≥40 em 5min

O log_auth e o iptables_drops entendem tanto o formato clássico do syslog (Mmm dd HH:MM:SS, hora local) quanto RFC3339 com fuso e o short-iso do journalctl.

Pré-requisito para `iptables_drops`

O sinal lê as linhas com prefixo iptables-drop:rl geradas pelo LOG limitado do rate-limit, que é opt-in:

sudo implant rate-limit drop-log enable

auto-ban config show avisa (warnings no JSON) quando o drop-log está desligado com o sinal ligado, ou quando o min_drops não cabe no teto do LOG.

`traefik_http` — pontuação

Cada resposta no access log do Traefik soma pontos para o IP de origem:

Evento Peso (default)
Status em statuses (default 400, 401, 403, 404, 405, 444) em path comum 2
5xx (só se "5xx" estiver em ranges ou o status em statuses) 1
Status em scanner_statuses em path típico de scanner (/.env, /.git, /wp-login.php, /phpmyadmin, …) 10

Sucesso (2xx/3xx) em path de scanner nunca conta. Pesos, listas, limiar (min_score) e janela são configuráveis.

Configs antigas com o bloco traefik_404: são convertidas na leitura: só 404 em path comum (mesmo limiar de antes) e 403/404 em path de scanner — o 403 é o que a guarda de arquivos sensíveis do traefik-edge devolve.

Pré-requisitos para `traefik_http`

  • Access log do Traefik ligado (implant traefik-accesslog --enable; no Traefik 3 isso inclui addInternals: true, necessário para logar o 403 da guarda do traefik-edge)
  • Traefik configurado com forwardedHeaders.trustedIPs para ClientHost ser o IP real do atacante (não do proxy upstream)

TTL progressive backoff

Ofensa TTL (base 6h)
1ª 6h
2ª 12h
3ª 24h
4ª 48h
5ª+ permanente

O TTL dobra a cada reincidência (teto de 16× a base, max_multiplier) e vira permanente a partir de permanent_after (default 5). Ofensas contam dentro de offense_window_days (default 30).

IP detectado por múltiplos sinais simultaneamente: TTL = max(ttl por sinal). Offense count incrementa uma vez (não multiplica por sinal).

Never-ban (3 camadas em ordem)

  1. Privados: RFC1918 + loopback + link-local
  2. IMPLANT_RL_WHITELIST: whitelist do rate-limit
  3. IMPLANT_AB_ALLOW: allowlist auto-ban-only (implant auto-ban allow)

Cada skip gera evento skip_* no audit JSONL.

Comandos

Comando Descrição
service install Cria unit + config + ipsets, enable + start
service uninstall Stop + disable + remove unit (config preservado)
service start/stop/restart/status Ciclo de vida systemd
service logs --lines N journalctl wrapper
scan [--dry-run] One-shot scan + report (--dry-run não aplica os bans)
list IPs banidos (delegado para blocklist)
events [--last N] [--ip X] [--signal Y] Tail do JSONL bounded (default 20; sinais: fail2ban, log_auth, iptables_drops, traefik_http)
offenses Dump do offense counter
offenses-clear [--ip X] Limpa contador (todos ou 1)
allow --ip X [--note "razão"] Adiciona ao IMPLANT_AB_ALLOW
unallow --ip X Remove
allow-list Lista IMPLANT_AB_ALLOW + v6
config show/path Imprime config / caminho

Todos com --output json para integração com automação ou console de gerenciamento remoto.

Config

/etc/protocolo-implant/auto-ban.yml — todos os campos têm default (operador pode sobrescrever só o que quiser). implant auto-ban config show imprime a config efetiva; config path, o caminho.

Emergency-mode

auto-ban é uma feature opt-in. emergency-mode enable para o service junto com as demais features opt-in. ipsets e offense counter preservados — deadman restaura.

Upgrade do binário

O daemon detecta a troca do binário do implant (self-update) a cada ciclo, registra daemon_restart na auditoria e sai com código 75; o Restart=on-failure da unit sobe a versão nova em até ~1 min.

Ban manual

implant ban / implant unban operam no mesmo ipset central. O unban encerra o cooldown do auto-ban para o IP (mantendo o histórico de ofensas); o cooldown só vale enquanto o ban continua no set.

Audit

/var/lib/implant/auto-ban-events.jsonl (bounded ~1.2MB). Tipos: ban, ban_permanent, skip_private, skip_whitelisted, skip_allowlisted, gc, error, scan_end, daemon_restart, e os do ban manual: manual_ban, manual_ban_permanent, manual_unban.