2.4.210

assistant.rst

@@ -7,26 +7,151 @@ Onion AI
 
     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 :ref:`pro` license.
 
-The Onion AI Assistant is your personal AI helper designed to assist you with a variety of tasks and provide information on demand. Several tools have been made available as you interact with the assistant so it can access up-to-date information and resources.
+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 help 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 seperately in :ref:`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:
+
+.. list-table::
+    :header-rows: 1
+    :name: assistant-config-table
+
+    * - 
+      - 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. If your license is setup to use an alternate cloud region this information will be included with the Security Onion license key. If it is not specified then 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.
+
+Using models over this adapter will cost credits. Contact your account representative for more information.
+
+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.
+
+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.
+
+.. _available-models:
+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.
 
 Credits
 -------
 
 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.
 
+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. **You need at least 96GB of VRAM** to host your own models locally. 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 :ref:`hunt` 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.
+ - **query_cases**: This tool allows the assistant to query cases from your local Security Onion instance similar to how you would use the :ref:`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 :ref:`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 :ref:`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.
-
-.. tip::
-
-		Currently this feature requires an internet connection. Local model support is coming soon!
+ - **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
 ~~~~~~~~~~~
@@ -39,9 +164,11 @@ 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 (acknowledge and escalate alerts) will still request explicit user approval.
+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::
 
@@ -56,7 +183,7 @@ Your system prompt addendum will be added after Security Onion's default system
 
 .. 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.
+    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
 -------

cloud-amazon.rst

@@ -33,7 +33,7 @@ Listed below are the minimum suggested single-node instance quantities, sizes, a
 Standalone:
 
 - Quantity: 1
-- Type: t3a.xlarge
+- Type: t3a.2xlarge
 - Storage: 256GB EBS (Optimized) gp3
 
 Evaluation
@@ -59,13 +59,13 @@ VPN Node
 Manager
 
 - Quantity: 1
-- Type: m5a.xlarge
+- Type: m5a.2xlarge
 - Storage: 300GB EBS (Optimized) gp3
 
 Search Nodes
 
 - Quantity: 2 or more
-- Type: m5ad.xlarge
+- Type: m5ad.2xlarge
 - Storage: 200GB EBS (Optimized) gp3
 - Storage: 150GB Instance Storage (SSD/NVMe)
 

cloud-azure.rst

@@ -39,7 +39,7 @@ Listed below are the minimum suggested single-node instance quantities, sizes, a
 Standalone:
 
 - Quantity: 1
-- Type: Standard_D4as_v4
+- Type: Standard_D8as_v4
 - Storage: 256GB Premium SSD
 
 Evaluation
@@ -65,13 +65,13 @@ VPN Node
 Manager
 
 - Quantity: 1
-- Type: Standard_D4as_v4
+- Type: Standard_D8as_v4
 - Storage: 256GB Premium SSD
 
 Search Nodes
 
 - Quantity: 2 or more
-- Type: Standard_D4as_v4
+- Type: Standard_D8as_v4
 - Storage: 256GB Premium SSD
 
 Sensor monitoring the VPN ingress

cloud-google.rst

@@ -34,7 +34,7 @@ Listed below are the minimum suggested single-node instance quantities, sizes, a
 Standalone:
 
 - Quantity: 1
-- Type: n2-standard-4
+- Type: n2-standard-8
 - Storage: 256GB Balanced Persistent Disk
 
 Evaluation*:
@@ -61,13 +61,13 @@ VPN Node
 Manager
 
 - Quantity: 1
-- Type: n2-standard-4
+- Type: n2-standard-8
 - Storage: 300GB Balanced Persistent Disk
 
 Search Nodes
 
 - Quantity: 2 or more
-- Type: n2-standard-4
+- Type: n2-standard-8
 - Storage: 256GB Balanced Persistent Disk
 - Storage: 375GB Local Disk (NVMe) [optional]
 

firewall.rst

@@ -48,39 +48,29 @@ If you choose to enable the Snort Talos ruleset, you will also need access to th
 Node Communication
 ~~~~~~~~~~~~~~~~~~
 
