HomeDocumentationAPI Reference
Log In
Documentation

AI Configuration

Located under Settings > Application settings > AI, the AI configuration page has two cards: AI analysis, which configures the AI Analysis feature that sends Sandfly data to a Large Language Model (LLM) for further security analysis, and AI triage, which configures AI triage, the feature that judges hosts and artifacts and returns a verdict.

AI Configuration Tab

AI Configuration Tab

AI Configuration Form

The edit form of the AI analysis card contains the following configurable fields:

  • AI agent enabled - Set this to Enabled to enable the AI Agent and provide access to its settings.
  • Results limit - Set the maximum number of results a user is allowed to select for generating a single analysis.
  • Provider - Select an LLM provider; choose from several commercial offerings or an OpenAI-compatible source.
  • API key - Enter the API Key for the selected LLM provider. Turn on the Edit switch to access that field.
  • Model - Select the LLM model to use for generating analyses; the Model list will be automatically populated based on the selected provider's available models. Models can also be manually entered by typing into the field.
  • Include requesting user in header - Send the username of the requesting user in an X-Sandfly-Username header for user-initiated AI submissions.
⚠️

WARNING: Protect Private and Sensitive Data

Enabling AI features may send data to an external third party. Private and sensitive data may be exposed by doing this and is outside the control of Sandfly.


Custom Provider

When the Custom (OpenAI compatible) option is selected for the Provider field, the form will display two additional fields:

  • URL - Enter the base URL for the AI service. Sandfly automatically appends the required API endpoints.
  • Server CA certificate (optional) - If needed by your LLM provider, enter a PEM-formatted certificate.

AI Triage Form

The AI triage card shows the current AI triage settings: its status, whether automatic triage is on, whether it inherits the AI analysis connection, the provider and model, and the limits. To change them, open the card's edit form, which contains the following configurable fields:

  • AI triage enabled - Set this to Enabled to turn on AI triage and provide access to its settings.
  • Triage mode - Select how AI triage runs:
    • Manual - Sandfly triages a host or an artifact only when a user requests it.
    • Automatic (recommended) - Sandfly judges each host as scans arrive, without being asked. This is the mode that sends data to the AI provider unattended. The limits below apply to automatic triage only; a request made by a user is not held by them.

Model Options

  • Inherit - Turn on to use the provider, API key, URL, and CA certificate of the AI analysis card. This is the default, and it requires AI analysis to be enabled. The Provider field then shows the AI analysis provider and cannot be changed.
  • Model - The model that AI triage submits to. With Inherit turned on, leave it empty to use the AI analysis model, or enter a faster and more cost-effective model; AI triage runs often, and a smaller model is usually enough for it. With Inherit turned off, the list shows the models of the selected provider; use the refresh button next to the field to save the settings and load the list.
  • Provider, API key, URL, and Server CA certificate - Shown when Inherit is turned off. They work the same as the fields of the AI analysis card described above.

Limits

  • Maximum concurrent - How many submissions may be in flight at once. The lowest value is 1. The default is 2.
  • Payload target - The size, in KB, that the document describing a host is built to. It is a target, not a maximum: the worst alerts always carry their full detail, and when the target is reached, the lesser alerts are sent as summaries. The lowest value is 16 KB. The default is 256 KB.
  • Submit timeout - How long one submission may take, in seconds, before it is abandoned and retried. Raise it for a self-hosted model on modest hardware. The value must be from 30 to 1800 seconds. The default is 300 seconds.
  • Minimum interval - The least time, in hours, between two automatic verdicts for one host. A host that changes inside the interval is judged when the interval is up. The lowest value is 0, which sets no minimum interval. The default is 6 hours.
  • Daily limit - The most submissions that automatic triage sends per UTC day, including submissions that fail. Requests made by users count toward it but are not held by it. When the limit is reached, automatic work waits for the next day. The default is 0, which means unlimited.
  • Exclude hosts with tags - Hosts that carry any one of these tags are never sent to the provider by automatic triage. A user can still request a verdict for such a host.
⚠️

WARNING: Automatic Triage Sends Host Data Without Being Asked

In the Automatic triage mode, Sandfly sends the alerting artifacts and the context of every host that changes to the configured AI provider. Use Exclude hosts with tags to keep sensitive hosts out, and the Daily limit to bound the cost.

For what AI triage does with the verdicts, see AI Triage.


Did this page help you?