Release Notes#

v0.5#

The v0.5 release is a large refactor and feature drop across the CLI, plugin system, state layer, and observability. Highlights below.

New CLI commands#

  • infraguard simulate-beacon: fires a fully profile-shaped request through the pipeline. Prints verdict and per-filter breakdown so you can see exactly which invariant a beacon would fail before firing real traffic. See CLI reference.
  • infraguard drop-preview: renders the drop response for a domain without sending traffic. Useful when tuning drop_action.
  • infraguard events tail: streams tracking DB events as JSON lines, pipe-friendly for jq and SIEM ingestion.
  • infraguard profile transpile: converts profiles between C2 frameworks via the shared IR. Native emitters for cobalt_strike, sliver, and mythic_http.
  • infraguard decoy: data-driven decoy site management. Five industry presets ship (banking, financial, healthcare, hospital, infrashield); add more by dropping a YAML file under pages/_templates/industries/.

CLI refactor#

main.py split from a 1323-LOC monolith into per-command modules under infraguard/cli/. Each command is under 150 LOC and testable in isolation.

Router refactor#

DomainRouter.handle() split from a ~320-LOC monolith into ten small private methods (_route_or_drop, _try_fronting, _parse_client_ip, _pre_content_gate, _run_plugin_on_request, _forward_with_failover, _attach_issued_tokens, _run_plugin_on_response, _apply_timing_jitter, _record_request_event). Behavior is byte-identical; each step is now individually reviewable.

Also extracted DomainRoute, the profile loader, and content-guard helpers into infraguard/core/routing/.

Shared state package (Redis-optional)#

New infraguard.state package with a StateBackend protocol and two implementations (InMemoryBackend, RedisBackend). Enables docker compose --scale proxy-node=N safely: the replay cache, circuit-breaker state, dynamic whitelist, per-beacon session bag, and drop-response rate-limit all consult the shared backend. See state-package.

Database migrations#

File-based async SQLite migration runner at infraguard/tracking/migrations/. Replaces the ad-hoc CREATE TABLE IF NOT EXISTS + one-off ALTER TABLE boot logic. Adds a schema_migrations version table, checksum-based drift detection, and a clean per-file “add-a-migration” workflow. See migrations.

Data-driven intel#

