The Anomaly Detector plugin provides advanced protection against suspicious and potentially malicious API usage patterns. It analyzes request patterns, content, headers, and token usage to identify anomalous behavior that may indicate automated attacks, account takeovers, or other security threats.

​
Objective

The goal of this plugin is to detect improper or automated use of the AI Gateway by analyzing behavioral patterns in incoming HTTP requests. It leverages time series tracking, client fingerprinting, and semantic analysis to detect bots, abusive integrations, or non-human traffic in server-to-server (S2S) environments. This plugin helps you:
  • Detect timing-based attacks and suspicious request patterns
  • Identify content similarity across multiple requests
  • Detect artificially “clean” inputs lacking human-like imperfections
  • Monitor suspicious header configurations
  • Track token usage across different clients
  • Take configurable actions against detected anomalies

​
How It Works

The Anomaly Detector plugin works by analyzing multiple aspects of incoming requests and comparing them to historical data:
  1. Timing patterns - Detects suspiciously regular or frequent request patterns, identifying requests sent at exact, fixed intervals
  2. Content similarity - Identifies repeated identical content across requests using hash-based and semantic similarity analysis
  3. Artificially “clean” inputs - Detects inputs that lack human-like imperfections, suggesting programmatic generation
  4. Suspicious headers - Analyzes header configurations for bot-like patterns
  5. Token usage patterns - Monitors tokens used across multiple IPs or user agents to detect credential leakage or misuse
The plugin calculates an anomaly score based on these signals and takes action according to your configuration. When anomalous activity is detected, the plugin feeds metrics to the fingerprint tracking system, which can be used by other security plugins, especially the Contextual Security plugin, to create a layered defense against persistent bad actors.

​
Configuration Options

OptionTypeDescriptionDefault
thresholdfloatAnomaly score threshold (0.0-1.0) that triggers actionRequired
actionstringAction to take when anomaly is detectedRequired
retention_periodintegerPeriod in seconds to retain request data300 (5 minutes)
timing_pattern_weightfloatWeight for timing pattern detection0.2
content_similarity_weightfloatWeight for content similarity detection0.2
suspicious_headers_weightfloatWeight for suspicious headers detection0.2
token_usage_weightfloatWeight for token usage pattern detection0.2
min_time_between_requestsintegerMinimum time between requests in seconds1
max_requests_to_analyzeintegerMaximum number of past requests to analyze10

​
Available Actions

ActionDescription
alert_onlyLogs the detection but allows the request to proceed
throttleAdds a delay to suspicious requests to discourage automated activity
blockBlocks requests identified as anomalous with a 403 Forbidden response

​
Example Configuration

{
  "plugins": [
    {
      "name": "anomaly_detector",
      "settings": {
        "threshold": 0.7,
        "action": "block",
        "retention_period": 3600,
        "timing_pattern_weight": 0.3,
        "content_similarity_weight": 0.3,
        "suspicious_headers_weight": 0.2,
        "token_usage_weight": 0.2,
        "min_time_between_requests": 2,
        "max_requests_to_analyze": 20
      }
    }
  ]
}
Note: When action is set to block, requests identified as anomalous will be rejected with a 403 Forbidden status code.

​
Anomaly Detection Factors

The plugin analyzes multiple factors to calculate an anomaly score, flagging specific types of anomalies:

​
Timing Patterns

Analyzes the timing between requests to detect:
  • Suspiciously regular intervals between requests (e.g., exactly 1 request every 5 minutes)
  • Requests that come too frequently (based on min_time_between_requests)
  • Very short or perfectly even request intervals indicating automated traffic
  • Automated patterns that humans typically don’t exhibit
The plugin calculates metrics such as the standard deviation of inter-request intervals to identify fixed interval patterns that are strong indicators of automated behavior (cron jobs, scripts, etc.).

​
Content Similarity

Examines request content to identify:
  • Identical payloads sent repeatedly
  • Unusual repetition patterns
  • Content that appears machine-generated
The plugin uses hash-based comparison and can detect when request body content is always identical or semantically very similar across requests, indicating scripted or repeated usage. The similarity threshold is configurable through the weights system.

​
Suspicious Headers

Analyzes request headers for suspicious patterns:
  • Missing or generic User-Agent strings
  • Missing Accept headers
  • Missing Accept-Language headers
  • Missing Referer or Origin headers
  • Other header anomalies typical of automated tools

​
Token Usage Patterns

Monitors authentication token usage across:
  • Multiple IP addresses
  • Different User-Agent strings
  • Unusual access patterns
The plugin assigns higher anomaly scores when tokens are used across many different clients, which may indicate credential theft or sharing. This detection is flagged as token_fingerprint_mismatch and helps identify potential security breaches.

​
Best Practices

  1. Start with alert_only mode: Monitor anomaly detection before blocking to avoid false positives
  2. Adjust threshold based on your traffic: Lower thresholds catch more anomalies but may increase false positives
  3. Tune weights for your use case: Adjust the weights of different factors based on your application’s specific threats
  4. Use with rate limiting: Combine with rate limiting for comprehensive protection
  5. Consider user experience: Use throttling instead of blocking for borderline cases
  6. Monitor logs: Watch for patterns in anomaly detection to refine your configuration

​
Integration with Contextual Security

The Anomaly Detector plugin is designed to work seamlessly with the Contextual Security plugin, creating a powerful layered defense system:
  1. Data Sharing: When the Anomaly Detector identifies suspicious behavior, it feeds this data to the fingerprint tracking system.
  2. Enhanced Decision Making: The Contextual Security plugin can then use this data to make more informed decisions about whether to allow, block, or challenge requests.
  3. Persistent Protection: Even if an attacker changes their behavior slightly, the combined fingerprinting and contextual analysis can still identify them.
  4. Adaptive Security: As more anomalous behavior is detected, the security posture automatically strengthens against the specific threats targeting your application.
To maximize security, we recommend using both plugins together in your TrustGate configuration.

​
Client Fingerprint Strategy

The plugin generates a fingerprint for each client using:
  • IP address
  • User-Agent
  • Token (if present)
  • Additional headers (e.g., Accept-Language)
This fingerprinting allows tracking client behavior over time regardless of token changes, creating a persistent identity for each client that helps detect anomalous behavior patterns.

​
Data Storage

The plugin uses a short-lived storage system (Redis with TTL) to track:
  • Timestamp history per fingerprint
  • Last N request bodies for semantic analysis
  • Last headers per fingerprint/token
This data is retained according to the configured retention_period and is used to build a behavioral profile of each client.

​
Use Cases

CaseDescriptionDetection Trigger
Cron botScript sending 1 request every 5 minfixed_interval_pattern
Repetitive promptBody is 95% identical every timesemantic_repetition
Low entropy inputNo user variabilityinput_cleanliness_suspicious
Missing headersNo User-Agent, Accept, etc.header_anomaly
Token reuse across agentsSame token, different fingerprintstoken_fingerprint_mismatch