Plugins & Alerting#
Plugins receive events from InfraGuard, extend the request pipeline, and dispatch real-time alerts. As of v0.5 InfraGuard ships 20+ built-in plugins across six categories:
- Alerting:
slack,discord,generic_webhook,syslog,elasticsearch,wazuh,pagerduty,telegram_bot - Detection:
yara_scan,ja4_enricher,p0f_fingerprint,greynoise,http_smuggling,ml_bot_classifier - 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 helpers:
request_recorder,shadow_block,prom_custom
Runtime management from the dashboard#
Since v0.5 the web dashboard has a Plugins tab (/static/plugins.html)
that lists every loaded plugin, shows its version and options, and
toggles it enable/disable at runtime without a restart. A Plugin
Marketplace panel underneath lists every built-in plugin not yet
loaded; clicking + Add & Enable imports the module, wires it into
the running plugin list, calls its on_startup hook, and writes the
change back to config.yaml so it survives a restart.
The Command Post exposes the same routes and fans out to every registered instance:
GET /api/plugins- list plugins on every instancePOST /api/plugins/{name}/enable[?instance=<name>]POST /api/plugins/{name}/disable[?instance=<name>]
Omit ?instance= to broadcast to every instance in the Command Post
config; pass ?instance=proxy to target one.
Every dashboard-driven toggle is committed to the config-history git repo so an operator can audit or roll back a change.
The built-in plugin registry (short-name → module path) lives in
infraguard/plugins/builtin/__init__.py and
covers all 29 built-in plugins:
discord, elasticsearch, generic_webhook, pagerduty, slack,
syslog, telegram_bot, wazuh, greynoise, ml_bot_classifier,
response_canary, yara_scan, geoip_enricher, ja4_enricher,
p0f_fingerprint, beacon_labeler, js_challenge, html_rewriter,
sig_strip, cache_mimicry, http_smuggling, shadow_block,
slow_tarpit, stager_rate_limit, payload_shred,
payload_watermark, prom_custom, request_recorder,
timing_profiler.
Schema#
plugins:
- infraguard.plugins.builtin.discord
- infraguard.plugins.builtin.slack
plugin_settings:
discord:
enabled: true
event_filter:
only_blocked: false # true = only alert on blocked requests
min_score: 0.5 # minimum pipeline score to alert on
options:
webhook_url: "${DISCORD_WEBHOOK_URL}"
username: "InfraGuard"
slack:
enabled: true
event_filter:
only_blocked: true
min_score: 0.7
options:
webhook_url: "${SLACK_WEBHOOK_URL}"
channel: "#red-team-alerts"Discord#
Each event generates an embed with:
- Source IP and geolocation
- Pipeline score and filter that triggered the block
- Domain and path
- User-Agent
- Timestamp
High-value phishing.club events (credentials submitted, MFA captured) generate @here pings.
Slack#
Identical event data, delivered as Block Kit message to the configured channel.
Syslog#
Forwards structured log events to a syslog endpoint (UDP/TCP). Useful for SIEM ingestion.
plugins:
- infraguard.plugins.builtin.syslog
plugin_settings:
syslog:
enabled: true
options:
host: "siem.internal"
port: 514
protocol: "udp" # udp | tcp
facility: "local0"Event Filter#
only_blocked: true - only fire when the request was blocked (score ≥ threshold).
only_blocked: false - fire on all events. Combined with min_score: 0.5, this fires on:
- All blocked requests
- All suspected (scored but below threshold) requests
- Phishing.club credential captures (synthesized score 1.0)
- Burn indicators from CT/reputation monitors
v0.5 Built-in Plugin Reference#
Each plugin below is enabled by listing it under plugins: and (where
applicable) supplying plugin_settings.<name>.options.
Alerting#
pagerduty#
PagerDuty Events API v2. Fires on circuit_open,
all_upstreams_failed, cert_expiring, rotation_failed,
burn_threshold_crossed. Uses a per (domain, trigger) dedup key so a
flapping breaker does not page repeatedly.
plugin_settings:
pagerduty:
options:
integration_key: "${PAGERDUTY_INTEGRATION_KEY}"
severity: "warning"
event_types:
- circuit_open
- all_upstreams_failed
- cert_expiringtelegram_bot#
Two-way ops over Telegram. Forwards RequestEvents as short messages
and accepts commands (/status, /help) from allowlisted chat IDs.
plugin_settings:
telegram_bot:
options:
bot_token: "${TELEGRAM_BOT_TOKEN}"
allowed_chat_ids: [111222333]
post_events: false
event_filter:
only_blocked: trueDetection#
yara_scan#
Runs YARA rules against request bodies (and optionally upstream
responses). Requires the yara-python package.
plugin_settings:
yara_scan:
options:
rules_dir: /etc/infraguard/yara
scan_requests: true
scan_responses: false
action_on_request_hit: block # block | suspect | log-only
max_body_bytes: 1048576ja4_enricher#
Computes JA4 / JA4H fingerprints alongside JA3. Populates
ctx.metadata["ja4"] and ctx.metadata["ja4h"]. Never blocks.
p0f_fingerprint#
Passive OS fingerprint enrichment via a local p0f unix socket, with
a user-agent fallback. Adds ctx.metadata["os_guess"].
plugin_settings:
p0f_fingerprint:
options:
p0f_socket: /var/run/p0f.sockgreynoise#
Queries the GreyNoise Community API for classification of the source
IP. Blocks on malicious; downgrades score on benign (avoids
blocking researchers). Cached in-process.
http_smuggling#
Flags requests with Content-Length + Transfer-Encoding collisions,
non-chunked Transfer-Encoding, or duplicated Content-Length headers.
ml_bot_classifier#
Logistic-regression classifier on nine cheap request features (header count, cookie / referer / accept-language presence, UA length, UA has-slash / has-paren, URI depth, URI-has-asset-extension). Ships a baseline model tuned to distinguish curl / wget / python-requests / sqlmap from real browsers. Retrain on your own tracking DB for better precision.
plugin_settings:
ml_bot_classifier:
options:
threshold: 0.7 # >= threshold => bot
action: suspect # block | suspect | log-only
model: /etc/infraguard/bot-model.json # optional; overrides baselinePopulates ctx.metadata["bot_prob"] for downstream filters. Inference
is one dot product + sigmoid; no numpy or sklearn at runtime.
Response Manipulation#
response_canary#
Injects a canarytokens.org tracking pixel or script into decoy HTML responses.
plugin_settings:
response_canary:
options:
token_url: "https://canarytokens.com/traffic/xyz.gif"
include_pixel: true
include_script: falsehtml_rewriter#
CSS-selector-based server-side HTML rewriter. Swap og:image,
analytics IDs, or inject banners. Requires beautifulsoup4.
plugin_settings:
html_rewriter:
options:
rules:
- select: 'meta[property="og:image"]'
attr: content
value: "https://cdn.example.com/og-{domain}.png"payload_watermark#
Injects a per-fetch marker into served payloads so a payload that lands on VirusTotal can be traced back to a specific target.
plugin_settings:
payload_watermark:
options:
binary: false # opt-in; verify your loader tolerates trailing bytessig_strip#
Aggressive response-header sanitizer. Extends the built-in denylist
and normalizes the Date header format.
slow_tarpit#
Drop-action extension. Streams a byte drip to blocked scanners so they spend their connection budget waiting on nothing.
plugin_settings:
slow_tarpit:
options:
only_domains: []
bytes_per_second: 20
total_bytes: 4096js_challenge#
Proof-of-work JavaScript challenge for suspect-scored requests.
Cheap for a real browser; expensive for a headless scanner fleet
without a JS engine. Not a CAPTCHA (no accessibility issue).
cache_mimicry#
Makes proxied beacon responses look like cached CDN assets by
injecting deterministic ETag, Last-Modified, Cache-Control,
Age, and X-Cache headers.
Session Tracking#
beacon_labeler#
Tags beacons with per-engagement metadata (campaign, target group) from either static per-domain config or beacon-supplied headers.
timing_profiler#
Cadence-based beacon detector. Flags source IPs whose request inter-arrival coefficient-of-variation matches a jitter-shaped distribution.
geoip_enricher#
Adds {country, asn, org} to ctx.metadata["geo"] so other filters
can use them.
Payload Security#
payload_shred#
Returns an empty body after N fetches per content-route path even if
the underlying payload_tokens counter is bypassed. Belt-and-braces.
stager_rate_limit#
Per-source rate limit on the profile’s http_stager URIs.
Testing Helpers#
request_recorder#
Records allow-verdict events to a rotating JSONL log for later
replay against a modified profile.
shadow_block#
Evaluates the pipeline as-if a filter threshold change were active, without blocking. Emits a Prometheus counter of the delta so operators can tune thresholds risk-free.
prom_custom#
Operator-defined Prometheus counters populated from request features
via dotted paths (metadata.geo.country, metadata.beacon_labels.campaign).
Writing Custom Plugins#
Implement the InfraGuardPlugin interface:
from infraguard.plugins.base import InfraGuardPlugin, RequestEvent
class MyPlugin(InfraGuardPlugin):
async def on_event(self, event: RequestEvent) -> None:
# event.ip, event.domain, event.path, event.score,
# event.filter_result, event.metadata
await self.send_somewhere(event)Register in config:
plugins:
- mypackage.myplugin.MyPlugin