> [!NOTE] > This README was generated by [SKILL](https://github.com/agenvoy/skill-readme-generate), get the ZH version from [here](https://github.com/pardnchiu/go-ip-sentry/blob/main/doc/README.zh.md). ***

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](#features) - [Architecture](#architecture) - [License](#license) - [Author](#author) ## Features > `go get github.com/pardnchiu/golang-ip-sentry` · [Documentation](https://github.com/pardnchiu/go-ip-sentry/blob/main/doc/doc.md) - **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](https://github.com/pardnchiu/go-ip-sentry/blob/main/doc/architecture.md) ```mermaid graph TB REQ[HTTP Request] --> MW[Gin / net/http Middleware] MW --> DEV[Device Identification
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](https://github.com/pardnchiu/go-ip-sentry/blob/main/LICENSE). ## Author Just [open an issue](https://github.com/pardnchiu/go-ip-sentry/issues/new) to share an idea.