Files

T

check / check (push) Waiting to run

Details

README rewritten from scratch so a newcomer can follow it (closes #154 , closes #155 )

The old README opened with project history and one list of a hundred
settings. The new one leads with what smallwebwaf is, what it protects
against, how to build and deploy it, how it sits in front of the app,
what happens to a request, the settings most deployments touch, how to
check it works and how to develop it. The reference material, every
setting, bans, rule files, the Core Rule Set, the admin endpoints, the
request log, alerts, metrics, state files, lookups, reputation sources,
the image and gitea, moves to files under docs/, each linked from the
README. Every statement was checked against the code on next.

Model: fable-5-1

2026-10-22 21:02:38 +00:00

3.1 KiB

Raw Blame History

The metrics

GET /_smallwebwaf/metrics answers in the Prometheus text format. The requirements are under "Metrics endpoint" in SPEC.md; this file lists the metrics. Every metric carries the label instance, set to SWWAF_INSTANCE_NAME; Prometheus keeps it as exported_instance unless the scrape sets honor_labels: true. No metric carries a client's address.

Traffic

smallwebwaf_requests_total, smallwebwaf_request_bytes_total and smallwebwaf_response_bytes_total, by status_class such as 2xx and by action;
smallwebwaf_request_duration_seconds and smallwebwaf_upstream_duration_seconds, as histograms;
smallwebwaf_requests_in_flight.

Limits and bans

smallwebwaf_rate_limit_hits_total, by window and by kind (requests, bytes or refusals);
smallwebwaf_size_and_time_limit_hits_total, by limit, the setting passed;
smallwebwaf_offences_total, by kind;
smallwebwaf_bans_made_total, by cause;
smallwebwaf_active_bans and smallwebwaf_permanent_bans.

Attack detection

smallwebwaf_rule_matches_total, by rule_id and action, and smallwebwaf_rules_loaded;
smallwebwaf_waf_matches_total, by mode and rule_id, for the rules that fired.

Countries and AS numbers

For the SWWAF_METRICS_TOP_N busiest of each, the rest as other:

smallwebwaf_country_requests_total, smallwebwaf_country_request_bytes_total, smallwebwaf_country_response_bytes_total and smallwebwaf_country_list_refusals_total, by country;
smallwebwaf_asn_requests_total, smallwebwaf_asn_request_bytes_total and smallwebwaf_asn_response_bytes_total, by asn.

Lookups

smallwebwaf_geojs_requests_total and smallwebwaf_geojs_failures_total;
smallwebwaf_geojs_unanswered_total: the requests that needed an answer and went on without it;
with the file source, smallwebwaf_lookup_database_last_read_timestamp_seconds and smallwebwaf_lookup_database_read_failures_total.

Reputation sources

By source: each list's URL, each zone, and abuseipdb:

smallwebwaf_reputation_hits_total, smallwebwaf_reputation_queries_total and smallwebwaf_reputation_failures_total;
smallwebwaf_reputation_last_fetch_timestamp_seconds, for a list;
smallwebwaf_reputation_daily_budget_remaining, for AbuseIPDB.

State files

By file:

smallwebwaf_state_file_writes_total, smallwebwaf_state_file_write_failures_total, smallwebwaf_state_file_last_write_timestamp_seconds and smallwebwaf_state_file_size_bytes;
smallwebwaf_state_file_edits_taken_in_total and smallwebwaf_state_file_edits_set_aside_total;
smallwebwaf_tracked_clients: the clients in the table.

Remote log, alerts and the process

while a syslog server is set, smallwebwaf_remote_log_lines_sent_total, smallwebwaf_remote_log_lines_dropped_total and smallwebwaf_remote_log_buffer_depth;
by destination, smallwebwaf_alerts_sent_total, smallwebwaf_alerts_failed_total, smallwebwaf_alerts_suppressed_total and smallwebwaf_alerts_dropped_total;
Go's own go_ metrics and the process's process_ metrics.

3.1 KiB Raw Blame History