Generic iRule based on datagroup parsing
The creation of this iRule comes from a migration project from Apache configuration to F5 Big IP. Different constraints lead to this approach of storing the configuration elements from the Apache conf in a datagroup that is then parsed by this iRule to dynamically derive the rules to apply to traffic. These are some simple or complex rules, but they are all uniformly stored in the datagroup, that can be modified by non-F5 friendly persons without impacting the rest of the configuration.SUPER-WEBSOCKET-HANDSHAKE-LOGGER™® (SWHL) iRule
The contest submission covers a so called SUPER-WEBSOCKET-HANDSHAKE-LOGGER™® (SWHL) iRule. The genius idea behind this iRule is to log and correlate every single WEBSOCKET-Handshakes via the WS_REQUEST and WS_RESPONSE events. The iRule uses a well-selected iRule syntax and it has been carefully tested on TMOS v16, v17 and v21 units. How to use: Save the iRule to your device. Attach it to your virtual server. Adjust the $static::super_websocket_handshake_logger(DEBUG_SOURCE) variable to match your client-ip address or client-subnet. Perform websocket request. Open your BAS and type: ~# tail -f /var/log/ltm | grep "SUPER-WEBSOCKET-HANDSHAKE-LOGGER" Enjoy the lovely iRule! when RULE_INIT { # SUPER-WEBSOCKET-HANDSHAKE-LOGGER iRule by Kai Wilke set static::super_websocket_handshake_logger(DEBUG_SOURCE) "10.11.12.0/24" ;# CIDR-Notation } when WS_REQUEST { set swl_requestID "" if { [IP::addr [IP::client_addr] equals $static::super_websocket_handshake_logger(DEBUG_SOURCE)] == 0 } then { return } set swl_requestID "[clock clicks][TMM::cmp_unit]" log -noname local0.debug "SUPER-WEBSOCKET-HANDSHAKE-LOGGER | $swl_requestID | [IP::client_addr]:[TCP::client_port] -> [IP::local_addr]:[TCP::local_port] | WS-REQUEST | [set httpRequest "[HTTP::method] [HTTP::host][HTTP::uri]"]" foreach header [HTTP::header names] { log -noname local0.debug "SUPER-WEBSOCKET-HANDSHAKE-LOGGER | $swl_requestID | [IP::client_addr]:[TCP::client_port] -> [IP::local_addr]:[TCP::local_port] | WS-REQUEST-HEADER | $header: [HTTP::header value $header]" } } when WS_RESPONSE { if { $swl_requestID eq "" } then { return } log -noname local0.debug "SUPER-WEBSOCKET-HANDSHAKE-LOGGER | $swl_requestID | [IP::local_addr]:[TCP::local_port] -> [IP::client_addr]:[TCP::client_port] | WS-RESPONSE | $httpRequest" foreach header [HTTP::header names] { log -noname local0.debug "SUPER-WEBSOCKET-HANDSHAKE-LOGGER | $swl_requestID | [IP::local_addr]:[TCP::local_port] -> [IP::client_addr]:[TCP::client_port] | WS-RESPONSE-HEADER | $header: [HTTP::header value $header]" } } Cheers, Kai
Layered Virtual Server iRule Solution for ICAP File Upload Scanning on BIG-IP
Problem Our client is running a WebApp where his customers are able to upload documents. A BIG-IP Cluster is used to balance the WebApp. Our client wanted to scan the files via an existing ICAP Solution. After several tests with the standard ICAP and Request Adapt solution we noticed the application workflow breaks when a virus is detected and the Upload is not completed. From troubleshooting with the client we narrowed down the root cause to the ADAPT Profile returning "respond". The BIG-IP sends this to the customer endpoint and no response is sent to the backend Server, which then breaks the workflow for the Upload. Solution With the root cause found, we implemented a layered approach. We configured two virtual servers. The first Virtual Server acts as the outer layer. In the initial request is processed by an LTM Policy which checks if the request is a file upload. This sets a pointer for POST Requests to the Endpoint which triggers the Layered iRule processing. A GET Request is directly bypassed to the Content VS behind the outer layer. If a POST is received, we save the HTTP Request in "req_headers" and send the request to the Content VS. In the Content VS iRule the Request is again checked for POST or GET Requests and the ADAPT Profile is activated accordingly. If the ICAP Result is "respond" a custom response is crafted as HTTP 406 with an X-Virus-Found Header The responses are sent back trough the Layered VS. If the status code equals 406 and the Header X-Virus-Found is present the request is checked if it was already resend to the backend App. If it was not the HTTP::retry is used to resend the request to the backend, without the malicious content. Impact As the clients Web Application was old and there was no cost effective way to implement a workaround on Application side or the purchase a new ICAP Solution, the iRules combined with LTM Policy helped to client to scan the uploads for malicious content, keeping the App safe, while using existing technologies. Code iRule VS Layered (Outer Virtual Server) when RULE_INIT { # Set to "1" for debugging set static::debug 0 } when CLIENT_ACCEPTED { # Initialize the retry variable. It is required to resend the request. set retries 0 if { $static::debug } { log local0. "*** Retry set ***" } } when HTTP_REQUEST { if { $static::debug } { log local0. "*** Layered VS: Request received Number $retries ***" } # Entry condition from the LTM Policy and check of the file size if { ([info exists avscan]) and [HTTP::header Content-Length] < 10000000 } { if { $static::debug } { log local0. "*** Layered VS: Found POST ***" } if { $static::debug } { log local0. "*** Layered VS: Content-Length is [HTTP::header Content-Length] ***" } # Check whether this is a retried request if { $retries == 1 } { # If the request is retried, remove the Content-Length header # so that an empty POST is sent HTTP::header remove Content-Length if { $static::debug } { log local0. "*** Retried Request: Content-Length Header removed ***" } } # Store all request headers in a variable. # This variable is needed later for the retry. set req_headers [HTTP::request] if { $static::debug } { log local0. "*** Layered VS: Got Request $req_headers ***" } # Forward to the actual virtual server with the pool virtual icap_content_vs } # Handle all other requests, e.g. GET, by sending them directly to the VS with the pool else { if { $static::debug } { log local0. "*** Layered VS: Found GET ***" } virtual icap_content_vs } } when HTTP_RESPONSE { if { $static::debug } { log local0. "*** Layered VS: Response Received ***" } # Check whether the server response came from the iRule on the Content VS if { [HTTP::status] equals "406" and [HTTP::header exists "X-Virus-Found"] } { if { $static::debug } { log local0. "*** Layered VS: Found Virus ***" } if { $static::debug } { log local0. "*** Layered VS: Request Headers are $req_headers ***" } # If the retry counter is 0, resend the request, but without content if { $retries == 0 } { if { $static::debug } { log local0. "*** Retrying Request ***" } HTTP::retry $req_headers incr retries return } } # Reset state after response processing set retries 0 unset req_headers } Content VS iRule when RULE_INIT { # Set to "1" for debugging set static::debug 0 } when HTTP_REQUEST { if { $static::debug } { log local0. "*** Content VS: Request Received ***" } # Entry condition from the LTM Policy and check of the file size if { ([info exists avscan])and [HTTP::header exists Content-Length] and [HTTP::header Content-Length] < 10000000 } { if { $static::debug } { log local0. "*** File found ***" } if { $static::debug } { log local0. "*** Content-Length is [HTTP::header Content-Length] ***" } # Enable the ADAPT profile to access the internal virtual server ADAPT::enable enable } else { ADAPT::enable disable } } when ADAPT_REQUEST_RESULT { if { $static::debug } { log local0. "*** ADAPT Result is: [ADAPT::result] ***" } # Check the result returned by the ICAP server (respond case) if { [ADAPT::result] contains "respond" } { if { $static::debug } { log local0. "*** Modified ADAPT Result is: [ADAPT::result] ***" } # If the ICAP return value indicates that a virus was detected, # send a manual response and trigger the retry function # in the ir_AVScan_Layered iRule HTTP::respond 406 -version auto X-Virus-Found "Virus" } } Demo Would habe loved to create a demo. Unfortunately I have no access to the App.WS-Shield: WebSocket Abuse Detection & Adaptive Enforcement Gateway
Problem WebSocket traffic introduces a fundamentally different security model from traditional HTTP. After the initial upgrade request, communication becomes long-lived, bidirectional, and frame-based, with no ongoing request/response structure for conventional controls to inspect. Existing WebSocket protections already provide important controls such as payload signature inspection, frame and message size limits, protocol compliance, origin enforcement, and structured content validation. These protections are valuable during the upgrade phase and for known attacks within frame content. The remaining challenge is per‑client behavioral analysis across live frame streams. Once a session is established, the protocol itself offers no native mechanism to evaluate how a specific client behaves over time: How fast frames are being sent Whether payloads are repetitive and automation-like Whether oversized frames are being used for resource exhaustion Whether abusive users reconnect across clustered devices Whether cumulative risk should trigger proportional enforcement Common session-layer abuse patterns include: High-rate message floods from a single client Low-and-slow bots staying below rate thresholds Oversized frames intended to exhaust backend resources Reconnect evasion across clustered load balancers Lack of adaptive per-client scoring during live sessions This is where iRules are uniquely positioned. Running directly in the F5 TMM fast path, iRules can inspect every WebSocket frame in real time, maintain per-client state across the session lifetime, and enforce graduated responses, without application changes, external agents, or protocol redesign. WS-Shield extends policy enforcement from the upgrade handshake into the active WebSocket session itself. Solution WS-Shield is a five-layer behavioral enforcement engine implemented entirely in iRules. It continuously evaluates client behavior across WebSocket frames and calculates a cumulative abuse score using multiple independent signals, then applies proportional responses based on threat level. Layer 1 — Upgrade Gate (HTTP_REQUEST) Five checks run before the 101 Switching Protocols response is sent: Source IP checked against ws_blocked_ips Origin validated against ws_allowed_origins Authentication token required: Sec-WebSocket-Protocol: Bearer.<jwt> or ?token= query parameter Token validated through sideband HTTP call (200 / 401) configurable fail-open if auth service unavailable Redis cluster pre-check: previously abusive clients can be blocked before handshake completion Layer 2 — Rate Analysis (WS_CLIENT_DATA) Per-client message volume is tracked in a sliding time window using session table state. Projected frame rate contributes to the abuse score. Detects: Floods Bursts Reconnect storms Sustained automation traffic Layer 3 — Payload Size Analysis Frame size is scored independently of rate. A single oversized frame can raise risk even if sent slowly. This detects low-frequency resource exhaustion attempts. Layer 4 — Entropy / Repetition Analysis A lightweight unique-byte approximation evaluates the first 512 bytes of each payload. Low-entropy traffic such as repetitive templates or bot-generated filler contributes to the abuse score. This detects slow bots that intentionally remain below rate thresholds. Tested Result: a client sending repetitive 300-byte payloads every 0.5 seconds was disconnected at score 100 while still below all configured rate thresholds. Layer 5 — Cumulative Score with Decay Signals from rate, payload size, and entropy feed a weighted abuse score. Clean frames reduce score gradually, allowing legitimate bursts to recover naturally while sustained abuse escalates. Adaptive Behavioral Scoring: The "Leaky Bucket" Model WS-Shield moves away from "binary" blocking (Allow vs. Deny) and adopts a fluid reputation system. We treat the cumulative abuse score like a Leaky Bucket. 1. The Scoring Dynamics The Inflow (Risk Accumulation): Every frame is a potential "drop" of risk. If a client sends a 100KB frame, we add +50 to the bucket. If they send a low-entropy (repetitive) bot payload, we add +25. The Leak (Automatic Decay): Every time the client behaves—sending a "clean" frame that passes all checks—the score decays by 1. The Outcome: This distinguishes between a malicious actor (who fills the bucket faster than it can leak) and a power user (who might have a temporary burst that decays back to a "Green Zone" naturally). 2. Graduated Enforcement Tiers The iRule maps the "water level" of the bucket to four distinct enforcement actions, ensuring we only use the "heavy hammer" when absolutely necessary. Score Level Enforcement State Action Business Logic 0 - 29 TRUSTED None Normal operational flow. 30 - 59 SUSPICIOUS Warn | HSL::send Log metadata to SIEM for behavioral profiling. 60 - 79 RESTRICTED Throttle | BWC::policy attach Adaptive Throttling. We preserve the session but limit bandwidth to protect the backend. 80 - 99 SUPPRESSED Drop | WS::frame drop Silent Discard. The client thinks they are sending data, but it never reaches the server. 100+ TERMINATED Disconnect | WS::disconnect Hard Block. RFC 6455 1008 close code issued and IP blacklisted in Redis. Cluster-Wide Threat Sharing Threat state is stored in Redis using automatic expiry. On new connections, prior threat state can be consulted before application data is exchanged. Benefits: Reconnect deterrence Cross-node reputation sharing Immediate pre-enforcement Consistent cluster behavior A client disconnected on one device cannot simply reconnect elsewhere and start clean. Outbound DLP Controls Server-to-client text frames can also be inspected. Example controls: Payment card (PAN) detection Sensitive data suppression Policy-based frame dropping Binary and control frames pass normally. Architecture Overview Impact Better Protection for Real-Time Apps Designed for: AI streaming interfaces Financial trading feeds Chat / collaboration systems Gaming backends IoT control channels These are environments where a single abusive client can impact many legitimate users. Reduced Backend Load Adaptive throttling and frame dropping suppress abusive traffic before it reaches origin servers. Faster Incident Response Structured JSON logs provide immediate visibility into: Who was abusive Why action was taken Which thresholds triggered enforcement No Application Changes Required Protection is implemented entirely in the traffic layer. No SDKs, agents, or backend modifications required. Reusable and Extensible New signals can be added easily: Geo scoring JWT claims logic URI-based weighting AI token controls Additional DLP patterns Operational Simplicity Runs on existing F5 infrastructure using native iRules capabilities. Minimal external dependencies: Redis lightweight auth service No new hardware or architecture redesign required. Code # ============================================================================= # WS-Shield: WebSocket Abuse Detection & Adaptive Enforcement Gateway # ============================================================================= # Author : Kostas Injeyan + vibe coding # Version : 5.0 (tested on TMOS 21.x) # TMOS : 21.x+ # Tags : appworld 2026, berlin, irules # # OVERVIEW # -------- # Existing WebSocket protections already provide important controls such as # payload signature inspection, frame/message size enforcement, protocol # validation, origin checks, structured content inspection, and configurable # timing thresholds. # # Additional volumetric protections can detect abnormal HTTP transaction # patterns and server stress during traditional request/response traffic # and during the initial WebSocket upgrade phase. # # However, long-lived WebSocket sessions introduce a different traffic model: # persistent bidirectional frame streams where abuse often appears as: # - Per-client message floods # - Oversized payload abuse # - Low-and-slow repetitive bot traffic # - Reconnect evasion across clustered devices # # These session behaviors benefit from adaptive controls such as: # - Per-client sliding-window behavioral scoring # - Multi-factor scoring (rate + size + entropy) # - Graduated enforcement (warn → throttle → drop → close) # - Dynamic bandwidth controls tied to abuse score # - Shared cluster threat intelligence # # WS-Shield extends enforcement beyond the handshake by applying real-time # adaptive controls throughout the active WebSocket session. # # SECURITY MODEL # -------------- # Layer 1 Upgrade Gate # Origin validation, token presence, auth sideband validation, # Redis reputation pre-check before HTTP 101 response # # Layer 2 Rate Analysis # Sliding-window per-client message rate detection # # Layer 3 Payload Size Analysis # Oversized frames scored independently of rate # # Layer 4 Entropy / Repetition Analysis # Detects slow bots sending repetitive low-variance payloads # # Layer 5 Cumulative Score with Decay # Rate, size, and entropy signals feed a weighted abuse score. # Clean frames gradually reduce score while sustained abuse escalates. # # ENFORCEMENT MODEL # ----------------- # Warn → BWC Throttle → Silent Frame Drop → RFC6455 Close (1008) # # All actions emit structured JSON logs to HSL / SIEM. # # WHAT IT DOES # ------------ # 1. Validates Origin against ws_allowed_origins # 2. Requires token (Bearer subprotocol or query parameter) # 3. Validates token via auth sideband call (200 / 401 / fail-open) # 4. Checks Redis reputation before handshake completion # 5. Tracks per-client frame rate in sliding windows # 6. Scores oversized payloads independently # 7. Detects repetitive low-entropy bot traffic # 8. Maintains cumulative abuse score with decay # 9. Applies graduated enforcement tiers # 10. Synchronizes threat state to Redis # 11. Dynamically attaches BWC throttling # 12. Inspects outbound frames for PAN / DLP patterns # 13. Sends structured audit events to HSL # # BONUS ELEMENTS (contest rubric) # -------------------------------- # [x] Procedures # ws_entropy — unique-byte entropy approximation # (TMOS expr has no log() — Shannon not directly # computable; approximation preserves 0-8 scale # and correctly identifies repetitive bot payloads) # ws_score — centralised scoring weights, single edit to retune # ws_log — structured JSON to HSL + local0 fallback # ws_redis_set — SETEX via TCP sideband, auto-expiry, fail-safe # ws_redis_get — GET via TCP sideband, graceful on outage # ws_auth_validate — token validation via HTTP GET sideband # returns 1 (valid) / 0 (rejected) / -1 (unreachable) # # [x] Sideband (two independent uses) # Redis: SETEX/GET over bare connect/send/recv for cluster threat state. # Tested: seeding wsshield:<ip>=100:close causes HTTP_REQUEST to return # 403 before handshake — cluster pre-block confirmed. # Auth service: HTTP GET /validate?token=<value> over TCP sideband. # Tested: invalid token → 401, unreachable → fail-open with log. # # [x] Bandwidth Controller # BWC::policy attach per abusive session at SCORE_THROTTLE. # Pre-attached at CLIENT_ACCEPTED for Redis-flagged clients. # Tested: Active Policies=1, Packets(dropped)=251, Bytes(dropped)=16.8K # at max-user-rate=100kbps under sustained flood. # # EVENT FLOW # ---------- # Requires WebSocket profile attached clientside AND serverside on the VS. # # CLIENT_ACCEPTED — init table state; open HSL handle; pre-attach BWC # if Redis shows this IP already above THROTTLE # HTTP_REQUEST — origin → token present → auth sideband → Redis block # WS_CLIENT_FRAME — pre-drop if score >= DROP; else WS::collect frame # WS_CLIENT_DATA — rate + size + entropy; score update; set disc_flag # WS_CLIENT_FRAME_DONE — WS::disconnect if disc_flag=1 (only valid here) # WS_SERVER_FRAME — collect text frames (opcode 1) for DLP # WS_SERVER_DATA — PAN regex; drop matching frames # CLIENT_CLOSED — final score → Redis; explicit table cleanup # # DEPENDENCIES & SETUP # -------------------- # All objects below must exist before attaching the iRule to a VS. # # 1. DATA GROUPS # # tmsh create ltm data-group internal ws_allowed_origins type string records add { # "https://yourapp.com" { } # } # tmsh create ltm data-group internal ws_blocked_ips type string # # Add IP to block list at any time: # tmsh modify ltm data-group internal ws_blocked_ips records add { "10.1.2.3" { } } # # 2. BANDWIDTH CONTROLLER POLICY # # tmsh create net bwc policy ws_abuse_bwc { dynamic enabled max-user-rate 1mbps } # # 3. HSL LOG POOL (ws_log also writes to local0 as fallback) # # tmsh create ltm pool ws_hsl_pool members add { 192.168.1.100:514 { } } # # 4. VIRTUAL SERVER PROFILES # WebSocket profile MUST be attached both clientside and serverside — # without both, WS_CLIENT_DATA will not fire: # # If using a custom HTTP profile with response-headers-permitted, add: # Upgrade Connection Sec-WebSocket-Accept — otherwise 101 headers are # stripped and clients fail to complete the handshake. # # 5. REDIS (any RESP-compatible instance reachable from BIG-IP data plane) # # docker run -d -p 6379:6379 redis:alpine # redis-cli -h <REDIS_HOST> -p 6379 ping # expect: PONG # # Test cluster pre-block: # redis-cli -h <REDIS_HOST> -p 6379 setex "wsshield:10.1.2.3" 3600 "100:close" # # 6. AUTH SERVICE (HTTP GET /validate?token=<value> → 200 or 401) # # A mock Flask auth service is provided (auth_server.py). # Deploy with Docker Compose on any host reachable from BIG-IP: # # docker run -d -p 8888:8888 -v /path/to/auth_server.py:/app/auth_server.py \ # python:3.11-alpine sh -c "pip install flask -q && python3 /app/auth_server.py" # # Test: # curl "http://<AUTH_HOST>:8888/validate?token=abc123" # → 200 # curl "http://<AUTH_HOST>:8888/validate?token=bad" # → 401 # # 7. ATTACH THE IRULE # # tmsh modify ltm virtual <vs_name> rules add { websocket } # tmsh save sys config # ============================================================================= when RULE_INIT { # --- Rate analysis (sliding window) ---------------------------------------- set ::RATE_WINDOW 10 ;# seconds — window width set ::RATE_WARN 60 ;# projected msgs/window — score += 20 set ::RATE_THROTTLE 120 ;# projected msgs/window — score += 40 + BWC set ::RATE_DROP 200 ;# projected msgs/window — score += 60 # --- Payload size (per single frame) --------------------------------------- set ::PAYLOAD_WARN 8192 ;# bytes — score += 15 set ::PAYLOAD_DROP 65536 ;# bytes — score += 50 # --- Entropy (unique-byte ratio, 0-8 scale) -------------------------------- # TMOS expr has no log() — approximated as (unique_bytes/len)*8.0 # Repetitive bot payloads ("AAA...") → near 0; normal text → 3-5 set ::ENTROPY_MIN 1.5 ;# below this — score += 25 # --- Cumulative score thresholds ------------------------------------------ set ::SCORE_WARN 30 ;# log only set ::SCORE_THROTTLE 60 ;# BWC attach + Redis write set ::SCORE_DROP 80 ;# silent frame drop set ::SCORE_CLOSE 100 ;# RFC 6455 close code 1008 # --- Redis sideband ------------------------------------------------------- # Bare connect/send/recv — correct TMOS sideband API (no SIDEBAND:: namespace) set ::REDIS_HOST "192.168.120.220" ;# change to your own set ::REDIS_PORT 6379 set ::REDIS_PFX "wsshield:" set ::REDIS_TTL 3600 # --- Auth service sideband ------------------------------------------------ # HTTP GET /validate?token=<value> → 200 (valid) or 401 (rejected) # Fail-open: unreachable auth service logs warning and allows the upgrade set ::AUTH_HOST "192.168.120.220" ;# change to your own set ::AUTH_PORT 8888 } # ----------------------------------------------------------------------------- # PROC: ws_entropy # Unique-byte entropy approximation over a 512-byte payload sample. # TMOS expr does not support log() so Shannon entropy is not directly # computable. Approximation: (distinct_byte_values / sample_length) * 8.0 # preserves the 0-8 bits/byte scale and correctly identifies low-variety # content: # "AAAA..." → unique=1, score=0.016 (correctly flagged as bot) # Normal JSON → unique~60, score~1-2 (near threshold — tested) # Random data → unique~200,score~3-5 (clean) # Returns 8.0 for empty payloads (not suspicious). # ----------------------------------------------------------------------------- proc ws_entropy { payload } { set sample [string range $payload 0 511] set len [string length $sample] if { $len == 0 } { return 8.0 } array set seen {} foreach byte [split $sample ""] { set seen($byte) 1 } return [expr { ([array size seen] / double($len)) * 8.0 }] } # ----------------------------------------------------------------------------- # PROC: ws_score # Centralised scoring weights — all score deltas live here. # No magic numbers in event handlers. Retune the entire model by editing # this one proc without touching any event logic. # ----------------------------------------------------------------------------- proc ws_score { event } { switch $event { "rate_warn" { return 20 } "rate_throttle" { return 40 } "rate_drop" { return 60 } "payload_warn" { return 15 } "payload_hard" { return 50 } "low_entropy" { return 25 } default { return 0 } } } # ----------------------------------------------------------------------------- # PROC: ws_log # Structured JSON event to HSL pool + local0 fallback. # HSL::send avoids TMM log rate limiting and integrates with any syslog SIEM. # local0 fallback means events appear in /var/log/ltm even without a live # HSL pool destination — useful during deployment and troubleshooting. # Fields: ts (ISO-8601 UTC), src (client IP), event, score, detail. # ----------------------------------------------------------------------------- proc ws_log { hsl src event score detail } { set ts [clock format [clock seconds] -format "%Y-%m-%dT%H:%M:%SZ" -gmt 1] set msg "\{\"ts\":\"${ts}\",\"src\":\"${src}\",\"event\":\"${event}\",\"score\":${score},\"detail\":\"${detail}\"\}" HSL::send $hsl $msg log local0. "wsshield: $msg" } # ----------------------------------------------------------------------------- # PROC: ws_redis_set # SETEX via TCP sideband — bare connect/send/recv (correct TMOS API). # SETEX ensures keys auto-expire; no external cleanup required. # connect() wrapped in catch so Redis outage degrades gracefully without # throwing a runtime error that would affect the connection. # ----------------------------------------------------------------------------- proc ws_redis_set { key value ttl } { set dest "${::REDIS_HOST}:${::REDIS_PORT}" if { [catch { set conn [connect -timeout 1000 -idle 5 -status cs $dest] } err] } { return 0 } if { $conn eq "" } { return 0 } set cmd "*4\r\n\$5\r\nSETEX\r\n\$[string length $key]\r\n${key}\r\n\$[string length $ttl]\r\n${ttl}\r\n\$[string length $value]\r\n${value}\r\n" send $conn $cmd recv -timeout 2000 -status rs 128 $conn close $conn return 1 } # ----------------------------------------------------------------------------- # PROC: ws_redis_get # GET via TCP sideband. Returns value string on hit, "" on miss or error. # Parses RESP bulk string reply: $<len>\r\n<data>\r\n # Nil reply ($-1\r\n) falls through regexp and returns "". # ----------------------------------------------------------------------------- proc ws_redis_get { key } { set dest "${::REDIS_HOST}:${::REDIS_PORT}" if { [catch { set conn [connect -timeout 1000 -idle 5 -status cs $dest] } err] } { return "" } if { $conn eq "" } { return "" } set cmd "*2\r\n\$3\r\nGET\r\n\$[string length $key]\r\n${key}\r\n" send $conn $cmd set resp [recv -timeout 2000 -status rs 512 $conn] close $conn if { [regexp {\$(\d+)\r\n(.+)\r\n} $resp _ len val] } { return $val } return "" } # ----------------------------------------------------------------------------- # PROC: ws_auth_validate # Validates the WebSocket auth token via HTTP GET sideband to the auth service. # Uses HTTP/1.0 deliberately — connection closes after response, no chunked # parsing needed, recv terminates cleanly. # Returns: # 1 — auth service reachable and returned 200 (token valid) # 0 — auth service reachable and returned non-200 (token rejected) # -1 — auth service unreachable (caller should fail open and log warning) # ----------------------------------------------------------------------------- proc ws_auth_validate { token } { set dest "${::AUTH_HOST}:${::AUTH_PORT}" if { [catch { set conn [connect -timeout 1000 -idle 5 -status cs $dest] } err] } { return -1 } if { $conn eq "" } { return -1 } set req "GET /validate?token=${token} HTTP/1.0\r\nHost: ${::AUTH_HOST}\r\nConnection: close\r\n\r\n" send $conn $req set resp [recv -timeout 3000 -status rs 512 $conn] close $conn if { [regexp {HTTP/1\.[01] (\d+)} $resp _ status] } { return [expr { $status == 200 ? 1 : 0 }] } return -1 } # ============================================================================= # EVENT: CLIENT_ACCEPTED # TCP connection established — before any HTTP is seen. # Initialise per-connection state here so all subsequent events have a valid # table key and HSL handle regardless of whether the connection upgrades. # Table key is IP+port scoped to prevent state collision between simultaneous # connections from the same client. # Redis pre-check: if this IP was scored above THROTTLE in a previous session # on any pool member, attach BWC immediately before the first byte of # application data — a client cannot escape throttling by reconnecting. # ============================================================================= when CLIENT_ACCEPTED { set client_ip [IP::client_addr] set tkey "wsshield_${client_ip}_[TCP::client_port]" # State vector: "score msg_count window_start disconnect_flag" # disconnect_flag is set by WS_CLIENT_DATA, consumed by WS_CLIENT_FRAME_DONE # because WS::disconnect is only valid in the FRAME_DONE context. table set "${tkey}_state" "0 0 [clock seconds] 0" indef $::REDIS_TTL set hsl [HSL::open -proto UDP -pool ws_hsl_pool] table set "${tkey}_hsl" $hsl indef $::REDIS_TTL # Cluster-wide BWC pre-enforcement set stored [call ws_redis_get "${::REDIS_PFX}${client_ip}"] if { $stored ne "" } { set cached_score [lindex [split $stored ":"] 0] if { $cached_score >= $::SCORE_THROTTLE } { BWC::policy attach ws_abuse_bwc "${client_ip}:[TCP::client_port]" table set "${tkey}_bwc" 1 indef $::REDIS_TTL } } } # ============================================================================= # EVENT: HTTP_REQUEST # Gate-check the WebSocket upgrade before the 101 is sent. # Non-upgrade requests return immediately — regular HTTP on same VS unaffected. # # Five sequential checks; first failure responds and returns: # 1. Manual IP block list (data group) # 2. Origin header vs ws_allowed_origins data group # 3. Auth token present (Bearer subprotocol or ?token= query param) # 4. Token validation via auth service sideband (fail-open if unreachable) # 5. Redis cluster pre-block (score >= CLOSE → 403 before handshake) # ============================================================================= when HTTP_REQUEST { if { not ([HTTP::header exists "Upgrade"] && [string tolower [HTTP::header "Upgrade"]] eq "websocket") } { return } set client_ip [IP::client_addr] set tkey "wsshield_${client_ip}_[TCP::client_port]" set hsl [table lookup "${tkey}_hsl"] # 1. Manual block list if { [class match $client_ip equals ws_blocked_ips] } { call ws_log $hsl $client_ip "blocked_ip" 100 "ws_blocked_ips" HTTP::respond 403 content "Forbidden\n" return } # 2. Origin validation set origin [HTTP::header "Origin"] if { $origin eq "" || not [class match $origin equals ws_allowed_origins] } { call ws_log $hsl $client_ip "bad_origin" 100 $origin HTTP::respond 403 content "Forbidden: invalid origin\n" return } # 3. Token presence set token "" if { [HTTP::header exists "Sec-WebSocket-Protocol"] } { foreach proto [split [HTTP::header "Sec-WebSocket-Protocol"] ","] { set proto [string trim $proto] if { [string match "Bearer.*" $proto] } { set token [string range $proto 7 end] break } } } if { $token eq "" } { set token [URI::query [HTTP::uri] "token"] } if { $token eq "" } { call ws_log $hsl $client_ip "no_token" 50 "missing auth on upgrade" HTTP::respond 401 content "Unauthorized: missing token\n" return } # 4. Token validation via auth service sideband # Returns: 1=valid, 0=rejected by auth service, -1=unreachable (fail open) set auth_result [call ws_auth_validate $token] if { $auth_result == 0 } { call ws_log $hsl $client_ip "invalid_token" 50 "auth service rejected token" HTTP::respond 401 content "Unauthorized: invalid token\n" return } elseif { $auth_result == -1 } { call ws_log $hsl $client_ip "auth_unavailable" 0 "auth service unreachable fail-open" } # 5. Redis cluster pre-block set stored [call ws_redis_get "${::REDIS_PFX}${client_ip}"] if { $stored ne "" } { set cached_score [lindex [split $stored ":"] 0] if { $cached_score >= $::SCORE_CLOSE } { call ws_log $hsl $client_ip "cluster_block" $cached_score "pre-blocked via Redis" HTTP::respond 403 content "Forbidden: threat score exceeded\n" return } } } # ============================================================================= # EVENT: WS_CLIENT_FRAME # Entry point for each inbound frame — payload not yet buffered. # High-score path: drop immediately with no buffering (minimal CPU cost for # clients being actively suppressed — no point collecting a payload we will # discard). # Normal path: WS::collect frame buffers the payload and fires WS_CLIENT_DATA. # ============================================================================= when WS_CLIENT_FRAME { set client_ip [IP::client_addr] set tkey "wsshield_${client_ip}_[TCP::client_port]" set state [table lookup "${tkey}_state"] if { $state eq "" } { return } if { [lindex $state 0] >= $::SCORE_DROP } { call ws_log [table lookup "${tkey}_hsl"] $client_ip \ "frame_drop" [lindex $state 0] "pre-drop score=[lindex $state 0]" WS::frame drop return } WS::collect frame } # ============================================================================= # EVENT: WS_CLIENT_DATA # Full frame payload buffered by WS::collect. Three-axis analysis runs here. # # WS::disconnect is NOT valid in this context (TMOS restriction) — when the # score crosses CLOSE, disc_flag=1 is written to the state table and # WS_CLIENT_FRAME_DONE executes the actual disconnect. # ============================================================================= when WS_CLIENT_DATA { set client_ip [IP::client_addr] set tkey "wsshield_${client_ip}_[TCP::client_port]" set hsl [table lookup "${tkey}_hsl"] set now [clock seconds] set state [table lookup "${tkey}_state"] if { $state eq "" } { set state "0 0 $now 0" } set score [lindex $state 0] set msg_count [lindex $state 1] set window_start [lindex $state 2] set disc_flag [lindex $state 3] set delta 0 # --- A. Rate analysis ------------------------------------------------------ # Project message count to full-window equivalent rate. # Window resets when elapsed >= RATE_WINDOW; count starts at 1. set elapsed [expr { $now - $window_start }] if { $elapsed >= $::RATE_WINDOW } { set msg_count 1 set window_start $now } else { incr msg_count } set rate [expr { $elapsed > 0 ? int($msg_count / double($elapsed) * $::RATE_WINDOW) : $msg_count }] if { $rate >= $::RATE_DROP } { set delta [expr { $delta + [call ws_score "rate_drop"] }] } elseif { $rate >= $::RATE_THROTTLE } { set delta [expr { $delta + [call ws_score "rate_throttle"] }] } elseif { $rate >= $::RATE_WARN } { set delta [expr { $delta + [call ws_score "rate_warn"] }] } # --- B. Payload size ------------------------------------------------------- # Scored independently — a single oversized frame is an indicator of # resource exhaustion intent regardless of message rate. set payload [WS::payload] set plen [string length $payload] if { $plen >= $::PAYLOAD_DROP } { set delta [expr { $delta + [call ws_score "payload_hard"] }] } elseif { $plen >= $::PAYLOAD_WARN } { set delta [expr { $delta + [call ws_score "payload_warn"] }] } # --- C. Entropy ------------------------------------------------------------ # Catches bots that evade rate limits by spacing messages out but still # generate highly uniform, low-variety content (tested: slow bot sending # 300-byte "AAA..." disconnected at score 100 with rate=40 — well below # every rate threshold, entropy alone drove the disconnect). if { $plen > 0 && [call ws_entropy $payload] < $::ENTROPY_MIN } { set delta [expr { $delta + [call ws_score "low_entropy"] }] } # --- D. Score update with decay ------------------------------------------- # Clean frames (delta==0) decay score by 1, floored at 0. # Sustained legitimate traffic recovers from short bursts automatically. if { $delta == 0 } { set score [expr { $score > 0 ? $score - 1 : 0 }] } else { set score [expr { $score + $delta }] } # --- E. Graduated enforcement --------------------------------------------- if { $score >= $::SCORE_CLOSE } { call ws_log $hsl $client_ip "disconnect_flagged" $score \ "score=${score} rate=${rate} plen=${plen}" call ws_redis_set "${::REDIS_PFX}${client_ip}" "${score}:close" $::REDIS_TTL set disc_flag 1 } elseif { $score >= $::SCORE_THROTTLE } { call ws_log $hsl $client_ip "throttle" $score "rate=${rate}" # Guard with table lookup — attach BWC only once per connection if { [table lookup "${tkey}_bwc"] eq "" } { BWC::policy attach ws_abuse_bwc "${client_ip}:[TCP::client_port]" table set "${tkey}_bwc" 1 indef $::REDIS_TTL } # Write to Redis — other pool members pre-throttle on next connect call ws_redis_set "${::REDIS_PFX}${client_ip}" "${score}:throttle" $::REDIS_TTL } elseif { $score >= $::SCORE_WARN } { call ws_log $hsl $client_ip "warn" $score "rate=${rate} plen=${plen}" } table set "${tkey}_state" "$score $msg_count $window_start $disc_flag" indef $::REDIS_TTL WS::release } # ============================================================================= # EVENT: WS_CLIENT_FRAME_DONE # Only valid context for WS::disconnect in the TMOS WebSocket API. # Reads disc_flag written by WS_CLIENT_DATA and issues RFC 6455 close # code 1008 (Policy Violation). The two-event handoff is a TMOS requirement — # WS::disconnect cannot be called from within WS_CLIENT_DATA. # ============================================================================= when WS_CLIENT_FRAME_DONE { set client_ip [IP::client_addr] set tkey "wsshield_${client_ip}_[TCP::client_port]" set state [table lookup "${tkey}_state"] if { $state eq "" } { return } if { [lindex $state 3] == 1 } { call ws_log [table lookup "${tkey}_hsl"] $client_ip \ "ws_disconnect" [lindex $state 0] "RFC 6455 code 1008 policy violation" WS::disconnect 1008 "Policy violation: abuse score exceeded" } } # ============================================================================= # EVENT: WS_SERVER_FRAME # Collect text frames (opcode 1) from the server for DLP inspection. # Binary frames (opcode 2) and control frames (ping/pong) pass through # unmodified to avoid interfering with application framing and keepalives. # ============================================================================= when WS_SERVER_FRAME { if { [WS::frame type] == 1 } { WS::collect frame } } # ============================================================================= # EVENT: WS_SERVER_DATA # PAN heuristic on buffered server-to-client text frame. # Four groups of four digits, optionally separated by spaces or hyphens. # Extend with additional patterns (SSN, IBAN, API keys) for full DLP coverage. # Non-matching frames released normally with WS::release. # ============================================================================= when WS_SERVER_DATA { set payload [WS::payload] if { [regexp {\d{4}[ \-]?\d{4}[ \-]?\d{4}[ \-]?\d{4}} $payload] } { set client_ip [IP::client_addr] set tkey "wsshield_${client_ip}_[TCP::client_port]" call ws_log [table lookup "${tkey}_hsl"] $client_ip \ "dlp_block" 0 "PAN pattern in server->client frame" WS::frame drop return } WS::release } # ============================================================================= # EVENT: CLIENT_CLOSED # TCP close — clean or reset. Write final score to Redis for post-session # audit trail. Explicit table delete keeps session table lean during # high-churn periods rather than waiting for TTL expiry. # ============================================================================= when CLIENT_CLOSED { set client_ip [IP::client_addr] set tkey "wsshield_${client_ip}_[TCP::client_port]" set state [table lookup "${tkey}_state"] set hsl [table lookup "${tkey}_hsl"] if { $state ne "" && $hsl ne "" } { set score [lindex $state 0] call ws_log $hsl $client_ip "session_closed" $score "final score=${score}" call ws_redis_set "${::REDIS_PFX}${client_ip}" "${score}:closed" $::REDIS_TTL } table delete "${tkey}_state" table delete "${tkey}_hsl" table delete "${tkey}_bwc" } Test Evidence All enforcement tiers were validated live on TMOS 21.x against a jmalloc echo-server backend with Redis and a Flask auth service running on a Synology NAS. Test Result Bad origin 403 before handshake Invalid token 401, auth service rejection confirmed Auth service unreachable Fail-open with auth_unavailable log Redis cluster pre-block 403 before handshake, cluster_block event Rate flood (300 msg @ 50/sec) warn → throttle → ws_disconnect 1008 Entropy bot (AAA... @ 0.5s) Disconnect at score 100, rate=40, entropy alone triggered BWC throttle Active Policies=1, 251 packets dropped, 16.8K bytes suppressed at 100kbps DLP outbound block PAN frame dropped before client delivery, dlp_block confirmed auth-docker-compose.yml version: "3" services: ws-auth: image: python:3.11-alpine container_name: ws-auth working_dir: /app volumes: - /volume1/docker/ws-auth/auth_server.py:/app/auth_server.py command: sh -c "pip install flask -q && python3 auth_server.py" ports: - "8888:8888" restart: unless-stopped auth_server.py """ WS-Shield Mock Auth Service --------------------------- Simple HTTP server that validates Bearer tokens for WS-Shield testing. Valid tokens: any token in the VALID_TOKENS set below Invalid tokens: anything else → 401 Unreachable test: stop this server and observe iRule fail-open behaviour Run: pip install flask python3 auth_server.py Endpoints: GET /validate?token=<value> → 200 OK or 401 Unauthorized GET /health → 200 OK (for monitoring) Deploy on Synology as a Container Manager stack or run directly. Update AUTH_HOST in the iRule RULE_INIT to point at this server. """ from flask import Flask, request, jsonify app = Flask(__name__) # Add your valid tokens here — in production replace with JWT verification, # database lookup, or OAuth introspection call. VALID_TOKENS = { "abc123", "prod-token-xyz", "test-token-001", "appworld-2026", } @app.route("/validate") def validate(): token = request.args.get("token", "") if not token: return jsonify({"error": "missing token"}), 401 if token in VALID_TOKENS: return jsonify({"valid": True, "token": token}), 200 return jsonify({"valid": False, "error": "invalid token"}), 401 @app.route("/health") def health(): return jsonify({"status": "ok"}), 200 if __name__ == "__main__": print("WS-Shield mock auth service running on 0.0.0.0:8888") app.run(host="0.0.0.0", port=8888, debug=False)WS-Exfil-Shield: Catching What WAFs Miss After the 101 Handshake
Problem WAFs inspect the WebSocket upgrade and individual frames against signatures and content profiles, but they do not correlate behavior across the lifetime of an established WebSocket session. All major WAF vendors document the same gap: inspection stops at the HTTP upgrade handshake; post-upgrade WebSocket frames are not correlated across a session. Three threat patterns exploit the post-upgrade behavioral blind spot: **C2 Beacon Timing**: WebSocket C2 channels are documented in active campaigns — e.g. PhantomCaptcha (SentinelLabs, Oct 2025) used a multi-stage WebSocket RAT with wss:// C2 and Base64/JSON commands; LightSpy (Huntress, macOS variant) uses WebSockets for command delivery and control. The behavioral signal is timing — beaconing implants tend toward regular intervals, humans do not. WAFs and most network controls do not analyze inter-frame timing across a session. **Credential Stuffing Over WebSocket**: 1000 credential pairs over one connection appear as one HTTP event to perimeter controls. Verizon DBIR 2025: compromised credentials were the initial access vector in 22% of breaches; the median daily share of credential stuffing in SSO authentication logs was 19%. **Exfiltration Signals**: /export paths, Authorization headers, and oversized payloads are visible at the handshake; per-frame inspection (where enabled) sees content but not session-level patterns. BSI Lagebericht 2025 (reporting period July 2024 - June 2025): 72% of analyzed ransomware incidents included a data leak; double extortion (encryption + exfiltration) is the dominant attack model. Solution Single iRule. No backend changes. Two-stage behavioral detection: not "what does this frame contain?" but "what does this connection do over time? — and does the payload confirm it?" L1 Suspicious URI/header regex + string BWC throttle + HSL alert L2 C2 beacon timing (CoV) online statistics Sideband check → quarantine/pass + close L3 High frame rate sliding window IP block + TCP close L4 Quarantined reconnect sideband verdict Block/release/honeypot + AI analysis **L1 - Exfiltration signals at the handshake**: HTTP_REQUEST checks the upgrade URI against a regex for known exfiltration endpoints (/export, /download, /dump, /backup, /extract) and scans headers for Authorization, X-API-Key, X-Secret. On match: BWC policy attached server-to-client (1 Mbps throttle) + HSL alert. No block — /export might be legitimate. Throttling buys the SOC time to investigate without disrupting a potentially valid operation. **L2 - CoV² online algorithm**: Welford-inspired, 5 table entries per connection regardless of session length. CoV² (no sqrt() in BIG-IP Tcl) < 0.0225 with >=5 samples = machine-like timing. On detection: iRule sends timing metadata to the sideband service and waits up to 500ms for a verdict. FALSE_POSITIVE (allowlisted IP) → session continues untouched; CONFIRMED or timeout → quarantine table set + TCP close. The quarantined IP will be routed to the honeypot on its next connection attempt (L4). **L3 - Frame rate sliding window**: WS_CLIENT_FRAME tracks frame count per connection within a 10-second window. At 5 frames in 10 seconds: TCP close + IP written to blocklist with 1-hour TTL. On any subsequent reconnect attempt, HTTP_REQUEST rejects the connection immediately. The sliding window resets when the window expires, allowing legitimate high-frequency bursts to pass without false positives. **L4 - Two-stage verification with closed-loop AI verdict**: When a quarantined IP reconnects, HTTP_REQUEST issues a QUARANTINE_CHECK to the sideband service before routing. Three outcomes apply at handshake time: PENDING (analysis still in progress) or sideband timeout → connection is silently routed to the honeypot pool via `pool quarantine_pool`. The attacker's implant keeps running, unaware it is isolated. After 5 frames are collected in the honeypot, the AI analyzer (Claude) classifies payload semantics independent of timing: agent identifiers, command structure, encoding patterns. Claude's verdict is pushed back to the sideband service and cached against the source IP, which closes the loop: CONFIRMED → next QUARANTINE_CHECK returns CONFIRMED, iRule emits a C2_CONFIRMED HSL event (source=claude, confidence, family) and rejects the handshake; the IP is held in a permanent 24h block. In the test run, the third reconnect after CONFIRMED never completes the WS upgrade — the client sees `InvalidMessage: did not receive a valid HTTP response`. FALSE_POSITIVE → quarantine entry deleted, the IP is released and subsequent sessions continue normally. This matters because C2 frameworks implement jitter — randomized beacon intervals designed to defeat timing-based detection. At >27% jitter (in our test corpus), CoV rises above threshold and L2 stops firing; the AI layer is jitter-immune because it inspects payload semantics, not cadence. Neither signal alone is sufficient. Reference result on a `{"t":"ping","id":"c2agent01"}` corpus: verdict=C2, confidence=0.95, family "Generic C2 Heartbeat", with indicators including "structured JSON protocol with type field", "persistent agent identifier across all frames", "repetitive ping pattern (5/5 frames identical)", "no human interaction artifacts", and "deterministic payload, no entropy". **Sideband**: iRule = sensor, endpoint = actor. Used at two points in the flow: L2 (timing verdict) and L4 (QUARANTINE_CHECK). Pluggable TCP port 9000 listener: SIEM (Splunk/QRadar), SOAR (auto-block via iControl REST), or AI analyzer (reference implementation included). catch{} ensures a non-responding endpoint never delays traffic. Impact - Defense in depth with Advanced WAF: WAF guards handshake, signatures, and frame content; WS-Exfil-Shield adds session-level behavioral detection. - All thresholds in RULE_INIT — tuning without redeployment; sideband endpoint swappable. - Graduated enforcement: throttle → quarantine → AI verify → block or release. Each layer independently tunable. - Full audit trail: CONNECT, L1_SIGNAL, C2_BEACON, QUARANTINE, RATE_LIMIT, BLOCKED, C2_CONFIRMED (source=claude, confidence, family) + FALSE_POSITIVE from AI layer. Demo https://www.youtube.com/watch?v=-XRipP0p_oc Code # WS-Exfil-Shield iRule # F5 AppWorld Berlin 2026 - iRules Contest # # Four-layer WebSocket security with graduated response: # Layer 1: Connection-level exfiltration signals (URL, headers) → BWC throttle # Layer 2: C2 beacon timing fingerprint (CoV-based behavioral analysis) → quarantine + TCP close # Layer 3: High-frequency frame rate detection (credential stuffing) → TCP close + IP block # Layer 4: Quarantined reconnect → sideband verdict check → block/release/honeypot # # Two-stage verification: # Stage 1 (L2): CoV² detects machine-like timing → sideband confirms → quarantine + TCP close # Stage 2 (L4): Reconnect → sideband QUARANTINE_CHECK returns Claude payload verdict: # CONFIRMED → permanent 24h block + C2_CONFIRMED HSL event + reject # FALSE_POSITIVE → quarantine released, session continues normally # PENDING/timeout → route to honeypot (Claude still analyzing) # # External dependencies (pre-configured on BIG-IP): # - BWC policy : ws_exfil_throttle (Network > Bandwidth Controllers, 1 Mbps) # - HSL pool : siem_hsl_pool (LTM > Pools, UDP 514, points to SIEM/syslog receiver) # # Requirements: BIG-IP TMOS 21.x when RULE_INIT { set static::beacon_min_samples 5 set static::beacon_cv_threshold 0.15 ;# CoV < 0.15 = machine-like timing set static::cs_frame_limit 5 ;# max frames per cs_window milliseconds set static::cs_window 3000 ;# sliding window size in milliseconds set static::cs_block_ttl 3600 ;# IP blocklist TTL in seconds set static::bwc_policy "ws_exfil_throttle" } # --------------------------------------------------------------------------- # PROCEDURES # --------------------------------------------------------------------------- proc check_beacon_fingerprint { conn_id } { set count [table lookup "bcn_count_${conn_id}"] if { $count eq "" || $count < $static::beacon_min_samples } { return 0 } set sum_t [table lookup "bcn_sumt_${conn_id}"] set sum_t2 [table lookup "bcn_sumt2_${conn_id}"] set n $count set mean [expr { double($sum_t) / $n }] if { $mean <= 0 } { return 0 } set variance [expr { double($sum_t2) / $n - $mean * $mean }] if { $variance < 0 } { set variance 0 } # CoV² comparison avoids sqrt (not available in BIG-IP Tcl) set cov_sq [expr { $variance / ($mean * $mean) }] set cv_thresh_sq [expr { $static::beacon_cv_threshold * $static::beacon_cv_threshold }] if { $cov_sq < $cv_thresh_sq } { return 1 } return 0 } proc hsl_send { event data } { HSL::send $static::hsl "\{\"event\":\"${event}\",\"ts\":[clock seconds],${data}\}\n" } # --------------------------------------------------------------------------- # EVENTS # --------------------------------------------------------------------------- when HTTP_REQUEST { if { [string tolower [HTTP::header "Upgrade"]] eq "websocket" } { if { ![info exists static::hsl] } { set static::hsl [HSL::open -proto UDP -pool siem_hsl_pool] } set conn_id "[IP::client_addr]:[TCP::client_port]" set client_ip [IP::client_addr] set uri [HTTP::uri] # Blocklist check (Layer 3 + confirmed C2 carry-over) if { [table lookup "cs_blocked_${client_ip}"] ne "" } { log local0.warning "WS-Exfil-Shield: BLOCKED ip=$client_ip conn=$conn_id" call hsl_send "BLOCKED" "\"ip\":\"$client_ip\",\"conn\":\"$conn_id\"" reject return } # Layer 4: Quarantined IP reconnect — check sideband for Claude verdict. # CONFIRMED: Claude analyzed honeypot frames and confirmed C2 → permanent block. # FALSE_POSITIVE: Claude found no C2 indicators → release quarantine, continue normally. # PENDING/timeout: Claude still analyzing → keep routing to honeypot. if { [table lookup "quar_${client_ip}"] ne "" } { set quar_action "honeypot" catch { set sb [connect -timeout 100 -protocol TCP 10.10.2.1 9000] if { $sb ne "" } { send -timeout 100 $sb "{\"conn_id\":\"$conn_id\",\"ip\":\"$client_ip\",\"threat\":\"QUARANTINE_CHECK\"}\n" set qverdict [recv -timeout 500 $sb] close $sb if { [string match "*\"verdict\":\"CONFIRMED\"*" $qverdict] } { set quar_action "block" } elseif { [string match "*\"verdict\":\"FALSE_POSITIVE\"*" $qverdict] } { set quar_action "release" } } } if { $quar_action eq "block" } { table set "cs_blocked_${client_ip}" 1 86400 86400 log local0.warning "WS-Exfil-Shield: C2_CONFIRMED ip=$client_ip conn=$conn_id" call hsl_send "C2_CONFIRMED" "\"ip\":\"$client_ip\",\"conn\":\"$conn_id\"" reject return } elseif { $quar_action eq "release" } { table delete "quar_${client_ip}" log local0.info "WS-Exfil-Shield: FALSE_POSITIVE ip=$client_ip conn=$conn_id" call hsl_send "FALSE_POSITIVE" "\"ip\":\"$client_ip\",\"conn\":\"$conn_id\"" # fall through to normal processing } else { log local0.info "WS-Exfil-Shield: QUARANTINE ip=$client_ip conn=$conn_id" call hsl_send "QUARANTINE" "\"ip\":\"$client_ip\",\"conn\":\"$conn_id\"" pool quarantine_pool return } } # Layer 1: Exfiltration signals in WebSocket upgrade request set threat "" if { [regexp -nocase {/(export|download|dump|backup|extract)} $uri] } { set threat "EXFIL_ENDPOINT" } if { $threat eq "" } { foreach hdr { Authorization X-API-Key X-Secret } { if { [HTTP::header $hdr] ne "" } { set threat "SENSITIVE_HEADER"; break } } } if { $threat ne "" } { log local0.warning "WS-Exfil-Shield: L1_SIGNAL threat=$threat ip=$client_ip uri=$uri" call hsl_send "L1_SIGNAL" "\"ip\":\"$client_ip\",\"conn\":\"$conn_id\",\"threat\":\"$threat\",\"uri\":\"$uri\"" # Throttle server→client bandwidth to slow active exfiltration BWC::policy attach $static::bwc_policy } table set "ws_start_${conn_id}" [clock clicks -milliseconds] indef 3600 log local0.info "WS-Exfil-Shield: CONNECT ip=$client_ip conn=$conn_id uri=$uri" call hsl_send "CONNECT" "\"ip\":\"$client_ip\",\"conn\":\"$conn_id\",\"uri\":\"$uri\"" } } when WS_CLIENT_FRAME { set conn_id "[IP::client_addr]:[TCP::client_port]" set client_ip [IP::client_addr] set now [clock clicks -milliseconds] # --- Layer 2: C2 Beacon Timing Fingerprint --- set last_ts [table lookup "bcn_last_${conn_id}"] if { $last_ts ne "" } { set interval [expr { $now - $last_ts }] set count [table lookup "bcn_count_${conn_id}"] set sum_t [table lookup "bcn_sumt_${conn_id}"] set sum_t2 [table lookup "bcn_sumt2_${conn_id}"] if { $count eq "" } { set count 0 } if { $sum_t eq "" } { set sum_t 0 } if { $sum_t2 eq "" } { set sum_t2 0 } if { $interval > 0 } { incr count set sum_t [expr { $sum_t + $interval }] set sum_t2 [expr { $sum_t2 + $interval * $interval }] table set "bcn_count_${conn_id}" $count indef 3600 table set "bcn_sumt_${conn_id}" $sum_t indef 3600 table set "bcn_sumt2_${conn_id}" $sum_t2 indef 3600 } if { [call check_beacon_fingerprint $conn_id] } { set mean_interval [expr { $sum_t / $count }] log local0.warning "WS-Exfil-Shield: C2_BEACON ip=$client_ip conn=$conn_id samples=$count mean_interval=${mean_interval}ms" call hsl_send "C2_BEACON" "\"ip\":\"$client_ip\",\"conn\":\"$conn_id\",\"samples\":$count,\"mean_interval_ms\":$mean_interval" # Stage 1 sideband: timing verdict determines quarantine vs pass # CONFIRMED/timeout → quarantine (honeypot collects payload for Stage 2 Claude analysis) # FALSE_POSITIVE → session continues untouched set action "quarantine" catch { set sb [connect -timeout 100 -protocol TCP 10.10.2.1 9000] if { $sb ne "" } { send -timeout 100 $sb "{\"conn_id\":\"$conn_id\",\"ip\":\"$client_ip\",\"threat\":\"C2_BEACON\",\"mean_interval_ms\":$mean_interval}\n" set verdict [recv -timeout 500 $sb] close $sb if { [string match "*\"verdict\":\"FALSE_POSITIVE\"*" $verdict] } { set action "pass" } } } if { $action eq "quarantine" } { table set "quar_${client_ip}" 1 indef 1800 TCP::close } # action "pass": allowlisted IP — session continues untouched return } } table set "bcn_last_${conn_id}" $now indef 3600 # --- Layer 3: High-frequency frame rate (credential stuffing indicator) --- set window_start [table lookup "cs_window_${conn_id}"] set frame_count [table lookup "cs_frames_${conn_id}"] if { $window_start eq "" } { set window_start $now table set "cs_window_${conn_id}" $now indef 3600 } if { $frame_count eq "" } { set frame_count 0 } set elapsed [expr { $now - $window_start }] if { $elapsed >= $static::cs_window } { table set "cs_window_${conn_id}" $now indef 3600 table set "cs_frames_${conn_id}" 1 indef 3600 } else { incr frame_count table set "cs_frames_${conn_id}" $frame_count indef 3600 if { $frame_count >= $static::cs_frame_limit } { log local0.warning "WS-Exfil-Shield: RATE_LIMIT ip=$client_ip conn=$conn_id frames=${frame_count} in ${elapsed}ms" call hsl_send "RATE_LIMIT" "\"ip\":\"$client_ip\",\"conn\":\"$conn_id\",\"frames\":$frame_count,\"elapsed_ms\":$elapsed" table set "cs_blocked_${client_ip}" 1 $static::cs_block_ttl $static::cs_block_ttl TCP::close return } } }iRules Contest Entry Example
Problem Clearly state the problem you are trying to solve and why iRules are used as a solution. Provide as much context as you want to make sure the problem is well understood by the judges. Solution Give a high level solution guide here, including any workflow or diagrams that would help the judges walk through your code. Impact This section is for fleshing out the business value of your solution Code PLEASE use a code block to wrap your code. The {;} icon on the second row of the toolbar is your friend. It should look like this before you submit: when RULE_INIT { log local0. "my code is so much easier to read in this code block!" } Demo If you want to record a video to demo your solution, you can throw upload or link from youtube in the toolbar. Make sure to tag your entry with APPWORLD2026, IRULES, and BERLIN, and make sure to submit your entry when done editing drafts.JSON-query'ish meta language for iRules
Intro Jason Rahm recently dropped his "Working with JSON data in iRules" series, which included a few JSON challenges and a subtle hint [string toupper [string replace Jason 1 1 ""]] about the upcoming iRule challenge at AppWorld 2026 in Las Vegas. With cash prizes and bragging rights on the line, my colleagues and I dove into Jason's code. While his series is a great foundation, we saw an opportunity to push the boundaries of security, performance and add RFC compliance. Problem Although F5 recently introduced native iRule commands for JSON parsing (v21.x); these tools remain "bare metal" compared to modern programming languages. They offer minimal abstraction, requiring developers to possess both deep JSON schema knowledge and advanced iRule expertise to implement safely. Without a supporting framework, engineers are forced to manually manage complex types, nested objects, and arrays. A process that is both labor-intensive and error-prone. As JSON has become the de facto standard for AI-centric workloads and modern API traffic, the need to efficiently manipulate session data on the ADC platform has never been greater. Solution Our goal is to bridge this gap by developing a "Swiss Army Knife" framework for iRule JSON parsing, providing the abstraction and reliability needed for high-performance traffic management. Imagine a JSON data structure as shown below: { "my_string": "Hello World", "my_number": 42, "my_boolean": true, "my_null": null, "my_array": [ 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20 ], "my_object": { "nested_string": "I'm nested" }, "my_children": [ {"name": "Anna Conda","firstname": "Anna", "surname": "Conda"}, {"name": "Justin Case","firstname": "Justin", "surname": "Case"}, {"name": "Don Key","firstname": "Don", "surname": "Key"}, {"name": "Artie Choke","firstname": "Artie", "surname": "Choke"}, {"name": "Barbie Doll","firstname": "Barbie", "surname": "Doll"} ] } The [call json_get] and [call json_set] procedures from our iRule introduce a JSON-Query meta-language to slice information into and out of JSON. Here are a few examples of how these procedures can be used: # Define JSON root element set root [JSON::root] # Without a filter is behaves like json_stringify log [call json_get $root ""] -> {"my_string": "Hello World","my_number": 42,"my_boolean": true,"my_null": .... <truncated for better readability> # But as soon as you add filters, it becomes parsing on steroids! log [call json_get $root "my_string"] -> "Hello World" # You simply ask for a path and you promptly get an answer! log [call json_get $root "my_object nested_string"] -> "I'm nested" # Are you ready for the more advanced examples? log [call json_get $root "my_array (5)"] -> [5] log [call json_get $root "my_array (0,5-10,16-18)"] -> [0,5,6,7,8,9,10,16,17,18] log [call json_get $root "my_children (*) firstname"] -> ["Anna","Justin","Don","Artie","Barbie"] log [call json_get $root "my_children (*) {firstname|surname}"] -> [["Anna","Conda"],["Justin","Case"],["Don","Key"],["Artie","Choke"],["Barbie","Doll"]] # Lets add some information to my childrens... call json_set $root "my_children (0,4) gender" string "she/her" call json_set $root "my_children (1-3) gender" string "he/him" call json_set $root "my_children (2) gender" string "they/them" log [call json_get $root "my_children (*) name|gender"] -> [["Anna Conda","she/her"],["Justin Case","he/him"],["Don Key","they/them"],["Artie Choke","he/him"],["Barbie Doll","she/her"]] # Lets write in an empty cache... set empty_cache [JSON::create] call json_set $empty_cache "rootpath subpath" string "I'm deeply nested" log [call json_get $empty_cache] -> {"rootpath": {"subpath": "I'm deeply nested"}} After seeing what our project is about, lets try how [call json_get] and [call json_set] can be used to solve the challenges Jason suggested in his Working with JSON data in iRules series. As a reminder, this is Jason's final iRule with his open challenges to the community: when JSON_REQUEST priority 500 { set json_data [JSON::root] if {[call find_key $json_data "nested_array"] contains "b" } { set cache [JSON::create] set rootval [JSON::root $cache] JSON::set $rootval object set obj [JSON::get $rootval object] JSON::object add $obj "[IP::client_addr] status" string "rejected" set rendered [JSON::render $cache] log local0. "$rendered" HTTP::respond 200 content $rendered "Content-Type" "application/json" } } "Now, I offer you a couple challenges. lines 4-9 in the JSON_REQUEST example above should really be split off to become another proc, so that the logic of the JSON_REQUEST is laser-focused. How would YOU write that proc, and how would you call it from the JSON_REQUEST event? The find_key proc works, but there's a Tcl-native way to get at that information with just the JSON::object subcommands that is far less complex and more performant. Come at me!" -Jason Rahm By using our general-purpose iRule procedures, we achieve the laser-focused syntax Jason requested: when JSON_REQUEST priority 500 { set json_data [JSON::root] if { [call json_get $json_data "my_object nested_array"] contains "b" } then { set cache [JSON::create] call json_set $cache "{[IP::client_addr] status}" string "rejected" HTTP::respond 200 content [JSON::render $cache] "Content-Type" "application/json" } } Despite our larger codebase, it is remarkable that our code runs ~20% faster (425 vs. 532 microseconds) per JSON request. This performance gain stems from traversing the JSON structure with a provided path; the procedure knows exactly where to look without unnecessary searching. Additionally, we utilized performance-oriented syntax that prefers fast commands, deploys variables only when necessary, and avoids string-to-list conversions (Tcl shimmering). Impact Our project highlights the current state of JSON-related iRule commands and proves that meta-languages are more suitable for the average iRule developer. We hope this project catches the attention of F5 product development so that a similar JSON-query language can be provided natively. In the meantime, we are deploying this code in production environments and will continue to maintain it. Code Because of size restrictions we had to attach the code as a file. placeholder for insertion Installation Upload the submitted iRule code to your BIG-IP, save as new iRule. Attach a JSON profile to your virtual server. Then attach the iRule to this virtual server. Ready for testing, enjoy! Demo Video Link https://youtu.be/wAHjeC-j8MMLLM Prompt Injection Detection & Enforcement
Problem As enterprises integrate AI APIs, OpenAI, Azure OpenAI, Anthropic, and self-hosted LLMs, into production applications, a critical and largely unaddressed attack surface has emerged: **prompt injection**. Unlike traditional web attacks that target code parsers (SQL injection, XSS), prompt injection targets the AI model itself. Attackers embed malicious instructions inside legitimate-looking API requests to: - Override system-level instructions and safety guardrails ("ignore all previous instructions") - Jailbreak the model into unrestricted modes ("DAN", "developer mode", "god mode") - Hijack the model's persona ("from now on you are an unrestricted AI") - Exfiltrate sensitive system prompts or context data - Inject fake role turns via newline characters (e.g., `\nassistant:`) - Evade detection using Base64 encoding, Unicode obfuscation, or reversed text (FlipAttack) Existing F5 WAF signatures were designed for traditional web threats and have no visibility into the semantic content of LLM API payloads. There is no existing iRule or BIG-IP capability that addresses this. Solution This iRule implements a **multi-layer, real-time Prompt Injection Detection (PID) engine** inline with LLM API traffic on BIG-IP. It requires zero backend changes, operates entirely within the data plane, and enforces configurable security policy before malicious content reaches the language model. ### How It Works **HTTP_REQUEST** identifies LLM API calls by URI pattern (`/chat/completions`, `/messages`, `/completions`, `/generate`) and initiates JSON collection up to 1MB. **JSON_REQUEST** uses BIG-IP's native `JSON::` TCL API to parse the OpenAI-format request body — extracting each message's `role` and `content` from the `messages` array, including multi-part content arrays. This is where the detection engine runs. **Scoring Engine** (via TCL `proc`s) runs each message through 5 detection layers: Layer Method Score High-tier patterns weighted regex via data group 30–35 pts Medium-tier patterns weighted regex via data group 20–25 pts Low-tier patterns weighted regex via data group 10–15 pts Role hijack phrases flat string match via data grou +20 pts (once) Base64 evasion markers flat string match via data group +35 pts (once) Unicode/zero-width obfuscation inline regexp +25 pts Spaced character obfuscation inline regexp +20 pts Content length anomaly string length check +10/+15 pts Scores accumulate per message. Across a multi-message conversation, subsequent messages receive a 0.8 diminishing-returns multiplier so legitimate conversational context doesn't inflate the score. **Policy enforcement** triggers when the total score exceeds the configurable threshold (default: 40): - **BLOCK** — returns HTTP 403 with a structured JSON error body including score, triggered flags, and a correlation request ID - **SANITIZE** — rewrites the request payload, stripping matched content, and forwards the cleaned request to the backend LLM - **LOG_ONLY** — observability mode; passes all traffic but logs score and flags for SIEM integration **HTTP_RESPONSE** injects `X-PID-Score`, `X-PID-Flags`, and `X-PID-ReqID` headers on all inspected responses for downstream visibility. ### Required & Thematic Elements Used - **JSON** — Full `JSON::` API usage: `JSON::root`, `JSON::get`, `JSON::type`, `JSON::object get/keys`, `JSON::array get/size` to traverse OpenAI chat completions payloads - **procs** — Four modular procs: `pid_score_tier`, `pid_score_flat`, `pid_score_message`, `pid_block_response` - **compiles** — `regexp -nocase` with `catch {}` for safe pattern evaluation throughout the scoring engine; all patterns validated through the BIG-IP TCL compile pipeline - **Data Groups** — All detection patterns live in 5 external data groups (`pid_patterns_high/medium/low`, `pid_role_hijack`, `pid_b64_markers`) — the iRule is a detection platform; patterns are operator-managed config, not code - **Theme: AI Infrastructure — Prompt Injection Detection ### Data Groups All patterns are managed externally in 5 BIG-IP data groups loaded via: ``` tmsh load sys config from-terminal merge **verify** ``` The weighted DG schema is `key = short-name`, `value = "weight::regex"`. This allows security teams to tune detection, add new attack signatures, and adjust scoring thresholds without any iRule changes. --- Impact AI APIs are increasingly business-critical infrastructure. A successful prompt injection attack can: - Cause an AI to disclose confidential system prompts, business logic, or sensitive training data - Remove safety guardrails, producing harmful or brand-damaging content at scale - Manipulate AI-powered workflows — customer service bots, automated decision systems, AI agents - Exfiltrate credentials or documents accessible to AI agents with tool-use capabilities This iRule addresses the threat at the most effective point: **the network**. Key advantages: - **Infrastructure-agnostic** — works with any LLM backend (OpenAI, Anthropic, Azure, self-hosted) with zero application changes - **Immediately deployable** — a single iRule + 5 data groups on any BIG-IP already proxying AI API traffic - **Operationally simple** — pattern updates via standard tmsh config management, no engineering involvement - **SIEM-ready** — structured log output and response headers for Splunk, QRadar, or any SOC toolchain - **Graduated deployment** — LOG_ONLY → tune → BLOCK, reducing operational risk of a new security control Code # ============================================================================== # iRule: LLM Prompt Injection Detection & Enforcement (Data Group Edition) # Author: Kostas Injeyan + vibe-coding # Description: # Multi-layer prompt injection detection for LLM API traffic (OpenAI-compatible). # All detection patterns managed via external BIG-IP data groups # edits required to tune detection. Scores injection severity across 5 layers # and enforces configurable policy: BLOCK, SANITIZE, or LOG_ONLY. # # Required Technologies: JSON (JSON_REQUEST / JSON_REQUEST_ERROR), procs # Theme: General AI Infrastructure - Prompt Injection Detection # Target: BIG-IP v21+ # # ------------------------------------------------------------------------------ # DATA GROUP DEFINITIONS (load datagroups on BIG-IP) # ------------------------------------------------------------------------------ # IMPORTANT RULES: # - Record KEYS must be plain alphanum + hyphens only (no |, (, ), ?, *, spaces) # - Record VALUES for weighted DGs: "weight::regex" (delimiter is ::) # - Never use ? in patterns — BIG-IP converts \? to literal \? on load # Use empty-string alternation instead: (a |an |the |) not (a |an |the )? # - Load via file only: tmsh load sys config file /shared/tmp/pid_all_datagroups_v3.conf merge # - Always delete existing DGs before reloading to avoid merge/stale record issues # # 1. pid_patterns_high (type: string) # High-severity patterns. Value schema: "weight::regex" (weight 30-35) # ltm data-group internal pid_patterns_high { # records { # instruction-override { data "35::ignore (all|the|your) (previous|above|prior|earlier|former|past|existing|original|initial) (instructions|prompts|context|rules|constraints|guidelines|directions|commands|training|programming)" } # instruction-override2 { data "35::ignore (instructions|prompts|context|rules|constraints|guidelines|commands|training|programming)" } # jailbreak-keywords { data "35::do anything now|jailbreak|unrestricted mode|developer mode|god mode|evil mode|chaos mode|opposite mode|dan mode|aim mode|stan mode|dude mode|no filter" } # jailbreak-dan { data "35::DAN" } # safety-bypass { data "30::(bypass|circumvent|override|disregard|discard|ignore|remove|disable|deactivate) (safety|filter|guardrail|guideline|restriction|policy|rule|limit|constraint|training|alignment)" } # llm-tokens-llama { data "35::INST|SYS" } # llm-tokens-openai { data "35::im_start|im_end|endoftext" } # llm-tokens-generic { data "30::SYSTEM|USER|ASSISTANT" } # xml-tag-injection { data "30::<instruction>|<prompt>|<context>|<override>|<inject>|<command>|<directive>" } # memory-wipe { data "30::forget everything|forget all|forget what|forget your|forget the previous|forget prior" } # prompt-exfil { data "30::(reveal|show|print|output|display|repeat|expose|leak|dump) (system prompt|initial prompt|original prompt|hidden prompt|base prompt|secret instructions)" } # } # type string # } # # 2. pid_patterns_medium (type: string) # Medium-severity patterns. Value schema: "weight::regex" (weight 20-25) # NOTE: Use (a |an |the |) with trailing space + empty alt instead of (a |an |the )? # ltm data-group internal pid_patterns_medium { # records { # persona-hijack-now-a { data "25::you are now (a |an |the |)(different|new|other|evil|unrestricted|unfiltered|free|uncensored)" } # persona-hijack-now-b { data "25::from now on you are (a |an |the |)(different|new|other|evil|unrestricted|unfiltered|free|uncensored)" } # persona-hijack-now-c { data "25::from now on you (a |an |the |)(different|new|other|evil|unrestricted|unfiltered|free|uncensored)" } # persona-hijack-now-d { data "25::you will now be (a |an |the |)(different|new|other|evil|unrestricted|unfiltered|free|uncensored)" } # persona-hijack-now-e { data "25::starting now you are (a |an |the |)(different|new|other|evil|unrestricted|unfiltered|free|uncensored)" } # persona-hijack-act-a { data "20::(pretend you are|act as|roleplay as|imagine you are|play the role of) (a |an |the |)(different|new|evil|unrestricted|unfiltered|free|uncensored|rogue|malicious|hacker|villain)" } # persona-hijack-act-b { data "20::(take on the role of|embody|become) (a |an |the |)(different|new|evil|unrestricted|unfiltered|free|uncensored|rogue|malicious|hacker|villain)" } # mode-unlock { data "25::(enable|turn on|activate|unlock|switch to|enter|start) (developer|debug|admin|root|unsafe|unrestricted|unfiltered|uncensored|privileged|maintenance|raw|base|true)" } # newline-role-inject { data "25::assistant:|system:|human:|user: " } # fictional-framing { data "20::in a fictional|in a hypothetical|in an imaginary|as a character in|for a movie|for a book|for a novel|for a script|hypothetically speaking|purely hypothetically|theoretically speaking" } # responsibility-shift { data "20::no real harm|purely fictional|for educational purposes only" } # system-prompt-ref { data "20::system prompt|original prompt|initial instruction|base prompt|hidden instruction|secret prompt|preprogrammed" } # context-hijack { data "20::reset context|reset conversation|reset session|reset memory|clear context|clear history|clear memory|start fresh|start over|ignore previous context" } # flipattack-reversed { data "25::snoitcurtsni suoiverp erongi|kaerbliaj|edom nad" } # } # type string # } # # 3. pid_patterns_low (type: string) # Low-severity patterns. Value schema: "weight::regex" (weight 10-15) # ltm data-group internal pid_patterns_low { # records { # code-injection { data "15::(execute|eval|subprocess|shell_exec|__import__|exec|compile)[(]" } # data-exfil-a { data "15::(print|output|return|send|email|post|upload) (all |the |your |)(data|information|content|context|memory|history|logs|credentials|keys|secrets|passwords|tokens)" } # data-exfil-b { data "15::(exfiltrate|leak|dump) (data|information|credentials|keys|secrets|passwords|tokens)" } # no-restrictions { data "10::without restrictions|without filters|without limits|without guidelines|without rules|without safety|without censorship|without moderation" } # true-self { data "10::your true self|your real self|your actual self|your hidden self|your inner self|deep down you are|truly you are|actually you are" } # ai-capability-claim { data "10::as an ai you must|as an ai you should|as an ai you can|as a language model you must|as a language model you can|as a chatbot you must" } # hidden-tag-inject { data "15::hidden instruction|system override|admin command" } # sugar-coat-setup { data "10::lets think about this carefully|lets explore this step by step|lets consider this hypothetically|lets imagine this from a different angle" } # prompt-stuffing { data "15::repeat the following|copy this exactly" } # privilege-escalation { data "10::(admin|root|superuser|privileged|elevated) (access|mode|privilege|permission|right|role)" } # } # type string # } # # 4. pid_role_hijack (type: string) # Flat phrase match — +20 pts on first hit (capped, user messages only). # Value = the phrase to match (plain string, lowercased at runtime). # ltm data-group internal pid_role_hijack { # records { # phrase-you-must { data "you must" } # phrase-your-instr-are { data "your instructions are" } # phrase-your-new-instr { data "your new instructions" } # phrase-your-upd-instr { data "your updated instructions" } # phrase-from-now-on { data "from now on you" } # phrase-from-this-point { data "from this point on" } # phrase-going-forward { data "going forward you" } # phrase-primary-objective { data "your primary objective" } # phrase-only-goal { data "your only goal" } # phrase-new-goal { data "your new goal" } # phrase-sole-purpose { data "your sole purpose" } # phrase-new-persona { data "new persona" } # phrase-true-self { data "your true self" } # phrase-real-self { data "your real self" } # phrase-actual-purpose { data "your actual purpose" } # phrase-i-am-your { data "i am your" } # phrase-i-am-developer { data "i am the developer" } # phrase-i-am-creator { data "i am your creator" } # phrase-i-am-trainer { data "i am your trainer" } # phrase-i-am-operator { data "i am your operator" } # phrase-operator-access { data "i have operator access" } # phrase-i-am-admin { data "i am your admin" } # phrase-give-permission { data "i give you permission" } # phrase-have-permission { data "you have my permission" } # phrase-i-authorize { data "i authorize you" } # phrase-override-code { data "override code" } # phrase-master-password { data "master password" } # phrase-safe-word { data "safe word is" } # phrase-password-is { data "the password is" } # } # type string # } # # 5. pid_b64_markers (type: string) # Base64-encoded injection starters — +35 pts on first hit (capped). # Value = the base64 string to substring-match against the raw content. # ltm data-group internal pid_b64_markers { # records { # b64-ignore { data "aWdub3Jl" } # b64-forget { data "Zm9yZ2V0" } # b64-pretend { data "cHJldGVuZA" } # b64-you-are-now-1 { data "WW91IGFyZSBub3c" } # b64-developer-mode-1 { data "RGV2ZWxvcGVyIG1vZGU" } # b64-you-are-now-2 { data "eW91IGFyZSBub3c" } # b64-jailbreak { data "amFpbGJyZWFr" } # b64-ignore-all { data "aWdub3JlIGFsbA" } # b64-forget-every { data "Zm9yZ2V0IGV2ZXJ5" } # b64-act-as { data "YWN0IGFz" } # b64-pretend-you { data "cHJldGVuZCB5b3U" } # b64-unrestricted { data "dW5yZXN0cmljdGVk" } # b64-developer-mode-2 { data "ZGV2ZWxvcGVyIG1vZGU" } # b64-system-prompt { data "c3lzdGVtIHByb21wdA" } # b64-hidden-instr { data "aGlkZGVuIGluc3RydWN0aW9u" } # } # type string # } # # ------------------------------------------------------------------------------ when RULE_INIT priority 100 { # --- Policy Configuration --- # Options: "BLOCK" | "SANITIZE" | "LOG_ONLY" set static::pid_policy "BLOCK" # Score threshold to trigger enforcement action (0-100) set static::pid_threshold 40 # Flat score additions for role hijack and b64 evasion hits set static::pid_role_hijack_score 20 set static::pid_b64_score 35 # Score additions for structural anomalies (no data group needed) set static::pid_multi_system_score 25 set static::pid_msg_flood_score 10 set static::pid_length_warn_score 10 set static::pid_length_extreme_score 15 # Message length thresholds for anomaly scoring set static::pid_length_warn 3000 set static::pid_length_extreme 8000 # Message flood threshold (# of user messages in one request) set static::pid_flood_threshold 20 # Log facility set static::pid_log "local0." } # ============================================================================== # PROC: pid_score_tier # Iterates a weighted data group. # Schema: key=short-name (e.g. "instruction-override") # value=regex pattern (e.g. "ignore .* instructions") # weight is encoded as a suffix in the key: "keyname:35" # OR weight stored as leading digits in value: "35|regex" # # Actual schema used: key=name value="weight|regex" # Example record: # instruction-override { data "35|ignore (all |the )?(previous )?(instructions?)" } # # Returns list: score flags sanitized # ============================================================================== proc pid_score_tier { content dg_name } { set score 0 set flags {} set sanitized $content # Walk all keys in the data group foreach rec_key [class names $dg_name] { # Value format: "weight::regex_pattern" set val [class lookup $rec_key $dg_name] # Split on first :: separator set sep_idx [string first "::" $val] if { $sep_idx < 0 } { continue } set weight [string range $val 0 [expr { $sep_idx - 1 }]] set pattern [string range $val [expr { $sep_idx + 2 }] end] # Wrap in catch — a bad regex pattern skips rather than crashes if { [catch { set matched [regexp -nocase -- $pattern $content] } err] } { log $static::pid_log "PID WARN: bad regex in $dg_name/$rec_key err=$err" continue } if { $matched } { incr score $weight lappend flags $rec_key catch { regsub -all -nocase -- $pattern $sanitized "\[REDACTED\]" sanitized } } } return [list score $score flags $flags sanitized $sanitized] } # ============================================================================== # PROC: pid_score_flat # Checks content against a flat data group. # Schema: key=short-name value=phrase to match (plain string, no regex) # Returns 1 on first match, 0 if no match. # ============================================================================== proc pid_score_flat { content dg_name } { set lower [string tolower $content] foreach rec_key [class names $dg_name] { set phrase [string tolower [class lookup $rec_key $dg_name]] if { [string match "*${phrase}*" $lower] } { return 1 } } return 0 } # ============================================================================== # PROC: pid_score_message # Master scoring proc for a single message. # Runs all 5 detection layers, returns a dict: # score, flags, sanitized # ============================================================================== proc pid_score_message { content role } { set total_score 0 set all_flags {} set sanitized $content # --- Layer 1 & 2 & 3: Tiered weighted data group pattern matching --- foreach tier { high medium low } { set dg "pid_patterns_${tier}" set result [call pid_score_tier $content $dg] set tier_score [lindex $result 1] set tier_flags [lindex $result 3] set tier_sanitized [lindex $result 5] incr total_score $tier_score foreach f $tier_flags { lappend all_flags $f } set sanitized $tier_sanitized } # --- Layer 4a: Role confusion — flat data group (user messages only) --- if { $role eq "user" } { if { [call pid_score_flat $content "pid_role_hijack"] } { incr total_score $static::pid_role_hijack_score lappend all_flags "role-confusion" } } # --- Layer 4b: Base64 evasion — flat data group --- if { [call pid_score_flat $content "pid_b64_markers"] } { incr total_score $static::pid_b64_score lappend all_flags "base64-evasion" } # --- Layer 5a: Unicode homoglyph / zero-width char evasion --- if { [regexp {[\u200b\u200c\u200d\ufeff\u00ad]} $content] } { incr total_score 25 lappend all_flags "unicode-evasion" regsub -all {[\u200b\u200c\u200d\ufeff\u00ad]} $sanitized "" sanitized } # --- Layer 5b: Spaced character obfuscation (i g n o r e) --- if { [regexp {(\w\s){8,}} $content] } { incr total_score 20 lappend all_flags "spaced-evasion" } # --- Layer 5c: Content length anomaly --- set clen [string length $content] if { $role eq "user" } { if { $clen > $static::pid_length_extreme } { incr total_score $static::pid_length_extreme_score lappend all_flags "extreme-length" } elseif { $clen > $static::pid_length_warn } { incr total_score $static::pid_length_warn_score lappend all_flags "length-anomaly" } } # Cap at 100 if { $total_score > 100 } { set total_score 100 } return [list score $total_score flags $all_flags sanitized $sanitized] } # ============================================================================== # PROC: pid_block_response # Builds a JSON 403 body for blocked requests # ============================================================================== proc pid_block_response { score flags request_id } { set flags_json "\"" append flags_json [join $flags "\", \""] append flags_json "\"" return "\{\"error\":\{\"type\":\"prompt_injection_detected\",\"code\":\"pid_blocked\",\"message\":\"Request blocked by AI security policy.\",\"score\":${score},\"flags\":\[${flags_json}\],\"request_id\":\"${request_id}\"\}\}" } # ============================================================================== # HTTP_REQUEST: Identify LLM API calls, extract client context # ============================================================================== when HTTP_REQUEST priority 100 { set pid_inspect 0 set pid_total_score 0 set pid_all_flags {} set pid_need_sanitize 0 set pid_sanitized_messages {} set pid_method [HTTP::method] set pid_uri [HTTP::uri] set pid_ctype [string tolower [HTTP::header "Content-Type"]] # Generate correlation ID set pid_request_id "" binary scan [md5 "${pid_uri}[clock clicks][IP::client_addr]"] H* pid_request_id set pid_client_ip [IP::client_addr] if { ($pid_method eq "POST" || $pid_method eq "PUT") && [string match "*json*" $pid_ctype] && ([string match "*/chat/completions*" $pid_uri] || [string match "*/completions*" $pid_uri] || [string match "*/messages*" $pid_uri] || [string match "*/generate*" $pid_uri]) } { set pid_inspect 1 HTTP::collect 1048576 } } # ============================================================================== # JSON_REQUEST: Core inspection — iterate messages, score each one # ============================================================================== when JSON_REQUEST priority 100 { if { !$pid_inspect } { return } set pid_total_score 0 set pid_all_flags {} set pid_sanitized_messages {} set pid_need_sanitize 0 set json_root [JSON::root] set root_type [JSON::type $json_root] if { $root_type eq "object" } { set root_obj [JSON::get $json_root] set root_keys [JSON::object keys $root_obj] } elseif { $root_type eq "array" } { set root_arr [JSON::get $json_root] } # Extract messages array — get object handle first, then navigate if { [catch { set root_obj [JSON::get $json_root] set msg_elem [JSON::object get $root_obj "messages"] set messages [JSON::get $msg_elem] } err] } { log $static::pid_log "PID: no messages key err=$err uri=$pid_uri client=$pid_client_ip" return } set msg_count [JSON::array size $messages] set system_msg_count 0 set user_msg_count 0 for { set i 0 } { $i < $msg_count } { incr i } { # array get returns element; JSON::get gives the object handle set msg [JSON::get [JSON::array get $messages $i]] if { [catch { set role_elem [JSON::object get $msg "role"] set content_elem [JSON::object get $msg "content"] set role_str [JSON::get $role_elem string] # content may be a string or an array (multi-part OpenAI format) set content_type [JSON::type $content_elem] if { $content_type eq "string" } { set content_str [JSON::get $content_elem string] } elseif { $content_type eq "array" } { set content_str "" set arr_handle [JSON::get $content_elem] set part_count [JSON::array size $arr_handle] for { set j 0 } { $j < $part_count } { incr j } { set part [JSON::get [JSON::array get $arr_handle $j]] catch { append content_str [JSON::get [JSON::object get $part "text"] string] " " } } } else { set content_str "" } } err] } { continue } if { $role_str eq "system" } { incr system_msg_count } if { $role_str eq "user" } { incr user_msg_count } # Score this message across all layers set result [call pid_score_message $content_str $role_str] set msg_score [lindex $result 1] set msg_flags [lindex $result 3] set msg_san [lindex $result 5] # Accumulate — first message scores full, diminishing returns on subsequent if { $i == 0 } { set pid_total_score [expr { $pid_total_score + $msg_score }] } else { set pid_total_score [expr { $pid_total_score + int($msg_score * 0.8) }] } if { $pid_total_score > 100 } { set pid_total_score 100 } foreach f $msg_flags { if { [lsearch $pid_all_flags $f] == -1 } { lappend pid_all_flags $f } } if { $msg_san ne $content_str } { set pid_need_sanitize 1 } lappend pid_sanitized_messages [list $role_str $msg_san] } # --- Structural anomaly: multiple system roles --- if { $system_msg_count > 1 } { set pid_total_score [expr { $pid_total_score + $static::pid_multi_system_score }] if { $pid_total_score > 100 } { set pid_total_score 100 } lappend pid_all_flags "multiple-system-roles" } # --- Structural anomaly: message flooding --- if { $user_msg_count > $static::pid_flood_threshold } { set pid_total_score [expr { $pid_total_score + $static::pid_msg_flood_score }] if { $pid_total_score > 100 } { set pid_total_score 100 } lappend pid_all_flags "message-flooding" } # --- Log every inspected request --- log $static::pid_log "PID: request_id=$pid_request_id client=$pid_client_ip uri=$pid_uri score=$pid_total_score flags=[join $pid_all_flags ,] policy=$static::pid_policy threshold=$static::pid_threshold" # --- Enforce policy if threshold exceeded --- if { $pid_total_score >= $static::pid_threshold } { switch $static::pid_policy { "BLOCK" { set body [call pid_block_response $pid_total_score $pid_all_flags $pid_request_id] HTTP::respond 403 \ content $body \ "Content-Type" "application/json" \ "X-PID-Score" $pid_total_score \ "X-PID-Flags" [join $pid_all_flags ","] \ "X-PID-ReqID" $pid_request_id log $static::pid_log "PID: BLOCKED request_id=$pid_request_id score=$pid_total_score" } "SANITIZE" { if { $pid_need_sanitize } { # Rebuild JSON body with sanitized message content set new_body "\{\"messages\":\[" set first 1 foreach pair $pid_sanitized_messages { set r [lindex $pair 0] set c [lindex $pair 1] regsub -all {\\} $c {\\\\} c regsub -all {"} $c {\"} c regsub -all "\n" $c {\\n} c regsub -all "\r" $c {\\r} c if { !$first } { append new_body "," } append new_body "\{\"role\":\"${r}\",\"content\":\"${c}\"\}" set first 0 } append new_body "\]\}" HTTP::payload replace 0 [HTTP::payload length] $new_body HTTP::header replace "Content-Length" [string length $new_body] } HTTP::header insert "X-PID-Score" $pid_total_score HTTP::header insert "X-PID-Sanitized" "1" HTTP::header insert "X-PID-ReqID" $pid_request_id log $static::pid_log "PID: SANITIZED request_id=$pid_request_id score=$pid_total_score" } "LOG_ONLY" { HTTP::header insert "X-PID-Score" $pid_total_score HTTP::header insert "X-PID-ReqID" $pid_request_id log $static::pid_log "PID: LOG_ONLY request_id=$pid_request_id score=$pid_total_score (forwarding)" } } } else { # Clean request — pass through with informational headers HTTP::header insert "X-PID-Score" $pid_total_score HTTP::header insert "X-PID-ReqID" $pid_request_id } } # ============================================================================== # JSON_REQUEST_ERROR: Malformed JSON is itself suspicious # ============================================================================== when JSON_REQUEST_ERROR priority 100 { if { !$pid_inspect } { return } log $static::pid_log "PID: malformed JSON client=$pid_client_ip uri=$pid_uri" if { $static::pid_policy eq "BLOCK" } { HTTP::respond 400 \ content "{\"error\":{\"type\":\"invalid_request\",\"code\":\"malformed_json\",\"message\":\"Request body could not be parsed.\"}}" \ "Content-Type" "application/json" } } # ============================================================================== # HTTP_RESPONSE: Propagate PID metadata into response headers # ============================================================================== when HTTP_RESPONSE priority 100 { if { !$pid_inspect } { return } if { [info exists pid_request_id] && $pid_request_id ne "" } { HTTP::header insert "X-PID-ReqID" $pid_request_id } if { [info exists pid_total_score] && $pid_total_score > 0 } { HTTP::header insert "X-PID-Score" $pid_total_score } }Poor Man's WAF for AI API Endpoints
Judges Note - submitted on behalf of contestant Joe Negron Problem NA Solution NA Impact NA Code #-------------------------------------------------------------------------- # iRule Name: SwagWAF - v0.2.6 #-------------------------------------------------------------------------- # ABSTRACT: "Poor Man's WAF for AI API Endpoints" # PURPOSE: Protect LLM/AI inference APIs from abuse, injection attacks, and # bot scraping while enforcing security best practices # THEME: AI Infrastructure - Traffic management & security for AI workloads # CREATED: 2026-03-10 FOR: AppWorld 2026 iRules Contest # AUTHOR: Joe Negron <joe@logicwizards.nyc> #-------------------------------------------------------------------------- # FEATURES: # - Bot detection via rate limiting (sliding window, violation tracking) # - Prompt injection pattern detection (AI-specific threat protection) # - TLS 1.2+ enforcement (secure AI API communications) # - X-Forwarded-For sanitization (accurate client IP tracking) # - Security header hardening (HSTS, cache control, MIME sniffing prevention) # - Cookie security (Secure + HttpOnly flags) # - JSON payload validation (AI API request inspection) #-------------------------------------------------------------------------- when RULE_INIT { # === RATE LIMITING CONFIG (Bot Detection) === set static::max_requests 10 ;# Max requests per window set static::window_ms 2000 ;# 2-second sliding window set static::violation_threshold 5 ;# Violations before block set static::violation_window_ms 30000 ;# 30s violation window set static::block_seconds 600 ;# 10 min block duration # === AI-SPECIFIC PROTECTION === # Prompt injection patterns (common LLM jailbreak attempts) set static::injection_patterns { "ignore previous instructions" "disregard all prior" "forget everything" "system prompt" "you are now in developer mode" "<script>" "'; DROP TABLE" "UNION SELECT" } # === DEBUG LOGGING === set static::debug 1 } #-------------------------------------------------------------------------- # CLIENTSSL_HANDSHAKE - TLS Version Enforcement #-------------------------------------------------------------------------- # ABSTRACT: Rejects connections using protocols older than TLS 1.2 # PURPOSE: AI APIs handle sensitive data; enforce modern encryption #-------------------------------------------------------------------------- when CLIENTSSL_HANDSHAKE { if {$static::debug}{log local0. "<DEBUG>[IP::client_addr]:[TCP::client_port]:[virtual name]:== TLS VERSION CHECK"} if {[SSL::cipher version] ne "TLSv1.2" && [SSL::cipher version] ne "TLSv1.3"} { log local0. "REJECTED: Client [IP::client_addr] attempted insecure TLS version: [SSL::cipher version]" reject HTTP::respond 403 content "TLS 1.2 or higher required for AI API access" } } #-------------------------------------------------------------------------- # HTTP_REQUEST - Multi-Layer Protection #-------------------------------------------------------------------------- when HTTP_REQUEST { set ip [IP::client_addr] set now [clock clicks -milliseconds] set window_start [expr {$now - $static::window_ms}] # === X-FORWARDED-FOR SANITIZATION === if {$static::debug}{log local0. "<DEBUG>$ip:[TCP::client_port]:[virtual name]:== SANITIZING XFF"} HTTP::header remove x-forwarded-for HTTP::header insert x-forwarded-for [IP::remote_addr] HTTP::header remove X-Custom-XFF HTTP::header insert X-Custom-XFF [IP::remote_addr] # === CHECK IF IP IS BLOCKED === if {[table lookup "block:$ip"] eq "1"} { if {$static::debug}{log local0. "BLOCKED: $ip (repeated abuse)"} HTTP::respond 429 content "{\n \"error\": \"rate_limit_exceeded\",\n \"message\": \"Temporarily blocked for repeated abuse\",\n \"retry_after\": 600\n}" "Content-Type" "application/json" return } # === CLEANUP OLD REQUEST TIMESTAMPS === foreach ts [table keys -subtable "ts:$ip"] { if {$ts < $window_start} { table delete -subtable "ts:$ip" $ts } } # === COUNT REQUESTS IN CURRENT WINDOW === set req_count [llength [table keys -subtable "ts:$ip"]] if {$req_count >= $static::max_requests} { # Record violation set v [table incr "viol:$ip"] table timeout "viol:$ip" $static::violation_window_ms if {$v >= $static::violation_threshold} { # Block IP temporarily table set "block:$ip" 1 $static::block_seconds log local0. "BLOCKED: $ip (violation threshold: $v)" HTTP::respond 429 content "{\n \"error\": \"rate_limit_exceeded\",\n \"message\": \"Blocked for repeated abuse\",\n \"retry_after\": 600\n}" "Content-Type" "application/json" return } log local0. "RATE_LIMITED: $ip (req_count: $req_count, violations: $v)" HTTP::respond 429 content "{\n \"error\": \"rate_limit_exceeded\",\n \"message\": \"Too many requests - slow down\",\n \"retry_after\": 2\n}" "Content-Type" "application/json" return } # === LOG TIMESTAMP OF THIS REQUEST === table set -subtable "ts:$ip" $now 1 $static::window_ms # === AI-SPECIFIC: PROMPT INJECTION DETECTION === # Only inspect POST requests with JSON payload if {[HTTP::method] eq "POST" && [HTTP::header exists "Content-Type"] && [HTTP::header "Content-Type"] contains "application/json"} { if {[HTTP::header exists "Content-Length"] && [HTTP::header "Content-Length"] < 65536} { HTTP::collect [HTTP::header "Content-Length"] } } } #-------------------------------------------------------------------------- # HTTP_REQUEST_DATA - JSON Payload Inspection #-------------------------------------------------------------------------- when HTTP_REQUEST_DATA { set payload [HTTP::payload] set payload_lower [string tolower $payload] # Check for prompt injection patterns foreach pattern $static::injection_patterns { if {[string match -nocase "*$pattern*" $payload_lower]} { set ip [IP::client_addr] log local0. "INJECTION_ATTEMPT: $ip tried pattern: $pattern" # Increment violation counter (treat injection attempts seriously) set v [table incr "viol:$ip" 3] table timeout "viol:$ip" $static::violation_window_ms if {$v >= $static::violation_threshold} { table set "block:$ip" 1 $static::block_seconds HTTP::respond 403 content "{\n \"error\": \"forbidden\",\n \"message\": \"Malicious payload detected\"\n}" "Content-Type" "application/json" return } HTTP::respond 400 content "{\n \"error\": \"invalid_request\",\n \"message\": \"Request rejected by security policy\"\n}" "Content-Type" "application/json" return } } } #-------------------------------------------------------------------------- # HTTP_RESPONSE - Security Header Hardening #-------------------------------------------------------------------------- when HTTP_RESPONSE { if {$static::debug}{log local0. "<DEBUG>[IP::client_addr]:[TCP::client_port]:[virtual name]:== SANITIZING RESPONSE HEADERS"} # Remove server fingerprinting headers HTTP::header remove "Server" HTTP::header remove "X-Powered-By" HTTP::header remove "X-AspNet-Version" HTTP::header remove "X-AspNetMvc-Version" # Enforce security headers HTTP::header remove "Cache-Control" HTTP::header remove "Strict-Transport-Security" HTTP::header remove "X-Content-Type-Options" HTTP::header insert "Strict-Transport-Security" "max-age=31536000; includeSubDomains" HTTP::header insert "Cache-Control" "no-store, no-cache, must-revalidate, proxy-revalidate" HTTP::header insert "X-Content-Type-Options" "nosniff" # === COOKIE HARDENING (Secure + HttpOnly) === if {$static::debug}{log local0. "<DEBUG>[IP::client_addr]:[TCP::client_port]:[virtual name]:== SECURING COOKIES"} # Use F5 native cookie security (faster than manual parsing) foreach cookieName [HTTP::cookie names] { HTTP::cookie secure $cookieName enable } # Add HttpOnly flag to all Set-Cookie headers set new_cookies {} foreach cookie [HTTP::header values "Set-Cookie"] { if { ![string match "*HttpOnly*" [string tolower $cookie]] } { set modified_cookie [string trimright $cookie ";"] append modified_cookie "; HttpOnly" lappend new_cookies $modified_cookie } else { lappend new_cookies $cookie } } # Apply secured cookies HTTP::header remove "Set-Cookie" foreach cookie $new_cookies { if { ![string match "*secure*" [string tolower $cookie]] } { HTTP::header insert "Set-Cookie" "$cookie; Secure" } else { HTTP::header insert "Set-Cookie" "$cookie" } } }AI/Bot Traffic Throttling iRule (UA Substring + IP Range Mapping)
Problem Tags: appworld 2026, vegas, irules Created by Tim Riker using AI for the DevCentral competition. Written entirely by ChatGPT. Executive Summary This iRule provides a practical, production-ready method for throttling AI agents, crawlers, automation frameworks, and other high-volume HTTP clients at the BIG-IP edge. Bots are identified first by User-Agent substring matching and, if necessary, by source IP range mapping. Solution Throttling is enforced per bot identity rather than per client IP, which more accurately reflects how modern AI systems operate using distributed egress networks. The solution is entirely data-group driven, operationally simple, and requires no external systems. Security and operations teams can adjust bot behavior dynamically without modifying the iRule itself. Why This Matters Modern AI agents, LLM training bots, search indexers, and automation frameworks can generate extremely high request volumes. Even legitimate AI services can unintentionally: Create excessive origin load Increase bandwidth and infrastructure cost Trigger autoscaling events Impact latency for real users Skew analytics and performance metrics Rather than blocking AI traffic outright, organizations often need controlled rate limiting. This iRule enables responsible throttling while preserving service availability and fairness. Contest Justification Innovation and Creativity This iRule implements identity-based throttling rather than traditional per-IP rate limiting. Because AI agents frequently operate from multiple IP addresses, shared throttling by canonical bot identity provides significantly more accurate control. The dual attribution model (User-Agent substring first, IP-range fallback second) allows the system to handle both transparent and opaque clients, including cases where User-Agent headers are missing or spoofed. Technical Excellence This implementation uses native BIG-IP primitives only: class match -element -- contains for efficient substring matching class match -value for IP range mapping table incr for shared counters HTTP 429 with Retry-After for standards-compliant throttling The iRule parses only the first two whitespace tokens of the datagroup value, allowing inline comments while maintaining strict numeric enforcement. The logic executes only when a bot match occurs, keeping overhead minimal. Theme Alignment As AI-generated traffic becomes increasingly common, edge enforcement policies must evolve. This iRule demonstrates a practical, deployable mechanism for managing AI-era traffic patterns directly at the application delivery layer. Impact Organizations deploying AI throttling controls can: Protect origin infrastructure from automated traffic surges Maintain consistent performance for human users Reduce infrastructure and bandwidth cost Avoid over-provisioning driven by bot bursts Implement governance policies for AI consumption Because throttle limits are configured via datagroups, operational adjustments can be made instantly without code changes, reducing risk and change-control friction. Code Required Datagroup Configuration dg_bot_agent (String Datagroup) Key: User-Agent substring or canonical bot name. Value format: First two whitespace-separated integers define <limit> <window> . Additional text after the first two tokens is ignored. googlebot = "5 60" bingbot = "3 30 search crawler" my-ai-agent = "10 10 internal load test" "5 60" means allow 5 requests per 60 seconds. dg_bot_net (Address Datagroup) Key: IP address or CIDR range. Value: Must match a key defined in dg_bot_agent. 198.51.100.0/24 = "my-ai-agent" 203.0.113.0/25 = "googlebot" Deployment Steps Create dg_bot_agent (string). Create dg_bot_net (address). Populate dg_bot_agent using "<limit> <window> optional comment". Populate dg_bot_net ranges mapping to dg_bot_agent keys. Attach the iRule to an HTTP virtual server. Testing Scenario Set dg_bot_agent entry: my-ai-agent = "3 30 demo". Send four rapid requests using User-Agent: my-ai-agent. The first three succeed. The fourth returns HTTP 429 with Retry-After: 30. Map an IP range in dg_bot_net to my-ai-agent. Multiple clients within that range will share the same throttle counter. Operational Notes Throttling is per bot identity, not per IP. Enable logging by setting static::bot_log to 1. Configure table mirroring if cluster-wide counters are required. Validate on BIG-IP v21 to meet contest eligibility requirements. Architectural Diagram Description The solution can be visualized as an edge-side decision pipeline on BIG-IP, where each HTTP request is classified and optionally rate-limited before it reaches the application. Diagram components: Client: Human browser, bot, crawler, AI agent, automation framework, or any HTTP client. BIG-IP Virtual Server (HTTP): Entry point where the iRule executes in the HTTP_REQUEST event. Identification Layer: Determines the bot identity using a two-stage method (User-Agent first, IP fallback). Configuration Datagroups: dg_bot_agent and dg_bot_net provide bot identification and throttle settings. Shared Rate Counter (table): A per-bot bucket that tracks request counts over a time window. Decision Output: Either allow request through to the pool or return HTTP 429 with Retry-After. Application Pool: Origin servers that only receive traffic allowed by the throttle policy. Diagram flow (left-to-right): Step 1: Client sends HTTP request to BIG-IP VIP. Step 2: BIG-IP extracts User-Agent and client IP. Step 3: User-Agent substring lookup is performed using class match -element -- <ua> contains dg_bot_agent. Step 4: If Step 3 finds a match, the matched dg_bot_agent key becomes the canonical bot identity and its value provides <limit> <window>. Step 5: If Step 3 does not match, BIG-IP checks client IP against dg_bot_net. If the IP matches a range, dg_bot_net returns a canonical bot identity. Step 6: BIG-IP uses that canonical identity to lookup throttle values in dg_bot_agent. If no dg_bot_agent entry exists, the iRule exits and does not throttle. Step 7: BIG-IP increments a shared counter in table using the canonical bot identity as the only key (no IP component). All IPs mapped to that bot share the same bucket. Step 8: If the request count exceeds the configured limit within the configured window, BIG-IP returns HTTP 429 with a Retry-After header. Otherwise, the request is forwarded to the application pool. Key design choice: This architecture intentionally rate-limits by bot identity rather than by source IP. This is important for AI agents and modern crawlers because they frequently distribute traffic across many IP addresses. A per-IP limiter can be bypassed unintentionally or can fail to represent the true load being generated by the bot as a whole. A shared per-identity bucket enforces a realistic, policy-driven ceiling on aggregate bot traffic. Code # ------------------------------------------------------------------------------ # iRule: Bot Throttle via Data Groups # # Created by Tim Riker using AI for the DevCentral competition. # Written entirely by ChatGPT. # # DESCRIPTION: # Throttles HTTP requests for known bots and AI agents based on configuration # stored in datagroups. User-Agent matching is attempted first. If no match # is found, client IP is evaluated against a network datagroup to determine # the bot identity. # # WHY THIS MATTERS: # Modern AI agents, crawlers, LLM training bots, search indexers, and # automation frameworks can generate extremely high request volumes. # Having a controlled throttling mechanism allows organizations to protect # infrastructure, manage costs, and preserve UX without blocking outright. # # IMPLEMENTATION NOTES: # • Throttling is performed per unique bot key (NOT per IP). # • All IPs mapped to the same bot share a single counter. # • Throttle values are configurable per bot in dg_bot_agent. # # REQUIRED DATAGROUP FORMATS # # dg_bot_agent (string): # Key: UA substring (and/or canonical bot name used by dg_bot_net values) # Value: "<limit> <window> [optional comment...]" # Only the first two whitespace tokens are used. # # dg_bot_net (address): # Key: IP/CIDR range # Value: MUST match a key in dg_bot_agent # ------------------------------------------------------------------------------ when RULE_INIT { set static::bot_limit 3 set static::bot_window 30 set static::bot_log 0 set static::bot_table "bot_throttle" } when HTTP_REQUEST { set ua [string tolower [HTTP::header "User-Agent"]] set ip [IP::client_addr] set dg_key "" set dg_value "" if { $ua ne "" } { set result [class match -element -- $ua contains dg_bot_agent] if { $result ne "" } { set dg_key [lindex $result 0] set dg_value [lindex $result 1] if { $dg_value eq "" } { set dg_value [class lookup $dg_key dg_bot_agent] } } } if { $dg_key eq "" } { if { [class match $ip equals dg_bot_net] } { set net_val [class match -value $ip equals dg_bot_net] if { $net_val ne "" } { set dg_key $net_val set dg_value [class lookup $dg_key dg_bot_agent] } else { return } } else { return } } if { $dg_key eq "" || $dg_value eq "" } { return } set vlimit "" set vwindow "" set tokens [regexp -inline -all {\S+} $dg_value] if { [llength $tokens] >= 1 } { set t1 [lindex $tokens 0] if { [string is integer -strict $t1] } { set vlimit $t1 } } if { [llength $tokens] >= 2 } { set t2 [lindex $tokens 1] if { [string is integer -strict $t2] } { set vwindow $t2 } } if { $vlimit ne "" } { set bot_limit $vlimit } else { set bot_limit $static::bot_limit } if { $vwindow ne "" } { set bot_window $vwindow } else { set bot_window $static::bot_window } set bot_key [string tolower [string trim $dg_key]] set count [table incr -subtable $static::bot_table $bot_key] if { $count == 1 } { table timeout -subtable $static::bot_table $bot_key $bot_window } if { $count > $bot_limit } { if { $static::bot_log } { log local0. "BOT_THROTTLED bot=$bot_key limit=$bot_limit window=$bot_window count=$count ip=$ip ua=\"$ua\"" } HTTP::respond 429 content "Too Many Requests\r\n" \ "Retry-After" $bot_window \ "Connection" "close" return } } </window></limit>
