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 instance
  • POST /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_expiring

telegram_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: true

Detection#

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: 1048576

ja4_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.sock

greynoise#

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 baseline

Populates 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: false

html_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 bytes

sig_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: 4096

js_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