--- title: "Running a Local IP Knowledge Service" date: 2026-11-17 tldr: "Why I built a tiny Go + SQLite microservice to cache AbuseIPDB lookups, verify reverse DNS, and track IP policy decisions locally." tags: - Go - SQLite - Docker - Security - Homelab layout: post.njk lang: en translationKey: running-local-ip-knowledge-service --- 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](/img/local-ip-knowledge-service.svg) 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`. ```bash 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.