Appearance
Threat Analysis Policy
Organization administrators can configure AI threat analysis behavior, lock finding types to severity levels, and manage batch re-analysis. This guide covers the policy settings, metrics, and notification options available in the Admin Dashboard.
Overview
The threat analysis policy controls:
- Whether AI threat analysis is enabled for the organization
- Which finding types are locked to specific severity levels (overriding AI verdicts)
- Which LLM model is used for analysis
- How confirmed malicious findings trigger notifications
Enabling or Disabling AI Threat Analysis
AI threat analysis can be enabled or disabled per organization via the threat_analysis.enabled configuration.
| Setting | Path | Default | Description |
|---|---|---|---|
| Enabled | threat_analysis.enabled | true | When false, findings are not sent to the AI. Verdicts remain unset; original risk levels are used. |
When disabled, security findings still appear from the rule-based detectors, but no AI verdicts, explanations, or adjusted risk levels are computed.
Locking Finding Types to Severity
Administrators can lock specific finding types to a minimum severity level. Locked types override the AI-adjusted risk — even if the AI classifies a finding as benign, the risk level will not be downgraded below the locked value.
| Setting | Path | Example | Description |
|---|---|---|---|
| Locked types | threat_analysis.locked_types | {"pdf_js": "high", "macro": "critical"} | Map of detector type to enforced severity (low, medium, high, critical). |
Example: To require all PDF JavaScript findings to remain at least HIGH:
json
{
"threat_analysis": {
"locked_types": {
"pdf_js": "high"
}
}
}Locked types apply organization-wide. Users will see the Policy override indicator on affected findings.
Configuring the Model
The LLM model used for threat analysis can be configured per organization.
| Setting | Path | Default | Description |
|---|---|---|---|
| Model | threat_analysis.model | gpt-4o-mini | OpenAI-compatible model identifier for threat analysis. |
Use a faster, cost-effective model (e.g., gpt-4o-mini) for high-volume scanning, or a more capable model for complex or ambiguous findings.
Batch Re-Analysis
Administrators can trigger a batch re-analysis to invalidate cached AI verdicts and force re-evaluation on next access.
Endpoint
POST /api/files/admin/threat-reanalysisRequest body:
json
{
"scope": "all"
}| Parameter | Type | Description |
|---|---|---|
scope | string | "all" — invalidate all cached verdicts. Future values may support "type:<type>" or "since:<date>" for scoped invalidation. |
Response:
json
{
"status": "initiated",
"scope": "all",
"message": "Cache invalidated. Files will be re-analyzed on next access or scan."
}Cache Invalidation
The endpoint invalidates the threat analysis cache (content-hash keys under the threat: prefix). Files are not re-analyzed immediately; they are re-analyzed when:
- The file is scanned again (e.g., re-upload or new chat with attachment)
- A user requests threat analysis results for the file
Use batch re-analysis after:
- Updating the threat analysis model
- Changing prompt versions or heuristics
- Receiving significant user feedback indicating systematic misclassification
Viewing Metrics
The Admin Dashboard and compliance reports expose threat analysis metrics:
Verdict Distribution
| Metric | Description |
|---|---|
| Malicious | Count of findings classified as malicious |
| Suspicious | Count of findings classified as suspicious |
| Benign | Count of findings classified as benign |
| Inconclusive | Count of findings below confidence threshold |
Cache Performance
| Metric | Description |
|---|---|
| Cache hit rate | Ratio of cache hits to total analyses; higher values reduce LLM calls and latency |
| Cache miss | Count of analyses that required a new LLM call |
Feedback Agreement
User feedback (thumbs up/down) is recorded in the audit log. Review threat_feedback_submitted events to assess agreement with AI verdicts and identify patterns for model or prompt tuning.
Notification Configuration for Confirmed Malicious Findings
When the AI confirms one or more findings as malicious, the system can notify organization administrators.
Behavior
- Trigger: At least one finding with
ai_verdict: "malicious"andai_status: "complete" - Recipients: Organization admins (from
get_org_admins) - Notification type:
security_alert - Content: Filename, count of malicious findings, and per-finding details (label, type, explanation)
Configuration
Notifications are sent via the NotificationService. Ensure that:
- The notification service is configured and operational
- Organization admins have valid user records and notification preferences
- The
notify_if_malicioushook is invoked after threat analysis completes (handled automatically in the file scan pipeline)
To disable notifications for a deployment, the notify_if_malicious call can be bypassed at the integration point in the file processing flow.
Audit Logging
The following actions are recorded in the audit log:
| Action | Description |
|---|---|
security_threat_ai_analyzed | AI completed analysis; risk may have been adjusted |
security_threat_downgraded | AI downgraded risk (e.g., benign verdict) |
threat_feedback_submitted | User submitted thumbs up/down on a verdict |
threat_batch_reanalysis_triggered | Admin triggered cache invalidation |
Related
- AI Threat Analysis — End-user feature documentation
- File Processing — Security threat inspection
- AI Protection — PII detection and model configuration
- Audit Logs — Event types and querying