> ## Documentation Index
> Fetch the complete documentation index at: https://verifyngo.chocolatemoo53.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Report abusive IPs to AbuseIPDB

> Set up verifyngo to report IP addresses to AbuseIPDB automatically once they reach a configurable ban count, with a 15-minute cooldown.

verifyngo can automatically report IP addresses to [AbuseIPDB](https://www.abuseipdb.com) when they have been banned multiple times. This helps the wider community by contributing to the shared abuse database, making it easier for other operators to identify and block the same bad actors. You will need a free AbuseIPDB API key to enable this feature.

## Getting an API key

Go to [abuseipdb.com](https://www.abuseipdb.com), create an account, and generate a new API key. Make sure the key has the **report** permission enabled and save your key somewhere safe.

## Configuration

Add an `abuseipdb` block to your verifyngo config file and fill in the fields below.

**enabled** `boolean` (default: false)

Set to `true` to enable AbuseIPDB reporting. No reports are sent while this is `false`, even if an API key is configured.

**api\_key** `string` *required*

Your AbuseIPDB API key. Required when `enabled` is `true`.

**categories** `string` (default: "19,21")

Comma-separated list of [AbuseIPDB category IDs](https://www.abuseipdb.com/categories) to attach to each report. The defaults are `19` (Web App Attack) and `21` (DDoS). Adjust these to match the type of abuse you are seeing.

**comment** `string` (default: "verifyngo: exceeded walk-away threshold")

The comment included with each report. verifyngo automatically appends the most recent request paths seen from the IP (up to 10) so reviewers have context. You can override the base comment here; the paths are always appended regardless.

**report\_after\_bans** `integer` (default: 3)

The number of ban events that must occur for an IP before verifyngo submits a report. This prevents a single accidental ban from triggering a report — only persistent offenders are reported.

```json theme={null}
"abuseipdb": {
  "enabled": true,
  "api_key": "your-api-key-here",
  "categories": "19,21",
  "comment": "verifyngo: repeated bot activity",
  "report_after_bans": 3
}
```

> [!NOTE]
>
> verifyngo enforces a 15-minute cooldown between reports for the same IP address. This prevents the same IP from being reported repeatedly in a short window and avoids flooding AbuseIPDB with duplicate submissions.

> [!TIP]
>
> If you want to be conservative about what you report, raise `report_after_bans` to `5` or `10`. This way only IPs that have been banned many times — strong evidence of persistent automated abuse — are reported to AbuseIPDB.

# Using the AbuseIPDB blacklist

With `abuseipdb.blacklist.enabled = true` (and `abuseipdb.api_key` set), verifyngo automatically pulls the free AbuseIPDB blacklist (the top \~10,000 entries) at startup and re-pulls it every `abuseipdb.blacklist.refresh` (default `6h`), denying any request whose IP is on the list with `403 Forbidden`.

```json theme={null}
"abuseipdb": {
  "api_key": "your-key",
  "blacklist": {
    "enabled": true,
    "refresh": "6h"
  }
}
```

The list only applies to the configured key; requests that already hold a valid verified cookie or match `whitelist`/`always_pass_paths` are not affected. If a refresh fails, the previous list stays in effect, and it retries on the next tick.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.