AI Analysis

Sentinel includes an optional AI-powered analysis system that brings intelligent threat interpretation to your security data. By integrating with leading LLM providers — Anthropic Claude, OpenAI, or Google Gemini — Sentinel can generate plain-English explanations of threat events, assess the risk level of threat actors, summarize your daily security posture, answer natural language questions about your data, and even recommend new WAF rules based on recent attack patterns.

AI analysis is entirely optional. When not configured, all AI endpoints gracefully return a message indicating that AI is not set up, and the dashboard shows setup instructions instead of analysis results. No API calls are made to any external service unless you explicitly provide a provider and API key.

Supported Providers

Sentinel supports three AI providers out of the box. Each provider uses a sensible default model, but you can override it with any model the provider supports.

Configuration

AI analysis is configured through the AI field on the main sentinel.Config struct. This field is a pointer (*AIConfig), so setting it to nil (or simply omitting it) disables all AI features.

AIConfig

1// AIConfig configures optional AI-powered analysis.
2type AIConfig struct {
3    Provider       AIProvider
4    APIKey         string
5    Model          string
6    MaxCallsPerDay int64 // default 500
7
8    // Deprecated: has no effect.
9    DailySummary bool
10}
11
12// AIProvider specifies which AI provider to use.
13type AIProvider string
14
15const (
16    Claude AIProvider = "claude"
17    OpenAI AIProvider = "openai"
18    Gemini AIProvider = "gemini"
19)

Basic Configuration (Claude)

1sentinel.Mount(r, nil, sentinel.Config{
2    WAF: sentinel.WAFConfig{
3        Enabled: true,
4        Mode:    sentinel.ModeBlock,
5    },
6    AI: &sentinel.AIConfig{
7        Provider: sentinel.Claude,
8        APIKey:   os.Getenv("ANTHROPIC_API_KEY"),
9    },
10})

OpenAI Configuration

1AI: &sentinel.AIConfig{
2    Provider: sentinel.OpenAI,
3    APIKey:   os.Getenv("OPENAI_API_KEY"),
4}

Gemini Configuration

1AI: &sentinel.AIConfig{
2    Provider: sentinel.Gemini,
3    APIKey:   os.Getenv("GEMINI_API_KEY"),
4}

Custom Model Override

If you want to use a specific model version instead of the default, set the Model field:

1AI: &sentinel.AIConfig{
2    Provider: sentinel.OpenAI,
3    APIKey:   os.Getenv("OPENAI_API_KEY"),
4    Model:    "gpt-4-turbo",  // Override the default gpt-4o
5}

What Is Sent to the AI Provider

Turning on AI means sending security data to a third party — Anthropic, OpenAI, or Google. This is exactly what leaves your process, so you can decide whether that is acceptable for your data.

• Nothing is sent unless someone asks. Every call is triggered by a dashboard user opening an AI feature. Nothing runs on a schedule, and with AI left nil — the default — nothing is ever sent.
• Responses are cached for an hour, and MaxCallsPerDay caps total calls.
• Data is redacted before it is sent (v2.4.0+). Query strings and body snippets are attacker-controlled, but they are recorded from requests to your application and can contain your users' data — a login form body, a token in a query string, an email address in a search. By default, query-string values are masked, bodies are dropped, IPs are truncated, and personal data and secrets are scrubbed from every field below. See Redaction.

Redaction

Every field in the table above passes through AIConfig.Redaction before the request is built. The zero value is the most private setting:

The attack fragments the WAF matched (for example UNION SELECT password FROM users) are kept after scrubbing, so an analysis still sees the payload that triggered the detection, and WAF recommendations are built from them. Redaction runs directly around the network call and never changes what Sentinel stores.

1AI: &sentinel.AIConfig{
2    Provider: sentinel.Claude,
3    APIKey:   os.Getenv("ANTHROPIC_API_KEY"),
4
5    // Defaults shown — the most private setting. Only opt out if you have
6    // decided your provider may see your users' request data.
7    Redaction: sentinel.AIRedaction{
8        SendPayloads:     false,
9        SendFullIPs:      false,
10        DisableScrubbing: false,
11    },
12},

