# IRDB — IP Reputation Database, in plain English
A self-hosted way to share known-bad IP addresses across all your servers and firewalls. One place to collect, one tailored list per system to defend.

## What IRDB solves

Most teams already block bad IP addresses — but each server, each firewall, each plugin keeps its own list. Lists go stale, knowledge stays trapped in one machine, and an attack already seen by your web server walks straight through your mail gateway. IRDB turns that scattered information into one shared, up-to-date defence layer.

●

### Collect from anywhere

Web servers, mail servers, fail2ban, intrusion detectors, custom scripts — anything that spots an attack can report it through one simple endpoint.

▲

### Score, don't just list

Each report has a weight, an age and a category. IRDB turns those into a reputation score per IP that fades over time, so old noise drops away on its own.

◆

### Shape lists per consumer

Your edge firewall might want strict blocking, your mail relay only spam-related sources. Each consumer gets a list tailored by a named policy you control.

## How it fits your environment

IRDB sits in the middle of two flows you already have: machines that see attacks, and machines that block them. Below is the same picture, in plain steps.

### Identify your reporters

Every server, service or device that can detect an attack is a reporter — for example a web server seeing brute-force attempts, a mail relay spotting spam, or an intrusion detector. Each reporter gets a name, a trust weight (how much you believe its reports) and a token.

### Send reports as events happen

When a reporter spots a bad IP, it sends a small message to IRDB: which IP, which kind of attack, and any helpful context. The work for your operations team is one-time: drop a small script or plugin into the reporter, and it streams events from then on.

### Define policies for who gets what

A policy describes the kind of list a system should receive — for example, "block anything with high spam score" or "block strict: anything reported for brute force, scanning, or web attacks". You design these once with your team, and adjust thresholds visually at any time.

### Connect your consumers

Every firewall, proxy or load balancer that should defend itself becomes a consumer. You assign it a policy and give it a token. From then on, the consumer pulls a fresh, tailored block list at an interval you choose (typically every minute or two).

### Watch, refine, override

The dashboard shows what is being seen and what is being blocked. Operators can promote individual IPs to permanent blocks, allowlist trusted partners to never be blocked by mistake, and inspect the full history of any address. Every change is recorded in an audit log.

## A quick tour of the interface

The web interface is built for daily use by ops and security teams — clear lists, fast search, visual feedback, light and dark mode. Here is what you actually see when you log in.

### Dashboard — what's happening right now

One glance gives you the live picture: how many reports are flowing in, which categories of attack dominate today, which sources are the busiest, and which consumers are actually pulling their lists.

- Real-time activity counts
- Top categories and reporters at a glance
- Health indicators for background jobs

### IP list — search and filter the whole population

Find any address by score, country, network owner or attack category. Sort, filter and drill in with one click. Useful for incident response ("did we ever see this IP before?") and for the ops team's monthly reviews.

- Filter by category, country, ASN, score range
- Visible reputation per address, decayed by age
- Quick links into the full per-IP history

### IP details — the full story per address

Open any IP to see who reported it, when, for what, with what context. You see the score per category, geographical and network owner information, manual block status, and the complete timeline of events.

- Per-category reputation with decay
- Country and network owner enrichment
- Full audit trail of reports and admin actions

### Policies — design lists visually

A policy is just a recipe: which categories matter, and how strict the threshold is. Adjust them with a slider, see immediately how many addresses would be on the resulting list, and ship the change to all matching consumers without a deploy.

- Per-category thresholds with live preview
- Optional inclusion of manual blocks
- Score distribution chart to set thresholds confidently

### Audit log — full accountability

Every administrative action — token created, IP allowlisted, policy edited, user role changed — is recorded with who, when and what. The audit log keeps your team aligned with internal compliance and gives security a clean trail when something needs review.

- Tamper-evident, append-only history
- Filter by actor, action or target
- Configurable retention to match your policy

## Why teams choose IRDB

Light to run, simple to integrate, no vendor lock-in.

100% Self-hosted, your data stays with you
~5 min From clone to a running stack
1 Endpoint to report — language-agnostic
∞ Reporters and consumers, no per-seat fee

## Quick install

IRDB ships as a Docker Compose stack. If you have Docker, you have everything you need. The default storage is a small embedded database — no external services required to get started.

### In one terminal

Three commands. Then visit http://localhost:8080 to log in.

Source code, full documentation and release notes live at git.chiapparini.org/chiappa/irdb.

    # 1. clone
    git clone https://git.chiapparini.org/chiappa/irdb
    cd irdb

    # 2. configure (generate a few secrets)
    cp .env.example .env
    $EDITOR .env

    # 3. run
    docker compose up -d