v1.0.0

pardnchiu/go-ip-sentry

Last updated

NoteThis README was generated by SKILL, get the ZH version from here.

WarningArchived on 2026-10-30. go-ip-sentry is no longer maintained. The final release is v1.0.0; go get github.com/pardnchiu/golang-ip-sentry remains available, but no new features, bug fixes, or security updates will be published, and issues and pull requests are no longer accepted.



STOP MALICIOUS IPS BEFORE THEY REACH YOUR HANDLERS!


Go ReferenceReleaseLicense




A Go IP filter and rate limiting middleware with Redis IP blacklist, GeoLite2 impossible travel, and device risk scoring

Table of Contents



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 - 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
  1. graph TB
  2. REQ[HTTP Request] --> MW[Gin / net/http Middleware]
  3. MW --> DEV[Device Identification - Session + Fingerprint]
  4. DEV --> LIST{Three-Tier Lists}
  5. LIST -->|Allow| PASS[Pass]
  6. LIST -->|Deny / Block| REJ[403 Reject]
  7. LIST -->|Unlisted| SCORE[Concurrent Scoring]
  8. SCORE <--> REDIS[(Redis)]
  9. SCORE --> GEO[GeoLite2]
  10. SCORE --> RL{Tiered Rate Limit}
  11. RL -->|Within limit| PASS
  12. RL -->|Over limit / score ≥ 100| REJ

License


This project is licensed under the MIT LICENSE.

Author


Just open an issue to share an idea.
go-ip-sentry contributors


©️ 2025 邱敬幃 Pardn Chiu
中文