Shared State Package#
Added in v0.5. The infraguard.state package exposes a small
StateBackend protocol covering the operations the pipeline needs
(key/value with TTL, atomic check_and_set, shared counters). Two
implementations ship:
InMemoryBackend(default) preserves the historical single-node behavior.RedisBackend(opt-in) enablesdocker compose --scale proxy-node=N.
Why#
Before v0.5, the replay cache, circuit-breaker state, dynamic
whitelist, and login rate-limit all lived in per-process Python
objects. That made docker compose --scale proxy-node=N unsafe: an
attacker whose first attempt hit node A could replay against node B,
and a breaker that tripped on one node stayed closed on the others.
The state package fixes that. Behavior is identical on a single-node deploy; the Redis backend adds cluster-wide consistency when enabled.
Configure#
state:
backend: memory # default; or "redis"
redis_url: "redis://redis:6379/0" # only used when backend=redis
key_prefix: "infraguard:"Turn on Redis at deploy time with the compose profile:
docker compose --profile scale up -d --scale proxy-node=3The bundle’s docker-compose.yml (generated by
infraguard config generate) already declares the redis service and
the proxy-node scale block behind the scale profile.
What uses the backend#
Initial wiring in v0.5:
ReplayFilter(pipeline/replay_filter.py) checkscheck_and_set(f"replay:{hash}", ttl=window)to reject replays fleet-wide.CircuitBreaker(core/circuit_breaker.py) mirrors failure counts andopened_attimestamps so a tripped breaker on one node opens on the others.
Also wired in v0.5 (in the infraguard/state/ subpackage), all now
active in the hot path:
SharedWhitelist(state/whitelist.py): dynamic whitelist entries a beacon earned on any replica are visible to all replicas. Wired throughIntelManager.record_valid_request(push) andis_blocked(check).record_beacon_request(state/beacons.py): per-beacon session bag keyed on(client_ip, JA3, first_seen_ua). Called fromDomainRouter._maybe_record_whitelist_and_issue_tokens. Feedsinfraguard_active_beaconsfor the Kubernetes HPA.DropRateLimiter(state/drop_rate_limit.py): per-source-IP rate-limit on the drop response so a scanner does not turn N replicas into an amplifier. Consulted at the top ofcore.drop.handle_drop; over-quota requests receive a bare TCP reset (Response(status_code=444)).
Failure mode#
Every state-backend call is best-effort. A Redis blip logs at DEBUG and falls back to per-process behavior. The pipeline never blocks on Redis.
Redis service#
The redis:7-alpine container ships under the scale compose
profile with:
appendonly yesfor durability across restartsmaxmemory 256mb/allkeys-lru- healthcheck (
redis-cli ping, 10s interval)
Inspect keys directly:
docker exec -it infraguard-redis redis-cli
> KEYS infraguard:*
> GET infraguard:kv:replay:abc123...