pardnchiu/go-ip-sentry

[!NOTE] This README was generated by SKILL, get the ZH version from here.

STOP MALICIOUS IPS BEFORE THEY REACH YOUR HANDLERS!

A Go IP risk-control library with concurrent dynamic scoring, GeoLite2 anomaly detection, and drop-in Gin/net/http middleware

Table of Contents

• Features
• Architecture
• License
• Author

Features

go get github.com/pardnchiu/golang-ip-sentry · Documentation

• Concurrent Four-Dimension Scoring — Correlation, geo, behavior, and fingerprint checks run in parallel goroutines and merge into a 0–100 score that selects a normal, suspicious, or dangerous per-minute rate limit.
• GeoLite2 Anomaly Detection — Haversine-based travel speed flags impossible travel above 800 km/h, multi-country hopping within an hour, and frequent city switching.
• HMAC-Signed Session and Device Fingerprint — An HMAC-SHA256 signed session cookie paired with a device fingerprint exposes shared accounts and proxy pools through session-to-IP and IP-to-device fan-out.
• Bot Rhythm Recognition — Variance across the last 10 request intervals catches scripts with unnaturally regular timing, alongside long-session, login-failure, and 404-scan signals.
• Three-Tier IP Access Control — Allow and Deny lists persist to both Redis and local JSON and reload on startup; Block applies exponentially growing temporary bans, and Deny can trigger email alerts.

Architecture

Full Architecture

graph TB
    REQ[HTTP Request] --> MW[Gin / net/http Middleware]
    MW --> DEV[Device Identification<br/>Session + Fingerprint]
    DEV --> LIST{Three-Tier Lists}
    LIST -->|Allow| PASS[Pass]
    LIST -->|Deny / Block| REJ[403 Reject]
    LIST -->|Unlisted| SCORE[Concurrent Scoring]
    SCORE <--> REDIS[(Redis)]
    SCORE --> GEO[GeoLite2]
    SCORE --> RL{Tiered Rate Limit}
    RL -->|Within limit| PASS
    RL -->|Over limit / score ≥ 100| REJ

License

This project is licensed under the MIT LICENSE.

Author

Just open an issue to share an idea.

©️ 2025 邱敬幃 Pardn Chiu