Moved seven signature lists from Python constants into rules/*.txt: banned_ips.txt, banned_headers.txt, banned_rdns.txt, cloud_cidrs.txt, ja3_blocklist.txt, scanner_cidrs.txt, scanner_uas.txt. Reload without a code release via SIGHUP or the dashboard reload endpoint. See rules-directory.

Profile IR + registry#

infraguard.profiles.registry centralizes the 8-way parser dispatch that used to be duplicated across three call sites (CLI helper, generate backend, router load path). New C2 support drops in by calling register_parser once.

Auto-rotation watchdog#

New watchdog: config block. Monitors burn score, TLS cert expiry, and (opt-in) cloud spend. Fires infraguard rotate when a threshold is crossed, or alerts via the plugin path in auto_rotate: false mode. See rotation-watchdog.

Observability#

  • OpenTelemetry integration under infraguard.observability (opt-in; no-op if the SDK is not installed). See opentelemetry.
  • Grafana overview dashboard in-tree at deploy/grafana/infraguard.json. See grafana.

New plugins#

Twenty new built-in plugins across six categories:

  • Alerting: pagerduty, telegram_bot
  • Detection: yara_scan, ja4_enricher, p0f_fingerprint, greynoise, http_smuggling
  • Response manipulation: response_canary, html_rewriter, payload_watermark, sig_strip, slow_tarpit, js_challenge, cache_mimicry
  • Session tracking: beacon_labeler, timing_profiler, geoip_enricher
  • Payload security: payload_shred, stager_rate_limit
  • Testing: request_recorder, shadow_block, prom_custom

See Plugins & Alerting.

Cross-C2 profile transpiler#

profile transpile uses the shared C2Profile IR and the parser registry. Native emitters for three targets; others fall back to the InfraGuard JSON representation with a header comment naming the intended target.

LLM-assisted “why blocked?”#

infraguard.integrations.why_blocked feeds a blocked request and the domain’s profile into the local Ollama endpoint. The model explains in plain English which invariant the request violated and how to shape a compliant beacon. Uses the same Ollama config as the existing profile-assist path.

Command Post intel sharing#

Bi-directional blocklist sync and cross-instance JA3 anomaly detection in ui/command_post/intel_sharing.py. STIX 2.1 bundle publisher in ui/command_post/stix_publisher.py for red-team consortium sharing.

Config git integration#

infraguard.config.git_history auto-commits every dashboard mutation to a local git repo (~/.config/infraguard/history.git by default). Recovery via infraguard config log / infraguard config revert.

Security headers middleware#

Dashboard responses now carry CSP, HSTS (HTTPS only), X-Content-Type-Options, X-Frame-Options, Referrer-Policy, and Permissions-Policy. CSP still allows 'unsafe-inline' while the inline dashboard JS/CSS ships; the Vite scaffold under infraguard/ui/web/ is the migration path to drop that.

Data-driven decoy blogs#

pages/*Blog/index.html regenerable from pages/_templates/blog.html.j2 + per-industry YAML. Every existing blog (BankingBlog, FinancialBlog, HealthcareBlog, HospitalBlog, InfraShieldBlog) has been migrated with structural parity confirmed against the originals.

Experimental transports#

Scaffolds shipped for HTTP/3 (QUIC), WebSocket beacon, gRPC beacon, and uTLS ClientHello mimicry under infraguard/listeners/experimental/ and infraguard/core/utls_mimicry.py. Real module scaffolding and TODO checklists in each; wire-in is a follow-up.

Redis service in compose#

Opt-in via --profile scale in the compose file, plus the proxy-node scale block enabled and gated on Redis.

Kubernetes Helm chart#

Ships at deploy/helm/infraguard/. Deploys proxy, dashboard, and optional Redis; wires an HPA that scales the proxy on the infraguard_active_beacons custom metric via prometheus-adapter. See kubernetes.

Observability compose profile#

New --profile observability in docker-compose.yml starts an OpenTelemetry collector, Prometheus, and Grafana with the InfraGuard overview dashboard pre-provisioned. Configs at deploy/otel/config.yaml, deploy/prometheus/prometheus.yml, and deploy/grafana/dashboards.yaml.

Dockerfile changes#

  • Ships the rules/ tree into the image so data-driven intel works out of the box (still overridable at runtime).
  • Exposes 443/udp for HTTP/3 (QUIC) when a h3 listener is configured.
  • VOLUME declaration extended with /app/rules.

Bundle generator fixes#

infraguard config generate bugs found by QA and patched:

  • No longer emits command: infraguard <sub> (double-prefix that Dockerized entrypoints choked on).
  • Dashboard command: now includes -c /app/config/config.yaml.
  • Uses a managed Docker volume (infraguard-data) for the SQLite DB and adds a data-init alpine service to chown it to UID 1000.
  • .env template populates INFRAGUARD_DOMAIN, INFRAGUARD_*_UPSTREAM, and cert paths from CLI flags (previously left blank).
  • api.bind set to 0.0.0.0 so the published container port works.
  • Tmpfs mount for /app/.infraguard (intel-feed cache).
  • Config tracking.db_path forced to ${INFRAGUARD_DB_PATH} instead of leaking a platform-default host path into the bundle.

Wizard fixes#

Path prompts now handle Windows Explorer “Copy as path” (quoted paths), trailing whitespace, and WSL / drive-letter mismatches with diagnostic hints (“Looks like a Windows path but we are on Linux. From WSL / Linux, try: /mnt/f/…”).

Profile-conversion wizard reconnected to the registry-based dispatch after the CLI helper refactor.

Deprecation cleanup#

  • pyproject.toml gains a dev extra with httpx2>=2.0 so the Starlette TestClient stops emitting the “install httpx2” warning (Starlette 0.44+ prefers httpx2 over the legacy httpx package). Install with pip install infraguard[dev].
  • Test suite migrated off deprecated per-request client.get(..., cookies=...) to client.cookies.set(...) on the client instance.
  • pytest.ini_options in pyproject.toml pins asyncio_mode = "auto" and asyncio_default_fixture_loop_scope = "function" so future pytest-asyncio releases do not change the semantics silently.

Bundle: Let’s Encrypt default#

config generate now emits INFRAGUARD_LETSENCRYPT=false by default so a freshly-generated bundle can docker compose up without a non-existent cert path breaking the TLS handshake. Enable properly:

  1. Point DNS for the domain at the host.
  2. Set INFRAGUARD_LETSENCRYPT=true and edit INFRAGUARD_DOMAIN_EMAIL.
  3. docker compose --profile letsencrypt up certbot.
  4. Restart the proxy to pick up the new cert.

Windows console fixes#

infraguard drop-preview no longer crashes with UnicodeEncodeError on Windows shells that have not set UTF-8 mode. The hardcoded U+2192 (->) in the output banner is now ASCII.

Final v0.5 wave#

Every scaffold from earlier in v0.5 is now wired end-to-end:

  • SharedWhitelist consulted by IntelManager.is_blocked and populated by record_valid_request.
  • Beacon session tracking active in the router; feeds the new infraguard_active_beacons Prometheus gauge.
  • DropRateLimiter gates handle_drop; over-quota requests get a bare TCP reset (444) instead of the real drop response.
  • Rotation watchdog + purple-team mirror + OpenTelemetry started from core/app.py lifespan when their config blocks are enabled; graceful shutdown drains each.
  • HTTP/3 QUIC listener functional (real H3 frame adapter).
  • WebSocket beacon transport functional (frame -> Request adapter).
  • uTLS ClientHello mimicry: ProxyHandler._get_client swaps in a curl_cffi.AsyncSession when domain.tls_profile is set.
  • Adversary-emulation self-test shipped as infraguard preflight.
  • 23rd plugin: ml_bot_classifier (logistic regression on nine cheap features; baseline model ships in the plugin).
  • Command Post intel routes live at /api/intel/push, /api/intel/pull, /taxii2/collections/{id}/objects/.
  • Config git history auto-commits every dashboard mutation to ~/.config/infraguard/history.git.

Kubernetes Helm chart#

Ships at deploy/helm/infraguard/ (14 files). Deploys proxy, dashboard, and Redis StatefulSet; wires an HPA that scales the proxy on the infraguard_active_beacons custom metric via prometheus-adapter. See kubernetes.

Observability compose profile#

docker compose --profile observability up -d starts an OTEL collector, Prometheus, and Grafana with the InfraGuard overview dashboard auto-provisioned. Configs at deploy/otel/config.yaml, deploy/prometheus/prometheus.yml, deploy/grafana/dashboards.yaml. See observability-stack.

Dockerfile changes#

  • Ships the rules/ tree in the image so data-driven intel works out of the box (still overridable at runtime).
  • Exposes 443/udp for HTTP/3 (QUIC) when a h3 listener is configured.
  • VOLUME declaration extended with /app/rules.

docker-compose changes#

  • Both proxy and dashboard now bind-mount ./rules:/app/rules:ro.
  • Proxy publishes 443:443/udp for QUIC in addition to TCP.
  • New --profile observability (OTEL + Prometheus + Grafana).
  • Redis service + proxy-node scale block already under --profile scale from earlier in v0.5.

v0.5.1 (late v0.5 wave)#

Follow-ups that landed after v0.5 shipped, all backwards-compatible.

Dashboard plugin management#

  • New Plugins tab in the web dashboard (/static/plugins.html): lists loaded plugins with version and options, toggles enable/disable at runtime without a restart, and a Plugin Marketplace panel that loads any built-in plugin from a picker.
  • New API routes on the proxy dashboard: GET /api/plugins, POST /api/plugins/{name}/enable, POST /api/plugins/{name}/disable. Toggles are persisted back to config.yaml with a config-history commit.
  • Command Post fans the same routes out to every registered instance; ?instance=<name> narrows to one.
  • BasePlugin._runtime_enabled gates every dispatch site in the router and recorder so a disabled plugin stops receiving hooks the instant it is toggled.
  • BUILTIN_PLUGINS short-name registry expanded from 6 to 29 entries so every built-in resolves without a full dotted path.

gRPC beacon transport#

Second-class beacon transport alongside HTTP, WebSocket, and QUIC. Stream/stream RPC with pass-through byte serializers so no .proto codegen is required. Enable with protocol: grpc under listeners:; optional grpcio extra via pip install "infraguard[grpc-listener]". See gRPC Beacon.

Config schema for v0.5 blocks#

StateConfig, WatchdogConfig, ObservabilityConfig, and PurpleTeamConfig are now first-class fields on InfraGuardConfig. Before this fix, Pydantic silently dropped the state:, watchdog:, observability:, and purple_team: top-level keys, so every v0.5 feature that read them via getattr(config, ...) got None and was effectively unreachable from YAML.

Example configs#

Five new example configs under config/examples/ covering the v0.5 subsystems:

  • v05-scale-redis-observability.yaml - Redis shared state + OTEL
  • v05-watchdog-rotation.yaml - auto-rotation on burn + cert expiry
  • v05-purple-team-mirror.yaml - blue-team mirror
  • v05-detection-plugins.yaml - YARA, GreyNoise, ML classifier, canary, p0f, JA4
  • v05-alerter-multichannel.yaml - PagerDuty + Telegram + Slack + Discord + generic webhook + syslog

Bug fixes#

  • Config loader opens YAML with encoding="utf-8", fixing a cp1252 crash on Windows for every example that used box characters.
  • Initial threat-feed refresh no longer blocks startup unless intel.feeds.require_feeds: true; a dead feed used to deadlock the ASGI startup for the full retry budget.
  • Dashboard-to-proxy forwarders now propagate the caller’s Authorization header (or fall back to the dashboard’s own token), so drop-action, profile-swap, and plugin toggle mutations succeed.
  • Plugin loader no longer NameErrors on the success-path log message.
  • Container hardening: proxy and dashboard set INFRAGUARD_SELF_SIGNED_DIR=/app/.infraguard/tls and INFRAGUARD_CONFIG_HISTORY=/app/data/config-history.git so writes land on tmpfs / the data volume, not the read-only home. Runtime image now installs git so the audit repo actually commits.
  • Helm probes use scheme: HTTPS since both the proxy on 443 and the dashboard on 8080 auto-enable TLS when the config has any listener with a tls: block.
  • .dockerignore added so a Windows build context does not choke on broken symlinks under nested venvs (pulumi_deploy/venv/lib64).