Running a Local IP Knowledge Service

TL;DR

Why I built a tiny Go + SQLite microservice to cache AbuseIPDB lookups, verify reverse DNS, and track IP policy decisions locally.

If you run a few services at home or in a small lab, you eventually start wondering who is knocking on your door. Every time a firewall log, reverse proxy, or custom script sees a suspicious IP address, you want to know: is this a known scanner, a legitimate crawler, or just noise?

My first instinct was to query the AbuseIPDB API directly from every script that needed it. That works for a bit, until you hit rate limits, wait on external HTTP calls, or realize three different tools just asked about the exact same IP within five minutes. So I put together a small, local IP Knowledge Service to sit in the middle and remember things for me.

Why Go and SQLite?

Local IP Knowledge Service Architecture

I wanted something that barely uses any resources. The service is written in Go (1.24+) using a pure Go SQLite driver (modernc.org/sqlite) with WAL (Write-Ahead Logging) mode enabled. Because there's no CGO and no external database daemon to babysit, it compiles to a single static binary and runs in a tiny container with a <10 MB RAM footprint.

Cached queries come back in under a millisecond, which means my local tools don't have to stall waiting for external APIs.

What It Actually Does

When an internal client asks GET /api/v1/ip/{ip}, the service follows a pretty simple flow:

  1. Check the local SQLite cache: If the record is fresh (controlled by CACHE_TTL_HOURS, defaulting to 24 hours), it updates the lastSeen timestamp and returns the cached result immediately.
  2. Skip internal ranges: Bogon and RFC 1918 addresses (like private, loopback, or CGNAT ranges) are detected automatically so I don't waste AbuseIPDB API quota on my own LAN.
  3. Verify DNS: It runs a reverse DNS (PTR) lookup and a Forward-Confirmed Reverse DNS (FCrDNS) check to spot spoofed hostnames.
  4. Query AbuseIPDB v2: Only on a cache miss, expired TTL, or explicit ?refresh=true does it reach out to AbuseIPDB.

On top of that, I added a policy decision engine (neutral, blacklisted, whitelisted) with optional expiration TTLs and an audit history array. If a proxy or firewall just wants to say "I saw this IP again" without triggering an external lookup, it can hit POST /api/v1/ip/{ip}/seen.

There's also a drop-in AbuseIPDB v2 caching proxy at GET /api/v2/check (and GET /check) that matches the official schema, so existing tools only need a base URL change. And when I want to inspect things manually, there's an embedded dark-mode web dashboard at / or /ui.

Running It with Docker Compose

In docker-compose.yml, the main ip-knowledge-service container exposes port 8085 (mapped to 8080 internally) and stores its SQLite database in a persistent volume at /data/ip_knowledge.db.

cp .env.example .env
docker compose up -d

Alongside it, a lightweight cron container runs sync_cidr_groups.py at startup and every night at 3:00 AM to keep CIDR groups synced.

The Honest Trade-Offs

It's intentionally simple. Using SQLite means it's built for a single-node homelab or internal network, not a multi-region cluster. Also, if you don't provide an ABUSEIPDB_API_KEY in .env, it still works—but only with local DNS/FCrDNS checks and manual decisions.

For my setup, though, having a fast, local source of truth for IP reputation has been a huge relief. No more burning through API quotas, and my logs finally have context.

Share this post: