Onion AI¶

Note

This is an enterprise-level feature of Security Onion. Contact Security Onion Solutions, LLC via our website at https://securityonion.com/pro for more information about purchasing a Security Onion Pro license.

Note

Onion AI is disabled by default. To enable it for your Security Onion Pro deployment, go to the Administration --> Configuration page and navigate to soc --> config --> server --> client --> assistant --> enabled.

The Onion AI Assistant is your personal AI helper designed to assist you with a variety of tasks and provide information on demand. We support accessing LLMs from a variety of sources. Several tools have been made available as you interact with the assistant so it can access up-to-date information and resources.

Adapters¶

There are a variety of adapters available to connect to different LLM providers. When configuring an adapter, you're instructing SOC how to connect to an LLM provider. You configure the models separately in Available Models and tell each model which adapter to use. This allows you to connect to multiple providers at the same time and choose which models you want to use from each provider. The available adapters are:

SOAI: The Security Onion AI adapter connects to our own hosted gateway and provides access to a variety of models. This is the default adapter, and is hosted in the cloud with an allotted number of credits per Security Onion Pro licensed grids.
Gemini: Google's Gemini models can be accessed through this adapter. You can connect through either the Gemini Developer API or the Vertex API. These models are hosted in Google's cloud and require the use of your own Google Cloud key, or Gemini API key.
OpenAI Responses: This adapter can connect to the newest OpenAI compatible APIs that support the Responses protocol. This adapter allows Security Onion grids to connect to locally-hosted LLMs.
OpenAI Chat: This adapter can connect to any OpenAI Chat compatible APIs, an older protocol still supported by many AI providers. This adapter allows Security Onion grids to connect to locally-hosted LLMs.

Most features are supported across all adapters, but capabilities may change depending on the model or provider you connect to. Credits are unique to SOAI, it's the only adapter that responds with a credit balance. Multiple adapters can be configured at the same time.

Configuration¶

A fresh install will come with the SOAI adapter pre-configured and ready to use. To connect to other providers or modify the SOAI adapter, go to Administration --> Configuration page, be sure "Show advanced settings" is turned on in the Options at the top of the page, and check under soc --> config --> server --> modules --> assistant --> adapters. Here you can add as many adapters as you need. Each adapter defines how to connect to a provider. Different adapters have different configuration requirements. Every adapter needs a unique name, the protocol it uses, and a Health Timeout measured in seconds. Below is a table of which fields are required for which adapters:

	Adapter Name	Protocol	API Url	API Key	Service Account JSON	Service Account Location	Health Timeout Seconds
SOAI	R	R	R	--	--	--	R
Gemini	R	R	--	O	O	O	R
OpenAI Responses	R	R	R	O	--	--	R
OpenAI Chat	R	R	R	O	--	--	R

R = Required, O = Optional, -- = Not Used

SOAI¶

This adapter should not require any configuration, aside from the API Url, which will be different for Security Onion Pro customers located in different regions. To change the SOAI API Url, go to the Administration --> Configuration page and navigate to soc --> config --> server --> modules --> assistant --> adapters. Select the SOAI adapter and update the API Url field. If your license is setup to use an alternate cloud region, the correct API Url will be included with your Security Onion license key. If an alternate URL is not specified, use the default API Url.

Any additionally supplied fields are ignored. Generally at most one instance of this adapter should be configured at a time.

Credits¶

Using models over the SOAI adapter will consume credits from your Security Onion Pro license. Credits are only applicable to the SOAI adapter. If you use a local model or another external provider (such as Gemini or OpenAI), SOAI credits are not consumed.

The Security Onion Pro license includes an initial amount of credits to get started. For long term usage planning contact your Security Onion account representative. They will assist with estimating credit usage rates as well as the provisioning of additional credits. Credits are consumed based on the number of tokens used in the conversation including user input, assistant output, and tool usage. Your organization's balance can be viewed at the top right of the assistant page or on the management page under Administration --> AI Metrics.

Gemini¶

Security Onion supports connecting to Google's Gemini models through either the Gemini Developer API or the Vertex API.

To connect over the Gemini Developer API, you will need to generate an API Key in the Google Cloud Console or Google AI Studio, and provide it in the API Key field. To connect over the Vertex API, you will need to create a Service Account with the appropriate permissions for the models you would like to access, generate a JSON key for that account, paste the JSON into the Service Account JSON field, and you must also specify the Service Account Location. Some Gemini models may only be available in certain locations, such as global. The API Url field is not used for Gemini connections.

If an API Key and Service Account JSON + Service Account Location are both provided, SOC will attempt to connect using the Service Account and the API Key will be ignored.

This adapter will not use any credits from your Security Onion Pro license, but Google will charge you based on their pricing. Security Onion Solutions, LLC does not provide support for Google Gemini, aside from assisting with the adapter configuration referenced on this page.

OpenAI Responses¶

The OpenAI Responses adapter can connect to the newest OpenAI compatible APIs that support the Responses protocol. To connect, you will need to provide an API Url. The API Url should be the base url for the provider you are connecting to, for example https://api.openai.com/v1/. An API Key may or may not be required depending on the provider you are connecting to. If you're unsure if your provider supports the Responses protocol, check with their support or try connecting with this adapter. If it doesn't work, you can try the OpenAI Chat adapter which supports an older protocol that is still widely used.

Tip

Some providers require URL parameters passed along with the API calls. For example, Azure requires an api-version parameter. To support this, starting with Security Onion 3.1.0, you can append the parameter(s) to the API Url field. For example:

https://api.someprovider.invalid/v1/?api-version=2024-08-01-preview

OpenAI Chat¶

The OpenAI Chat adapter can connect to any OpenAI compatible API that supports the Chat protocol. To connect, you will need to provide an API Url. The API Url should be the base url for the provider you are connecting to, for example https://api.openai.com/v1/. An API Key may or may not be required depending on the provider you are connecting to.

Tip

Some providers require URL parameters passed along with the API calls. To support this, starting with Security Onion 3.1.0, you can append the parameter(s) to the API Url field. For example:

https://api.someprovider.invalid/v1/?api-version=2024-08-01-preview

Available Models¶

In order to control what models are available inside SOC, individual models must be configured. To configure a model, go to the Administration --> Configuration page, be sure "Show advanced settings" is turned on in the Options at the top of the page, and check under soc --> config --> server --> client --> assistant --> availableModels. Here you can add as many models as you need. Each model needs a unique name, the adapter it uses, and a model identifier which tells the adapter which model to connect to on the provider.

Note

If a provider offers models that aren't listed in availableModels, they will not be accessible within SOC.

Local Model Considerations¶

Security Onion now supports local models through any OpenAI-compatible endpoint. Because the assistant relies on large context windows, the minimum recommended context length is 128k tokens. The following open-source models have been tested with OnionAI:

GPT OSS 120B -- (US) Fast inference but limited to a 128k context window. Accuracy is fair.
Kimi 2.5 -- (China) A capable model with average accuracy and a 256k context window sufficient for most tasks. Note that this model requires significant VRAM to maintain performance.
GLM 5 -- (China) Average accuracy with a 200k context window.
Qwen 3.5 -- (China) Average accuracy with a 200k context window.

Note

Local models will not match the performance of proprietary foundational models such as those from Anthropic, Google, or OpenAI.

Hosting Local Models¶

Hosting your own models requires powerful and expensive hardware. For beginners we recommend using a tool such as LM Studio. The models listed above are large, and you need at least 96GB of VRAM to host them locally. Smaller mixture-of-experts models can run in considerably less memory while still offering a context window large enough for the assistant; see Local LLM Hosting for a tested walkthrough on a single machine. The speed and accuracy of OnionAI when hosted locally is based on the hardware that you are using. For the most accurate results we recommend using credits with OnionAI.

Available Tools¶

The assistant currently runs in the cloud. In order to reference local information, SOC makes the following tools available to the assistant:

query_events: This read-only tool allows the assistant to query security events from your local Security Onion instance similar to how you would use the Hunt page.
query_cases: This tool allows the assistant to query cases from your local Security Onion instance similar to how you would use the Cases page.
query_detections: This tool allows the assistant to query detections from your local Security Onion instance similar to how you would use the Detections page.
get_playbooks: When the assistant uses this read-only tool, SOC will gather the playbooks, execute their queries, and return all the data ready for analysis. This tool is read-only.
ack_alerts: The assistant can use this tool to query and acknowledge Alerts in your local Security Onion instance.
escalate_alerts: Similar to the ack tool, this tool allows the assistant to query for alerts and escalate them to a new case.
create_detection: The assistant will use this tool to create new detections in your local Security Onion instance.
add_overrides: This tool allows the assistant to tune existing detections by adding overrides to them.
toggle_detections: The assistant can use this tool to enable or disable existing detections in your local Security Onion instance.
update_detection_content: If a detection needs its content updated, the assistant can use this tool to update the content and keep the same metadata, overrides, and enabled status.
update_overrides: This tool allows the assistant to update existing overrides for detections.

Permissions¶

When the assistant requests any of these tools, the user will be prompted to approve or reject the usage. Approval will have the tool run and the result entered into the conversation followed by a response from the AI. Rejection will notify the assistant and allow it to respond.

Auto Approve Read-Only Tools¶

The following read-only tools can be used by the assistant without requiring explicit user approval:

query_events
query_cases
query_detections
get_playbooks

By default, permission must be granted for each tool request. However, users can enable auto-approval for read-only tools by toggling the slider in the Options dropdown at the top of the assistant page. With the option enabled, read-only tools will auto approve, while tools that modify data will still request explicit user approval.

Note

Conversation data is stored locally and not used to train any models. However, be cautious about sharing sensitive or personal information during your interactions as others in your organization may have access to the conversation history.

Customizing the System Prompt¶

The system prompt sets the behavior and context for the AI assistant. Users can customize this prompt to tailor the assistant's responses to their specific needs, such as describing network resources, environments, or workflows. The prompt is included in every session and can be modified at any time on the Administration --> Configuration page under SOC --> config --> server --> modules --> assistant --> systemPromptAddendum.

Your system prompt addendum will be added after Security Onion's default system prompt.

Note

Be cautious when customizing the system prompt, as it can significantly influence the assistant's behavior and responses. A longer prompt will also use more credits.

Metrics¶

Superusers can review token usage and conversation history for all users by going to Administration --> AI Metrics. This page provides usage statistics for a given date range. The page starts with a table of usage by user. Clicking a user's binoculars icon on the right hand side will show any sessions the user interacted with during the selected date range, even deleted sessions. Clicking on a session's binoculars icon will show the full conversation. Administrators can adjust who has permissions via RBAC roles.

To provide an accurate history, deleted sessions are retained on the metrics page even after being deleted by the user.

Memory¶

OnionAI can utilize its memory system to retain and reference facts disclosed by users when chatting with the assistant. Memory works by scanning sessions in the background looking for new facts and storing them in a database. The memory is then used to provide contextual information to the assistant when it responds to a user's message.

How Memory Works¶

The memory system scans sessions in the background extracting, embedding, reconciling, and saving memories to later be referenced when chatting with Onion AI.

First, extraction. The selected sessions have their transcripts given to a Memory agent that parses out useful facts. The agent also identifies the scope of the fact: is it specific to the user who owns the session we just scanned or is it applicable to the entire organization.

These facts are then embedded using an Embed agent. This enables SOC to compare memories and is the heart of how memory works.

Note

The embedding process is model specific. Memories embedded by one model cannot be accurately compared to memories embedded by any other model. Changing the model used for embedding will render all your previous memories unusable. They will not be deleted and will be accessible if the model is reverted back.