AI Capabilities

Sentinel provides five distinct AI-powered analysis features. Each one is accessible via the dashboard UI and the REST API.

1. Threat Analysis

Generate a detailed, plain-English analysis of a specific threat event. The AI examines the threat type, severity, payload, targeted route, and the associated actor profile to produce an explanation of what happened, why it matters, and what you should do about it.

2. Actor Assessment

Generate a risk assessment of a threat actor based on their IP address, behavioral history, and recent events. The AI evaluates the actor's intent, sophistication level, and overall risk to your application.

3. Daily Summary

Generate an AI-powered summary of the last 24 hours of security events. This provides a high-level overview of your security posture, highlights the most significant threats, identifies trends, and offers strategic recommendations.

4. Natural Language Query

Ask questions about your security data in plain English. The AI receives context about your recent threats, top actors, threat statistics, and security score, then answers your question using that live data.

{ "query": "What are the most common attack types this week?" }
{ "query": "Is the IP 203.0.113.50 a serious threat?" }
{ "query": "Should I be worried about the spike in XSS attempts?" }
{ "query": "Summarize the threats targeting my /api/auth endpoint" }

5. WAF Recommendations

The AI analyzes recent threat events and suggests new WAF rules to improve your defenses. Each recommendation includes a rule ID, name, regex pattern, severity, the request components it should apply to, and the reasoning behind the suggestion.

API Endpoints

All AI endpoints are protected by dashboard authentication (JWT). They are available under the /sentinel/api/ai prefix by default.

Analyze Threat

# Analyze a specific threat event
curl -X POST http://localhost:8080/sentinel/api/ai/analyze-threat/te-abc123 \
  -H "Authorization: Bearer <token>"

Analyze Actor

# Get risk assessment for a threat actor
curl http://localhost:8080/sentinel/api/ai/analyze-actor/203.0.113.50 \
  -H "Authorization: Bearer <token>"

Daily Summary

# Generate AI daily security summary
curl http://localhost:8080/sentinel/api/ai/daily-summary \
  -H "Authorization: Bearer <token>"

Natural Language Query

# Ask a question about your security data
curl -X POST http://localhost:8080/sentinel/api/ai/query \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the most targeted endpoints this week?"}'

WAF Recommendations

# Get AI-suggested WAF rules
curl http://localhost:8080/sentinel/api/ai/waf-recommendations \
  -H "Authorization: Bearer <token>"

Response Caching

To minimize API costs and improve response times, Sentinel wraps every AI provider with a CachedProvider. The caching layer intercepts requests and returns cached responses when available, falling back to the real provider only when the cache misses or expires.

The default cache TTL is 1 hour. After the TTL expires, the next request for the same key triggers a fresh AI call. Natural language queries are never cached because each query is unique and users expect real-time answers.

1// CachedProvider wraps a Provider with response caching.
2type CachedProvider struct {
3    provider Provider
4    cache    map[string]*cacheEntry
5    mu       sync.RWMutex
6    ttl      time.Duration
7}
8
9// NewCachedProvider creates a caching wrapper around any Provider.
10func NewCachedProvider(provider Provider, ttl time.Duration) *CachedProvider {
11    if ttl == 0 {
12        ttl = 1 * time.Hour  // Default TTL
13    }
14    return &CachedProvider{
15        provider: provider,
16        cache:    make(map[string]*cacheEntry),
17        ttl:      ttl,
18    }
19}

Graceful Degradation

When AI is not configured (the AI field is nil or the API key is empty), Sentinel degrades gracefully rather than failing. All AI endpoints remain available but return a clear message indicating that AI is not set up.

API Response When AI Is Not Configured

{
  "data": null,
  "message": "AI not configured"
}

This consistent response format means your frontend or API consumers can check for the message field and display appropriate UI — such as a setup prompt or a feature explanation — without error handling.

1// NewProvider creates the appropriate Provider based on configuration.
2// Returns nil if AI is not configured.
3func NewProvider(config *AIConfig) Provider {
4    if config == nil || config.APIKey == "" {
5        return nil
6    }
7    // ... create provider based on config.Provider
8}

