# pardnchiu/go-ip-sentry

> Go IP risk scoring middleware for Gin and net/http: Redis-backed rate limits, GeoLite2 impossible travel, device fingerprints, IP blacklist. By 邱敬幃 Pardn Chiu.

Maintained by 邱敬幃 Pardn Chiu (pardnchiu), Pardn Co., Ltd. Source: https://github.com/pardnchiu/go-ip-sentry

Full text in one file: [English](https://go-ip-sentry.pardn.io/llms-full.txt) · [中文](https://go-ip-sentry.pardn.io/zh/llms-full.txt)

## Overview

- [Home](https://go-ip-sentry.pardn.io/index.md): Go IP risk scoring middleware for Gin and net/http: Redis-backed rate limits, GeoLite2 impossible travel, device fingerprints, IP blacklist. By 邱敬幃 Pardn Chiu.
- [Getting Started](https://go-ip-sentry.pardn.io/getting-started.md): Install go-ip-sentry, start Redis, protect a net/http server, and watch the 100-request-per-minute default return 403 with curl.

## Concepts

- [Architecture](https://go-ip-sentry.pardn.io/architecture.md): One diagram of go-ip-sentry layers: middleware, Check flow, device identification, four-dimension scoring, GeoLite2, Allow/Deny/Block lists, Redis.
- [Request Lifecycle](https://go-ip-sentry.pardn.io/request-lifecycle.md): The order IPGuardian.Check runs: Allow, Block, Deny, scoring, tiered rate limits, each status code and error, side effects, and failure handling.
- [Risk Scoring](https://go-ip-sentry.pardn.io/risk-scoring.md): How four detection dimensions run in parallel and merge into a 0-100 score, the +25 detail bonus, suspicious and dangerous tiers, and every flag.

## Detection

- [Correlation Signals](https://go-ip-sentry.pardn.io/correlation-signals.md): Session-to-IP, IP-to-device, and device-to-IP sets, tiered 1x/2x scoring, login-failure and 404 counters, and NAT and mobile edge cases.
- [Behavior Signals](https://go-ip-sentry.pardn.io/behavior-signals.md): Bot detection from request-interval variance over the last 10 intervals, extremely regular timing, and long-session scoring with a 15-minute idle reset.
- [Session and Fingerprint](https://go-ip-sentry.pardn.io/session-fingerprint.md): The HMAC-SHA256 signed session cookie, .sessionSecret for multi-instance setups, the SHA-256 device fingerprint, and fingerprint multi-session detection.
- [Geo Detection](https://go-ip-sentry.pardn.io/geo-detection.md): GeoLite2 setup, 24-hour location cache, impossible travel above 800 km/h via haversine distance, country hopping, and city switching checks.

## Access Control

- [Allow and Deny Lists](https://go-ip-sentry.pardn.io/access-lists.md): How the Allow and Deny IP lists load from JSON files, sync to Redis, take precedence, get removed manually, and behave across instances.
- [Temporary Blocking](https://go-ip-sentry.pardn.io/blocking.md): Block durations that grow as 2^n times BlockTimeMin up to BlockTimeMax, record accumulation, the permanent-block zero-value trap, and unblocking.
- [Email Alerts](https://go-ip-sentry.pardn.io/email-alerts.md): SMTP alerts when an IP joins the Deny list: config, custom subject and body, port 587 STARTTLS, PLAIN auth, and the undelivered CC limit.

## Integration

- [Middleware](https://go-ip-sentry.pardn.io/middleware.md): Wire go-ip-sentry into Gin or net/http, skip health-check and polling paths, keep gin.Recovery, or call Check directly for custom responses.
- [Event Reporting](https://go-ip-sentry.pardn.io/event-reporting.md): Report login failures and 404 scans with LoginFailure and NotFound404, their per-session one-hour windows, and their double-count side effects.
- [Client IP Resolution](https://go-ip-sentry.pardn.io/client-ip.md): The header order go-ip-sentry trusts for the client IP, why X-Forwarded-For can be spoofed, proxy hardening steps, and internal-range detection.

## Reference

- [Configuration](https://go-ip-sentry.pardn.io/configuration.md): Config, Redis, Log, Filepath, and EmailConfig fields with JSON keys and defaults, plus loading the whole configuration from a JSON file.
- [Parameters](https://go-ip-sentry.pardn.io/parameters.md): Every Parameter field with JSON key and default: rate limits, tier thresholds, correlation, behavior, geo scores, block durations, and tuning tips.
- [API Reference](https://go-ip-sentry.pardn.io/api-reference.md): Every exported golangIPSentry function, method, and type: New, Check, middleware, list managers, IPGuardianResult, IPItem, internal types.
- [Redis Keys](https://go-ip-sentry.pardn.io/redis-keys.md): Every Redis key go-ip-sentry writes, grouped by lists, counters, behavior, and geo, with type, TTL, writer, and cleanup commands.
- [Known Issues](https://go-ip-sentry.pardn.io/known-issues.md): Confirmed v1.0.0 defects: Redis-outage panic, spoofable proxy headers, permanent zero blocks, inactive HighRiskCountry and BlockToBan, and workarounds.
- [Removed API](https://go-ip-sentry.pardn.io/removed-api.md): Symbols removed in go-ip-sentry v0.3.0, such as TrustManager, BanManager, and LogConfig, with replacements and an upgrade example.

## Symbols

Exported symbol -> page that documents it.

- `AllowIPManager` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md)
- `BasicItem` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md)
- `BlockIPManager` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md)
- `Config` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md), [Architecture](https://go-ip-sentry.pardn.io/architecture.md)
- `DenyIPManager` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md)
- `Device` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md), [Request Lifecycle](https://go-ip-sentry.pardn.io/request-lifecycle.md)
- `EmailConfig` (.): [Configuration](https://go-ip-sentry.pardn.io/configuration.md)
- `Filepath` (.): [Configuration](https://go-ip-sentry.pardn.io/configuration.md), [Geo Detection](https://go-ip-sentry.pardn.io/geo-detection.md)
- `GeoLite2` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md)
- `GeoLite2Config` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md)
- `IP` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md), [Request Lifecycle](https://go-ip-sentry.pardn.io/request-lifecycle.md)
- `IPGuardian` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md), [Middleware](https://go-ip-sentry.pardn.io/middleware.md)
- `IPGuardianResult` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md), [Middleware](https://go-ip-sentry.pardn.io/middleware.md)
- `IPItem` (.): [Redis Keys](https://go-ip-sentry.pardn.io/redis-keys.md), [Allow and Deny Lists](https://go-ip-sentry.pardn.io/access-lists.md)
- `IS` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md)
- `Location` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md)
- `Log` (.): [Configuration](https://go-ip-sentry.pardn.io/configuration.md), [Getting Started](https://go-ip-sentry.pardn.io/getting-started.md)
- `Logger` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md)
- `Manager` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md), [Allow and Deny Lists](https://go-ip-sentry.pardn.io/access-lists.md)
- `New` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md), [Allow and Deny Lists](https://go-ip-sentry.pardn.io/access-lists.md)
- `Parameter` (.): [Configuration](https://go-ip-sentry.pardn.io/configuration.md), [Architecture](https://go-ip-sentry.pardn.io/architecture.md)
- `Redis` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md), [Allow and Deny Lists](https://go-ip-sentry.pardn.io/access-lists.md)
- `RiskScore` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md)
- `ScoreItem` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md), [Risk Scoring](https://go-ip-sentry.pardn.io/risk-scoring.md)
- `ScoreResult` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md)
- `ScoreTask` (.): [API Reference](https://go-ip-sentry.pardn.io/api-reference.md)

## 中文文件

- [首頁](https://go-ip-sentry.pardn.io/zh/index.md): Gin／net/http Go IP 風險評分中介層：Redis 限流、GeoLite2 異地偵測、裝置指紋、IP 黑名單，邱敬幃 Pardn Chiu 開發
- [快速開始](https://go-ip-sentry.pardn.io/zh/getting-started.md): 安裝 go-ip-sentry、啟動 Redis、保護 net/http 伺服器，並用 curl 觀察每分鐘 100 次預設上限回 403。
- [架構](https://go-ip-sentry.pardn.io/zh/architecture.md): 以一張圖呈現 go-ip-sentry 分層：中介層、Check 流程、裝置識別、四維評分、GeoLite2、三層名單與 Redis。
- [請求流程](https://go-ip-sentry.pardn.io/zh/request-lifecycle.md): IPGuardian.Check 的判定順序：Allow、Block、Deny、評分與分級限流，各狀態碼、副作用與錯誤處理。
- [風險評分](https://go-ip-sentry.pardn.io/zh/risk-scoring.md): 四個偵測維度如何並行計算並合併為 0–100 分、Detail 加權 25、可疑與危險分級，以及所有 flag。
- [關聯訊號](https://go-ip-sentry.pardn.io/zh/correlation-signals.md): Session 對 IP、IP 對裝置、裝置對 IP 三組集合、1 倍／2 倍分級計分、登入失敗與 404 計數及 NAT 邊界。
- [行為訊號](https://go-ip-sentry.pardn.io/zh/behavior-signals.md): 以最近 10 個請求間隔的變異數辨識機器人、極度規律的節奏，以及閒置 15 分鐘重置的長 Session 計分。
- [Session 與指紋](https://go-ip-sentry.pardn.io/zh/session-fingerprint.md): HMAC-SHA256 簽章 Session Cookie、多實例共用 .sessionSecret、SHA-256 裝置指紋與指紋多 Session 偵測。
- [地理偵測](https://go-ip-sentry.pardn.io/zh/geo-detection.md): GeoLite2 啟用條件、24 小時位置快取、以 Haversine 距離偵測時速逾 800 km 的不可能旅行、跨國跳躍與城市切換。
- [Allow 與 Deny 名單](https://go-ip-sentry.pardn.io/zh/access-lists.md): Allow 與 Deny IP 名單如何從 JSON 檔載入、同步到 Redis、優先順序、手動移除與多實例行為。
- [暫時封鎖](https://go-ip-sentry.pardn.io/zh/blocking.md): Block 時長以 2^n × BlockTimeMin 倍增至上限、紀錄累加、零值造成永久封鎖的陷阱與解除方式。
- [Email 通知](https://go-ip-sentry.pardn.io/zh/email-alerts.md): IP 加入 Deny 名單時的 SMTP 通知：設定、自訂主旨與內文、587 埠 STARTTLS、PLAIN 認證與 CC 不投遞限制。
- [中介層](https://go-ip-sentry.pardn.io/zh/middleware.md): 把 go-ip-sentry 接到 Gin 或 net/http、排除健康檢查與輪詢路徑、保留 gin.Recovery，或直接呼叫 Check 自訂回應。
- [事件回報](https://go-ip-sentry.pardn.io/zh/event-reporting.md): 以 LoginFailure 與 NotFound404 回報登入失敗與 404 掃描、每 Session 一小時固定視窗，以及重複計數的副作用。
- [用戶端 IP 解析](https://go-ip-sentry.pardn.io/zh/client-ip.md): go-ip-sentry 取得用戶端 IP 的標頭順序、X-Forwarded-For 可被偽造的原因、代理加固方式與內網判定。
- [設定](https://go-ip-sentry.pardn.io/zh/configuration.md): Config、Redis、Log、Filepath、EmailConfig 欄位的 JSON key 與預設值，以及從 JSON 檔載入完整設定。
- [參數](https://go-ip-sentry.pardn.io/zh/parameters.md): Parameter 每個欄位的 JSON key 與預設：速率、分級門檻、關聯、行為、地理分數、封鎖時長與調整方向。
- [API 參考](https://go-ip-sentry.pardn.io/zh/api-reference.md): golangIPSentry 所有匯出函式、方法與型別：New、Check、中介層、名單管理器、IPGuardianResult、IPItem。
- [Redis Key](https://go-ip-sentry.pardn.io/zh/redis-keys.md): go-ip-sentry 寫入的所有 Redis key，依名單、計數、行為、地理分組，列出型別、TTL、寫入時機與清除指令。
- [已知問題](https://go-ip-sentry.pardn.io/zh/known-issues.md): v1.0.0 已確認缺陷：Redis 中斷 panic、可偽造代理標頭、零值永久封鎖、未生效的 HighRiskCountry 等及因應。
- [已移除 API](https://go-ip-sentry.pardn.io/zh/removed-api.md): go-ip-sentry v0.3.0 移除的符號（TrustManager、BanManager、LogConfig 等）、替代寫法與升級範例。

## Optional

- [Release Notes](https://go-ip-sentry.pardn.io/released/index.md): pardnchiu/go-ip-sentry changelog by version