README
¶
ipreputation
Scores the source IP against threat intelligence and blocks or flags the ones that come back dirty.
Known botnet nodes, scanners and addresses with a history of abuse tend to show up on
reputation feeds long before they show up in your logs. This plugin asks a Provider for a
score from 0 to 100, then applies two thresholds: one where you want to know, and one where
you want it stopped. Results are cached so you are not paying for a lookup on every request.
Use it when
- You're being hit by automated credential stuffing from rented infrastructure
- You already pay for a threat feed and want it enforced at the auth boundary
- You want a cheap first filter so the expensive checks run on fewer requests
Skip it when
- You have no
Providerwired. The plugin needs a data source and does not ship one - Your users are largely on carrier-grade NAT or shared mobile IPs, where one bad actor poisons the score for thousands of innocent people
- Latency on the auth path is tight and your provider is a remote HTTP call
Wiring
authsome.WithPlugin(ipreputation.New(ipreputation.Config{
Provider: myThreatFeed, // implements ipreputation.Provider
BlockThreshold: 80,
WarnThreshold: 50,
CacheTTL: 6 * time.Hour,
}))
Config
| Field | Type | Default | What it does |
|---|---|---|---|
Provider |
Provider |
none | Where scores come from. Required |
BlockThreshold |
int |
80 |
Score at or above this is refused |
WarnThreshold |
int |
50 |
Score at or above this is flagged but allowed |
CacheTTL |
time.Duration |
6h |
How long a score stays cached |
BlockMessage |
string |
see settings | Error text returned on a block |
Settings
| Key | Default |
|---|---|
ipreputation.block_threshold |
80 |
ipreputation.warn_threshold |
50 |
ipreputation.cache_ttl_hours |
6 |
ipreputation.block_message |
access denied due to IP reputation |
Lifecycle hooks
| Hook | What happens |
|---|---|
BeforeSignUp |
Blocks registration from a high-scoring address |
BeforeSignIn |
Blocks the sign-in before credentials are checked |
BeforePrincipalAuth |
Same gate for non-user principals |
Related
vpndetect classifies the kind of connection. This plugin scores the address itself. Running
both gives you two independent reasons to be suspicious.
Documentation
¶
Overview ¶
contract.go: Wires the ipreputation plugin into the forge-dashboard contract surface via plugin.ContractContributor.
Package ipreputation checks IP addresses against threat intelligence sources and blocks or flags high-risk IPs during authentication.
Index ¶
- Variables
- type Config
- type IPReputation
- type Plugin
- func (p *Plugin) DeclareSettings(m *settings.Manager) error
- func (p *Plugin) Name() string
- func (p *Plugin) OnBeforePrincipalAuth(ctx context.Context, a *principal.AuthAttempt) error
- func (p *Plugin) OnBeforeSignIn(ctx context.Context, req *account.SignInRequest) error
- func (p *Plugin) OnBeforeSignUp(ctx context.Context, req *account.SignUpRequest) error
- func (p *Plugin) OnInit(_ context.Context, engine plugin.Engine) error
- func (p *Plugin) RegisterContract(d *dispatcher.Dispatcher, reg contract.Registry, wreg contract.WardenRegistry, ...) error
- type Provider
Constants ¶
This section is empty.
Variables ¶
var ( // SettingBlockThreshold is the score at or above which IPs are blocked. SettingBlockThreshold = settings.Define("ipreputation.block_threshold", 80, settings.WithDisplayName("Block Threshold"), settings.WithDescription("Score at or above which IPs are blocked"), settings.WithCategory("IP Reputation"), settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp), settings.WithEnforceable(), settings.WithUIValidation(formconfig.Validation{Min: intPtr(0), Max: intPtr(100)}), settings.WithHelpText("Score at or above which IPs are blocked (0-100)"), settings.WithOrder(10), ) // SettingWarnThreshold is the score at or above which IPs are flagged with a warning. SettingWarnThreshold = settings.Define("ipreputation.warn_threshold", 50, settings.WithDisplayName("Warn Threshold"), settings.WithDescription("Score at or above which IPs are flagged with a warning"), settings.WithCategory("IP Reputation"), settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp), settings.WithUIValidation(formconfig.Validation{Min: intPtr(0), Max: intPtr(100)}), settings.WithHelpText("Score at or above which IPs are flagged with a warning (0-100)"), settings.WithOrder(20), ) // SettingCacheTTLHours is how long IP reputation results are cached, in hours. SettingCacheTTLHours = settings.Define("ipreputation.cache_ttl_hours", 6, settings.WithDisplayName("Cache TTL (Hours)"), settings.WithDescription("How long IP reputation results are cached"), settings.WithCategory("IP Reputation"), settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp), settings.WithHelpText("How long IP reputation results are cached, in hours"), settings.WithOrder(30), ) // SettingBlockMessage is the error message shown when an IP is blocked. SettingBlockMessage = settings.Define("ipreputation.block_message", "access denied due to IP reputation", settings.WithDisplayName("Block Message"), settings.WithDescription("Error message shown when an IP is blocked"), settings.WithCategory("IP Reputation"), settings.WithScopes(settings.ScopeGlobal, settings.ScopeApp), settings.WithHelpText("Error message shown when an IP is blocked"), settings.WithOrder(40), ) )
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Provider is the reputation data source.
Provider Provider
// BlockThreshold is the score at/above which IPs are blocked (default: 80).
BlockThreshold int
// WarnThreshold is the score at/above which IPs are flagged (default: 50).
WarnThreshold int
// CacheTTL is how long reputation results are cached (default: 6h).
CacheTTL time.Duration
// BlockMessage is the error message on block.
BlockMessage string
// MaxCachedIPs bounds the in-memory reputation cache; the least
// recently used address is dropped when it is full (default: 10000).
MaxCachedIPs int
}
Config configures the IP reputation plugin.
type IPReputation ¶
type IPReputation struct {
IP string `json:"ip"`
Score int `json:"score"` // 0 (clean) to 100 (malicious)
Categories []string `json:"categories,omitempty"`
ISP string `json:"isp,omitempty"`
ASN int `json:"asn,omitempty"`
IsBlacklisted bool `json:"is_blacklisted"`
Source string `json:"source"`
ExpiresAt time.Time `json:"expires_at"`
}
IPReputation represents the reputation score for an IP address.
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin checks IP reputation before authentication.
func (*Plugin) DeclareSettings ¶
DeclareSettings implements plugin.SettingsProvider. It registers all IP reputation-related configurable settings.
func (*Plugin) OnBeforePrincipalAuth ¶
OnBeforePrincipalAuth checks the IP reputation of a machine caller.
The same check sign-in gets. API-key traffic reaches strategy.Authenticate and fires none of the sign-in hooks, so without this a leaked key works from any address in the world.
func (*Plugin) OnBeforeSignIn ¶
OnBeforeSignIn checks the IP reputation.
func (*Plugin) OnBeforeSignUp ¶
OnBeforeSignUp checks the IP reputation.
func (*Plugin) RegisterContract ¶
func (p *Plugin) RegisterContract( d *dispatcher.Dispatcher, reg contract.Registry, wreg contract.WardenRegistry, engine plugin.Engine, ) error
Source Files
Directories