Skip to content

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.

SettingPathDefaultDescription
Enabledthreat_analysis.enabledtrueWhen 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.

SettingPathExampleDescription
Locked typesthreat_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.

SettingPathDefaultDescription
Modelthreat_analysis.modelgpt-4o-miniOpenAI-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-reanalysis

Request body:

json
{
  "scope": "all"
}
ParameterTypeDescription
scopestring"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 ​

MetricDescription
MaliciousCount of findings classified as malicious
SuspiciousCount of findings classified as suspicious
BenignCount of findings classified as benign
InconclusiveCount of findings below confidence threshold

Cache Performance ​

MetricDescription
Cache hit rateRatio of cache hits to total analyses; higher values reduce LLM calls and latency
Cache missCount 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" and ai_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:

  1. The notification service is configured and operational
  2. Organization admins have valid user records and notification preferences
  3. The notify_if_malicious hook 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:

ActionDescription
security_threat_ai_analyzedAI completed analysis; risk may have been adjusted
security_threat_downgradedAI downgraded risk (e.g., benign verdict)
threat_feedback_submittedUser submitted thumbs up/down on a verdict
threat_batch_reanalysis_triggeredAdmin triggered cache invalidation

SOC 2 Type II Certified | BAA Available | HIPAA-Ready