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 tuningdrop_action.infraguard events tail: streams tracking DB events as JSON lines, pipe-friendly forjqand SIEM ingestion.infraguard profile transpile: converts profiles between C2 frameworks via the shared IR. Native emitters forcobalt_strike,sliver, andmythic_http.infraguard decoy: data-driven decoy site management. Five industry presets ship (banking,financial,healthcare,hospital,infrashield); add more by dropping a YAML file underpages/_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
h3listener is configured. VOLUMEdeclaration 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 adata-initalpine service to chown it to UID 1000. .envtemplate populatesINFRAGUARD_DOMAIN,INFRAGUARD_*_UPSTREAM, and cert paths from CLI flags (previously left blank).api.bindset to0.0.0.0so the published container port works.- Tmpfs mount for
/app/.infraguard(intel-feed cache). - Config
tracking.db_pathforced 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.tomlgains adevextra withhttpx2>=2.0so the Starlette TestClient stops emitting the “install httpx2” warning (Starlette 0.44+ prefers httpx2 over the legacyhttpxpackage). Install withpip install infraguard[dev].- Test suite migrated off deprecated per-request
client.get(..., cookies=...)toclient.cookies.set(...)on the client instance. pytest.ini_optionsinpyproject.tomlpinsasyncio_mode = "auto"andasyncio_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:
- Point DNS for the domain at the host.
- Set
INFRAGUARD_LETSENCRYPT=trueand editINFRAGUARD_DOMAIN_EMAIL. docker compose --profile letsencrypt up certbot.- 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:
SharedWhitelistconsulted byIntelManager.is_blockedand populated byrecord_valid_request.- Beacon session tracking active in the router; feeds the new
infraguard_active_beaconsPrometheus gauge. DropRateLimitergateshandle_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.pylifespan 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_clientswaps in acurl_cffi.AsyncSessionwhendomain.tls_profileis 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
h3listener is configured. VOLUMEdeclaration extended with/app/rules.
docker-compose changes#
- Both proxy and dashboard now bind-mount
./rules:/app/rules:ro. - Proxy publishes
443:443/udpfor QUIC in addition to TCP. - New
--profile observability(OTEL + Prometheus + Grafana). - Redis service +
proxy-nodescale block already under--profile scalefrom 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 toconfig.yamlwith a config-history commit. - Command Post fans the same routes out to every registered
instance;
?instance=<name>narrows to one. BasePlugin._runtime_enabledgates every dispatch site in the router and recorder so a disabled plugin stops receiving hooks the instant it is toggled.BUILTIN_PLUGINSshort-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 + OTELv05-watchdog-rotation.yaml- auto-rotation on burn + cert expiryv05-purple-team-mirror.yaml- blue-team mirrorv05-detection-plugins.yaml- YARA, GreyNoise, ML classifier, canary, p0f, JA4v05-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
Authorizationheader (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/tlsandINFRAGUARD_CONFIG_HISTORY=/app/data/config-history.gitso writes land on tmpfs / the data volume, not the read-only home. Runtime image now installsgitso the audit repo actually commits. - Helm probes use
scheme: HTTPSsince both the proxy on 443 and the dashboard on 8080 auto-enable TLS when the config has any listener with atls:block. .dockerignoreadded so a Windows build context does not choke on broken symlinks under nested venvs (pulumi_deploy/venv/lib64).