-When configuring network firewalls for distributed deployments, you'll want to ensure that nodes can connect as shown below. Please read through this entire list because your deployment may need firewall rules from multiple sections. For example, please note that grid nodes will need all ports in the ``All nodes to Manager`` and ``Elastic Agent`` sections and may also need ports from other sections as well.
+When configuring network firewalls for distributed deployments, you'll want to ensure that nodes can connect as shown in the table below. Please note that some of the sources and destinations listed in the table have specific definitions:
+
+- ``Security Onion grid nodes`` includes any node joined to your manager. This includes search nodes, sensors, fleet nodes, receiver nodes, and IDH nodes.
+- ``Search nodes`` are grid nodes that run Elasticsearch and join to the manager to enlarge its Elastic cluster.
+- ``Elastic cluster nodes`` include the search nodes and the manager itself.
+- ``Endpoint Elastic Agents`` includes any endpoint where you have deployed the Elastic Agent and want to send the data to your Security Onion grid.
+
+========================= ======================= ===================================================== =============
+ Source (SRC)              Destination (DST)       Destination Port(s) (TCP)                             Description
+========================= ======================= ===================================================== =============
+Security Onion grid nodes  Manager                 443, 4505, 4506, 5000, 5055, 8086, 8220, 8443         Management, Registry, Salt, Updates
+Security Onion grid nodes  Fleet node              5055, 8220                                            Elastic Agent data and management
+Security Onion grid nodes  Receiver node           5055                                                  Elastic Agent data
+Search nodes               Manager                 443, 4505, 4506, 5000, 5055, 8086, 8220, 8443, 9696   Management, Registry, Salt, Updates, Redis
+Elastic cluster nodes      Elastic cluster nodes   9200, 9300                                            Logstash to Elasticsearch and Elasticsearch node-to-node
+Endpoint Elastic Agents    Manager                 8220, 8443, 5055                                      Elastic Agent management, binary updates, data
+Endpoint Elastic Agents    Fleet node              5055, 8220                                            Elastic Agent management and data
+Endpoint Elastic Agents    Receiver node           5055                                                  Elastic Agent data
+Fleet node                 Receiver node           5056                                                  Logstash-to-Logstash
+Fleet node                 Manager                 5056, 9200                                            Logstash-to-Logstash and Elasticsearch node-to-node
+Manager                    IDH node                2222                                                  SSH for management
+========================= ======================= ===================================================== =============
 
-All nodes to Manager:
-
-- TCP/443 - Sensoroni
-- TCP/5000 - Docker registry
-- TCP/8086 - influxdb
-- TCP/4505 - Salt
-- TCP/4506 - Salt
-
-Elastic Agent:
-
-- TCP/8220 (All nodes to Manager, Fleet nodes) - Elastic Agent management
-- TCP/8443 (All nodes to Manager) - Elastic Agent binary updates
-- TCP/5055 (All nodes to Manager, Fleet nodes, Receiver nodes) - Elastic Agent data
-
-Elastic cluster nodes (manager and all search nodes) to all other Elastic cluster nodes (manager and all search nodes):
-
-- TCP/9200 - Logstash connecting to :ref:`elasticsearch`
-- TCP/9300 - Node-to-node for :ref:`elasticsearch`
-
-Search nodes to Manager:
-
-- TCP/9696 - :ref:`redis`
-
-Elastic Fleet nodes to Manager:
-
-- TCP/9200 - Node-to-node for :ref:`elasticsearch`
-- TCP/5056 - Logstash-to-Logstash for Elastic Agent data ingest
-
-Elastic Fleet nodes to Receiver nodes:
-
-- TCP/5056 - Logstash-to-Logstash for Elastic Agent data ingest
 
 Host Firewall
 -------------

oidc.rst

@@ -198,9 +198,9 @@ Upon the first login via OIDC the user will likely be returned back to the login
 Roles
 -----
 
-When a new OIDC user logs into SOC, that user will not be assigned any roles. This greatly limits what functions the user will be capable of performing within SOC. For example, new users will be unable to see any alerts, hunt for events, view dashboard data, view or create cases, manage the grid, or view other users. Attempting to view those role-protected screens will result in an error message.
+When a new OIDC user logs into SOC, that user will not be assigned any roles, unless a :ref:`default_system_role` has been configured. This greatly limits what functions the user will be capable of performing within SOC. For example, new users will be unable to see any alerts, hunt for events, view dashboard data, view or create cases, manage the grid, or view other users. Attempting to view those role-protected screens will result in an error message.
 
-An administrator will need to login to SOC and assign roles to OIDC users via the Adminstration -> Users screen. This is a one time operation, per user. 
+If a default system role is not configured, an administrator will need to login to SOC and assign roles to OIDC users via the Adminstration -> Users screen. This is a one time operation, per user. 
 
 Managing OIDC Users
 -------------------