Dashboard Behavior

When AI is not configured, the dashboard AI Insights page detects the "AI not configured" response and displays setup instructions instead of analysis results. This guides users through enabling the feature without showing error states.

Dashboard — AI Insights

The Sentinel dashboard includes a dedicated AI Insights page that provides a visual interface for all five AI capabilities. Access it at http://localhost:8080/sentinel/ui and navigate to the AI Insights section.

• Threat Analysis — Click the "Analyze with AI" button on any threat event detail page to generate an in-depth analysis. The result includes the summary, explanation, severity assessment, confidence score, and actionable recommendations.
• Actor Assessment — From any threat actor profile page, trigger an AI risk assessment. The result shows the actor's likely intent, sophistication level, overall risk rating, and recommended actions.
• Daily Summary — The AI Insights page features a daily summary section that provides a narrative overview of the last 24 hours, including highlights, top threats, trend analysis, and strategic recommendations.
• Natural Language Query — A chat-like interface where you can type questions about your security data in plain English and receive AI-generated answers grounded in your live data.
• WAF Recommendations — A dedicated section that displays AI-suggested WAF rules with their patterns, severity levels, and the reasoning behind each recommendation. Review and apply them directly from the dashboard.

Testing Without an API Key

You can run Sentinel with the AI feature unconfigured and everything works normally. The system gracefully handles the absence of an API key at every level:

1. Provider creation — ai.NewProvider(nil) returns nil when the config is nil or the API key is empty. No provider is instantiated, no external connections are attempted.
2. API handlers — Every AI handler checks if aiProvider is nil before proceeding. If it is, the handler returns an HTTP 200 with {"data": null, "message": "AI not configured"}.
3. Dashboard — The frontend checks the API response and shows setup instructions rather than error messages when AI is not available.

1// AI is completely optional — just omit the AI field
2sentinel.Mount(r, nil, sentinel.Config{
3    WAF: sentinel.WAFConfig{
4        Enabled: true,
5        Mode:    sentinel.ModeBlock,
6    },
7    // AI: nil — not configured, all AI endpoints return gracefully
8})

Full Configuration Example

The following example enables the WAF, alerting, and AI analysis with Claude. The AI system will analyze threats, assess actors, generate daily summaries, answer queries, and recommend WAF rules — all powered by Claude.

1package main
2
3import (
4    "os"
5
6    sentinel "github.com/MUKE-coder/sentinel/v2"
7    "github.com/gin-gonic/gin"
8)
9
10func main() {
11    r := gin.Default()
12
13    sentinel.Mount(r, nil, sentinel.Config{
14        Dashboard: sentinel.DashboardConfig{
15            Username:  "admin",
16            Password:  "s3cur3-p4ss!",
17            SecretKey: "my-jwt-secret-change-in-production",
18        },
19
20        WAF: sentinel.WAFConfig{
21            Enabled: true,
22            Mode:    sentinel.ModeBlock,
23        },
24
25        Alerts: sentinel.AlertConfig{
26            MinSeverity: sentinel.SeverityHigh,
27            Slack: &sentinel.SlackConfig{
28                WebhookURL: os.Getenv("SLACK_WEBHOOK_URL"),
29            },
30        },
31
32        // Enable AI analysis with Claude
33        AI: &sentinel.AIConfig{
34            Provider: sentinel.Claude,
35            APIKey:   os.Getenv("ANTHROPIC_API_KEY"),
36            // Model defaults to claude-sonnet-4-20250514
37        },
38    })
39
40    r.GET("/api/data", func(c *gin.Context) {
41        c.JSON(200, gin.H{"status": "ok"})
42    })
43
44    r.Run(":8080")
45}

Next Steps

• WAF — Configure the detection rules that generate threat events for AI analysis
• Threat Intelligence — Enrich threat actor profiles that feed into AI assessments
• Alerting — Get notified when high-severity threats are detected
• Anomaly Detection — Add behavioral analysis that complements AI insights
• Dashboard — Explore the AI Insights page and other dashboard features