Default the netblock and AS number anomaly thresholds (closes #410) #484

Merged
clawbot merged 3 commits from issue-410-anomaly-net-asn-defaults into next 2026-11-20 06:42:26 +01:00
7 changed files with 149 additions and 32 deletions
Showing only changes of commit b8abb87738 - Show all commits

No files matched your search

+11 -9
View File
@@ -288,7 +288,9 @@ account, a key, a token or an alert destination stays off until you give one.
- An anomaly is more requests or bytes than an `SWW_WAF_ANOMALY_` threshold
allows. Crossing a threshold sends one `anomaly` alert to the alert
destinations, and does nothing else: no client is banned, rate limited or
blocked.
blocked. The thresholds per netblock and per AS number are on by default, set
high enough to alert only on obvious abuse. They are a starting point: tune
them to your own site's traffic, which the metrics show.
- An invalid setting stops the process at start with one log line naming the
variable and what is wrong with the value. The settings in effect are logged
on one line at start, with tokens, keys and webhook paths shown as `********`.
@@ -396,16 +398,16 @@ Every setting the code reads, with its default:
| `SWW_WAF_ANOMALY_CLIENT_REQUESTS_PER_HOUR` | `off` | Sends one alert to the alert destinations when one client makes more requests than this in an hour, a count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_CLIENT_BYTES_PER_MINUTE` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for one client in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_CLIENT_BYTES_PER_HOUR` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for one client in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_NET_REQUESTS_PER_MINUTE` | `off` | Sends one alert to the alert destinations when the netblock around a client makes more requests than this in a minute, a count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_NET_REQUESTS_PER_HOUR` | `off` | Sends one alert to the alert destinations when the netblock around a client makes more requests than this in an hour, a count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_NET_BYTES_PER_MINUTE` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for the netblock around a client in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_NET_BYTES_PER_HOUR` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for the netblock around a client in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_NET_REQUESTS_PER_MINUTE` | `1200` | Sends one alert to the alert destinations when the netblock around a client makes more requests than this in a minute, a count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_NET_REQUESTS_PER_HOUR` | `15000` | Sends one alert to the alert destinations when the netblock around a client makes more requests than this in an hour, a count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_NET_BYTES_PER_MINUTE` | `5G` | Sends one alert to the alert destinations when more bytes than this are counted for the netblock around a client in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_NET_BYTES_PER_HOUR` | `50G` | Sends one alert to the alert destinations when more bytes than this are counted for the netblock around a client in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_NET_V4_PREFIX` | `24` | The prefix length of the netblock around an IPv4 client that the `SWW_WAF_ANOMALY_NET_` thresholds count, from 0 to 32. Those thresholds only send alerts. |
| `SWW_WAF_ANOMALY_NET_V6_PREFIX` | `48` | The prefix length of the netblock around an IPv6 client that the `SWW_WAF_ANOMALY_NET_` thresholds count, from 0 to 128. Those thresholds only send alerts. |
| `SWW_WAF_ANOMALY_ASN_REQUESTS_PER_MINUTE` | `off` | Sends one alert to the alert destinations when one AS number makes more requests than this in a minute, a count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_ASN_REQUESTS_PER_HOUR` | `off` | Sends one alert to the alert destinations when one AS number makes more requests than this in an hour, a count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_ASN_BYTES_PER_MINUTE` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for one AS number in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_ASN_BYTES_PER_HOUR` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for one AS number in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_ASN_REQUESTS_PER_MINUTE` | `6000`, or `off` while the lookup source is `off` | Sends one alert to the alert destinations when one AS number makes more requests than this in a minute, a count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_ASN_REQUESTS_PER_HOUR` | `75000`, or `off` while the lookup source is `off` | Sends one alert to the alert destinations when one AS number makes more requests than this in an hour, a count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_ASN_BYTES_PER_MINUTE` | `25G`, or `off` while the lookup source is `off` | Sends one alert to the alert destinations when more bytes than this are counted for one AS number in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_ASN_BYTES_PER_HOUR` | `250G`, or `off` while the lookup source is `off` | Sends one alert to the alert destinations when more bytes than this are counted for one AS number in an hour, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_TOTAL_REQUESTS_PER_MINUTE` | `off` | Sends one alert to the alert destinations when the whole service gets more requests than this in a minute, a count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_TOTAL_REQUESTS_PER_HOUR` | `off` | Sends one alert to the alert destinations when the whole service gets more requests than this in an hour, a count. No client is banned, rate limited or blocked. |
| `SWW_WAF_ANOMALY_TOTAL_BYTES_PER_MINUTE` | `off` | Sends one alert to the alert destinations when more bytes than this are counted for the whole service in a minute, a size. `SWW_WAF_BYTES_COUNTED` says which bytes count. No client is banned, rate limited or blocked. |
+8 -6
View File
@@ -2113,12 +2113,14 @@ host, sharing one address, would often fetch too close together.
### Anomaly thresholds
These only alert; nothing is blocked. None is set by default, and a threshold
left unset sends no alert. An alert needs a destination only the operator can
supply, and what counts as unusual depends on each service's normal traffic,
which the metrics show. They reveal a widely distributed scraper, thousands of
addresses at low rates each, which the per-client limits do not see. A low
percentage for its `asn=` tag in `SWW_WAF_TAG_LIMIT_PERCENT` is the response.
These only alert; nothing is blocked. The thresholds per netblock and per AS
number have defaults high enough to alert only on obvious abuse. The others are
off by default. What counts as unusual depends on each service's normal traffic,
which the metrics show, so the defaults are a starting point for the operator to
tune. An alert goes nowhere until the operator sets a destination. The
thresholds reveal a widely distributed scraper, thousands of addresses at low
rates each, which the per-client limits do not see. A low percentage for its
`asn=` tag in `SWW_WAF_TAG_LIMIT_PERCENT` is the response.
- Requests and body bytes, as `SWW_WAF_BYTES_COUNTED` counts them, are counted
per minute and per hour, for each of:
+19 -2
View File
@@ -378,8 +378,9 @@ Crossing a threshold sends one `anomaly` alert to the destinations under
Each scope has four thresholds: the most requests and the most body bytes
counted in a minute and in an hour. The bytes are those `SWW_WAF_BYTES_COUNTED`
names. Requests are counts, bytes are sizes. Each is `off` by default. The four
thresholds per client are:
names. Requests are counts, bytes are sizes. Each is `off` by default, except
those per netblock and per AS number listed below. The four thresholds per
client are:
- `SWW_WAF_ANOMALY_CLIENT_REQUESTS_PER_MINUTE`;
- `SWW_WAF_ANOMALY_CLIENT_REQUESTS_PER_HOUR`;
@@ -403,6 +404,22 @@ as `REQUESTS_PER_MINUTE`:
`office=203.0.113.0/24,scraper-x=198.51.100.0/22`. An item without `=` or a
name, or with a bad netblock, is refused. So is a name used twice.
The thresholds per netblock and per AS number have defaults set high enough to
alert only on obvious abuse:
- per netblock:
- `REQUESTS_PER_MINUTE` `1200` and `REQUESTS_PER_HOUR` `15000`, ten clients
at the default rate limits;
- `BYTES_PER_HOUR` `50G`, one client at the default byte limit per hour;
- `BYTES_PER_MINUTE` `5G`, a tenth of that.
- per AS number, five times those: `6000`, `75000`, `25G` and `250G`.
While `SWW_WAF_LOOKUP_SOURCE` is `off`, no request has an AS number, so the
thresholds per AS number are `off` by default. Setting one then stops the start.
These defaults are a starting point. Tune them to your own site's traffic, which
the metrics show.
## Settings given as files
To give a token as a file, as "Tokens" under "Deployment" in
+51 -13
View File
@@ -313,7 +313,9 @@ type WAF struct {
// per netblock around a client (SWW_WAF_ANOMALY_NET_*), per AS number
// (SWW_WAF_ANOMALY_ASN_*), for the whole service (SWW_WAF_ANOMALY_TOTAL_*)
// and per watched netblock (SWW_WAF_ANOMALY_WATCHED_NET_*), each 0 while
// it is off. AnomalyNetV4Prefix and AnomalyNetV6Prefix are the lengths
// it is off. Only the thresholds per netblock and per AS number are on by
// default, those per AS number only while clients are looked up.
// AnomalyNetV4Prefix and AnomalyNetV6Prefix are the lengths
// of the netblock around a client (SWW_WAF_ANOMALY_NET_V4_PREFIX and
// SWW_WAF_ANOMALY_NET_V6_PREFIX), and AnomalyWatchedNets the watched
// netblocks (SWW_WAF_ANOMALY_WATCHED_NETS).
@@ -555,11 +557,6 @@ func WAFFromEnvironment(v *viper.Viper) (*WAF, error) {
"SWW_WAF_ALERT_MAX_PER_HOUR",
"60",
),
AnomalyClient: env.thresholds("SWW_WAF_ANOMALY_CLIENT_"),
AnomalyNet: env.thresholds("SWW_WAF_ANOMALY_NET_"),
AnomalyASN: env.thresholds("SWW_WAF_ANOMALY_ASN_"),
AnomalyTotal: env.thresholds("SWW_WAF_ANOMALY_TOTAL_"),
AnomalyWatchedNet: env.thresholds("SWW_WAF_ANOMALY_WATCHED_NET_"),
AnomalyNetV4Prefix: env.v4Prefix(
"SWW_WAF_ANOMALY_NET_V4_PREFIX",
"24",
@@ -578,6 +575,7 @@ func WAFFromEnvironment(v *viper.Viper) (*WAF, error) {
// The app gets the headers by default, unless no client is looked up.
cfg.AddLookupHeaders = env.boolean("SWW_WAF_ADD_LOOKUP_HEADERS",
strconv.FormatBool(cfg.LookupSource != LookupSourceOff))
env.anomalyThresholds(cfg)
cfg.BlocklistAction, cfg.BlocklistLimitPercent = env.action(
BlocklistActionSetting, string(ReputationActionDeny))
cfg.DNSBLAbuseIPDBAction, cfg.DNSBLAbuseIPDBLimitPercent = env.action(
@@ -2693,15 +2691,55 @@ func (e *environment) duration(name, defaultValue string) time.Duration {
return duration
}
// thresholdDefaults are the defaults of a scope's four anomaly thresholds,
// each a count, a size or off.
type thresholdDefaults struct {
requestsPerMinute, requestsPerHour, bytesPerMinute, bytesPerHour string
}
// anomalyThresholds reads the anomaly thresholds of every scope into cfg.
// Only those per netblock and per AS number are on by default, high
// enough to alert on obvious abuse alone. Those per netblock count the
// requests of ten clients at the default per-client rate limits, and the
// bytes of one client at its default byte limit per hour, a tenth of
// that in a minute. Those per AS number are five times those per
// netblock. They are off by default while no client is looked up, since
// no request then has an AS number.
func (e *environment) anomalyThresholds(cfg *WAF) {
allOff := thresholdDefaults{off, off, off, off}
asnDefaults := thresholdDefaults{
requestsPerMinute: "6000", requestsPerHour: "75000",
bytesPerMinute: "25G", bytesPerHour: "250G",
}
if cfg.LookupSource == LookupSourceOff {
asnDefaults = allOff
}
cfg.AnomalyClient = e.thresholds("SWW_WAF_ANOMALY_CLIENT_", allOff)
cfg.AnomalyNet = e.thresholds("SWW_WAF_ANOMALY_NET_", thresholdDefaults{
requestsPerMinute: "1200", requestsPerHour: "15000",
bytesPerMinute: "5G", bytesPerHour: "50G",
})
cfg.AnomalyASN = e.thresholds("SWW_WAF_ANOMALY_ASN_", asnDefaults)
cfg.AnomalyTotal = e.thresholds("SWW_WAF_ANOMALY_TOTAL_", allOff)
cfg.AnomalyWatchedNet = e.thresholds("SWW_WAF_ANOMALY_WATCHED_NET_",
allOff)
}
// thresholds reads the four anomaly thresholds whose settings' names
// start with prefix: requests and bytes per minute and per hour. Each is
// off by default.
func (e *environment) thresholds(prefix string) anomaly.Thresholds {
// start with prefix: requests and bytes per minute and per hour.
func (e *environment) thresholds(
prefix string, defaults thresholdDefaults,
) anomaly.Thresholds {
return anomaly.Thresholds{
RequestsPerMinute: e.count(prefix+"REQUESTS_PER_MINUTE", off),
RequestsPerHour: e.count(prefix+"REQUESTS_PER_HOUR", off),
BytesPerMinute: e.size(prefix+"BYTES_PER_MINUTE", off),
BytesPerHour: e.size(prefix+"BYTES_PER_HOUR", off),
RequestsPerMinute: e.count(prefix+"REQUESTS_PER_MINUTE",
defaults.requestsPerMinute),
RequestsPerHour: e.count(prefix+"REQUESTS_PER_HOUR",
defaults.requestsPerHour),
BytesPerMinute: e.size(prefix+"BYTES_PER_MINUTE",
defaults.bytesPerMinute),
BytesPerHour: e.size(prefix+"BYTES_PER_HOUR", defaults.bytesPerHour),
}
}
+40 -1
View File
@@ -178,6 +178,17 @@ func loggedAnomalyDefaults() map[string]string {
logged[name] = off
}
maps.Copy(logged, map[string]string{
anomalyNet + requestsPerMinute: "1200",
anomalyNet + requestsPerHour: "15000",
anomalyNet + bytesPerMinute: "5G",
anomalyNet + bytesPerHour: "50G",
anomalyASN + requestsPerMinute: "6000",
anomalyASN + requestsPerHour: "75000",
anomalyASN + bytesPerMinute: "25G",
anomalyASN + bytesPerHour: "250G",
})
return logged
}
@@ -1565,7 +1576,35 @@ func TestAnomalySettingsDefaults(t *testing.T) {
t.Parallel()
cfg := wafFromEnvironment(t, environment{})
wantAllOff(t, cfg)
const gibibyte = int64(1) << 30
want := map[string]anomaly.Thresholds{
anomalyClient: {},
anomalyNet: {
RequestsPerMinute: 1200, RequestsPerHour: 15000,
BytesPerMinute: 5 * gibibyte, BytesPerHour: 50 * gibibyte,
},
anomalyASN: {
RequestsPerMinute: 6000, RequestsPerHour: 75000,
BytesPerMinute: 25 * gibibyte, BytesPerHour: 250 * gibibyte,
},
anomalyTotal: {}, anomalyWatchedNet: {},
}
if got := thresholdsByScope(cfg); !maps.Equal(got, want) {
t.Errorf("thresholds by scope\n%+v\nwant\n%+v", got, want)
}
// With no client looked up, the thresholds per AS number are off.
want[anomalyASN] = anomaly.Thresholds{}
got := thresholdsByScope(
wafFromEnvironment(t, environment{lookupSource: off}))
if !maps.Equal(got, want) {
t.Errorf("with %s off, thresholds by scope\n%+v\nwant\n%+v",
lookupSource, got, want)
}
if cfg.AnomalyNetV4Prefix != 24 || cfg.AnomalyNetV6Prefix != 48 ||
len(cfg.AnomalyWatchedNets) != 0 {
+16
View File
@@ -32,6 +32,22 @@ const (
bytesPerHour = "BYTES_PER_HOUR"
)
// netAndASNThresholdsOff returns the anomaly thresholds per netblock and
// per AS number, the ones on by default, each set to off.
func netAndASNThresholdsOff() map[string]string {
settings := map[string]string{}
for _, scope := range []string{anomalyNet, anomalyASN} {
for _, end := range []string{
requestsPerMinute, requestsPerHour, bytesPerMinute, bytesPerHour,
} {
settings[scope+end] = off
}
}
return settings
}
// The other anomaly settings.
const (
anomalyNetV4Prefix = "SWW_WAF_ANOMALY_NET_V4_PREFIX"
+4 -1
View File
@@ -456,7 +456,9 @@ func (w *wafAndParts) banAbuseIPDBBlacklist(
// at abuseIPDBURL while env sets SWW_WAF_ABUSEIPDB_KEY, and its blacklist is
// fetched from abuseIPDBBlacklistURL.
// SWW_WAF_CORE_RULE_SET_MODE is off unless env sets it, so that only the tests of the
// Core Rule Set have their requests inspected by it.
// Core Rule Set have their requests inspected by it. Likewise the anomaly thresholds
// per netblock and per AS number are off unless env sets them, so that only the tests
// of the anomaly thresholds count requests.
func newWAF(
t *testing.T,
geojsURL string,
@@ -486,6 +488,7 @@ func newWAFWith(
settings[lookupSource] = off
}
maps.Copy(settings, netAndASNThresholdsOff())
maps.Copy(settings, env)
cfg, err := config.WAFFromEnvironment(configtest.Viper(settings))