diff --git a/assistant.rst b/assistant.rst index 3d129882..20897e9f 100644 --- a/assistant.rst +++ b/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 ------- diff --git a/cloud-amazon.rst b/cloud-amazon.rst index f32014df..061c6a08 100644 --- a/cloud-amazon.rst +++ b/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) diff --git a/cloud-azure.rst b/cloud-azure.rst index c8fa7419..6c96df11 100644 --- a/cloud-azure.rst +++ b/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 diff --git a/cloud-google.rst b/cloud-google.rst index c19662d1..ad8f72e8 100644 --- a/cloud-google.rst +++ b/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] diff --git a/firewall.rst b/firewall.rst index 26f54883..78fbd4c8 100644 --- a/firewall.rst +++ b/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 ------------- diff --git a/images/01_grub.png b/images/01_grub.png index 486b6d58..80192039 100644 Binary files a/images/01_grub.png and b/images/01_grub.png differ diff --git a/images/02_initial_install.png b/images/02_initial_install.png index 6541df23..6c1baa73 100644 Binary files a/images/02_initial_install.png and b/images/02_initial_install.png differ diff --git a/images/04_setup_init.png b/images/04_setup_init.png index f1edce32..9f45befd 100644 Binary files a/images/04_setup_init.png and b/images/04_setup_init.png differ diff --git a/images/05_setup_option.png b/images/05_setup_option.png index a9649bd8..03333747 100644 Binary files a/images/05_setup_option.png and b/images/05_setup_option.png differ diff --git a/images/06_setup_airgap.png b/images/06_setup_airgap.png index 0a50dfe7..d61192ac 100644 Binary files a/images/06_setup_airgap.png and b/images/06_setup_airgap.png differ diff --git a/images/06_setup_type.png b/images/06_setup_type.png index 00d578a3..cc0c3e67 100644 Binary files a/images/06_setup_type.png and b/images/06_setup_type.png differ diff --git a/images/07_setup_license.png b/images/07_setup_license.png index a1dd34e8..972e5214 100644 Binary files a/images/07_setup_license.png and b/images/07_setup_license.png differ diff --git a/images/08_setup_hostname.png b/images/08_setup_hostname.png index 44304561..e21e294b 100644 Binary files a/images/08_setup_hostname.png and b/images/08_setup_hostname.png differ diff --git a/images/09_setup_hostname_conflict.png b/images/09_setup_hostname_conflict.png index edb7bcc1..b66a362e 100644 Binary files a/images/09_setup_hostname_conflict.png and b/images/09_setup_hostname_conflict.png differ diff --git a/images/10_setup_mn_nic.png b/images/10_setup_mn_nic.png index 40f03435..b0ce6fd9 100644 Binary files a/images/10_setup_mn_nic.png and b/images/10_setup_mn_nic.png differ diff --git a/images/11_setup_mn_int.png b/images/11_setup_mn_int.png index 8a68ed0d..45ddb52a 100644 Binary files a/images/11_setup_mn_int.png and b/images/11_setup_mn_int.png differ diff --git a/images/12_setup_cidr.png b/images/12_setup_cidr.png index 02573504..8f687124 100644 Binary files a/images/12_setup_cidr.png and b/images/12_setup_cidr.png differ diff --git a/images/13_setup_gateway.png b/images/13_setup_gateway.png index 71d9273d..2e9a9262 100644 Binary files a/images/13_setup_gateway.png and b/images/13_setup_gateway.png differ diff --git a/images/14_setup_dns_servers.png b/images/14_setup_dns_servers.png index 319c033b..4e1a5d34 100644 Binary files a/images/14_setup_dns_servers.png and b/images/14_setup_dns_servers.png differ diff --git a/images/15_setup_dns_domain.png b/images/15_setup_dns_domain.png index 040fa51b..8a21ddbd 100644 Binary files a/images/15_setup_dns_domain.png and b/images/15_setup_dns_domain.png differ diff --git a/images/16_setup_docker_range.png b/images/16_setup_docker_range.png index d3cec11d..301f4eb5 100644 Binary files a/images/16_setup_docker_range.png and b/images/16_setup_docker_range.png differ diff --git a/images/18_setup_direct_proxy.png b/images/18_setup_direct_proxy.png index a91329b2..4d41a472 100644 Binary files a/images/18_setup_direct_proxy.png and b/images/18_setup_direct_proxy.png differ diff --git a/images/20_setup_webuser.png b/images/20_setup_webuser.png index 893f253c..6407827f 100644 Binary files a/images/20_setup_webuser.png and b/images/20_setup_webuser.png differ diff --git a/images/21_setup_webpass1.png b/images/21_setup_webpass1.png index bead11a5..db192aca 100644 Binary files a/images/21_setup_webpass1.png and b/images/21_setup_webpass1.png differ diff --git a/images/22_setup_webpass2.png b/images/22_setup_webpass2.png index ac366372..ecc01e1b 100644 Binary files a/images/22_setup_webpass2.png and b/images/22_setup_webpass2.png differ diff --git a/images/23_setup_access_type.png b/images/23_setup_access_type.png index 042ac244..7638f476 100644 Binary files a/images/23_setup_access_type.png and b/images/23_setup_access_type.png differ diff --git a/images/26_setup_so_allow.png b/images/26_setup_so_allow.png index 7f95a73f..7bb21601 100644 Binary files a/images/26_setup_so_allow.png and b/images/26_setup_so_allow.png differ diff --git a/images/27_setup_so_allow_input.png b/images/27_setup_so_allow_input.png index 1583a513..0970952c 100644 Binary files a/images/27_setup_so_allow_input.png and b/images/27_setup_so_allow_input.png differ diff --git a/images/27_telemetry.png b/images/27_telemetry.png index 1af2a27a..6a94472b 100644 Binary files a/images/27_telemetry.png and b/images/27_telemetry.png differ diff --git a/images/28_setup_summary.png b/images/28_setup_summary.png index 47d93765..58477860 100644 Binary files a/images/28_setup_summary.png and b/images/28_setup_summary.png differ diff --git a/images/29_setup_finished.png b/images/29_setup_finished.png index e0f5e458..097d309e 100644 Binary files a/images/29_setup_finished.png and b/images/29_setup_finished.png differ diff --git a/images/37_login.png b/images/37_login.png index 8df54328..8deb2ec5 100644 Binary files a/images/37_login.png and b/images/37_login.png differ diff --git a/images/38_overview.png b/images/38_overview.png index f7dbd770..33426fab 100644 Binary files a/images/38_overview.png and b/images/38_overview.png differ diff --git a/images/39_grid.png b/images/39_grid.png index 4c738f00..c34128c8 100644 Binary files a/images/39_grid.png and b/images/39_grid.png differ diff --git a/images/40_upload.png b/images/40_upload.png index fd0335db..38476126 100644 Binary files a/images/40_upload.png and b/images/40_upload.png differ diff --git a/images/45_import.png b/images/45_import.png index 058b0e5b..6d2b2ce2 100644 Binary files a/images/45_import.png and b/images/45_import.png differ diff --git a/images/50_alerts.png b/images/50_alerts.png index 9bedaf06..c108a43a 100644 Binary files a/images/50_alerts.png and b/images/50_alerts.png differ diff --git a/images/51_alerts_play.png b/images/51_alerts_play.png index 60fb4ec8..9b064690 100644 Binary files a/images/51_alerts_play.png and b/images/51_alerts_play.png differ diff --git a/images/52_alerts_options.png b/images/52_alerts_options.png index 25da02a5..7255708e 100644 Binary files a/images/52_alerts_options.png and b/images/52_alerts_options.png differ diff --git a/images/53_dashboards.png b/images/53_dashboards.png index 3536daef..fd2f618b 100644 Binary files a/images/53_dashboards.png and b/images/53_dashboards.png differ diff --git a/images/54_dashboards_options.png b/images/54_dashboards_options.png index f78649f9..0b253619 100644 Binary files a/images/54_dashboards_options.png and b/images/54_dashboards_options.png differ diff --git a/images/56_hunt.png b/images/56_hunt.png index 9385a320..4b682edd 100644 Binary files a/images/56_hunt.png and b/images/56_hunt.png differ diff --git a/images/57_0_cases.png b/images/57_0_cases.png index e9c5f209..28509d70 100644 Binary files a/images/57_0_cases.png and b/images/57_0_cases.png differ diff --git a/images/57_1_cases_options.png b/images/57_1_cases_options.png index 65ed71a8..a5768945 100644 Binary files a/images/57_1_cases_options.png and b/images/57_1_cases_options.png differ diff --git a/images/57_2_cases_create.png b/images/57_2_cases_create.png index 7fc627ab..4697763b 100644 Binary files a/images/57_2_cases_create.png and b/images/57_2_cases_create.png differ diff --git a/images/57_detections.png b/images/57_detections.png index 9ffa05ad..ab03f560 100644 Binary files a/images/57_detections.png and b/images/57_detections.png differ diff --git a/images/58_detections_options.png b/images/58_detections_options.png index c3fa9b44..7bc387c9 100644 Binary files a/images/58_detections_options.png and b/images/58_detections_options.png differ diff --git a/images/59_detection_create.png b/images/59_detection_create.png index e54aa4d1..2e38777d 100644 Binary files a/images/59_detection_create.png and b/images/59_detection_create.png differ diff --git a/images/60_detection_nids.png b/images/60_detection_nids.png index 5b68442e..ffbe30bc 100644 Binary files a/images/60_detection_nids.png and b/images/60_detection_nids.png differ diff --git a/images/60_detection_nids_0_comments.png b/images/60_detection_nids_0_comments.png index a659d75c..1280f9d2 100644 Binary files a/images/60_detection_nids_0_comments.png and b/images/60_detection_nids_0_comments.png differ diff --git a/images/60_detection_nids_1_signature.png b/images/60_detection_nids_1_signature.png index 46addfd9..23c6bfdc 100644 Binary files a/images/60_detection_nids_1_signature.png and b/images/60_detection_nids_1_signature.png differ diff --git a/images/60_detection_nids_2_tuning_1.png b/images/60_detection_nids_2_tuning_1.png index 4f9130ef..97e24170 100644 Binary files a/images/60_detection_nids_2_tuning_1.png and b/images/60_detection_nids_2_tuning_1.png differ diff --git a/images/60_detection_nids_2_tuning_2_add.png b/images/60_detection_nids_2_tuning_2_add.png index 7b19e539..3206dab5 100644 Binary files a/images/60_detection_nids_2_tuning_2_add.png and b/images/60_detection_nids_2_tuning_2_add.png differ diff --git a/images/60_detection_nids_3_playbook.png b/images/60_detection_nids_3_playbook.png index e0d4329f..94d5d064 100644 Binary files a/images/60_detection_nids_3_playbook.png and b/images/60_detection_nids_3_playbook.png differ diff --git a/images/60_detection_nids_4_history.png b/images/60_detection_nids_4_history.png index 0d3bcfb1..15a3a465 100644 Binary files a/images/60_detection_nids_4_history.png and b/images/60_detection_nids_4_history.png differ diff --git a/images/60_detection_sigma.png b/images/60_detection_sigma.png index 22b0eacb..d5efd3a7 100644 Binary files a/images/60_detection_sigma.png and b/images/60_detection_sigma.png differ diff --git a/images/60_detection_sigma_2_tuning_1.png b/images/60_detection_sigma_2_tuning_1.png index ca092b21..742033c3 100644 Binary files a/images/60_detection_sigma_2_tuning_1.png and b/images/60_detection_sigma_2_tuning_1.png differ diff --git a/images/60_detection_sigma_2_tuning_2_add.png b/images/60_detection_sigma_2_tuning_2_add.png index e3ff6f7a..35af0b6d 100644 Binary files a/images/60_detection_sigma_2_tuning_2_add.png and b/images/60_detection_sigma_2_tuning_2_add.png differ diff --git a/images/60_detection_yara.png b/images/60_detection_yara.png index 00ed4d35..1f5c8770 100644 Binary files a/images/60_detection_yara.png and b/images/60_detection_yara.png differ diff --git a/images/61_actions.png b/images/61_actions.png index ac024569..8a72d2e2 100644 Binary files a/images/61_actions.png and b/images/61_actions.png differ diff --git a/images/62_pcap.png b/images/62_pcap.png index 7d68e43a..181921b3 100644 Binary files a/images/62_pcap.png and b/images/62_pcap.png differ diff --git a/images/65_pcap_details.png b/images/65_pcap_details.png index eaba3d0c..e6aca06c 100644 Binary files a/images/65_pcap_details.png and b/images/65_pcap_details.png differ diff --git a/images/72_jobs.png b/images/72_jobs.png index 5d61c32d..87498ba4 100644 Binary files a/images/72_jobs.png and b/images/72_jobs.png differ diff --git a/images/73_jobs_add.png b/images/73_jobs_add.png index 5daa32e4..316f599b 100644 Binary files a/images/73_jobs_add.png and b/images/73_jobs_add.png differ diff --git a/images/75_grid.png b/images/75_grid.png index 4c738f00..b00b6ae9 100644 Binary files a/images/75_grid.png and b/images/75_grid.png differ diff --git a/images/76_grid_options.png b/images/76_grid_options.png index 9581019a..ab20ab13 100644 Binary files a/images/76_grid_options.png and b/images/76_grid_options.png differ diff --git a/images/78_downloads.png b/images/78_downloads.png index 2ec96b51..5cd932c8 100644 Binary files a/images/78_downloads.png and b/images/78_downloads.png differ diff --git a/images/81_users.png b/images/81_users.png index 9538d003..b6cd6726 100644 Binary files a/images/81_users.png and b/images/81_users.png differ diff --git a/images/82_users_detail.png b/images/82_users_detail.png index 22682bdd..5d2d77df 100644 Binary files a/images/82_users_detail.png and b/images/82_users_detail.png differ diff --git a/images/83_users_add.png b/images/83_users_add.png index 28422d7b..e8c71043 100644 Binary files a/images/83_users_add.png and b/images/83_users_add.png differ diff --git a/images/84_gridmembers.png b/images/84_gridmembers.png index 4557c232..d2e8487e 100644 Binary files a/images/84_gridmembers.png and b/images/84_gridmembers.png differ diff --git a/images/87_config.png b/images/87_config.png index 6ac8cbbf..843febf2 100644 Binary files a/images/87_config.png and b/images/87_config.png differ diff --git a/images/88_config_options.png b/images/88_config_options.png index 73adfda7..44969a74 100644 Binary files a/images/88_config_options.png and b/images/88_config_options.png differ diff --git a/images/91_licensekey.png b/images/91_licensekey.png index 9b074472..3ed423bb 100644 Binary files a/images/91_licensekey.png and b/images/91_licensekey.png differ diff --git a/images/94_usermenu.png b/images/94_usermenu.png index 34b4118a..5cc2f3cd 100644 Binary files a/images/94_usermenu.png and b/images/94_usermenu.png differ diff --git a/images/cheat-sheet/Security-Onion-Cheat-Sheet.pdf b/images/cheat-sheet/Security-Onion-Cheat-Sheet.pdf index b8b1d4e1..3d16e62e 100644 Binary files a/images/cheat-sheet/Security-Onion-Cheat-Sheet.pdf and b/images/cheat-sheet/Security-Onion-Cheat-Sheet.pdf differ diff --git a/images/config-item-backup.png b/images/config-item-backup.png index d1234e19..11c49602 100644 Binary files a/images/config-item-backup.png and b/images/config-item-backup.png differ diff --git a/images/config-item-bpf.png b/images/config-item-bpf.png index 4f5da71e..013a10f0 100644 Binary files a/images/config-item-bpf.png and b/images/config-item-bpf.png differ diff --git a/images/config-item-elastalert-alerter.png b/images/config-item-elastalert-alerter.png index 5c5c0e96..e1aee292 100644 Binary files a/images/config-item-elastalert-alerter.png and b/images/config-item-elastalert-alerter.png differ diff --git a/images/config-item-elastalert.png b/images/config-item-elastalert.png index 0fd6928a..7ebba17a 100644 Binary files a/images/config-item-elastalert.png and b/images/config-item-elastalert.png differ diff --git a/images/config-item-elasticfleet.png b/images/config-item-elasticfleet.png index 7f40f98f..54728162 100644 Binary files a/images/config-item-elasticfleet.png and b/images/config-item-elasticfleet.png differ diff --git a/images/config-item-elasticsearch.png b/images/config-item-elasticsearch.png index 2640f93e..a9a4064c 100644 Binary files a/images/config-item-elasticsearch.png and b/images/config-item-elasticsearch.png differ diff --git a/images/config-item-firewall.png b/images/config-item-firewall.png index f1563211..410830f5 100644 Binary files a/images/config-item-firewall.png and b/images/config-item-firewall.png differ diff --git a/images/config-item-global-url.png b/images/config-item-global-url.png index 4c9b7a59..32a9d882 100644 Binary files a/images/config-item-global-url.png and b/images/config-item-global-url.png differ diff --git a/images/config-item-global.png b/images/config-item-global.png index ae76a0fd..2ecdd685 100644 Binary files a/images/config-item-global.png and b/images/config-item-global.png differ diff --git a/images/config-item-host.png b/images/config-item-host.png index 62572618..c576df5c 100644 Binary files a/images/config-item-host.png and b/images/config-item-host.png differ diff --git a/images/config-item-idh.png b/images/config-item-idh.png index c3b597e3..5c955086 100644 Binary files a/images/config-item-idh.png and b/images/config-item-idh.png differ diff --git a/images/config-item-influxdb.png b/images/config-item-influxdb.png index b1dedc0a..15b06451 100644 Binary files a/images/config-item-influxdb.png and b/images/config-item-influxdb.png differ diff --git a/images/config-item-kafka.png b/images/config-item-kafka.png index 9ae6385e..c81308a4 100644 Binary files a/images/config-item-kafka.png and b/images/config-item-kafka.png differ diff --git a/images/config-item-kibana.png b/images/config-item-kibana.png index c54fb0fd..35a69125 100644 Binary files a/images/config-item-kibana.png and b/images/config-item-kibana.png differ diff --git a/images/config-item-kratos.png b/images/config-item-kratos.png index e687e500..714616ce 100644 Binary files a/images/config-item-kratos.png and b/images/config-item-kratos.png differ diff --git a/images/config-item-logstash.png b/images/config-item-logstash.png index 111131ee..e4d68bdb 100644 Binary files a/images/config-item-logstash.png and b/images/config-item-logstash.png differ diff --git a/images/config-item-manager.png b/images/config-item-manager.png index a87a1969..07f837b5 100644 Binary files a/images/config-item-manager.png and b/images/config-item-manager.png differ diff --git a/images/config-item-nginx.png b/images/config-item-nginx.png index 3c6313a7..b2c65bbb 100644 Binary files a/images/config-item-nginx.png and b/images/config-item-nginx.png differ diff --git a/images/config-item-ntp.png b/images/config-item-ntp.png index 19757a37..fd5c9883 100644 Binary files a/images/config-item-ntp.png and b/images/config-item-ntp.png differ diff --git a/images/config-item-patch.png b/images/config-item-patch.png index b3c175e0..990a11b1 100644 Binary files a/images/config-item-patch.png and b/images/config-item-patch.png differ diff --git a/images/config-item-pcap.png b/images/config-item-pcap.png index 56cf6224..4a141c01 100644 Binary files a/images/config-item-pcap.png and b/images/config-item-pcap.png differ diff --git a/images/config-item-redis.png b/images/config-item-redis.png index 33376e55..aabfbc7b 100644 Binary files a/images/config-item-redis.png and b/images/config-item-redis.png differ diff --git a/images/config-item-sensor.png b/images/config-item-sensor.png index 3bc466a8..500c611a 100644 Binary files a/images/config-item-sensor.png and b/images/config-item-sensor.png differ diff --git a/images/config-item-sensoroni.png b/images/config-item-sensoroni.png index 4edbb3d1..24a897cd 100644 Binary files a/images/config-item-sensoroni.png and b/images/config-item-sensoroni.png differ diff --git a/images/config-item-soc-additionalAlerters.png b/images/config-item-soc-additionalAlerters.png index 1bcea7bb..c7f45d51 100644 Binary files a/images/config-item-soc-additionalAlerters.png and b/images/config-item-soc-additionalAlerters.png differ diff --git a/images/config-item-soc-subgrids.png b/images/config-item-soc-subgrids.png index 9849adbf..05a8bb65 100644 Binary files a/images/config-item-soc-subgrids.png and b/images/config-item-soc-subgrids.png differ diff --git a/images/config-item-soc.png b/images/config-item-soc.png index fb557022..e84fdd6f 100644 Binary files a/images/config-item-soc.png and b/images/config-item-soc.png differ diff --git a/images/config-item-strelka.png b/images/config-item-strelka.png index 34f8de71..6ff76f8f 100644 Binary files a/images/config-item-strelka.png and b/images/config-item-strelka.png differ diff --git a/images/config-item-suricata.png b/images/config-item-suricata.png index be8991e4..4221afac 100644 Binary files a/images/config-item-suricata.png and b/images/config-item-suricata.png differ diff --git a/images/config-item-telegraf.png b/images/config-item-telegraf.png index 1c7441e7..ef114787 100644 Binary files a/images/config-item-telegraf.png and b/images/config-item-telegraf.png differ diff --git a/images/config-item-versionlock.png b/images/config-item-versionlock.png index 228ca725..b0653891 100644 Binary files a/images/config-item-versionlock.png and b/images/config-item-versionlock.png differ diff --git a/images/config-item-zeek.png b/images/config-item-zeek.png index 40ea859d..af218cff 100644 Binary files a/images/config-item-zeek.png and b/images/config-item-zeek.png differ diff --git a/images/diagrams/distributed.png b/images/diagrams/distributed.png index 8c20958f..8a97cde0 100644 Binary files a/images/diagrams/distributed.png and b/images/diagrams/distributed.png differ diff --git a/images/diagrams/idh.png b/images/diagrams/idh.png index 26488375..cafb2fdf 100644 Binary files a/images/diagrams/idh.png and b/images/diagrams/idh.png differ diff --git a/images/diagrams/receiver.png b/images/diagrams/receiver.png index 61fa8bb8..27d47312 100644 Binary files a/images/diagrams/receiver.png and b/images/diagrams/receiver.png differ diff --git a/oidc.rst b/oidc.rst index 13350880..0b45c0e9 100644 --- a/oidc.rst +++ b/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 ------------------- diff --git a/proxy.rst b/proxy.rst index e9357c7c..c4e1a636 100644 --- a/proxy.rst +++ b/proxy.rst @@ -59,7 +59,12 @@ If you're going to run something using sudo, remember to use the ``-i`` option t :: - sudo -i so-rule-update + sudo -i so-suricata-restart .. warning:: Using ``sudo su -`` will ignore ``/etc/environment``, instead use ``sudo su`` if you need to operate as root. + +NIDS Rules +---------- + +If you are using a proxy and need to download NIDS rulesets, you will also need to configure proxy settings for the NIDS ruleset downloads. These settings are separate from the system-wide proxy configuration above. See the :ref:`nids` documentation for details on configuring the Proxy URL, Proxy Username, Proxy Password, and Proxy CA Path for ruleset downloads. diff --git a/rbac.rst b/rbac.rst index 476d06ad..09cf6eb8 100644 --- a/rbac.rst +++ b/rbac.rst @@ -9,8 +9,8 @@ The ability to restrict or grant specific privileges to a subset of users is cov RBAC in Security Onion covers both Security Onion privileges and Elastic stack privileges. Security Onion privileges are only involved with functionality specifically provided by the components developed by Security Onion, while Elastic stack privileges are only involved with the :ref:`elasticsearch`, :ref:`kibana`, and related Elastic stack. For example, Security Onion will check if a user has permission to create a PCAP request, while Elastic will check if the same user has permission to view a particular index or document stored in :ref:`elasticsearch`. -Default Roles -------------- +System Roles +------------ Security Onion ships with the following user roles: ``superuser``, ``analyst``, ``limited-analyst``, ``auditor``, and ``limited-auditor``. @@ -232,6 +232,16 @@ Modifying User Roles In the :ref:`administration` interface, navigate to the Users screen and click the > icon to the left of the email address needing adjusting. Check or uncheck the desired roles. +.. _default_system_role: + +Default Role Assignment +----------------------- + +When a user is created, they can optionally be automatically assigned to a specific role. To enable this automatic assignment, locate the ``defaultRole`` configuration setting and specify the desired default role name. This automatic assignment will occur when the user logs into SOC for the first time. + +.. note:: + + If an administrator removes all role assignments from a user and the user logs back in that user will again be automatically assigned the default role. Always lock inactive users instead of removing role assignments from a user. Creating Custom Roles --------------------- @@ -343,7 +353,7 @@ Defining Security Onion Roles There are two ways to define a custom Security Onion role: -1) Building it from scratch using the built-in permissions and default roles available as outlined later in this document, or +1) Building it from scratch using the built-in permissions and system roles available as outlined later in this document, or 2) Inheriting the permissions of another role, and optionally adding more permissions to the new custom role. @@ -376,8 +386,8 @@ The common syntax for either method of defining a role is as such: limited-analyst:eastcoast-analyst -Security Onion Privileges and Default Roles -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Security Onion Privileges and Intermediate Roles +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The available low-level Security Onion privileges are listed in the table below: @@ -455,6 +465,8 @@ The available low-level Security Onion privileges are listed in the table below: - Chat with Onion AI * - *assistant/delete_authored* - Delete own Onion AI conversation history + * - *assistant/read_shared* + - View shared Onion AI conversation history * - *assistant/read_all* - View all Onion AI conversation history * - *assistant/write_all* @@ -517,8 +529,10 @@ These discrete privileges are then collected into privilege groups as defined be * - playbook-admin - *playbooks/read*, *playbooks/write*, *playbooks/delete* * - assistant-user - - *assistant/read_authored*, *assistant/write_authored*, *assistant/delete_authored* + - *assistant/read_authored*, *assistant/write_authored*, *assistant/delete_authored*, *assistant/read_shared* * - assistant-admin - - *assistant/read_authored*, *assistant/write_authored*, *assistant/delete_authored*, *assistant/read_all*, *assistant/write_all*, *assistant/delete_all* + - *assistant/read_authored*, *assistant/write_authored*, *assistant/delete_authored*, *assistant/read_shared*, *assistant/read_all*, *assistant/write_all*, *assistant/delete_all* + * - assistant-monitor + - *assistant/read_authored*, *assistant/read_shared*, *assistant/read_all* † intended for use by Sensoroni agents only diff --git a/release-notes.rst b/release-notes.rst index a14f6928..dfa61f19 100644 --- a/release-notes.rst +++ b/release-notes.rst @@ -3,6 +3,33 @@ Release Notes ============= +.. warning:: + + Security Onion 2.4.210 upgrades Salt to version 3006.19. This version of Salt has a configuration option minimum_auth_version for the Salt master. By default, this value is set to 3 and only minions on version 3006.12 or later support that version and are able to authenticate with the salt-master service. For this reason, during the soup to 2.4.210, we set the minimum_auth_version to 0. Since minions automatically update every 15 minutes, this allows older minion versions to authenticate, run a highstate, and upgrade to 3006.19. + + After seven days, a background process will change the minimum_auth_version from 0 to 3 and restart the salt-master service. Once this is done, any minions in the environment that have not upgraded to a version greater than 3006.12 will be unable to authenticate with the salt-master. The likely cause of this would be a minion that is offline. Additionally, if a user attempts to install a new node, using a version less than 2.4.200 (salt-minion 3006.16), the install will fail since the salt-minion will not be able to authenticate with the salt-master. + + If one of your nodes was unable to update by the time the minimum_auth_version was changed, then you may notice that the SOC Grid screen shows that you have a node running an older version of Security Onion that never updates. You can verify the issue by checking the following logs: + + In ``/opt/so/log/salt/minion`` on the remote node: + + :: + + 2026-02-20 14:36:43,479 [salt.crypt :884 ][ERROR ][2215] Sign-in attempt failed: bad load + 2026-02-20 14:36:43,480 [salt.minion :1155][ERROR ][2215] Error while bringing up minion for multi-master. Is master at soman1 responding? The error message was Unable to sign_in to master: Attempt to authenticate with the salt master failed + + In ``/opt/so/log/salt/master`` on the Security Onion manager: + + :: + + 2026-02-20 14:37:13,515 [salt.channel.server:147 ][WARNING ][2313166] Rejected authentication attempt using protocol version 2 (minimum required: 3) + + To force the node to update salt, you can connect to the remote node via ssh and then run the following: + + :: + + sudo dnf versionlock delete salt-* ; sudo yum clean all ; sudo sh /usr/sbin/bootstrap-salt.sh -X -r stable 3006.19 + .. warning:: Security Onion 2.4.200 changed the way Suricata detections are synchronized. Grids with custom Suricata rulesets will pause all Suricata detection syncing. For more information and required steps, see the :ref:`syncblock` section. @@ -16,13 +43,64 @@ Release Notes Known Issues ~~~~~~~~~~~~ -If you haven't viewed cases in a while, then escalating from Onion AI to an existing case will fail. - For all known issues, please see https://github.com/Security-Onion-Solutions/securityonion/issues. Release History ~~~~~~~~~~~~~~~ +2.4.210 [20260302] Changes +-------------------------- + +- FEATURE: Add graphs/charts to AI Metrics page +- FEATURE: Add support for default user roles `#15471 `_ +- FEATURE: Allow non-airgap soup to use ISO for all large files `#15467 `_ +- FEATURE: Gemini Adapter +- FEATURE: Model Thoughts +- FEATURE: multi-step ES upgrades smoother for airgap +- FEATURE: Onion AI model metrics +- FEATURE: OpenAI Chat Adapter +- FEATURE: OpenAI Responses Adapter +- FEATURE: Record user that acks and/or escalates events `#15373 `_ +- FEATURE: Show context used on each request/response pair +- FEATURE: Use new suricata.capture_file to improve PCAP lookups `#15398 `_ +- FIX: Appliance kickstart +- FIX: Change context indicator to m/k format +- FIX: Cleanup remaining idstools code `#15477 `_ +- FIX: Collection-backed config fields don't respect forcedType +- FIX: Disable redis on heavynodes `#15422 `_ +- FIX: Expanding alert with long unbreaking message content causes extra wide table `#15437 `_ +- FIX: Give message field focus when user navigates to Onion AI page +- FIX: Grid node elastic agent install state +- FIX: Hide Grid/Client menu links when unavailable to non-superusers `#15446 `_ +- FIX: If you haven't viewed cases in a while, then escalating from Onion AI to an existing case will fail +- FIX: Improve alert icon severity colors `#15450 `_ +- FIX: Kratos field mappings include unnecessary templates `#15354 `_ +- FIX: managed soc annotations migration +- FIX: Migrate off logs integration to filestream integration `#15364 `_ +- FIX: MoM subgrid showing Detection status pending `#15305 `_ +- FIX: Multiple lines of consecutive comments causes the BPF compile to error `#14908 `_ +- FIX: Pending status should not show crosshairs `#15376 `_ +- FIX: Rename to remaining "Forward" references to "Sensor" nodes `#15403 `_ +- FIX: Review Kratos field parsing `#7567 `_ +- FIX: Sensor and Heavynode Fail to install `#15441 `_ +- FIX: SOC Config - Apply Changes to the correct node `#15395 `_ +- FIX: SOC login form expiring without notifying user `#15346 `_ +- FIX: so-elastic-agent-grid-upgrade upgrade heavynode agents `#15434 `_ +- FIX: Soup fails if salt-relay.sh isn't running `#15518 `_ +- FIX: Successful logins sometimes would show a 403 error banner `#15527 `_ +- FIX: Telegraf logstash metrics `#15423 `_ +- FIX: Update redis-logs integration file path `#15425 `_ +- FIX: url_base annotation description `#15483 `_ +- FIX: Zeek excluded_files `#15439 `_ +- UPGRADE: Analyzer dependencies `#15512 `_ +- UPGRADE: Docker to 29.2.1 `#15495 `_ +- UPGRADE: Elasticsearch to 9.0.8 +- UPGRADE: Go dependencies to latest versions `#15474 `_ +- UPGRADE: ISO base image to Oracle 9.7 `#15352 `_ +- UPGRADE: Pcapfix to 1.1.7 `#15421 `_ +- UPGRADE: Salt to 3006.19 `#15490 `_ +- UPGRADE: Zeek to 8.0.6 `#15445 `_ + 2.4.201 [20260114] Changes -------------------------- diff --git a/requirements.txt b/requirements.txt index e618d843..4c46d4ad 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,3 @@ -setuptools +setuptools<81 sphinxcontrib-redoc sphinx-rtd-theme diff --git a/specs/openapi.yaml b/specs/openapi.yaml index 0ccebfb7..8e5b6a3d 100644 --- a/specs/openapi.yaml +++ b/specs/openapi.yaml @@ -276,7 +276,7 @@ components: type: number type: object model.AssistantSession: - description: A session for a user chatting with the Assistant. + description: Meta information about the session. properties: createTime: description: The date and time that this object was created. This is a read-only @@ -287,6 +287,10 @@ components: description: The time the session was deleted. example: "2025-09-05T15:33:00.000Z" type: string + entityId: + description: The entity ID associated with this session (e.g., alert soc_id). + example: WKhCuTw4GPvrQA-9ksmn + type: string id: description: The ID assigned to this object by the server. This is a read-only field. @@ -318,6 +322,10 @@ components: the user. example: Can you write a suricata rule for me? type: string + type: + description: The type of session (e.g., "alert_investigation"). + example: alert_investigation + type: string updateTime: description: The date and time that this object was last modified. This is a read-only field. @@ -331,6 +339,19 @@ components: example: socl_my_new_client type: string type: object + model.AssistantSessionDetails: + description: Detailed information about an Assistant session, including its + messages. + properties: + history: + description: The messages in the session. + items: + $ref: '#/components/schemas/model.StoredMessage' + type: array + uniqueItems: false + session: + $ref: '#/components/schemas/model.AssistantSession' + type: object model.AttachEventCriteria: properties: acknowledged: @@ -963,6 +984,11 @@ components: model.EngineState: description: The state of the Strelka detection engine properties: + blocked: + description: True if sync operations are currently blocked (e.g., during + migrations). + example: false + type: boolean importing: description: True if new detections are currently being imported into the engine. @@ -1619,11 +1645,16 @@ components: description: The sequence in which the message was stopped. example: end_turn type: string + thoughts: + description: The plain text thoughts from the model's response + type: string usage: $ref: '#/components/schemas/model.Usage' type: object model.ModelParameters: properties: + adapter: + type: string contextLimitLarge: type: integer contextLimitSmall: @@ -1636,6 +1667,27 @@ components: type: string lowBalanceColorAlert: type: integer + origin: + type: string + type: object + model.ModelUsageStats: + properties: + modelCredits: + description: The total credits used for this model. + example: 2 + type: integer + modelInputTokens: + description: The total input tokens used for this model. + example: 500 + type: integer + modelMessages: + description: The total messages sent using this model. + example: 10 + type: integer + modelOutputTokens: + description: The total output tokens used for this model. + example: 1000 + type: integer type: object model.Node: properties: @@ -1844,6 +1896,25 @@ components: if applicable to this node example: 1.1345 type: number + suriRulesFailed: + description: The number of Suricata rules that failed to load, if applicable + to this node + example: 0 + type: integer + suriRulesLoaded: + description: The number of Suricata rules currently loaded, if applicable + to this node + example: 45879 + type: integer + suriRulesReloadTime: + description: The timestamp of the last Suricata rule reload, if applicable + to this node + example: 2025-12-04T01:04:07.994734+0000 + type: string + suriRulesStatus: + description: 'The status of Suricata rule loading: ok, unknown' + example: ok + type: string swapTotalGB: description: Total size, in gigabytes, of the system swap memory example: 8.589930496000001 @@ -2277,6 +2348,11 @@ components: model.SessionUsage: description: Usage statistics for the session. properties: + modelUsage: + additionalProperties: + $ref: '#/components/schemas/model.ModelUsageStats' + description: Usage statistics per model@adapter combination. + type: object totalCredits: description: The total credits used during the session. example: 5 @@ -2501,6 +2577,10 @@ components: type: string message: $ref: '#/components/schemas/model.Message' + model: + description: The model used for this message. + example: sonnet-4.5@SOAI + type: string operation: description: The operation that was applied to the object. This is a read-only field. @@ -2639,6 +2719,15 @@ components: user before it can be saved type: boolean type: object + model.UpdateSessionRequest: + properties: + action: + example: add + type: string + tag: + example: shared + type: string + type: object model.Usage: description: Usage statistics after deducting the costs of the message. properties: @@ -2732,6 +2821,11 @@ components: type: object model.UserUsage: properties: + modelUsage: + additionalProperties: + $ref: '#/components/schemas/model.ModelUsageStats' + description: Usage statistics per model@adapter combination. + type: object totalCredits: description: The total credits used by the user in the date range. example: 5 @@ -2854,7 +2948,7 @@ info: url: https://securityonion.net/terms/ termsOfService: https://securityonion.net/terms/ title: Security Onion Connect API - version: 2.4.200 + version: 2.4.210 openapi: 3.1.0 paths: /api/assistant/admin/{userId}/sessions: @@ -3000,9 +3094,18 @@ paths: summary: Get Usage Statistics tags: - Assistant - /api/assistant/balance: + /api/assistant/balance/{modelAndAdapter}: get: description: Retrieve the current balance/usage information for the AI assistant. + parameters: + - description: Model Id (including slashes) and Adapter Name to get balance + for + example: qwen/qwen2.5-small@MyOpenAIChatAdapter + in: path + name: modelAndAdapter + required: true + schema: + type: string responses: "200": content: @@ -3028,6 +3131,18 @@ paths: post: description: Send a message to the AI assistant and receive a response. Supports both streaming (SSE) and non-streaming responses. + parameters: + - description: Type of entity associated with this session (e.g., 'alert_investigation') + in: query + name: entityType + schema: + type: string + - description: ID of the entity associated with this session (e.g., alert's + soc_id) + in: query + name: entityId + schema: + type: string requestBody: content: application/json: @@ -3119,7 +3234,8 @@ paths: tags: - Assistant get: - description: Retrieve the complete chat history for a specific session. + description: Retrieve the complete chat history and usage for a specific session. + Can lookup deleted sessions. parameters: - description: Session ID to retrieve history for in: path @@ -3132,10 +3248,8 @@ paths: content: application/json: schema: - items: - $ref: '#/components/schemas/model.StoredMessage' - type: array - description: Complete chat history for the session + $ref: '#/components/schemas/model.AssistantSessionDetails' + description: Complete chat history and session details "400": description: The provided session ID is invalid or missing "401": @@ -3147,7 +3261,48 @@ paths: security: - bearer: - assistant/read_authored - summary: Get Session History + - bearer: + - assistant/read_shared + summary: Get Session Details + tags: + - Assistant + put: + description: Allow a user to modify their own session tags. + parameters: + - description: Session ID to modify + in: path + name: sessionId + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/model.UpdateSessionRequest' + description: Indicate what field we're doing what operation with. + required: true + responses: + "206": + content: + application/json: + schema: + type: object + description: No content + "400": + description: The provided session ID is invalid or missing + "401": + description: Request was not properly authenticated + "403": + description: Insufficient permissions for this request + "404": + description: Session not found + "500": + description: Internal SOC error; review SOC logs + security: + - bearer: + - assistant/write_authored + summary: Update metadata for a Session tags: - Assistant /api/assistant/tool/{name}: @@ -4229,6 +4384,8 @@ paths: description: Insufficient permissions for this request "409": description: Public ID conflicts with existing detection + "423": + description: Rule synchronization is currently blocked "500": description: Internal SOC error; review SOC logs security: @@ -4282,6 +4439,8 @@ paths: description: Detection not found "409": description: Public ID conflicts with existing detection + "423": + description: Rule synchronization is currently blocked "500": description: Internal SOC error; review SOC logs security: @@ -4350,6 +4509,8 @@ paths: description: Insufficient permissions for this request "404": description: Detection not found + "423": + description: Sync operation is blocked "500": description: Internal SOC error; review SOC logs security: diff --git a/suricata.rst b/suricata.rst index 48b3d2f7..dbcf1217 100644 --- a/suricata.rst +++ b/suricata.rst @@ -214,6 +214,48 @@ To test a new rule, use the following utility on a node that runs Suricata (ie S The file should contain the new rule that you would like to test. The pcap should contain network data that will trigger the rule. +Variables +--------- + +To add or modify Suricata Variables, navigate to **suricata > config > vars > address-groups** or **port-groups**. + +You can assign a list of hosts, networks, or other customizations to a Suricata variable. The variable can then be re-used within Suricata rules and/or Overrides. This allows for a single adjustment to the variable that will affect all rules referencing it. + +### Address Groups + +Address groups define IP addresses or network ranges. Suricata comes with a number of common address groups already defined. + +#### Address Group Syntax + +Values can be specified using the following formats (single or multi-line): + +- Single IP: `192.168.1.100` +- CIDR notation: `192.168.1.0/24` +- IP range: `192.168.1.1-192.168.1.50` +- Multiple values: `192.168.1.0/24,10.0.0.0/8` +- Negation: `!192.168.1.100` or `!$OTHER_VAR` +- Variable reference: `$HOME_NET` + +### Port Groups + +Port groups define TCP/UDP ports for specific services. Suricata comes with a number of common port groups already defined. + +#### Port Group Syntax + +Values can be specified using the following formats (single or multi-line): + +- Single port: `80` +- Port range: `1024:65535` +- Multiple ports: `80,443,8080` +- Negation: `!80` +- Any port: `any` + +### Custom Variables + +Create custom variables by selecting an existing Address Group or Port Group and clicking "Duplicate". Enter a name using uppercase naming convention, then click "Create Setting". + +**Note:** The new variable is not saved until you modify its value and click the green "Save Changes" checkmark. + Disabling --------- diff --git a/third-party-integrations.rst b/third-party-integrations.rst index 041edb98..6db45bb4 100644 --- a/third-party-integrations.rst +++ b/third-party-integrations.rst @@ -58,7 +58,7 @@ To find integrations that have upgrades available: Managing Third Party Integration Index Templates ------------------------------------------------ -Index templates for third party integrations can be managed as described in the :ref:`elasticsearch` section, but first ``managed_integrations`` must be updated by navigating to :ref:`administration-advanced-settings` --> Configuration --> elasticsearch --> managed_integrations. +Index templates for third party integrations can be managed as described in the :ref:`elasticsearch` section, but first ``managed_integrations`` must be updated by navigating to :ref:`administration-advanced-settings` --> Configuration --> manager --> managed_integrations. Supported Integrations ----------------------