view release on metacpan or  search on metacpan

docs/kurs/abuseipdb.md  view on Meta::CPAN

  AbuseIPDB treats a re-report after the window as a fresh report,
  which for a still-banned, still-abusive IP is usually fine — but
  know it happens.

## AbuseIPDB-side setup

An account and an API key (webmaster/user tier is fine). Free tier
allows 1,000 reports/day — pace your ban sources accordingly.

## Requirements

- `LWP::UserAgent` and `LWP::Protocol::https` (the API is https
  only) — loaded only at runtime.

## Settings

- `ports` / `protocols` — **not supported**; specifying either is a
  fatal error at kur startup.
- `enable_cidr` — this backend can **not** carry ranges (reports are
  per IP); a kur with it set logs a warning at startup and answers
  range commands per `cidr_silent_drop`.
- `prefix` — only appears in the default comment.
- Both IPv4 and IPv6 report fine.

## Options

| option       | default                     | what                                                    |
|--------------|-----------------------------|----------------------------------------------------------|
| `key`        | *(required)*                | AbuseIPDB API key                                       |
| `categories` | `18`                        | category numbers, array or comma string — see below     |
| `comment`    | `banned by <prefix>_<name>` | report comment; `%%%BAN%%%` → the IP; blank = none      |
| `timeout`    | `30`                        | HTTP timeout in seconds                                 |

Categories are AbuseIPDB's numeric taxonomy
(<https://www.abuseipdb.com/categories>) — 18 is Brute-Force, 22
SSH, 14 Port Scan, 21 Web App Attack. Pick per kur to match what the
ban source actually saw.

**Comments are public** on the reported IP's AbuseIPDB page. Do not
template in log lines, usernames, or anything else you would not
publish.

## What each operation does

| operation  | API traffic                                                              |
|------------|-------------------------------------------------------------------------------|
| `init`     | `GET /api/v2/check?ipAddress=127.0.0.2&maxAgeInDays=1` — verifies the key   |
| `ban`      | `POST /api/v2/report` with `ip`, `categories`, `comment` (429 tolerated)     |
| `unban`    | nothing                                                                      |
| `list`     | no API call — the kur's own ban book                                         |
| `check`    | same probe as init                                                           |
| `flush`    | nothing (ban book cleared)                                                   |
| `re_init`  | teardown (no-op) + init                                                      |
| `teardown` | nothing (ban book kept)                                                      |

## self_heal

There is nothing on the AbuseIPDB side to establish, so there is
nothing to repair — the re_init after a failed `check` just probes
again. `check` re-runs init's credential probe (catching a revoked or
expired key), so a kur stuck failing it has a credentials problem,
not a firewall one.

## Gotchas

- Because unban costs no API call, `ban_time` here only governs the
  kur's own book (and thus which IPs a restart re-reports). Matching
  the blocking kur's `ban_time` keeps gate members' books aligned.
- The already-banned check means one report per IP per sentence —
  the kur will not spam reports while an IP sits in the book, even
  if the ban source keeps firing (a refreshed sentence is not a new
  report).
- `check` costs one API call per self_heal probe; with `self_heal`
  on (the default) that is one extra call per ban. Harmless against
  the daily quota unless you are very chatty — set `self_heal = 0`
  on this kur if it matters, there is nothing to heal anyway.
- Errors carry Error::Helper flags (`keyNotDefined`,
  `categoriesInvalid`, …) — [`Net::Firewall::BlockerHelper::backends::abuseipdb`](https://metacpan.org/pod/Net::Firewall::BlockerHelper::backends::abuseipdb) has the full
  table.