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) enables docker 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=3

The 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) checks check_and_set(f"replay:{hash}", ttl=window) to reject replays fleet-wide.
  • CircuitBreaker (core/circuit_breaker.py) mirrors failure counts and opened_at timestamps 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 through IntelManager.record_valid_request (push) and is_blocked (check).
  • record_beacon_request (state/beacons.py): per-beacon session bag keyed on (client_ip, JA3, first_seen_ua). Called from DomainRouter._maybe_record_whitelist_and_issue_tokens. Feeds infraguard_active_beacons for 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 of core.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 yes for durability across restarts
  • maxmemory 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...