Once embedded, the facts are compared against existing memories on the same topics in a step called Reconcilation. A Reconcile agent will decide how the facts should be added, merged, replaced or removed. The reconcile agent's recommendations are validated before being executed to ensure that user defined memories aren't modified and that the session owner's permissions are respected.

If any facts were rewritten during reconcilation, they are re-embedded before being stored in postgres.

Finally the session is updated indicating that it has been scanned. If new messages are sent in a previously scanned session, memory scans will find and scan only the new messages.

When a user sends a message to the assistant, the memory system will embed the message about to be sent and check for any similar memories. Memories are added to the conversation by being added to the end of the prompt.

Configuring Memory¶

Name	Default Value	Description
`useMemory`	`true`	Enable memory use when sending a message.
`useMemoryScanner`	`false`	Enables the scanning of historical sessions.
`dontScanBefore`	`""`	A date in RFC3339 format (2026-08-31T22:05:48Z) to use as a cutoff point for memory scans.
`memoryScanIntervalSeconds`	`300`	How long between scans the memory scanner waits before scanning again.
`memoryProximityThreshold`	`0.8`	A similarity threshold that determines how similar a fact must be to a previous memory for it to be considered "similar."
`messageProximityThreshold`	`0.5`	A similarity threshold that determines how similar a message from a user must be to a stored memory for it to be considered "similar."
`maxUserMemoriesToReconcile`	`20`	The maximum number of user-specific memories to reconcile at once.
`maxGlobalMemoriesToReconcile`	`20`	The maximum number of global memories to reconcile at once.
`maxUserMemoriesToInclude`	`5`	The maximum number of user-specific memories to include when sending a message.
`maxGlobalMemoriesToInclude`	`5`	The maximum number of global memories to include when sending a message.
`memoryModel`	`gemma@SOAI`	The model used to extract facts from sessions.
`memoryPersona`	`""`	Special instructions for the memory agent included in the prompt.
`embedModel`	`amazon.titan-embed-text-v2@SOAI`	The model used to embed facts.
`reconcileModel`	`gemma@SOAI`	The model used to reconcile facts from sessions with existing memories.
`reconcilePersona`	`""`	Special instructions for the reconcile agent included in the prompt.
`toolUseTurnAttempts`	`12`	When the assistant requests a read-only tool, SOC can approve it automatically. Because the approval can fire before the original request has finished being written to Elasticsearch, SOC will retry the approval up to this many times before giving up.
`toolUseTurnDelayMs`	`175`	The time to wait between auto-approval attempts. Together with the attempts setting, this defines the total grace period SOC allows for the tool request to become available.
`maxMemoryRetries`	`2`	The maximum number of times SOC will attempt to extract memories from sessions before marking the session to be ignored. Increasing this value may retry sessions that haven't been attempted in a long time.

Memory and the Memory Scanner may be enabled independently. Disabling memory will stop applying memories to prompts on outgoing messages. Disabling the memory scanner will prevent the scanner from extracting memories from previous assistant sessions. The memory scanner marks sessions as it extracts facts from them so that they are not re-scanned in future scans. If a memory scan takes longer than the interval between scans, then at most 1 scan will queue up for processing and it'll begin again immediately after the previous scan finishes.

How to Write a Good Memory¶

When entering memories in manually in the Agent Studio, it's important to understand that how the memory is written affects how it'll be used by the memory system.

One fact per memory. If a memory has multiple facts then matching is harder to accomplish resulting in the memory being accessed less.
Make each memory self-contained. It will be read out of context, alone, possibly months later in a conversation about something else. Every memory should make sense to someone who has only that sentence.
Declarative facts, not instructions. If you want to give an instruction, then use a prompt instead.
Present tense, absolute references, durable phrasing. A memory is read long after it's written and is never automatically updated, so describe how things are rather than how they changed. Prefer "PCAP retention is 90 days (set August 2026)" over "We recently changed retention to 90 days."

To help track your most successful memories, the Agent Studio presents how many times a memory has been accessed and when was the last time it was referenced.