diff --git a/_static/theme_overrides.js b/_static/theme_overrides.js index bc34754d..cb00b4cd 100644 --- a/_static/theme_overrides.js +++ b/_static/theme_overrides.js @@ -1,11 +1,11 @@ const banner_text = ` -NOTICE: You are viewing documentation for an older version of Security Onion. +NOTICE: You are viewing documentation for a development version of Security Onion.
-View the latest documentation. +View the documentation for the latest stable release. `; function show_banner() { - if (READTHEDOCS_DATA['version'] == '2.4') return; + if (READTHEDOCS_DATA['version'] != 'dev') return; const banner = document.createElement('div'); banner.className = "so-banner"; @@ -15,4 +15,4 @@ function show_banner() { rst.prepend(banner); } -window.setTimeout(show_banner, 100); \ No newline at end of file +window.setTimeout(show_banner, 100); diff --git a/about.rst b/about.rst index 9b4f62c4..d5a26b71 100644 --- a/about.rst +++ b/about.rst @@ -38,21 +38,21 @@ This documentation is published online at https://securityonion.net/docs. If you This documentation is also available in PDF format at https://readthedocs.org/projects/securityonion/downloads/pdf/2.4/. -Many folks have asked for a printed version of our documentation. Whether you work on airgapped networks or simply want a portable reference that doesn't require an Internet connection or batteries, this is what you've been asking for. Thanks to Richard Bejtlich for writing the inspiring foreword! Proceeds go to the Rural Technology Fund! You can purchase your copy at https://securityonion.net/book. +Many folks have asked for a printed version of our documentation. Whether you work on airgapped networks or simply want a portable reference that doesn't require an Internet connection or batteries, this is what you've been asking for. Thanks to Richard Bejtlich for writing the inspiring foreword! Proceeds go to the Rural Technology Fund! You can purchase your copy at https://securityonion.net/book. Authors ~~~~~~~ -Security Onion Solutions is the primary author and maintainer of this documentation. Some content has been contributed by members of our community. Thanks to all the folks who have contributed to this documentation over the years! +Security Onion Solutions is the primary author and maintainer of this documentation. Some content has been contributed by members of our community. Thanks to all the folks who have contributed to this documentation over the years! Contributing ~~~~~~~~~~~~ -We welcome your contributions to our documentation! We will review any suggestions and apply them if appropriate. +We welcome your contributions to our documentation! We will review any suggestions and apply them if appropriate. -If you are accessing the online version of the documentation and notice that a particular page has incorrect information, you can submit corrections by clicking the ``Edit on GitHub`` button in the upper right corner of each page. +If you are accessing the online version of the documentation and notice that a particular page has incorrect information, you can submit corrections by clicking the ``Edit on GitHub`` button in the upper-right corner of each page. Once you have made your corrections, you will need to submit your pull request (PR) to the ``dev`` branch. -To submit a new page, you can submit a pull request (PR) to the 2.4 branch of the ``securityonion-docs`` repo at https://github.com/Security-Onion-Solutions/securityonion-docs. +To submit a new page, you can submit a pull request (PR) to the ``dev`` branch of the ``securityonion-docs`` repo at https://github.com/Security-Onion-Solutions/securityonion-docs. Pages are written in RST format and you can find several RST guides on the Internet including https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html. diff --git a/accounts.rst b/accounts.rst index 17bed51f..67e168c9 100644 --- a/accounts.rst +++ b/accounts.rst @@ -20,4 +20,3 @@ OS accounts are controlled by standard Linux account utilities. SOC accounts are disabling-accounts rbac kratos - oidc diff --git a/adding-accounts.rst b/adding-accounts.rst index f9c0115c..cb022e15 100644 --- a/adding-accounts.rst +++ b/adding-accounts.rst @@ -12,20 +12,25 @@ If you need to add a new OS user account, you can use the ``adduser`` command. sudo adduser tom -We recommend creating usernames in lower case for consistency. +.. tip:: + + We recommend creating OS usernames in lower case for consistency. -For more information, please see the adduser manual by typing ``man adduser``. +For more information about adding OS user accounts, please see the adduser manual by typing ``man adduser``. SOC --- If you need to add a new account to :ref:`soc`, navigate to the :ref:`administration` interface, and then click ``Users``. -.. image:: images/59_users.png - :target: _images/59_users.png +.. image:: images/81_users.png + :target: _images/81_users.png Click the ``+`` button, fill out the necessary information, and then click the ``ADD`` button. +.. image:: images/83_users_add.png + :target: _images/83_users_add.png + .. tip:: We recommend specifying email addresses in lower case for consistency. diff --git a/additional-network.rst b/additional-network.rst new file mode 100644 index 00000000..3ea15e81 --- /dev/null +++ b/additional-network.rst @@ -0,0 +1,12 @@ +.. _additional-network: + +Additional Network Visibility +============================= + +In the :ref:`network` section, we looked at network visibility provided by Security Onion itself. The ideal situation would be to have Security Onion network sensors covering each and every one of your network segments. If you're able to achieve that ideal situation, then you may not need any additional network visibility. However, there may be times when you simply can't cover certain network segments with Security Onion network sensors and that's when these additional options can be beneficial. Keep in mind, though, that the data that they provide is nowhere near as comprehensive as a full Security Onion network sensor. One option would be :ref:`netflow` logs from firewalls, switches, or routers showing what traffic was observed by the network device. Another option would be firewall logs showing what traffic was allowed through the firewall and what traffic was denied. An example of that would be :ref:`pfsense` firewall logs. You can find other firewall integrations in the :ref:`third-party-integrations` section. + +.. toctree:: + :maxdepth: 2 + + netflow + pfsense diff --git a/administration.rst b/administration.rst index 11a3248b..7a09484e 100644 --- a/administration.rst +++ b/administration.rst @@ -10,19 +10,19 @@ Users The Users page shows all user accounts that have been created for the grid. -.. image:: images/users.png - :target: _images/users.png +.. image:: images/81_users.png + :target: _images/81_users.png The Note column allows administrators to include a short note on a user's account. The Role column lists roles assigned to the user as defined in the :ref:`rbac` section. -The Status column will show different icons depending on the status of the account. In the screenshot above: +The Status column will show different icons depending on the status of the account: -- the first account is enabled and has TOTP :ref:`mfa` enabled -- the second account is enabled and has changed their password but does not have :ref:`mfa` enabled -- the third account is enabled but has not yet changed their password and does not have :ref:`mfa` enabled -- the fourth account is locked +- orange exclamation point - account enabled but has not yet changed their password and does not have :ref:`mfa` enabled +- blue icon with shield - account enabled with :ref:`mfa` enabled +- no icon - account enabled and has changed their password but does not have :ref:`mfa` enabled +- grey user with slash - account locked Hovering over the icon in the Status column will show you these details as well. @@ -31,8 +31,8 @@ Grid Members The Grid Members page shows nodes that have attempted to join the grid and whether or not they have been accepted into the grid by an administrator. -.. image:: images/60_gridmembers.png - :target: _images/60_gridmembers.png +.. image:: images/84_gridmembers.png + :target: _images/84_gridmembers.png Unaccepted members are displayed on the left side and broken into three sections: Pending Members, Denied Members, and Rejected Members. When you accept a member, it will then move to the right side under Accepted Members. @@ -43,13 +43,14 @@ Configuration The Configuration page allows you to configure various components of your grid. -.. image:: images/61_config.png - :target: _images/61_config.png +.. image:: images/87_config.png + :target: _images/87_config.png The most common configuration options are shown in the quick links on the right side. On the left side, you can click on a component in the tree view to drill into it and show all available settings for that component. You can then click on a setting to show the current setting or modify it if necessary. If you make a mistake, you can easily revert back to the default value. If a blue question mark appears on the setting page, you can click it to go to the documentation for that component. If you're not sure of which component a particular setting may belong to, you can use the Filter at the top of the list to look for a particular setting. To the right of the Filter field are buttons that do the following: +- apply the search filter - expand all settings - collapse all settings - show settings that have been modified from the default value @@ -61,17 +62,34 @@ If you're not sure of which component a particular setting may belong to, you ca Some settings can be applied across the entire grid or to specific nodes. If you apply a setting to a specific node, it will override the grid setting. +Advanced Settings +~~~~~~~~~~~~~~~~~ + By default, the Configuration page only shows the most widely used settings. If you want to see all settings, you can go to the Options bar at the top of the page and then click the toggle labeled ``Show all configurable settings, including advanced settings``. .. warning:: Changing advanced settings is unsupported and could result in requiring a full cluster re-installation. +.. image:: images/88_config_options.png + :target: _images/88_config_options.png + +Duplicate Settings +~~~~~~~~~~~~~~~~~~ + +Starting in Security Onion 2.4.70, some settings can be duplicated to more easily create new settings. If a setting is eligible for duplication, then it will have a DUPLICATE button on the right side of the page, provided the Advanced Option is enabled at the top of the screen. Creating a duplicate setting is a TWO-STEP process. + +1. Click the DUPLICATE button and provide a name for the new setting, then click the CREATE SETTING button. +2. The new setting will automatically be shown in the Configuration screen. At this point it is not yet saved to the server. The setting's value must be modified explicitly to persist this new setting. Once the value has been modified, click the green checkmark button to save it. + +.. note:: + + Duplicated settings do not retain their original setting's full behavior. For example, if the original setting only allowed for CIDR values, this new setting will not have the same protections on later views in the Configuration screen. Further, duplicated settings are marked as advanced settings. In order to see the new setting at a later time the Advanced Option toggle must be enabled under the Configuration Options at the top of the Configuration screen. + License Key ----------- -In the future, we will offer some new enterprise features for Security Onion. If you are interested in those features and purchase a license key, then this screen will allow you to enter your license key and then show the status of that license key. - -.. image:: images/62_licensekey.png - :target: _images/62_licensekey.png +.. image:: images/91_licensekey.png + :target: _images/91_licensekey.png +Starting in Security Onion 2.4.70, you will have the option of adding a license key for :ref:`pro`. diff --git a/airgap.rst b/airgap.rst index 67ad9db6..6f3591c4 100644 --- a/airgap.rst +++ b/airgap.rst @@ -5,7 +5,7 @@ Airgap Security Onion is committed to allowing users to run a full install on networks that do not have Internet access. Our ISO image includes everything you need to run without Internet access. Make sure that you choose the airgap option during Setup. -If your network has Internet access but has overly restrictive proxies, firewalls, or other network devices, then you may want to consider the airgap option as everything will install via the ISO image. +If your network has Internet access but has overly restrictive proxies, firewalls, or other network devices that might prevent Security Onion from connecting to the sites shown in the :ref:`firewall` section, then you may want to consider the airgap option as everything will install from the ISO image itself. .. image:: images/06_setup_airgap.png :target: _images/06_setup_airgap.png diff --git a/alert-data-fields.rst b/alert-data-fields.rst index 3aa6f3f5..c0ed45fa 100644 --- a/alert-data-fields.rst +++ b/alert-data-fields.rst @@ -3,7 +3,7 @@ Alert Data Fields ================= -| :ref:`elasticsearch` receives NIDS alerts from :ref:`suricata` via :ref:`elastic-agent` or :ref:`logstash` and parses them using: +| :ref:`elasticsearch` receives :ref:`nids` alerts from :ref:`suricata` via :ref:`elastic-agent` or :ref:`logstash` and parses them using: | ``/opt/so/conf/elasticsearch/ingest/suricata.alert`` | ``/opt/so/conf/elasticsearch/ingest/common.nids`` | ``/opt/so/conf/elasticsearch/ingest/common`` @@ -16,7 +16,7 @@ https://github.com/Security-Onion-Solutions/securityonion/blob/2.4/main/salt/ela https://github.com/Security-Onion-Solutions/securityonion/blob/2.4/main/salt/elasticsearch/files/ingest-dynamic/common -You can find parsed NIDS alerts in :ref:`alerts`, :ref:`dashboards`, :ref:`hunt`, and :ref:`kibana` via their predefined queries and dashboards or by manually searching for: +You can find parsed :ref:`nids` alerts in :ref:`alerts`, :ref:`dashboards`, :ref:`hunt`, and :ref:`kibana` via their predefined queries and dashboards or by manually searching for: | ``event.module:"suricata"`` | ``event.dataset:"alert"`` diff --git a/alerts.rst b/alerts.rst index c8158ae0..e0fed5a4 100644 --- a/alerts.rst +++ b/alerts.rst @@ -13,6 +13,9 @@ Options At the top of the page, there is an Options menu that allows you to set options such as Acknowledged/Escalated, Automatic Refresh Interval, and Time Zone. +.. image:: images/51_alerts_options.png + :target: _images/51_alerts_options.png + Toggles ~~~~~~~ @@ -37,20 +40,12 @@ Alerts will try to detect your local time zone via your browser. You can manuall Query Bar --------- -The query bar defaults to ``Group By Name, Module`` which groups the alerts by ``rule.name`` and ``event.module``. If you want to send your current Alerts query to :ref:`hunt`, you can click the crosshair icon to the right of the query bar. - -.. image:: images/alerts-query-bar.png - :target: _images/alerts-query-bar.png - -You can click the dropdown box to select other queries which will group by other fields. +The query bar defaults to ``Group By Name, Module`` which groups the alerts by ``rule.name`` and ``event.module``. You can click the dropdown box to select other queries which will group by other fields. If you want to send your current Alerts query to :ref:`hunt`, you can click the crosshair icon to the right of the query bar. -.. image:: images/alerts-queries.png - :target: _images/alerts-queries.png - Time Picker ----------- -By default, Alerts searches the last 24 hours. If you want to search a different time frame, you can change it in the upper right corner of the screen. +By default, Alerts searches the last 24 hours. If you want to search a different time frame, you can change it in the upper-right corner of the screen. Data Table ---------- @@ -72,9 +67,6 @@ Grouped View By default, alerts are grouped by whatever criteria is selected in the query bar. Clicking a field value and then selecting the Drilldown option allows you to drill down into that value which switches to the detailed view. You can also click the value in the Count column to perform a quick drilldown. Note that this quick drilldown feature is only enabled for certain queries. -.. image:: images/alerts-grouped.png - :target: _images/alerts-grouped.png - If you'd like to remove a particular field from the grouped view, you can click the trash icon at the top of the table to the right of the field name. Detailed View @@ -82,13 +74,8 @@ Detailed View If you click a value in the grouped view and then select the Drilldown option, the display will switch to the detailed view. This shows all search results and allows you to then drill into individual search results as necessary. Clicking the table headers allows you to sort ascending or descending. Starting from the left side of each row, there is an arrow which will expand the result to show all of its fields. To the right of that arrow is the ``Timestamp`` field. Next, a few standard fields are shown: ``rule.name``, ``event.severity_label``, ``source.ip``, ``source.port``, ``destination.ip``, and ``destination.port``. Depending on what kind of data you're looking at, there may be some additional data-specific fields as well. -.. image:: images/alerts-detailed.png - :target: _images/alerts-detailed.png - -When you click the arrow to expand a row in the Events table, it will show all of the individual fields from that event. Field names are shown on the left and field values on the right. When looking at the field names, there is an icon to the left that will add that field to the ``groupby`` section of your query. You can click on values on the right to bring up the context menu to refine your search or pivot to other pages. - -.. image:: images/alerts-expanded.png - :target: _images/alerts-expanded.png +When you click the arrow to expand a row in the Events table, it will show all of the individual fields from that event. Field names are shown on the left and field values on the right. When looking at the field names, there are two icons to the left. Th +e Groupby icon, the left most icon, will add a new groupby table for that field. The Toggle Column icon, to the right of the Groupby icon, will toggle that column in the Events table, and the icon will be a blue color if the column is visible. You can click on values on the right to bring up the context menu to refine your search or pivot to other pages. Context Menu ------------ @@ -110,6 +97,16 @@ Only Clicking the ``Only`` option will start a new search for the selected value and retain any existing groupby terms. +Drilldown +~~~~~~~~~ + +Clicking the ``Drilldown`` option will drill down into a group of alerts to show each individual alert. + +Tune Detection +~~~~~~~~~~~~~~ + +Clicking the ``Tune Detection`` option will take you to :ref:`detections` and allow you disable or modify the detection that fired the alert. + Group By ~~~~~~~~ diff --git a/architecture.rst b/architecture.rst index fef08402..d1f8f67f 100644 --- a/architecture.rst +++ b/architecture.rst @@ -16,6 +16,7 @@ The simplest architecture is an ``Import`` node. An import node is a single stan Evaluation ---------- + The next architecture is ``Evaluation``. It's a little more complicated than ``Import`` because it has a network interface dedicated to sniffing live traffic from a TAP or span port. Processes monitor the traffic on that sniffing interface and generate logs. :ref:`elastic-agent` collects those logs and sends them directly to :ref:`elasticsearch` where they are parsed and indexed. Evaluation mode is designed for a quick installation to temporarily test out Security Onion. It is **not** designed for production usage at all and it does not support adding Elastic agents or additional Security Onion nodes. .. image:: images/diagrams/eval.png @@ -24,6 +25,7 @@ The next architecture is ``Evaluation``. It's a little more complicated than ``I Standalone ---------- + ``Standalone`` is similar to ``Evaluation`` in that all components run on one box. However, instead of :ref:`elastic-agent` sending logs directly to :ref:`elasticsearch`, it sends them to :ref:`logstash`, which sends them to :ref:`redis` for queuing. A second Logstash pipeline pulls the logs out of :ref:`redis` and sends them to :ref:`elasticsearch`, where they are parsed and indexed. This type of deployment is typically used for testing, labs, POCs, or **very** low-throughput environments. It's not as scalable as a distributed deployment. @@ -32,6 +34,13 @@ This type of deployment is typically used for testing, labs, POCs, or **very** l :align: center :target: _images/standalone.png +Desktop +------- + +The installer includes a :ref:`desktop` option that builds a simple desktop environment. This environment includes a web browser which allows you to log into an existing Security Onion deployment. It also includes some analyst utilities like :ref:`wireshark` and :ref:`networkminer`. + +For more information, please see the :ref:`desktop` section. + Distributed ----------- @@ -55,7 +64,7 @@ Node Types Management ~~~~~~~~~~ -The ``manager node`` runs :ref:`soc` and :ref:`kibana`. It has its own local instance of :ref:`elasticsearch`, but that's mainly used for storing :ref:`cases` data and central configuration. An analyst connects to the manager node from a client workstation (perhaps :ref:`desktop`) to execute queries and retrieve data. Please keep in mind that a dedicated manager node requires separate search nodes. +The ``manager node`` runs :ref:`soc` and :ref:`kibana`. It has its own local instance of :ref:`elasticsearch`, but that's mainly used for managing the :ref:`elasticsearch` cluster once search nodes join the cluster. An analyst connects to the manager node from a client workstation (perhaps :ref:`desktop`) to execute queries and retrieve data. Please keep in mind that a dedicated manager node requires separate search nodes. The manager node runs the following components: @@ -93,7 +102,7 @@ A manager search node runs the following components: Forward Node ~~~~~~~~~~~~ -A ``forward node`` forwards alerts and logs from :ref:`suricata` and :ref:`zeek` via :ref:`elastic-agent` to :ref:`logstash` on the manager node, where they are stored in :ref:`elasticsearch` on the manager node or a search node (if the manager node has been configured to use a search node). Full packet capture recorded by :ref:`stenographer` remains on the forward node itself. +A ``forward node`` forwards alerts and logs from :ref:`suricata` and :ref:`zeek` via :ref:`elastic-agent` to :ref:`logstash` on the manager node, where they are stored in :ref:`elasticsearch` on the manager node or a search node (if the manager node has been configured to use a search node). Full packet capture recorded by :ref:`stenographer` or :ref:`suricata` remains on the forward node itself. Forward nodes run the following components: @@ -121,7 +130,13 @@ Each receiver node runs :ref:`logstash` and :ref:`redis` and allows for events t :width: 450 :target: _images/receiver.png -If you don't have any receiver nodes and the manager goes down, the search nodes do not index anything because they cannot connect to :ref:`redis`. The agents cannot connect to :ref:`logstash` so the pipeline starts backing up on the agents. In this same scenario with a receiver node the agents would not be able to talk to :ref:`logstash` on the manager and then would try to connect to the receiver node. Once connected they would send their logs to the receiver like nothing was wrong. The search nodes connect to both the manager and receiver nodes and pull events from the :ref:`redis` queue. If the manager goes down, the search nodes will keep pulling the log events from the queue on the receiver node. This allows for scaling of the pipeline. More receivers + more search nodes = more event ingestion volume. +If you don't have any receiver nodes and the manager goes down, the search nodes do not index anything because they cannot connect to :ref:`redis`. The agents cannot connect to :ref:`logstash` so the pipeline starts backing up on the agents. + +In this same scenario with a receiver node, the agents would not be able to connect to :ref:`logstash` on the manager and so they would try to connect to the receiver node. Once connected, they would send their logs to the receiver. + +Search nodes connect to both the manager and receiver nodes and pull events from the :ref:`redis` queue. If the manager goes down, search nodes will keep pulling the log events from the queue on the receiver node. This allows for scaling of the pipeline. More receivers + more search nodes = more event ingestion volume. + +If you have a manager or managersearch that is under heavy load due to handling a high volume of events, then system resources can be freed by directing the Elastic Agent to only output events to the receiver node(s) in the environment. Once all configurable and advanced settings are enabled, this feature can be set in SOC Configuration UI under ``elasticfleet > enable_manager_output``. Setting this to ``False`` will prevent the Elastic Agent from sending events to the manager, managersearch, or standalone nodes. If you have a manager or managersearch that is under heavy load due to handling a high volume of events, then system resources can be freed by directing the Elastic Agent to only output events to the receiver node(s) in the environment. Once all configurable and advanced settings are enabled, this feature can be set in SOC Configuration UI under ``elasticfleet > enable_manager_output``. Setting this to ``False`` will prevent the Elastic Agent from sending events to the manager, managersearch, or standalone nodes. diff --git a/attack-navigator.rst b/attack-navigator.rst index af1bec0f..618404b6 100644 --- a/attack-navigator.rst +++ b/attack-navigator.rst @@ -16,8 +16,8 @@ Accessing To access Navigator, log into :ref:`soc` and then click the Navigator hyperlink on the left side. -.. image:: images/64_navigator.png - :target: _images/64_navigator.png +.. image:: images/97_navigator.png + :target: _images/97_navigator.png Default Layer - Playbook ------------------------ diff --git a/cases.rst b/cases.rst index 763fba00..35a2a6ae 100644 --- a/cases.rst +++ b/cases.rst @@ -5,54 +5,74 @@ Cases :ref:`soc` includes our Cases interface for case management. It allows you to escalate logs from :ref:`alerts`, :ref:`dashboards`, and :ref:`hunt`, and then assign analysts, add comments and attachments, and track observables. +On a new deployment, Cases will be empty until you create a new case. Once you have one or more cases, you can use the main Cases page to get an overview of all cases. + +.. image:: images/57_0_cases.png + :target: _images/57_0_cases.png + .. note:: Check out our Cases video at https://youtu.be/y_kr_hrtqVc! -Installation ------------- +Options +------- -Cases is a part of :ref:`soc`. It's automatically enabled when doing an Import, Eval, Standalone, Manager, or ManagerSearch installation. If you want the quickest and easiest way to try out Cases, you can follow our :ref:`first-time-users` guide to install a minimal Import installation. +.. image:: images/57_1_cases_options.png + :target: _images/57_1_cases_options.png -Creating a New Case -------------------- +Starting at the top of the main Cases page, the Options menu allows you to set options such as Automatic Refresh Interval and Time Zone. -On a new deployment, Cases will be empty until you create a new case. +There is also a toggle labeled ``Temporarily enable advanced interface features``. If you enable this option, then the interface will show more advanced features similar to :ref:`dashboards` and :ref:`hunt`. These advanced features are only enabled temporarily so if you navigate away from the page and then return to the page, it will default back to its simplified view. -.. image:: images/cases-empty.png - :target: _images/cases-empty.png +Query Bar +--------- -To create a new case, click the + icon and then fill out the Title and Description and optionally the fields on the right side including Assignee, Status, Severity, Priority, TLP, PAP, Category, and Tags. Clicking the fields on the right side reveals drop-down boxes with standard options. The Assignee field will only list user accounts that are currently enabled. +The query bar defaults to Open Cases. Clicking the drop-down box reveals other options such as Closed Cases, My Open Cases, My Closed Cases, and Templates. If you want to send your current query to Hunt, you can click the crosshair icon to the right of the query bar. + +Under the query bar, you’ll notice colored bubbles that represent the individual components of the query and the fields to group by. If you want to remove part of the query, you can click the X in the corresponding bubble to remove it and run a new search. + +Time Picker +----------- + +The time picker is to the right of the query bar. By default, Cases searches the last 12 months. If you want to search a different time frame, you can change it here. + +Data Table +---------- -.. image:: images/cases-add.png - :target: _images/cases-add.png +The remainder of the main Cases page is a data table that shows a high level overview of the cases matching the current search criteria. -Alternatively, if you find events of interest in :ref:`alerts`, :ref:`dashboards`, or :ref:`hunt`, you can escalate directly to Cases using the escalate button (blue triangle with exclamation point). Clicking the escalate button will escalate the data from the row as it is displayed. This means that if you're looking at an aggregated view, you will get limited details in the resulting escalated case. If you want more details to be included in the case, then first drill into the aggregation and escalate one of the individual items in that aggregation. +- Clicking the table headers allows you to sort ascending or descending. -.. image:: images/cases-escalate-aggregation.png - :target: _images/cases-escalate-aggregation.png +- Clicking a value in the table brings up a context menu of actions for that value. This allows you to refine your existing search, start a new search, or even pivot to external sites like Google and VirusTotal. -Once you click the escalate button, you can choose to escalate to a new case or an existing case. +- You can adjust the Rows per page setting in the bottom right and use the left and right arrow icons to page through the table. -.. image:: images/cases-escalate.png - :target: _images/cases-escalate.png - +- When you click the arrow to expand a row in the data table, it will show the high level fields from that case. Field names are shown on the left and field values on the right. When looking at the field names, there is an icon to the left that will add that field to the ``groupby`` section of your query. You can click on values on the right to bring up the context menu to refine your search. + +- To the right of the arrow is a binoculars icon. Clicking this will display the full case including the Comments, Attachments, Observables, Events, and History tabs. + +Creating a New Case +------------------- + +To create a new case, click the + icon and then fill out the Title and Description and optionally the fields on the right side including Assignee, Status, Severity, Priority, TLP, PAP, Category, and Tags. Clicking the fields on the right side reveals drop-down boxes with standard options. The Assignee field will only list user accounts that are currently enabled. + +.. image:: images/57_2_cases_create.png + :target: _images/57_2_cases_create.png + +Alternatively, if you find events of interest in :ref:`alerts`, :ref:`dashboards`, or :ref:`hunt`, you can escalate directly to Cases using the escalate button (blue triangle with exclamation point). Clicking the escalate button will escalate the data from the row as it is displayed. This means that if you're looking at an aggregated view, you will get limited details in the resulting escalated case. If you want more details to be included in the case, then first drill into the aggregation and escalate one of the individual items in that aggregation. Once you click the escalate button, you can choose to escalate to a new case or an existing case. + Comments -------- On the Comments tab, you can add comments about the case. The Comments field uses markdown syntax and you can read more about that at https://www.markdownguide.org/cheat-sheet/. -.. image:: images/cases-comments.png - :target: _images/cases-comments.png +If you've enabled :ref:`pro`, then when adding a comment you can also specify how many hours you spent working on that activity. You can then see the total time spent by all analysts in the Summary in the upper-right corner. Attachments ----------- On the Attachments tab, you can upload attachments. For each attachment, you can optionally define TLP and add tags. Cases will automatically generate SHA256, SHA1, and MD5 hash values for each attachment. Buttons next to the hash values allow you to copy the value or add it as an observable. -.. image:: images/cases-attachments.png - :target: _images/cases-attachments.png - Observables ----------- @@ -60,9 +80,6 @@ On the Observables tab, you can track observables like IP addresses, domain name You can add multiple observables of the same type by selecting the option labeled ``Enable this checkbox to have a separate observable added for each line of the provided value above``. -.. image:: images/cases-observables.png - :target: _images/cases-observables.png - For each observable, you can click the icon on the far left of the row to drill into the observable and see more information about it. To the right of that is the the hunt icon which will start a new hunt for the observable. Clicking the lightning bolt icon will analyze the observable (see the Analyzers section later). You can also add observables directly from :ref:`alerts`, :ref:`dashboards`, or :ref:`hunt`. Click the observable and select the ``Add to Case`` option. You'll then have the option of adding the observable to a new case or an existing case. @@ -72,14 +89,8 @@ Events On the Events tab, you can see any events that have been escalated to the case. This could be :ref:`suricata` alerts, network metadata from :ref:`suricata` or :ref:`zeek`, or endpoint logs. -.. image:: images/cases-events.png - :target: _images/cases-events.png - For each event, you can click the icon on the far left of the row to drill in and see all the fields included in that event. -.. image:: images/cases-events-drilldown.png - :target: _images/cases-events-drilldown.png - If you find something that you would like to track as an Observable, you can click the eye icon on the far left of the row to add it to the Observables tab. It will attempt to automatically identify well known data types such as IP addresses. To the right of the eye icon is a Hunt icon that can be used to start a new hunt for that particular value. @@ -89,51 +100,6 @@ History On the History tab, you can see the history of the case itself, including any changes made by each user. For each row of history, you can click the icon on the far left of the row to drill in and see more information. -.. image:: images/cases-history.png - :target: _images/cases-history.png - -Overview Page -------------- - -Once you have one or more cases, you can use the main Cases page to get an overview of all cases. - -.. image:: images/cases.png - :target: _images/cases.png - -Options -------- - -Starting at the top of the main Cases page, the Options menu allows you to set options such as Automatic Refresh Interval and Time Zone. - -There is also a toggle labeled ``Temporarily enable advanced interface features``. If you enable this option, then the interface will show more advanced features similar to :ref:`dashboards` and :ref:`hunt`. These advanced features are only enabled temporarily so if you navigate away from the page and then return to the page, it will default back to its simplified view. - -Query Bar ---------- - -The query bar defaults to Open Cases. Clicking the drop-down box reveals other options such as Closed Cases, My Open Cases, My Closed Cases, and Templates. If you want to send your current query to Hunt, you can click the crosshair icon to the right of the query bar. - -Under the query bar, you’ll notice colored bubbles that represent the individual components of the query and the fields to group by. If you want to remove part of the query, you can click the X in the corresponding bubble to remove it and run a new search. - -Time Picker ------------ - -The time picker is to the right of the query bar. By default, Cases searches the last 12 months. If you want to search a different time frame, you can change it here. - -Data Table ----------- - -The remainder of the main Cases page is a data table that shows a high level overview of the cases matching the current search criteria. - -- Clicking the table headers allows you to sort ascending or descending. - -- Clicking a value in the table brings up a context menu of actions for that value. This allows you to refine your existing search, start a new search, or even pivot to external sites like Google and VirusTotal. - -- You can adjust the Rows per page setting in the bottom right and use the left and right arrow icons to page through the table. - -- When you click the arrow to expand a row in the data table, it will show the high level fields from that case. Field names are shown on the left and field values on the right. When looking at the field names, there is an icon to the left that will add that field to the ``groupby`` section of your query. You can click on values on the right to bring up the context menu to refine your search. - -- To the right of the arrow is a binoculars icon. Clicking this will display the full case including the Comments, Attachments, Observables, Events, and History tabs. - Data ---- @@ -185,15 +151,7 @@ WhoisLookup ✓ Running Analyzers ~~~~~~~~~~~~~~~~~ -To enqueue an analyzer job, click the lightning bolt icon on the left side of the observable menu: - -.. image:: images/analyzers-analyze-icon.png - :target: _images/analyzers-analyze-icon.png - -All configured analyzers supporting the observable's data type will then run and return their analysis: - -.. image:: images/analyzers-hash-results-summary.png - :target: _images/analyzers-hash-results-summary.png +To enqueue an analyzer job, click the lightning bolt icon on the left side of the observable menu. All configured analyzers supporting the observable's data type will then run and return their analysis. .. note:: Observable values must be formatted to correctly match the observable type in order for analyzers to properly execute against them. For example, an IP observable type should not contain more than one IP address. @@ -201,15 +159,7 @@ All configured analyzers supporting the observable's data type will then run and Analyzer Output ~~~~~~~~~~~~~~~ -The collapsed job view for an analyzer will return a summary view of the analysis: - -.. image:: images/analyzers-job-summary.png - :target: _images/analyzers-job-summary.png - -Expanding the collapsed row will reveal a more detailed view of the analysis: - -.. image:: images/analyzers-job-details.png - :target: _images/analyzers-job-details.png +The collapsed job view for an analyzer will return a summary view of the analysis. Expanding the collapsed row will reveal a more detailed view of the analysis. .. warning:: @@ -234,14 +184,14 @@ The following analyzers require users to configure authentication or other param - Urlscan - VirusTotal -To configure an analyzer, navigate to :ref:`administration` -> Configuration -> sensoroni. +To configure an analyzer, navigate to :ref:`administration` --> Configuration --> sensoroni. .. image:: images/config-item-sensoroni.png :target: _images/config-item-sensoroni.png -At the top of the page, click the ``Options`` menu and then enable the ``Show all configurable settings, including advanced settings.`` option. Then navigate to sensoroni -> analyzers. +At the top of the page, click the ``Options`` menu and then enable the ``Show all configurable settings, including advanced settings.`` option. Then navigate to sensoroni --> analyzers. Developing Analyzers ~~~~~~~~~~~~~~~~~~~~ -If you'd like to develop a custom analyzer, take a look at the developer's guide at https://github.com/Security-Onion-Solutions/securityonion/tree/dev/salt/sensoroni/files/analyzers. +If you'd like to develop a custom analyzer, take a look at the developer's guide at https://github.com/Security-Onion-Solutions/securityonion/tree/2.4/main/salt/sensoroni/files/analyzers. diff --git a/configuration.rst b/configuration.rst index 34f51be1..e5ea54d4 100644 --- a/configuration.rst +++ b/configuration.rst @@ -14,15 +14,19 @@ Security Onion is designed for many different use cases. Here are just a few exa If this is your first time using Security Onion and you just want to try it out, we recommend the Import option as it's the quickest and easiest way to get started. +.. warning:: + + If the network configuration portion displays a message like ``The IP being routed by Linux is not the IP address assigned to the management interface``, then you have multiple network interfaces with IP addresses. In most cases, sniffing interfaces should not have IP addresses and there should only be an IP address on the management interface itself. Sometimes this is caused by a sniffing interface connected to a normal switch port (not a TAP/span port) and acquiring an IP address via DHCP. Double-check your network interfaces, wiring, and configuration. + Import ------ -One of the easiest ways to get started with Security Onion is using it to forensically analyze pcap and log files. Just install Security Onion in ``Import`` mode and then import pcap files or Windows event logs in EVTX format using the :ref:`grid` page. +One of the easiest ways to get started with Security Onion is using it to forensically analyze pcap and log files. Simply select the ``IMPORT`` option, follow the prompts, and then import pcap files or Windows event logs in EVTX format using the :ref:`grid` page. Evaluation ---------- -``Evaluation Mode`` is ideal for classroom or small lab environments. Evaluation is **not** designed for production usage. Choose ``EVAL``, follow the prompts (see screenshots below), and then proceed to the :ref:`post-installation` section. +Evaluation mode is ideal for classroom or small lab environments. Evaluation is **not** designed for production usage. Choose the ``EVAL`` option, follow the prompts, and then proceed to the :ref:`post-installation` section. Production Server - Standalone ------------------------------ @@ -34,8 +38,8 @@ Production Server - Distributed Deployment If deploying a distributed environment, install and configure the manager node first and then join the other nodes to it. For best performance, the manager node should be dedicated to just being a manager for the other nodes (the manager node should not do any network sniffing, that should be handled by dedicated forward nodes). -Build the manager by running Setup, selecting the ``DISTRIBUTED`` install submenu, and choosing the ``New Deployment`` option. You can choose either ``MANAGER`` or ``MANAGERSEARCH``. If you choose ``MANAGER``, then you must join one or more search nodes (this is optional if you choose ``MANAGERSEARCH``) and you will want to do this before you start joining other node types. +Build the manager by running Setup, selecting the ``DISTRIBUTED`` deployment option, and choosing the ``New Deployment`` option. You can choose either ``MANAGER`` or ``MANAGERSEARCH``. If you choose ``MANAGER``, then you must join one or more search nodes (this is optional if you choose ``MANAGERSEARCH``) and you will want to do this before you start joining other node types. -Build nodes by running Setup, selecting the ``DISTRIBUTED`` install submenu, choosing ``Existing Deployment``, and selecting the appropriate option. Please note that all nodes will need to be able to connect to the manager node on several ports and the manager will need to connect to search nodes and heavy nodes. You'll need to make sure that any network firewalls have firewall rules to allow this traffic as defined in the :ref:`firewall` section. In addition to network firewalls, you'll need to make sure the manager's host-based firewall allows the connections. You can do this in two ways. The first option is going to :ref:`administration` --> Configuration --> firewall --> hostgroups, selecting the appropriate node type, and adding the IP address. The second option is to wait until the node tries to join and it will prompt you to run a specific command on the manager. Regardless of which of the two options you choose, it will eventually prompt you to go to :ref:`administration` --> Grid Members, find the node in the Pending Members list, click the ``Review`` button, and then click the ``Accept`` button. +Build nodes by running Setup, selecting the ``DISTRIBUTED`` deployment option, choosing ``Existing Deployment``, and selecting the appropriate option. Please note that all nodes will need to be able to connect to the manager node on several ports and the manager will need to connect to search nodes and heavy nodes. You'll need to make sure that any network firewalls have firewall rules to allow this traffic as defined in the :ref:`firewall` section. In addition to network firewalls, you'll need to make sure the manager's host-based firewall allows the connections. You can do this in two ways. The first option is going to :ref:`administration` --> Configuration --> firewall --> hostgroups, selecting the appropriate node type, and adding the IP address. The second option is to wait until the node tries to join and it will prompt you to run a specific command on the manager. Regardless of which of the two options you choose, it will eventually prompt you to go to :ref:`administration` --> Grid Members, find the node in the Pending Members list, click the ``Review`` button, and then click the ``Accept`` button. Proceed to the :ref:`post-installation` section. diff --git a/customizing.rst b/customizing.rst index 964dc12a..c4248e6a 100644 --- a/customizing.rst +++ b/customizing.rst @@ -18,4 +18,5 @@ This section covers how to customize Security Onion for your environment. ssh hostname ip + dns url-base diff --git a/cyberchef.rst b/cyberchef.rst index 4c4a61bb..b76e334a 100644 --- a/cyberchef.rst +++ b/cyberchef.rst @@ -23,8 +23,8 @@ From https://github.com/gchq/CyberChef: Screenshot ---------- -.. image:: images/55_cyberchef.png - :target: _images/55_cyberchef.png +.. image:: images/68_cyberchef.png + :target: _images/68_cyberchef.png Accessing --------- diff --git a/dashboards.rst b/dashboards.rst index ca49c77a..97dc5d4f 100644 --- a/dashboards.rst +++ b/dashboards.rst @@ -5,8 +5,8 @@ Dashboards :ref:`soc` includes a Dashboards interface which includes an entire set of pre-built dashboards for our standard data types. -.. image:: images/51_dashboards.png - :target: _images/51_dashboards.png +.. image:: images/53_dashboards.png + :target: _images/53_dashboards.png .. note:: @@ -15,7 +15,10 @@ Dashboards Options ------- -At the top of the page, there is an Options menu that allows you to set options such as Auto Apply, Exclude case data, Exclude SOC Logs, Automatic Refresh Interval, and Time Zone. +At the top of the page, there is an Options menu that allows you to set options such as Auto Apply, Exclude case data, Exclude Detections data, Exclude SOC Logs, Automatic Refresh Interval, and Time Zone. + +.. image:: images/54_dashboards_options.png + :target: _images/54_dashboards_options.png Auto Apply ~~~~~~~~~~ @@ -27,6 +30,11 @@ Exclude case data Dashboards excludes :ref:`cases` data by default. If you disable this option, then you can use Dashboards to query your :ref:`cases` data. +Exclude Detections data +~~~~~~~~~~~~~~~~~~~~~~~ + +Dashboards excludes :ref:`detections` data by default. If you disable this option, then you can use Dashboards to query your :ref:`detections` data. + Exclude SOC Logs ~~~~~~~~~~~~~~~~ @@ -45,30 +53,24 @@ Dashboards will try to detect your local time zone via your browser. You can man Query Bar --------- -The easiest way to get started is to click the query drop down box and select one of the pre-defined dashboards. These pre-defined dashboards cover most of the major data types that you would expect to see in a Security Onion deployment: NIDS alerts from :ref:`suricata`, protocol metadata logs from :ref:`zeek` or :ref:`suricata`, endpoint logs, and firewall logs. +The easiest way to get started is to click the query drop down box and select one of the pre-defined dashboards. These pre-defined dashboards cover most of the major data types that you would expect to see in a Security Onion deployment: :ref:`nids` alerts from :ref:`suricata`, protocol metadata logs from :ref:`zeek` or :ref:`suricata`, endpoint logs, and firewall logs. If you would like to save your own personal queries, you can bookmark them in your browser. If you would like to customize the default queries for all users, please see the :ref:`soc-customization` section. Time Picker ----------- -By default, Dashboards searches the last 24 hours. If you want to search a different time frame, you can change it in the upper right corner of the screen. You can use the default relative time or click the clock icon to change to absolute time. +By default, Dashboards searches the last 24 hours. If you want to search a different time frame, you can change it in the upper-right corner of the screen. You can use the default relative time or click the clock icon to change to absolute time. Basic Metrics ------------- -The first section of output contains a Most Occurrences visualization, a timeline visualization, and a Fewest Occurrences visualization. Bar charts are clickable, so you can click a value to update your search criteria. Aggregation defaults to 10 values, so Most Occurrences is the Top 10 and Fewest Occurrences is the Bottom 10 (long tail). The number of aggregation values is controlled by the Fetch Limit setting in the Group Metrics section. - -.. image:: images/dashboards-basic-metrics.png - :target: _images/dashboards-basic-metrics.png +The Basic Metrics section of the page contains a Most Occurrences visualization, a timeline visualization, and a Fewest Occurrences visualization. Bar charts are clickable, so you can click a value to update your search criteria. Aggregation defaults to 10 values, so Most Occurrences is the Top 10 and Fewest Occurrences is the Bottom 10 (long tail). The number of aggregation values is controlled by the Fetch Limit setting in the Group Metrics section. Group Metrics ------------- -The middle section of output is the Group Metrics section. It consists of one or more data tables or visualizations that allow you to stack (aggregate) arbitrary fields. - -.. image:: images/dashboards-group-metrics.png - :target: _images/dashboards-group-metrics.png +The Group Metrics section of the page consists of one or more data tables or visualizations that allow you to stack (aggregate) arbitrary fields. Group metrics are controlled by the ``groupby`` parameter in the search bar. You can read more about the ``groupby`` parameter in the OQL section below. @@ -78,14 +80,8 @@ Clicking a value in the Group Metrics table brings up a context menu of actions You can use the buttons in the Count column header to convert the data table to a pie chart or bar chart. If the data table is grouped by more than one field, then you will see an additional button that will convert the data table to a sankey diagram. There is a Maximize View button that will maximize the table to fill the pane (you can press the Esc key to return to normal view). Each of the groupby field headers has a trash button that will remove the field from the table. -.. image:: images/dashboards-group-metrics-table.png - :target: _images/dashboards-group-metrics-table.png - Once you have switched to a chart, you will see different buttons at the top of the chart. You can use the Show Table button to return to the data table, the Toggle Legend button to toggle the legend, and the Remove button to remove the chart altogether. There is a Maximize View button that will maximize the chart to fill the pane (you can press the Esc key to return to normal view). -.. image:: images/dashboards-group-metrics-sankey.png - :target: _images/dashboards-group-metrics-sankey.png - Events ------ @@ -95,22 +91,13 @@ Clicking a value in the Events table brings up a context menu of actions for tha The default Fetch Limit for the Events table is ``100``. If you need to see more than 100 events, you can increase the Fetch Limit and then page through the output using the left and right arrow icons or increase the ``Rows per page`` setting. -.. image:: images/soc-events-table.png - :target: _images/soc-events-table.png - When you click the arrow to expand a row in the Events table, it will show all of the individual fields from that event. Field names are shown on the left and field values on the right. When looking at the field names, there are two icons to the left. The Groupby icon, the left most icon, will add a new groupby table for that field. The Toggle Column icon, to the right of the Groupby icon, will toggle that column in the Events table, and the icon will be a blue color if the column is visible. Additionally, clicking the Toggle Column icon will add a new ``| table xxx yyy zzz`` segment to the active query. You can click on values on the right to bring up the context menu to refine your search or pivot to other pages. -.. image:: images/hunt-expanded.png - :target: _images/hunt-expanded.png - Statistics ---------- The bottom left corner of the page shows statistics about the current query including the speed of the backend data fetch and the total round trip time. -.. image:: images/dashboards-statistics.png - :target: _images/dashboards-statistics.png - Context Menu ------------ diff --git a/desktop.rst b/desktop.rst index f971c17f..8a4f5cd0 100644 --- a/desktop.rst +++ b/desktop.rst @@ -5,9 +5,6 @@ Security Onion Desktop Full-time analysts may want to use a dedicated Security Onion desktop. This allows you to investigate pcaps, malware, and other potentially malicious artifacts without impacting your Security Onion deployment or your usual desktop environment. -.. image:: images/desktop.png - :target: _images/desktop.png - .. note:: Security Onion Desktop only supports Oracle Linux 9, so you'll either need to use our ISO image (recommended) or a :ref:`network-installation` on top of Oracle Linux 9 (unsupported). diff --git a/detections.rst b/detections.rst new file mode 100644 index 00000000..a68cce61 --- /dev/null +++ b/detections.rst @@ -0,0 +1,119 @@ +.. _detections: + +Detections +========== + +Starting in Security Onion 2.4.70, :ref:`soc` includes our Detections interface for managing all of your rules: + +- :ref:`nids` rules that get loaded into :ref:`suricata` +- :ref:`sigma` rules that get loaded into :ref:`elastalert` +- :ref:`yara` rules that get loaded into :ref:`strelka` + +.. image:: images/57_detections.png + :target: _images/57_detections.png + +.. note:: + + Check out our Detections sneak peek video at https://youtu.be/oxR4q53N6OI! + +Rule Engine Status +------------------ + +The upper-right corner shows a count of detections that matched the search query. To the left of that is a status indicator for each of the detection engines. The status can show whether a sync is in process, as well as whether the engine has detected errors. + +Here is the list of possible status messages and what they mean: + +- **Pending**: The browser is waiting for the server to send an initial status report. +- **Import Pending**: The import will start once the system stabilizes, usually within twenty minutes. Imports take place only once, after upgrading to Security Onion 2.4.70+. +- **Importing**: The previous version of Security Onion's rules are being imported into the new Detections system. This can take an hour or more on some systems. +- **Migrating**: Rules will be migrated between Security Onion versions following system upgrades. This can take some time if upgrading from a much older version. +- **Migration Failed**: A failure occurred during the migration. The migration will stop on the first error and will not attempt to migrate to newer versions until the issue is resolved. +- **Synchronizing**: A rule synchronization is in progress. This occurs daily, to ensure the Security Onion grid has the latest rules. +- **Sync Failed**: A failure occurred during the synchronization procedure. The next sync will retry within a few minutes. +- **Rule Mismatch**: An integrity check process detected a mismatch between the deployed rules and the enabled rules. The SOC log will note the specific mismatched rules. One way that this can happen is if you had previously added custom rules to /opt/so/saltstack/local/salt/idstools/rules/local.rules. If this is the case, you can remove the rules from that file and then re-add them using the Detections interface. +- **OK**: No known issues with the rule engine. + +Clicking the status text will navigate to :ref:`hunt` and attempt to find related logs. + +The Detections menu option on the left side of the application will show an exclamation mark if there is a recent failure in any of the detection engines. In this situation the web browser tab will also show an exclamation indicator. If no failures are detected, and if any of the detection engines has an import pending or is performing a rule import, synchronization, or migration, then a blue hourglass will appear next to the Detections menu option. + +Options +------- + +The Options menu allows you to synchronize a particular detection engine such as :ref:`elastalert`, :ref:`strelka`, or :ref:`suricata`. + +.. image:: images/58_detections_options.png + :target: _images/58_detections_options.png + +Once you've selected the detection engine that you want to synchronize, you can then click either the ``DIFFERENTIAL UPDATE`` or ``FULL UPDATE`` button. + +The differential update is a lightweight sync that will skip the thorough sync and comparison of each individual rule. For example, with :ref:`suricata` it will compute and compare the hash of the source rule list with the hash of the deployed rules, and only if there's a mismatch will it perform the full sync. + +A full sync can involve inspecting and comparing individual rules, of which there can be thousands. This more thorough sync can take much longer than the differential sync. Note that each engine has its own unique synchronization process. + +Query Bar +--------- + +The query bar defaults to ``All Detections``. Clicking the drop-down box reveals other options such as ``Custom Detections``, ``All Detections - Enabled``, and ``All Detections - Disabled``. + +Under the query bar, you’ll notice colored bubbles that represent the individual components of the query. If you want to remove part of the query, you can click the X in the corresponding bubble to remove it and run a new search. + +Group Metrics +------------- + +The Group Metrics section of output consists of one or more data tables or visualizations that allow you to stack (aggregate) arbitrary fields. + +Data Table +---------- + +The remainder of the main Detections page is a data table that shows a high level overview of the detections matching the current search criteria. + +- Clicking the table headers allows you to sort ascending or descending. +- Clicking a value in the table brings up a context menu of actions for that value. This allows you to refine your existing search or copy text to the clipboard. +- You can adjust the Rows per page setting in the bottom right and use the left and right arrow icons to page through the table. +- When you click the arrow to expand a row in the data table, it will show the high level fields from that detection. Field names are shown on the left and field values on the right. You can click on values on the right to bring up the context menu to refine your search. +- To the right of the arrow is a binoculars icon. Clicking this will take you to the detection details page. + +Detection Details +----------------- + +There are two ways to reach the detail page for an individual detection: + +- From the main :ref:`detections` interface, you can search for the desired detection and click the binoculars icon. +- From the :ref:`alerts` interface, you can click an alert and then click the ``Tune Detection`` menu item. + +Once you've used one of these methods to reach the detection detail page, you can check the Status field in the upper-right corner and use the slider to enable or disable the detection. + +To the left of the Status field are several tabs. The OVERVIEW tab displays the Summary, References, and Detection Logic for the detection. + +.. image:: images/60_detection_nids.png + :target: _images/60_detection_nids.png + +The OPERATIONAL NOTES tab allows you to add your own local notes to the detection in markdown format. + +.. image:: images/60_detection_nids_0_comments.png + :target: _images/60_detection_nids_0_comments.png + +The DETECTION SOURCE tab shows the full content of the detection. + +.. image:: images/60_detection_nids_1_signature.png + :target: _images/60_detection_nids_1_signature.png + +The TUNING tab allows you to tune the detection. For :ref:`nids` rules, you can modify, suppress, or threshold. For :ref:`sigma` rules, you can create a custom filter. + +.. image:: images/60_detection_nids_2_tuning_1.png + :target: _images/60_detection_nids_2_tuning_1.png + +The HISTORY tab shows the history of the detection since it was added to your deployment. + +.. image:: images/60_detection_nids_3_history.png + :target: _images/60_detection_nids_3_history.png + +More Information +---------------- + +For more information about managing :ref:`nids` rules for :ref:`suricata`, please see the :ref:`nids` section. + +For more information about managing :ref:`sigma` rules for :ref:`elastalert`, please see the :ref:`sigma` section. + +For more information about managing :ref:`yara` rules for :ref:`strelka`, please see the :ref:`yara` section. diff --git a/directory.rst b/directory.rst index 3e7d7407..29d8e9da 100644 --- a/directory.rst +++ b/directory.rst @@ -5,32 +5,45 @@ Directory Structure /opt/so/conf ------------ + Applications read their configuration from ``/opt/so/conf/``. However, please keep in mind that most config files are managed with :ref:`salt`, so if you manually modify those config files, your changes may be overwritten at the next Salt update. /opt/so/log ----------- + Debug logs are stored in ``/opt/so/log/``. /opt/so/rules ------------- + :ref:`elastalert` and :ref:`suricata` rules are stored in ``/opt/so/rules/``. /opt/so/saltstack/local ----------------------- + Custom :ref:`salt` settings can be added to ``/opt/so/saltstack/local/``. /nsm ---- + The vast majority of data is stored in ``/nsm/``. /nsm/zeek --------- + :ref:`zeek` writes its protocol logs to ``/nsm/zeek/``. /nsm/elasticsearch ------------------ + :ref:`elasticsearch` stores its data in ``/nsm/elasticsearch/``. /nsm/pcap --------- + :ref:`stenographer` stores full packet capture in ``/nsm/pcap/``. + +/nsm/suripcap +------------- + +:ref:`suricata` stores full packet capture in ``/nsm/pcap/``. diff --git a/disabling-accounts.rst b/disabling-accounts.rst index f22bb4cb..84c2bc5a 100644 --- a/disabling-accounts.rst +++ b/disabling-accounts.rst @@ -17,11 +17,11 @@ For more information, please see passwd manual by typing ``man passwd`` and the SOC --- -If you need to disable an account in :ref:`soc`, you can go to the :ref:`administration` interface, expand the user account, and click the ``LOCK USER`` button. +If you need to disable an account in :ref:`soc`, you can go to :ref:`administration` --> Users, expand the user account, and click the ``LOCK USER`` button. -After disabling a user account, the :ref:`administration` page will show the disabled user account with a disabled icon in the Status column: +.. image:: images/82_users_detail.png + :target: _images/82_users_detail.png -.. image:: images/users.png - :target: _images/users.png +After disabling a user account, it will be shown with a disabled icon in the Status column. For more information about the Users page, please see the :ref:`administration` section. diff --git a/dns.rst b/dns.rst new file mode 100644 index 00000000..6baeaa60 --- /dev/null +++ b/dns.rst @@ -0,0 +1,20 @@ +.. _dns: + +DNS +=== + +DNS is normally configured during initial setup. If you need to later change your DNS settings, you can use NetworkManager's console utilities, nmtui and nmcli. + +nmtui +----- + +nmtui is NetworkManager's text-based user interface: + +https://docs.oracle.com/en/operating-systems/oracle-linux/9/network/network-ConfiguringtheSystemsNetwork.html#ol-netconf-config-tui + +nmcli +----- + +nmcli is NetworkManager's command-line interface: + +https://docs.oracle.com/en/operating-systems/oracle-linux/9/network/network-ConfiguringtheSystemsNetwork.html#ol-netconf-config-cli diff --git a/downloads.rst b/downloads.rst index 141f9787..446471c9 100644 --- a/downloads.rst +++ b/downloads.rst @@ -5,8 +5,8 @@ Downloads :ref:`soc` includes a Downloads interface that allows you to download the :ref:`elastic-agent` for various operating systems. -.. image:: images/58_downloads.png - :target: _images/58_downloads.png +.. image:: images/78_downloads.png + :target: _images/78_downloads.png .. warning:: diff --git a/elastalert.rst b/elastalert.rst index e6e1a30e..166707d6 100644 --- a/elastalert.rst +++ b/elastalert.rst @@ -1,84 +1,48 @@ .. _elastalert: -ElastAlert -========== +ElastAlert 2 +============ From https://elastalert2.readthedocs.io/en/latest/elastalert.html#overview: - ElastAlert is a simple framework for alerting on anomalies, spikes, or other patterns of interest from data in Elasticsearch. + ElastAlert 2 is a simple framework for alerting on anomalies, spikes, or other patterns of interest from data in Elasticsearch. ElastAlert queries :ref:`elasticsearch` and provides an alerting mechanism with multiple output types, such as Slack, Email, JIRA, OpsGenie, and many more. -Configuration -------------- +Sigma Rules +----------- -You can modify ElastAlert configuration by going to :ref:`administration` --> Configuration --> elastalert. - -.. image:: images/config-item-elastalert.png - :target: _images/config-item-elastalert.png +The Detections module will generate ElastAlert 2 compatible rules automatically for all :ref:`sigma` detections. There is no need to manually modify the generated rules on disk. Further, any modifications will be overwritten during the next :ref:`sigma` rule synchronization. -ElastAlert Rules ----------------- +Adjusting a :ref:`sigma` rule should always be done via the :ref:`detections` screen. -ElastAlert rules are stored in ``/opt/so/rules/elastalert/``. +See the :ref:`notifications` section for information on how to enable outbound notifications via the Detections module. -By default, ElastAlert rules are configured with an output type of ``debug``, which simply outputs to a log file found in ``/opt/so/log/elastalert/``. +Custom Rules +------------ -ElastAlert logs to :ref:`elasticsearch` indices. You can search those indices in :ref:`dashboards`, :ref:`hunt`, or :ref:`kibana`. :ref:`soc` does not automatically search the ``elastalert`` indices by default so if you want to use :ref:`dashboards` or :ref:`hunt` to search ElastAlert logs, then you'll need to adjust the appropriate configuration setting. Find it in the Administration -> Configuration screen by filtering for ``elastic.index`` and selecting Options (at the top) and toggle on "Show all configurable settings". Add ``*:elastalert*`` to the ``index`` setting. The new setting value should resemble the following: +Custom ElastAlert 2 rules, which are not associated to the Detections module, can be added to the Security Onion manager node inside a custom subdirectory under the ``/opt/so/rules/elastalert/rules/`` directory. For example, create a subdirectory called ``/opt/so/rules/elastalert/rules/custom/`` and place custom rules within that directory. -:: +.. warning:: - *:so-*,*:endgame-*,*:logs-*,*:elastalert* + Do not modify or add rules to the ``/opt/so/rules/elastalert/rules/`` directory itself as those rules are overwritten by the Detections module. -Slack -~~~~~ +Refer to the ElastAlert 2 documention, linked above, for detailed information on how to write custom rules. Be aware that writing rules requires an in-depth understanding of Elasticsearch document records, their data structure, and other related concepts. -To have ElastAlert send alerts to something like Slack, we can simply change the alert type and details for a rule like so: - -:: - - alert: - - "slack": - slack_webhook_url: "https://hooks.slack.com/services/YOUR_WEBHOOK_URI" - -Email - Internal -~~~~~~~~~~~~~~~~ - -To have ElastAlert send to email, we could do something like the following: - -:: - - alert: - - "email" - email: - - "youremail@yourcompany.com" - smtp_host: "your_company_smtp_server" - smtp_port: 25 - from_addr: "elastalert@yourcompany.com" - -Email - External -~~~~~~~~~~~~~~~~ +Diagnostic Logging +------------------ -If we need to use an external email provider like Gmail, we can add something like the following: +Elastalert diagnostic logs are in ``/opt/so/log/elastalert/`` and may also appear in the :ref:`docker` logs for the container. To view container logs run the following command on the manager: :: - alert: - - "email" - email: - - "youremail@gmail.com" - smtp_host: "smtp.gmail.com" - smtp_port: 465 - smtp_ssl: true - from_addr: "youremail@gmail.com" - smtp_auth_file: '/opt/elastalert/rules/smtp_auth_file.txt' + sudo docker logs so-elastalert -Then create a new file called ``/opt/so/rules/elastalert/smtp_auth_file.txt`` and add the following: +ElastAlert 2 stores rule status information, such as number of hits, times each rule last ran, etc to :ref:`elasticsearch` indices. This data can helpful in assisting with troubleshooting custom rules. Searching in :ref:`dashboards`, :ref:`hunt`, or :ref:`kibana`. :ref:`soc` does not automatically include the ``elastalert`` indices by default. To include them adjust the appropriate configuration setting. Find it in the Administration --> Configuration screen by filtering for ``elastic.index`` and selecting Options (at the top) and toggle on "Show all configurable settings". Add ``*:elastalert*`` to the ``index`` setting. The new setting value should resemble the following: :: - user: youremail@gmail.com - password: yourpassword + *:so-*,*:endgame-*,*:logs-*,*:elastalert* so-elastalert-create ~~~~~~~~~~~~~~~~~~~~ @@ -94,14 +58,10 @@ so-elastalert-test ``so-elastalert-test`` does not yet include all options available to ``elastalert-test-rule``. -Defaults -~~~~~~~~ - -With Security Onion's example rules, Elastalert is configured by default to only count the number of hits for a particular match, and will not return the actual log entry for which an alert was generated. - -This is governed by the use of ``use_count_query: true`` in each rule file. +Performance +~~~~~~~~~~~ -If you would like to view the data for the match, you can simply remark this line in the rule file(s). This may impact performance negatively, so testing the change in a single file at a time may be the best approach. +For better performance, avoid writing rules that return large numbers of records. Instead, use the ``use_count_query: true`` in each rule file. This will only return counts of matching records and not the records themselves. Timeframe ~~~~~~~~~ @@ -118,14 +78,14 @@ For queries that span greater than a minute back in time, you may want to add th | https://elastalert2.readthedocs.io/en/latest/ruletypes.html#buffer-time | https://github.com/Yelp/elastalert/issues/805 -Diagnostic Logging ------------------- -Elastalert diagnostic logs are in ``/opt/so/log/elastalert/``. Depending on what you’re looking for, you may also need to look at the :ref:`docker` logs for the container: +Configuration +------------- -:: +You can modify ElastAlert 2 configuration by going to :ref:`administration` --> Configuration --> elastalert. - sudo docker logs so-elastalert +.. image:: images/config-item-elastalert.png + :target: _images/config-item-elastalert.png More Information ---------------- diff --git a/elastic-agent.rst b/elastic-agent.rst index 838fee79..9fbc5387 100644 --- a/elastic-agent.rst +++ b/elastic-agent.rst @@ -48,7 +48,7 @@ If deploying the Elastic Agent to macOS, you will need to take a few steps. Firs chmod +x ./so-elastic-agent_darwin_amd64 sudo ./so-elastic-agent_darwin_amd64 -After the installer has completed, review the Elastic docs for your version of macOS and approve the required settings (system extension and full drive access) as shown at https://www.elastic.co/guide/en/security/8.9/elastic-endpoint-deploy-reqs.html. +After the installer has completed, review the Elastic docs for your version of macOS and approve the required settings (system extension and full drive access) as shown at https://www.elastic.co/guide/en/security/current/elastic-endpoint-deploy-reqs.html. Logs ---- diff --git a/elastic-fleet.rst b/elastic-fleet.rst index 3373aa2e..62b917bb 100644 --- a/elastic-fleet.rst +++ b/elastic-fleet.rst @@ -8,27 +8,27 @@ Elastic Fleet Configuration ------------- -Elastic Fleet is pre-configured during Security Onion setup, however, centralized management of configuration is provided within its user interface inside of Kibana. - -Configuration options for various components are detailed below. +Elastic Fleet is pre-configured during Security Onion setup. If you need to make changes to the configuration, you can do so via the Fleet page in :ref:`kibana` as detailed below. Agents ------ -This section displays registered Elastic agents (https://docs.securityonion.net/en/2.4/elastic-agent.html) and allows the user to add additional agents. +This section displays registered Elastic agents and allows the user to add additional agents. For more information about Elastic agents, please see the :ref:`elastic-agent` section. To view agent details, click the ``Host`` name. To assign the agent to a new policy, unenroll, upgrade the agent, or perform other actions, click the ``Actions`` menu on the right side of the agent listing and select the appropriate option. -By default, Elastic Agent is installed on every Security Onion grid node. As a result, all grid node agents will be enrolled in the ``SO-Grid-Nodes`` agent policy. We do not recommend removing policy settings for Security Onion grid node agents. +By default, Elastic Agent is installed on every Security Onion grid node. As a result, all grid node agents will be enrolled in the ``SO-Grid-Nodes`` agent policy. + +.. warning:: + + We do not recommend removing policy settings for Security Onion grid node agents. Adding Agents ------------- -To add a new agent to your deployment, see the following: - -https://docs.securityonion.net/en/2.4/elastic-agent.html#deployment +To add a new agent to your deployment, see the :ref:`elastic-agent` section. Agent Policies -------------- @@ -56,7 +56,7 @@ For example, the ``SO-Grid-Nodes`` agent policy is comprised of the following in Agent Policies - endpoints-initial ---------------------------------- -Agent installers downloaded from SOC --> Downloads, are deployed using the ``endpoints-initial`` Agent Policy. This policy includes the ``Elastic Defend``, ``Osquery Manager``, ``System``, and ``Windows`` integrations. +Agent installers downloaded from :ref:`Downloads` are deployed using the ``endpoints-initial`` Agent Policy. This policy includes the ``Elastic Defend``, ``Osquery Manager``, ``System``, and ``Windows`` integrations. elastic-defend-endpoints (``Elastic Defend`` integration) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -89,7 +89,7 @@ The ``Elastic Defend`` integration has both free and paid features. By default, osquery-endpoints (``Osquery Manager`` integration) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The ``Osquery Manager`` integration runs osquery as a daemon on the endpoint, and makes the endpoint available for Live or Scheduled queries through the Osquery manager interface in Kibana. +The ``Osquery Manager`` integration runs osquery as a daemon on the endpoint and makes the endpoint available for Live or Scheduled queries through the Osquery manager interface in Kibana. system-endpoints (``System`` integration) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -126,130 +126,7 @@ The ``Windows`` integration collects the following logs from the endpoint, where Integrations ------------ -.. note:: - - Security Onion 2.4.10 supports the following Elastic integrations: - - - aws - - azure - - cloudflare - - elasticsearch - - endpoint - - fleet_server - - fim - - github - - google_workspace - - log - - osquery_manager - - redis - - system - - tcp - - udp - - windows - - 1password - - Security Onion 2.4.20 supports these additional Elastic integrations: - - - apache - - auditd - - barracuda - - cisco_asa - - crowdstrike - - darktrace - - f5_bigip - - fortinet - - fortinet_fortigate - - gcp - - http_endpoint - - httpjson - - juniper - - juniper_srx - - kafka_log - - lastpass - - m365_defender - - microsoft_defender_endpoint - - microsoft_dhcp - - netflow - - o365 - - okta - - panw - - pfsense - - sentinel_one - - sonicwall_firewall - - symantec_endpoint - - ti_abusech - - ti_misp - - ti_otx - - ti_recordedfuture - - zscaler_zia - - zscaler_zpa - - Security Onion 2.4.30 supports these additional Elastic integrations: - - - auth0 - - carbonblack_edr - - checkpoint - - cisco_duo - - cisco_meraki - - cisco_umbrella - - fireeye - - mimecast - - pulse_connect_secure - - snyk - - sophos - - sophos_central - - tenable_sc - - vsphere - - Security Onion 2.4.40 supports these additional Elastic integrations: - - - cisco_ftd - - cisco_ios - - cisco_ise - - iis - - microsoft_sqlserver - - mysql - - proofpoint_tap - - snort - - ti_anomali - - ti_cybersixgill - - ti_threatq - - Security Onion 2.4.50 supports these additional Elastic integrations: - - - citrix_adc - - citrix_waf - - nginx - - winlog - - Security Onion 2.4.60 supports these additional Elastic integrations: - - - journald - - ti_cybersixgill - -You can read more about Elastic integrations at https://docs.elastic.co/integrations. - -Adding an Integration ---------------------- - -New integrations can be added to existing policies to provide increased visibility and more comprehensive monitoring. - -To add an integration to an existing policy: - -From ``Fleet`` -> ``Agent policies`` -> ``$Policy name``, click ``Add Integration`` and follow the steps for adding the integration. - -When setting up a new integration, it is important that you add it to an appropriate Policy. - -If an integration pulls the data, you should add it to the Fleet Server policy. Depending on complexity and log volume, it might make sense to stand up a Fleet Node and add your integrations to it. - -If an integration receives data pushed to it (for example - receiving syslog), once again, consider adding it to the Fleet Server policy. If that is not feasible, and it will be added to the Grid Nodes policy, make sure to set the firewall rules correctly so that you are not opening ports on all of your nodes. - -If the integration is designed to listen on a port to receive data, it will most likely default to listening on ``localhost`` only. Depending on how you are sending data to the integration, you may need to change that to ``0.0.0.0`` so that it can receive data from other hosts. - -Adding a Custom Integration ---------------------------- - -A custom integration can be added by adding an integration such as the ``Custom Logs`` integration. We can specify various settings relative to the data source and define additional actions to be performed. +Elastic Fleet supports integrations and you can read more in the :ref:`third-party-integrations` section. Enrollment Tokens ----------------- diff --git a/elasticsearch.rst b/elasticsearch.rst index 7684f20d..7ff45421 100644 --- a/elasticsearch.rst +++ b/elasticsearch.rst @@ -7,11 +7,30 @@ From https://www.elastic.co/products/elasticsearch: Elasticsearch is a distributed, RESTful search and analytics engine capable of addressing a growing number of use cases. As the heart of the Elastic Stack, it centrally stores your data for lightning fast search, fine‑tuned relevancy, and powerful analytics that scale with ease. -Data ----- +Storage +------- + +All of the data Elasticsearch collects is stored under ``/nsm/elasticsearch/``. + +Schema +------ + +Security Onion tries to adhere to Elastic Common Schema (ECS) wherever possible. In some cases, additional fields or slight modifications to native Elastic field mappings may be found within the data. You can learn more about ECS at https://www.elastic.co/elasticsearch/common-schema. + +Querying +-------- + +You can query Elasticsearch using web interfaces like :ref:`alerts`, :ref:`dashboards`, :ref:`hunt`, and :ref:`kibana`. You can also query Elasticsearch from the command line using :ref:`so-elasticsearch-query`. + +Authentication +-------------- + +You can authenticate to Elasticsearch using the same username and password that you use for :ref:`soc`. + +You can add new user accounts to both Elasticsearch and :ref:`soc` at the same time as shown in the :ref:`adding-accounts` section. Please note that if you instead create accounts directly in Elastic, then those accounts will only have access to Elastic and not :ref:`soc`. Indexing -~~~~~~~~ +-------- Most data is associated with a data stream, which is an abstraction from traditional indices that leverages one or more backing indices to manage and represent the data within the data stream. The usage of data streams allows for greater flexibility in data management. @@ -39,65 +58,96 @@ Similarly, you can target a single backing index with the following query: You can learn more about data streams at https://www.elastic.co/guide/en/elasticsearch/reference/current/data-streams.html. -Schema -~~~~~~ +Configuration +------------- + +You can configure Elasticsearch by going to :ref:`administration` --> Configuration --> elasticsearch. -Security Onion tries to adhere to the Elastic Common Schema wherever possible. Otherwise, additional fields or slight modifications to native Elastic field mappings may be found within the data. +.. image:: images/config-item-elasticsearch.png + :target: _images/config-item-elasticsearch.png + +Index Management +---------------- + +Elasticsearch indices are managed by both the ``so-elasticsearch-indices-delete`` utility and Index Lifecycle Management (ILM). + +.. tip:: -Management -~~~~~~~~~~ + Starting in Security Onion 2.4.70, you have the option of disabling ``so-elasticsearch-indices-delete`` and just managing indices using ILM. This may be useful for production deployments since ILM provides more granular index management. You can find this option at :ref:`administration` --> Configuration --> elasticsearch --> index_clean. + +.. warning:: + + If you disable ``so-elasticsearch-indices-delete`` via the index_clean setting, then you will need to ensure that ILM is configured properly to delete indices before disk usage reaches the Elasticsearch watermark setting. Otherwise, Elasticsearch may stop ingesting new data. -Elasticsearch indices are managed by the ``so-elasticsearch-indices-delete`` utility and ILM (https://www.elastic.co/guide/en/elasticsearch/reference/current/index-lifecycle-management.html). +so-elasticsearch-indices-delete +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -``so-elasticsearch-indices-delete`` handles size-based index deletion and ILM handles the following: +``so-elasticsearch-indices-delete`` manages size-based deletion of Elasticsearch indices based on the value of the ``elasticsearch.retention.retention_pct`` setting. This setting is checked against the total disk space available for ``/nsm/elasticsearch`` across all nodes in the Elasticsearch cluster. If your indices are using more than ``retention_pct``, then ``so-elasticsearch-indices-delete`` will delete old indices until available disk space is back under ``retention_pct``. The default value for this setting is ``50`` percent so that standalone deployments have sufficient space for not only Elasticsearch but also full packet capture and other logs. For distributed deployments with dedicated search nodes where Elasticsearch is main consumer of disk space, you may want to increase this default value. + +To modify the ``retention_pct`` value, first navigate to :ref:`administration` --> Configuration. At the top of the page, click the ``Options`` menu and then enable the ``Show all configurable settings, including advanced settings.`` option. Then navigate to elasticsearch --> retention --> retention_pct. Once you make the change and save it, the new setting will take effect at the next 15 minute interval. If you would like to make the change immediately, you can click the ``SYNCHRONIZE GRID`` button under the ``Options`` menu at the top of the page. + +ILM +~~~ + +Index Lifecycle Management (ILM) manages the following: - size-based index rollover - time-based index rollover - time-based content tiers - time-based index deletion -Default ILM policies are preconfigured and associated with various data streams and index templates in ``/opt/so/saltstack/default/salt/elasticsearch/defaults.yaml``. +Time-based index deletion is based on the ``min_age`` setting within the global policy or the individual policy for the index itself. Please note that size-based deletion via ``so-elasticsearch-indices-delete`` takes priority over time-based deletion, as disk usage may reach ``retention_pct`` and indices will be deleted before the ``min_age`` value is reached. -Querying --------- +ILM settings can be found by navigating to :ref:`administration` --> Configuration --> elasticsearch --> index_settings. -You can query Elasticsearch using web interfaces like :ref:`alerts`, :ref:`dashboards`, :ref:`hunt`, and :ref:`kibana`. You can also query Elasticsearch from the command line using a tool like ``curl``. You can also use :ref:`so-elasticsearch-query`. +To edit the global policy that applies to ALL indices, navigate to global_overrides --> policy --> phases and there you will see the cold, delete, hot, and warm ILM phases. -Authentication --------------- +To edit the policy for an individual index, first click the ``Options`` menu at the top of the page and then enable the ``Show all configurable settings, including advanced settings.`` option. Then navigate to $index --> policy --> phases. There you will see the cold, delete, hot, and warm ILM phases for that particular index. -You can authenticate to Elasticsearch using the same username and password that you use for :ref:`soc`. +It's important to note that settings like ``min_age`` are calculated relative to the rollover date (NOT the original creation date of the index). For example, if you have an index that is set to rollover after 30 days and delete ``min_age`` set to 30 then there will be 30 days from index creation to rollover and then an additional 30 days before deletion. -You can add new user accounts to both Elasticsearch and :ref:`soc` at the same time as shown in the :ref:`adding-accounts` section. Please note that if you instead create accounts directly in Elastic, then those accounts will only have access to Elastic and not :ref:`soc`. +When modifying ILM settings, note that some settings will only take effect after a new index is created. -Diagnostic Logging ------------------- +.. note:: -- Elasticsearch logs can be found in ``/opt/so/log/elasticsearch/``. -- Logging configuration can be found in ``/opt/so/conf/elasticsearch/log4j2.properties``. + | You can learn more about ILM at: + | https://www.elastic.co/guide/en/elasticsearch/reference/current/index-lifecycle-management.html -Depending on what you're looking for, you may also need to look at the :ref:`docker` logs for the container: +Parsing +------- -:: +Elasticsearch receives unparsed logs from :ref:`logstash` or :ref:`elastic-agent`. Elasticsearch then parses and stores those logs. Parsers are stored in ``/opt/so/conf/elasticsearch/ingest/``. Custom ingest parsers can be placed in ``/opt/so/saltstack/local/salt/elasticsearch/files/ingest/``. To make these changes take effect, restart Elasticsearch using ``so-elasticsearch-restart``. - sudo docker logs so-elasticsearch +:ref:`elastic-agent` may pre-parse or act on data before the data reaches Elasticsearch, altering the data stream or index to which it is written, or other characteristics such as the event dataset or other pertinent information. This configuration is maintained in the agent policy or integration configuration in :ref:`elastic-fleet`. -Storage -------- +.. note:: -All of the data Elasticsearch collects is stored under ``/nsm/elasticsearch/``. + | You can learn more about Elasticsearch ingest parsing at: + | https://www.elastic.co/guide/en/elasticsearch/reference/current/ingest.html -Parsing +Cluster ------- -Elasticsearch receives unparsed logs from :ref:`logstash` or :ref:`elastic-agent`. Elasticsearch then parses and stores those logs. Parsers are stored in ``/opt/so/conf/elasticsearch/ingest/``. Custom ingest parsers can be placed in ``/opt/so/saltstack/local/salt/elasticsearch/files/ingest/``. To make these changes take effect, restart Elasticsearch using ``so-elasticsearch-restart``. +In a distributed deployment with a manager and one or more search nodes, the manager and search nodes are joined together as a multi-node Elastic cluster. -:ref:`elastic-agent` may pre-parse or act on data before the data reaches Elasticsearch, altering the data stream or index to which it is written, or other characteristics such as the event dataset or other pertinent information. This configuration is maintained in the agent policy or integration configuration in :ref:`elastic-fleet`. +For more information, please see the cluster information at https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html#modules-node. -.. note:: +Elasticsearch Node Roles +------------------------ + +Please see the Elasticsearch node roles documentation at https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html. + +When building a distributed deployment, the Security Onion manager has to start off with the ``data`` node role. If you later join a separate search node, then you may want to migrate the data from the manager to the search node and then remove the ``data`` node role from the manager. For more information, please see: + +https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cluster.html#cluster-shard-allocation-filtering - | For more about Elasticsearch ingest parsing, please see: - | https://www.elastic.co/guide/en/elasticsearch/reference/current/ingest.html +If you want to set certain search nodes to the ``data_hot``, ``data_warm``, or ``data_cold`` roles, make sure you remove the ``data`` role from them. You will also want to ensure that ``data_content`` is assigned to your hot nodes. + +.. warning:: + + Elasticsearch node roles is an advanced setting and you should be careful to avoid disruption to your cluster! + +To see and modify Elasticsearch node roles, first navigate to :ref:`administration` --> Configuration, click the ``Options`` menu at the top of the page, and enable the ``Show all configurable settings, including advanced settings.`` option. Then navigate to elasticsearch --> so_roles and select the desired role. Finally, navigate to config --> node --> roles and the list of roles should appear on the right side of the page. Templates --------- @@ -109,11 +159,10 @@ Component Templates From https://www.elastic.co/guide/en/elasticsearch/reference/current/index-templates.html: - Component templates are reusable building blocks that configure mappings, settings, and aliases. While you can use component templates to construct index templates, they aren’t directly applied to a set of indices. + Component templates are reusable building blocks that configure mappings, settings, and aliases. While you can use component templates to construct index templates, they aren’t directly applied to a set of indices. Also see https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-component-template.html. - Index Templates ~~~~~~~~~~~~~~~ @@ -131,21 +180,13 @@ Community ID | For logs that don’t naturally include :ref:`community-id`, we use the Elasticsearch Community ID processor: | https://www.elastic.co/guide/en/elasticsearch/reference/current/community-id-processor.html -Configuration -------------- - -You can configure Elasticsearch by going to :ref:`administration` --> Configuration --> elasticsearch. - -.. image:: images/config-item-elasticsearch.png - :target: _images/config-item-elasticsearch.png - field expansion matches too many fields -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------------- If you get errors like ``failed to create query: field expansion for [*] matches too many fields, limit: 3500, got: XXXX``, then this usually means that you're sending in additional logs and so you have more fields than our default ``max_clause_count`` value. To resolve this, you can go to :ref:`administration` --> Configuration --> elasticsearch --> config --> indices --> query --> bool --> max_clause_count and adjust the value for any boxes running Elasticsearch in your deployment. Shards -~~~~~~ +------ Here are a few tips from https://www.elastic.co/blog/how-many-shards-should-i-have-in-my-elasticsearch-cluster: @@ -174,7 +215,7 @@ The number of shards for an index can be adjusted by going to :ref:`administrati Please keep in mind that old indices will retain previous shard settings and the above settings will only be applied to newly created indices. Heap Size -~~~~~~~~~ +--------- If total available memory is 8GB or greater, Setup configures the heap size to be 33% of available memory, but no greater than 25GB. You may need to adjust the value for heap size depending on your system's performance. You can modify this by going to :ref:`administration` --> Configuration --> elasticsearch --> esheap. @@ -183,35 +224,16 @@ If total available memory is 8GB or greater, Setup configures the heap size to b | https://www.elastic.co/guide/en/elasticsearch/reference/current/important-settings.html#heap-size-settings Field limit -~~~~~~~~~~~ +----------- Security Onion currently defaults to a field limit of 5000. If you receive error messages from Logstash, or you would simply like to increase this, you can do so by going to :ref:`administration` --> Configuration --> elasticsearch --> index_settings --> so-INDEX-NAME --> index_template --> template --> settings --> index --> mapping --> total_fields --> limit. Please note that the change to the field limit will not occur immediately, only on index creation. -Deleting Indices ----------------- - -Size-based Index Deletion -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Size-based deletion of Elasticsearch indices occurs based on the value of cluster-wide ``elasticsearch.retention.retention_pct``, which is derived from the total disk space available for ``/nsm/elasticsearch`` across all nodes in the Elasticsearch cluster. The default value for this setting is ``50`` percent. - -To modify this value, first navigate to :ref:`administration` -> Configuration. At the top of the page, click the ``Options`` menu and then enable the ``Show all configurable settings, including advanced settings.`` option. Then navigate to elasticsearch -> retention -> retention_pct. The change will take effect at the next 15 minute interval. If you would like to make the change immediately, you can click the ``SYNCHRONIZE GRID`` button under the ``Options`` menu at the top of the page. - -If your indices are using more than ``retention_pct``, then ``so-elasticsearch-indices-delete`` will delete old indices until disk space is back under ``retention_pct``. - -Time-based Index Deletion -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Time-based deletion occurs through the use of the $data_stream.policy.phases.delete.min_age setting within the lifecycle policy tied to each index and is controlled by ILM. It is important to note that size-based deletion takes priority over time-based deletion, as disk may reach ``retention_pct`` and indices will be deleted before the ``min_age`` value is reached. - -Policies can be edited within the SOC administration interface by navigating to :ref:`administration` -> Configuration -> elasticsearch -> $index -> policy -> phases -> delete -> min_age. Changes will take effect when a new index is created. - Re-indexing ----------- -Re-indexing may need to occur if field data types have changed and conflicts arise. This process can be VERY time-consuming, and we only recommend this if keeping data is absolutely critical. +Re-indexing may need to occur if field data types have changed and conflicts arise. This process can be VERY time-consuming, and we only recommend this if keeping data is absolutely critical. | For more information about re-indexing, please see: | https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html @@ -234,6 +256,18 @@ Elasticsearch 8 no longer includes GeoIP databases by default. We include GeoIP downloader: enabled: true +Diagnostic Logging +------------------ + +- Elasticsearch logs can be found in ``/opt/so/log/elasticsearch/``. +- Logging configuration can be found in ``/opt/so/conf/elasticsearch/log4j2.properties``. + +Depending on what you're looking for, you may also need to look at the :ref:`docker` logs for the container: + +:: + + sudo docker logs so-elasticsearch + More Information ---------------- diff --git a/eol.rst b/eol.rst index 3048fb57..6049b073 100644 --- a/eol.rst +++ b/eol.rst @@ -5,7 +5,7 @@ End Of Life This page lists End Of Life (EOL) dates for older versions of Security Onion and older components. -| Security Onion 2.3 reaches EOL on April 6, 2024 (please migrate to Security Onion 2.4): +| Security Onion 2.3 reached EOL on April 6, 2024 (please migrate to Security Onion 2.4): | https://blog.securityonion.net/2023/10/6-month-eol-notice-for-security-onion-23.html | Ubuntu 18.04 reached End of Ubuntu Standard Support in April 2023: diff --git a/faq.rst b/faq.rst index cc457016..f8e32b2b 100644 --- a/faq.rst +++ b/faq.rst @@ -28,6 +28,16 @@ What's the recommended procedure for installing Security Onion? Please see the :ref:`installation` section. +What's the recommended procedure for configuring Security Onion? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Please see the :ref:`configuration` section. + +What if I receive a ``The IP being routed by Linux is not the IP address assigned to the management interface`` error message? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Please see the warning about this in the :ref:`configuration` section. + What languages are supported? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -53,6 +63,7 @@ Can I run Security Onion on Raspberry Pi or some other non-x86 box? No, we only support x86-64 (standard Intel/AMD 64-bit architectures). Please see the :ref:`hardware` section. + `back to top <#top>`__ Users / Passwords @@ -121,7 +132,7 @@ Please see the :ref:`timezones` section. Why is my disk filling up? ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Security Onion records full packet capture to disk via :ref:`stenographer`. +In general, Security Onion attempts to make use of as much disk space as you give it. Depending on installation type, it should continue writing data to disk until disk usage reaches 80-90% at which point it should begin purging old data. Most disk space is used by :ref:`elasticsearch` or full packet capture written to disk via :ref:`stenographer` or :ref:`suricata`. How is my data kept secure? ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/fips.rst b/fips.rst new file mode 100644 index 00000000..c45f5000 --- /dev/null +++ b/fips.rst @@ -0,0 +1,15 @@ +.. _fips: + +FIPS +==== + +FIPS stands for Federal Information Processing Standards and you can read more about it at https://en.wikipedia.org/wiki/Federal_Information_Processing_Standards. + +.. note:: + + This is an enterprise-level feature of Security Onion. Contact Security Onion Solutions, LLC via our website at https://securityonionsolutions.com for more information about purchasing a Security Onion Pro license to enable this feature. + +Enabling FIPS During the ISO Install +------------------------------------ + +The recommended way to use FIPS with Security Onion is to install via our Security Onion ISO image. At the ISO boot menu, you'll need to modify the boot command. This can be done using the ``e`` key in UEFI boot mode or the ``Tab`` key in BIOS boot mode before it automatically boots. Then append ``fips=1`` (and possibly other options like :ref:`luks` and :ref:`stig`) to the boot parameters and continue the boot process. diff --git a/firewall.rst b/firewall.rst index c6622378..b2a68bae 100644 --- a/firewall.rst +++ b/firewall.rst @@ -81,10 +81,14 @@ Elastic Fleet nodes to Receiver nodes: Host Firewall ------------- -The remainder of this section will cover the host firewall built into Security Onion. +The remainder of this section will cover the host firewall built into Security Onion. -Configuration -------------- +.. note:: + + Security Onion locks down the firewall by default. + +Configuring Host Firewall +------------------------- You can configure the firewall by going to :ref:`administration` --> Configuration --> firewall --> hostgroups. @@ -96,6 +100,18 @@ If for some reason you can't access :ref:`soc`, you can use the so-firewall comm so-firewall includehost analyst +Reviewing Host Firewall +----------------------- + +You can view the entire firewall configuration from the command line using the ``iptables`` command like this: +:: + + sudo iptables -nvL + +.. warning:: + + You can use this command to view the iptables configuration, but please do not modify the firewall manually using iptables as it is managed by :ref:`salt`. You should only make changes via the Configuration screen as shown above. + Port Groups ----------- diff --git a/first-time-users.rst b/first-time-users.rst index bea8fe5f..61557655 100644 --- a/first-time-users.rst +++ b/first-time-users.rst @@ -16,7 +16,7 @@ After booting the ISO image, the boot menu appears: .. image:: images/01_grub.png :target: _images/01_grub.png -When prompted, specify your username and password: +When prompted, enter your desired username and password: .. image:: images/02_initial_install.png :target: _images/02_initial_install.png @@ -151,77 +151,77 @@ After logging in, you will see the :ref:`soc` Overview page: .. image:: images/38_overview.png :target: _images/38_overview.png -Check :ref:`grid` to verify all services are running properly: +Go to the :ref:`grid` page, click the button to expand the node, and then verify all services are running properly: .. image:: images/39_grid.png :target: _images/39_grid.png -While on the :ref:`grid` page, you can upload a PCAP or EVTX file: +While on the :ref:`grid` page, you can import a PCAP or EVTX file using the upload button at the bottom of the screen: .. image:: images/40_upload.png :target: _images/40_upload.png -Review alerts on the :ref:`alerts` page: +Once the import is complete, the :ref:`grid` page should display a message at the of the page and provide a link to :ref:`dashboards` to view all alerts and logs from the import: -.. image:: images/50_alerts.png - :target: _images/50_alerts.png +.. image:: images/45_import.png + :target: _images/45_import.png -Review other logs on the :ref:`dashboards` page: +If you want to see just the alerts, you can go to the :ref:`alerts` page although you may need to manually adjust the time range: -.. image:: images/51_dashboards.png - :target: _images/51_dashboards.png +.. image:: images/50_alerts.png + :target: _images/50_alerts.png If you find something interesting on the :ref:`alerts` or :ref:`dashboards` pages, you may want to use the Correlate or Hunt actions to find related logs on the :ref:`hunt` page: -.. image:: images/52_hunt.png - :target: _images/52_hunt.png +.. image:: images/56_hunt.png + :target: _images/56_hunt.png If you find interesting network traffic, you can pivot to full packet capture via the :ref:`pcap` action: -.. image:: images/53_pcap.png - :target: _images/53_pcap.png +.. image:: images/62_pcap.png + :target: _images/62_pcap.png You can change the view to ASCII transcript for a more human readable view of the traffic: -.. image:: images/54_pcap_details.png - :target: _images/54_pcap_details.png +.. image:: images/65_pcap_details.png + :target: _images/65_pcap_details.png If you find an interesting artifact, you can send it to :ref:`cyberchef`: -.. image:: images/55_cyberchef.png - :target: _images/55_cyberchef.png +.. image:: images/68_cyberchef.png + :target: _images/68_cyberchef.png If you need to refer back to previous PCAP jobs, you can find them on the :ref:`pcap` page: -.. image:: images/56_jobs.png - :target: _images/56_jobs.png +.. image:: images/72_jobs.png + :target: _images/72_jobs.png -IMPORT installations do not support remote agents, but if you were running another installation type you could download the Elastic Agent installer from :ref:`downloads`: +IMPORT installations do not support remote agents, but if you were running a production installation you could download the Elastic Agent installer from :ref:`downloads`: -.. image:: images/58_downloads.png - :target: _images/58_downloads.png +.. image:: images/78_downloads.png + :target: _images/78_downloads.png The :ref:`administration` section allows to you manage user accounts: -.. image:: images/59_users.png - :target: _images/59_users.png +.. image:: images/81_users.png + :target: _images/81_users.png It also allows you to manage grid members: -.. image:: images/60_gridmembers.png - :target: _images/60_gridmembers.png +.. image:: images/84_gridmembers.png + :target: _images/84_gridmembers.png The :ref:`administration` section also allows you to configure various aspects of the system: -.. image:: images/61_config.png - :target: _images/61_config.png +.. image:: images/87_config.png + :target: _images/87_config.png It also allows you to upload a license key for additional enterprise features: -.. image:: images/62_licensekey.png - :target: _images/62_licensekey.png +.. image:: images/91_licensekey.png + :target: _images/91_licensekey.png All this in a minimal VM with only 4GB RAM! -.. image:: images/99_top.png - :target: _images/99_top.png +.. image:: images/39_grid.png + :target: _images/39_grid.png diff --git a/grid.rst b/grid.rst index 9c783e7e..c18811d8 100644 --- a/grid.rst +++ b/grid.rst @@ -8,7 +8,7 @@ Grid .. image:: images/39_grid.png :target: _images/39_grid.png -Starting at the top of the page, there is a ``Grid EPS`` value in the upper right corner that shows the sum of all ``Consumption EPS`` measurements in the entire grid. Below that you will find a list of all nodes in your grid. +Starting at the top of the page, there is a ``Grid EPS`` value in the upper-right corner that shows the sum of all ``Consumption EPS`` measurements in the entire grid. Below that you will find a list of all nodes in your grid. .. warning:: @@ -20,6 +20,9 @@ Starting at the top of the page, there is a ``Grid EPS`` value in the upper righ Starting in Security Onion 2.4.40, there is a new checkbox in the options dropdown near the top of the page. This checkbox will show additional sensor-related columns in the table. You can use these sortable columns to help identify sensors that may be underperforming or due for a hardware upgrade. As these additional columns take up significant screen area, they will only be visible on wide displays where the SOC web browser window is wide enough to show a large number of tabular columns. +.. image:: images/76_grid_options.png + :target: _images/76_grid_options.png + You can drill into individual nodes to see detailed information including Node Status, Container Status, and Appliance Images. Node Status diff --git a/hardware.rst b/hardware.rst index 95a852b6..b800bdea 100644 --- a/hardware.rst +++ b/hardware.rst @@ -17,24 +17,39 @@ Security Onion only supports x86-64 architecture (standard Intel or AMD 64-bit p Minimum Specs ------------- -Please note these are the absolute bare minimum requirements. Your requirements may increase drastically as you enable more services, monitor more traffic, and consume more logs. For more information, please see the detailed sections below. ================ ====== ===== ========= ====== Node Type CPUs RAM Storage NICs ================ ====== ===== ========= ====== Import 2 4GB 50GB 1 -Eval 4 12GB 200GB 2 +Eval 4 8GB 200GB 2 Standalone 4 16GB 200GB 2 Manager 4 16GB 200GB 1 ManagerSearch 8 16GB 200GB 1 Search node 4 16GB 200GB 1 -Forward node 4 12GB 200GB 2 +Sensor 4 12GB 200GB 2 Heavy node 4 16GB 200GB 2 IDH node 2 1GB 12GB 1 -Fleet node 4 12GB 200GB 1 +Fleet node 4 4GB 200GB 1 Receiver node 2 8GB 200GB 1 ================ ====== ===== ========= ====== +.. warning:: + + Please note these are the absolute bare minimum requirements. Your requirements may increase drastically as you enable more services, monitor more traffic, and consume more logs. For more information, please see the detailed sections below. + +Import +------ + +An Import installation runs the minimal processes required to import PCAP or EVTX files and view the results. As such, it has the lowest hardware requirements as shown in the table above. You can read more about Import in the :ref:`first-time-users` section. + +Eval +---- + +An Eval installation runs the minimal processes required for a single machine to sniff live network traffic from a TAP or span port and view the results. Therefore, its hardware requirements are higher than Import as shown in the table above. Eval is designed for temporary installations or homelab installations on a budget. Unlike a full Standalone installation, Evaluation is NOT designed for production usage. + +In order to minimize RAM usage, Eval does not run :ref:`logstash` or :ref:`redis` at all. Also, Eval defaults to using :ref:`suricata` for writing full packet capture to disk (instead of :ref:`stenographer`). + Production Deployments ---------------------- @@ -58,19 +73,19 @@ If you plan to sniff network traffic from a tap or span port, then you will need Make sure you get good quality network cards, especially for sniffing. Most users report good experiences with Intel cards. -Security Onion is designed to use wired interfaces. You may be able to make wireless interfaces work, but we don't recommend or support it. +Security Onion is designed to use wired interfaces. You may be able to make wireless interfaces work, but we don't recommend or support it. UPS --- -Like most IT systems, Security Onion has databases and those databases don't like power outages or other ungraceful shutdowns. To avoid power outages and having to manually repair databases, please consider a UPS. +As with most computer systems, you'll want to avoid power outages or other ungraceful shutdowns. Please consider a UPS (Uninterruptible Power Supply) for production deployments. Elastic Stack ------------- -Please refer to the :ref:`architecture` section for detailed deployment scenarios. +We recommend placing all Elastic storage (/nsm/elasticsearch) on SSD or fast spinning disk in a RAID 10 configuration. -**We recommend placing all Elastic storage (/nsm/elasticsearch) on SSD or fast spinning disk in a RAID 10 configuration.** +Please see the :ref:`architecture` section for detailed deployment scenarios. Standalone Deployments ---------------------- @@ -163,7 +178,7 @@ We recommend dedicated physical hardware (especially if you're monitoring lots o CPU ~~~ -:ref:`suricata` and :ref:`zeek` are very CPU intensive. The more traffic you are monitoring, the more CPU cores you'll need. A very rough ballpark estimate would be 200Mbps per :ref:`suricata` worker or :ref:`zeek` worker. So if you have a fully saturated 1Gbps link and are running :ref:`suricata` for NIDS alerts and :ref:`zeek` for metadata, then you'll want at least 5 :ref:`suricata` workers and 5 :ref:`zeek` workers. This means you'll need at least 10 CPU cores for :ref:`suricata` and :ref:`zeek` with additional CPU cores for :ref:`stenographer` and/or other services. If you are monitoring a high amount of traffic and/or have a small number of CPU cores, you might consider using :ref:`suricata` for both alerts and metadata. This eliminates the need for :ref:`zeek` and allows for more efficient CPU usage. +:ref:`suricata` and :ref:`zeek` are very CPU intensive. The more traffic you are monitoring, the more CPU cores you'll need. A very rough ballpark estimate would be 200Mbps per :ref:`suricata` worker or :ref:`zeek` worker. So if you have a fully saturated 1Gbps link and are running :ref:`suricata` for :ref:`nids` alerts and :ref:`zeek` for metadata, then you'll want at least 5 :ref:`suricata` workers and 5 :ref:`zeek` workers. This means you'll need at least 10 CPU cores for :ref:`suricata` and :ref:`zeek` with additional CPU cores for :ref:`stenographer` and/or other services. If you are monitoring a high amount of traffic and/or have a small number of CPU cores, you might consider using :ref:`suricata` for both alerts and metadata. This eliminates the need for :ref:`zeek` and allows for more efficient CPU usage. RAM ~~~ diff --git a/host.rst b/host.rst index 12ff5e58..0728b4b6 100644 --- a/host.rst +++ b/host.rst @@ -3,7 +3,7 @@ Host Visibility =============== -Security Onion can consume many kinds of host logs. You can send logs to Security Onion via your choice of either :ref:`elastic-agent` or :ref:`syslog`: +More and more of our network traffic is encrypted these days and that's a good thing for privacy but it's somewhat of a blind spot for us as defenders. Host visibility can help fill in those blind spots. You can send host logs to Security Onion via your choice of either :ref:`elastic-agent` or :ref:`syslog`: - Choose :ref:`elastic-agent` for comprehensive telemetry if you can install an agent on the host. - Choose :ref:`syslog` if you can't install an agent but the device supports sending standard syslog. Examples include firewalls, switches, routers, and other network devices. diff --git a/hunt.rst b/hunt.rst index f134c404..45409260 100644 --- a/hunt.rst +++ b/hunt.rst @@ -5,7 +5,7 @@ Hunt :ref:`soc` includes a Hunt interface which is similar to our :ref:`dashboards` interface but is tuned more for threat hunting. -.. image:: images/52_hunt.png - :target: _images/52_hunt.png +.. image:: images/56_hunt.png + :target: _images/56_hunt.png The main difference between Hunt and :ref:`dashboards` is that Hunt's default queries are more focused than the overview queries in :ref:`dashboards`. A second difference is that most of the default :ref:`dashboards` queries display a separate table for each aggregated field, whereas many of the default queries in Hunt aggregate multiple fields in a single table which can be beneficial when hunting for more obscure activity. diff --git a/idh.rst b/idh.rst index 9b1b0ab4..17abde8c 100644 --- a/idh.rst +++ b/idh.rst @@ -23,7 +23,7 @@ IDH nodes are dedicated to just being IDH nodes and cannot run any other service Configuration ------------- -- Run Setup and select the ``DISTRIBUTED`` install option. +- Run Setup and select the ``DISTRIBUTED`` deployment option. - Select the ``Existing Deployment`` option. - Select the ``IDH`` option. - You can optionally prevent the IDH services from listening on the management interface. diff --git a/images/01_grub.png b/images/01_grub.png index 7d05e326..da19d319 100644 Binary files a/images/01_grub.png and b/images/01_grub.png differ diff --git a/images/04_setup_init.png b/images/04_setup_init.png index 0f76aab2..76cf4320 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 9b0382fb..c8a0f4f2 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 226f05ec..fb22fe02 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 2f951d75..ff31bc63 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 c1805d6d..07e65903 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 a8b503c9..95c19c12 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 d49672e5..25222937 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 1394b004..326a4863 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 86a6d92d..de1816d8 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 e353660c..ecfc241e 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 96300260..341ee535 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 298029c4..33cde136 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 5fee4aa1..4c6071fc 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 3af37c4c..bf623d75 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 dd8d536b..02d17adc 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 0e117516..24646446 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 6a2f12d9..f0ba5de3 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 1ae61b08..4422d4e4 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 3fb34534..215c9c11 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 44bc2d01..3f8d1596 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 9ff68d2e..6e05affe 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 new file mode 100644 index 00000000..56cc1f65 Binary files /dev/null and b/images/27_telemetry.png differ diff --git a/images/28_setup_summary.png b/images/28_setup_summary.png index 7289eff4..e802f684 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 0f41dd83..5f809902 100644 Binary files a/images/29_setup_finished.png and b/images/29_setup_finished.png differ diff --git a/images/36_so-import-pcap.png b/images/36_so-import-pcap.png deleted file mode 100644 index 64736374..00000000 Binary files a/images/36_so-import-pcap.png and /dev/null differ diff --git a/images/38_overview.png b/images/38_overview.png index 8800fe80..7f7ff384 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 7c184f6a..71d78499 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 760cf7c9..dd64e222 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 new file mode 100644 index 00000000..ddb52311 Binary files /dev/null and b/images/45_import.png differ diff --git a/images/50_alerts.png b/images/50_alerts.png index 54366279..7ba53d88 100644 Binary files a/images/50_alerts.png and b/images/50_alerts.png differ diff --git a/images/51_alerts_options.png b/images/51_alerts_options.png new file mode 100644 index 00000000..3b2b1914 Binary files /dev/null and b/images/51_alerts_options.png differ diff --git a/images/51_dashboards.png b/images/51_dashboards.png deleted file mode 100644 index 7db0215d..00000000 Binary files a/images/51_dashboards.png and /dev/null differ diff --git a/images/52_hunt.png b/images/52_hunt.png deleted file mode 100644 index 1f5d7548..00000000 Binary files a/images/52_hunt.png and /dev/null differ diff --git a/images/53_dashboards.png b/images/53_dashboards.png new file mode 100644 index 00000000..00922c4f Binary files /dev/null and b/images/53_dashboards.png differ diff --git a/images/53_pcap.png b/images/53_pcap.png deleted file mode 100644 index b8f38278..00000000 Binary files a/images/53_pcap.png and /dev/null differ diff --git a/images/54_dashboards_options.png b/images/54_dashboards_options.png new file mode 100644 index 00000000..cb8c5dca Binary files /dev/null and b/images/54_dashboards_options.png differ diff --git a/images/54_pcap_details.png b/images/54_pcap_details.png deleted file mode 100644 index 49f01edd..00000000 Binary files a/images/54_pcap_details.png and /dev/null differ diff --git a/images/55_cyberchef.png b/images/55_cyberchef.png deleted file mode 100644 index b6cbb0cc..00000000 Binary files a/images/55_cyberchef.png and /dev/null differ diff --git a/images/56_hunt.png b/images/56_hunt.png new file mode 100644 index 00000000..e94ad5c4 Binary files /dev/null and b/images/56_hunt.png differ diff --git a/images/56_jobs.png b/images/56_jobs.png deleted file mode 100644 index bb59fa47..00000000 Binary files a/images/56_jobs.png and /dev/null differ diff --git a/images/57_0_cases.png b/images/57_0_cases.png new file mode 100644 index 00000000..5bf24390 Binary files /dev/null and b/images/57_0_cases.png differ diff --git a/images/57_1_cases_options.png b/images/57_1_cases_options.png new file mode 100644 index 00000000..2b137093 Binary files /dev/null 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 new file mode 100644 index 00000000..c3eb386f Binary files /dev/null and b/images/57_2_cases_create.png differ diff --git a/images/57_detections.png b/images/57_detections.png new file mode 100644 index 00000000..fddb54a7 Binary files /dev/null and b/images/57_detections.png differ diff --git a/images/57_grid.png b/images/57_grid.png deleted file mode 100644 index 7c184f6a..00000000 Binary files a/images/57_grid.png and /dev/null differ diff --git a/images/58_detection_create.png b/images/58_detection_create.png new file mode 100644 index 00000000..a0aa0890 Binary files /dev/null and b/images/58_detection_create.png differ diff --git a/images/58_detections_options.png b/images/58_detections_options.png new file mode 100644 index 00000000..fc3c7a69 Binary files /dev/null and b/images/58_detections_options.png differ diff --git a/images/58_downloads.png b/images/58_downloads.png deleted file mode 100644 index de062793..00000000 Binary files a/images/58_downloads.png and /dev/null differ diff --git a/images/59_detection_create.png b/images/59_detection_create.png new file mode 100644 index 00000000..a0aa0890 Binary files /dev/null and b/images/59_detection_create.png differ diff --git a/images/59_users.png b/images/59_users.png deleted file mode 100644 index a68b3462..00000000 Binary files a/images/59_users.png and /dev/null differ diff --git a/images/60_detection_nids.png b/images/60_detection_nids.png new file mode 100644 index 00000000..296f6ca2 Binary files /dev/null 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 new file mode 100644 index 00000000..56ac2137 Binary files /dev/null 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 new file mode 100644 index 00000000..c1a3f0d7 Binary files /dev/null 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 new file mode 100644 index 00000000..962808bf Binary files /dev/null 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 new file mode 100644 index 00000000..e3c1a54c Binary files /dev/null and b/images/60_detection_nids_2_tuning_2_add.png differ diff --git a/images/60_detection_nids_3_history.png b/images/60_detection_nids_3_history.png new file mode 100644 index 00000000..4d8818f3 Binary files /dev/null and b/images/60_detection_nids_3_history.png differ diff --git a/images/60_detection_sigma.png b/images/60_detection_sigma.png new file mode 100644 index 00000000..8c3f925f Binary files /dev/null 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 new file mode 100644 index 00000000..e980ec30 Binary files /dev/null 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 new file mode 100644 index 00000000..39e910c7 Binary files /dev/null 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 new file mode 100644 index 00000000..50a048ca Binary files /dev/null and b/images/60_detection_yara.png differ diff --git a/images/60_gridmembers.png b/images/60_gridmembers.png deleted file mode 100644 index c82e065f..00000000 Binary files a/images/60_gridmembers.png and /dev/null differ diff --git a/images/61_config.png b/images/61_config.png deleted file mode 100644 index fc4a52af..00000000 Binary files a/images/61_config.png and /dev/null differ diff --git a/images/62_licensekey.png b/images/62_licensekey.png deleted file mode 100644 index 45f88985..00000000 Binary files a/images/62_licensekey.png and /dev/null differ diff --git a/images/62_pcap.png b/images/62_pcap.png new file mode 100644 index 00000000..5e64c2ea Binary files /dev/null and b/images/62_pcap.png differ diff --git a/images/63_usermenu.png b/images/63_usermenu.png deleted file mode 100644 index a0f034a3..00000000 Binary files a/images/63_usermenu.png and /dev/null differ diff --git a/images/65_pcap_details.png b/images/65_pcap_details.png new file mode 100644 index 00000000..4da2f29a Binary files /dev/null and b/images/65_pcap_details.png differ diff --git a/images/68_cyberchef.png b/images/68_cyberchef.png new file mode 100644 index 00000000..ac92a802 Binary files /dev/null and b/images/68_cyberchef.png differ diff --git a/images/72_jobs.png b/images/72_jobs.png new file mode 100644 index 00000000..ce3ebde7 Binary files /dev/null and b/images/72_jobs.png differ diff --git a/images/73_jobs_add.png b/images/73_jobs_add.png new file mode 100644 index 00000000..636f51fb Binary files /dev/null and b/images/73_jobs_add.png differ diff --git a/images/75_grid.png b/images/75_grid.png new file mode 100644 index 00000000..a9b21de4 Binary files /dev/null and b/images/75_grid.png differ diff --git a/images/76_grid_options.png b/images/76_grid_options.png new file mode 100644 index 00000000..15253ec5 Binary files /dev/null and b/images/76_grid_options.png differ diff --git a/images/78_downloads.png b/images/78_downloads.png new file mode 100644 index 00000000..b69e49d1 Binary files /dev/null and b/images/78_downloads.png differ diff --git a/images/81_users.png b/images/81_users.png new file mode 100644 index 00000000..8af9c3a9 Binary files /dev/null and b/images/81_users.png differ diff --git a/images/82_users_detail.png b/images/82_users_detail.png new file mode 100644 index 00000000..47bb77cd Binary files /dev/null and b/images/82_users_detail.png differ diff --git a/images/83_users_add.png b/images/83_users_add.png new file mode 100644 index 00000000..a3ebf513 Binary files /dev/null and b/images/83_users_add.png differ diff --git a/images/84_gridmembers.png b/images/84_gridmembers.png new file mode 100644 index 00000000..a6f7799f Binary files /dev/null and b/images/84_gridmembers.png differ diff --git a/images/87_config.png b/images/87_config.png new file mode 100644 index 00000000..30fb4dc4 Binary files /dev/null and b/images/87_config.png differ diff --git a/images/88_config_options.png b/images/88_config_options.png new file mode 100644 index 00000000..bdd8760a Binary files /dev/null and b/images/88_config_options.png differ diff --git a/images/91_licensekey.png b/images/91_licensekey.png new file mode 100644 index 00000000..238acd76 Binary files /dev/null and b/images/91_licensekey.png differ diff --git a/images/94_usermenu.png b/images/94_usermenu.png new file mode 100644 index 00000000..aff0e89c Binary files /dev/null and b/images/94_usermenu.png differ diff --git a/images/64_navigator.png b/images/97_navigator.png similarity index 100% rename from images/64_navigator.png rename to images/97_navigator.png diff --git a/images/99_top.png b/images/99_top.png deleted file mode 100644 index b9d90455..00000000 Binary files a/images/99_top.png and /dev/null differ diff --git a/images/alerts-detailed.png b/images/alerts-detailed.png deleted file mode 100644 index 11433cb6..00000000 Binary files a/images/alerts-detailed.png and /dev/null differ diff --git a/images/alerts-expanded.png b/images/alerts-expanded.png deleted file mode 100644 index ae2de3c4..00000000 Binary files a/images/alerts-expanded.png and /dev/null differ diff --git a/images/alerts-grouped.png b/images/alerts-grouped.png deleted file mode 100644 index c378d68f..00000000 Binary files a/images/alerts-grouped.png and /dev/null differ diff --git a/images/alerts-queries.png b/images/alerts-queries.png deleted file mode 100644 index 86bc8b25..00000000 Binary files a/images/alerts-queries.png and /dev/null differ diff --git a/images/alerts-query-bar.png b/images/alerts-query-bar.png deleted file mode 100644 index ce3574d5..00000000 Binary files a/images/alerts-query-bar.png and /dev/null differ diff --git a/images/analyzers-analyze-icon.png b/images/analyzers-analyze-icon.png deleted file mode 100644 index 9a6d3901..00000000 Binary files a/images/analyzers-analyze-icon.png and /dev/null differ diff --git a/images/analyzers-hash-results-summary.png b/images/analyzers-hash-results-summary.png deleted file mode 100644 index 592fd922..00000000 Binary files a/images/analyzers-hash-results-summary.png and /dev/null differ diff --git a/images/analyzers-job-details.png b/images/analyzers-job-details.png deleted file mode 100644 index 85de75e8..00000000 Binary files a/images/analyzers-job-details.png and /dev/null differ diff --git a/images/analyzers-job-summary.png b/images/analyzers-job-summary.png deleted file mode 100644 index 1ab7ecd3..00000000 Binary files a/images/analyzers-job-summary.png and /dev/null differ diff --git a/images/cases-add.png b/images/cases-add.png deleted file mode 100644 index de743186..00000000 Binary files a/images/cases-add.png and /dev/null differ diff --git a/images/cases-attachments.png b/images/cases-attachments.png deleted file mode 100644 index 5c2ac84b..00000000 Binary files a/images/cases-attachments.png and /dev/null differ diff --git a/images/cases-comments.png b/images/cases-comments.png deleted file mode 100644 index 23bc00f9..00000000 Binary files a/images/cases-comments.png and /dev/null differ diff --git a/images/cases-empty.png b/images/cases-empty.png deleted file mode 100644 index ed299731..00000000 Binary files a/images/cases-empty.png and /dev/null differ diff --git a/images/cases-escalate-aggregation.png b/images/cases-escalate-aggregation.png deleted file mode 100644 index 383862fe..00000000 Binary files a/images/cases-escalate-aggregation.png and /dev/null differ diff --git a/images/cases-escalate.png b/images/cases-escalate.png deleted file mode 100644 index db35b3a2..00000000 Binary files a/images/cases-escalate.png and /dev/null differ diff --git a/images/cases-events-drilldown.png b/images/cases-events-drilldown.png deleted file mode 100644 index c7e6b958..00000000 Binary files a/images/cases-events-drilldown.png and /dev/null differ diff --git a/images/cases-events.png b/images/cases-events.png deleted file mode 100644 index bc5fa0d9..00000000 Binary files a/images/cases-events.png and /dev/null differ diff --git a/images/cases-history.png b/images/cases-history.png deleted file mode 100644 index 7813bbbe..00000000 Binary files a/images/cases-history.png and /dev/null differ diff --git a/images/cases-observables.png b/images/cases-observables.png deleted file mode 100644 index 905c3770..00000000 Binary files a/images/cases-observables.png and /dev/null differ diff --git a/images/cases.png b/images/cases.png deleted file mode 100644 index 678b899a..00000000 Binary files a/images/cases.png and /dev/null differ diff --git a/images/config-item-backup.png b/images/config-item-backup.png index 35ee0eb5..96988b3a 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 c7074640..3f35700d 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 new file mode 100644 index 00000000..33f7e9cb Binary files /dev/null and b/images/config-item-elastalert-alerter.png differ diff --git a/images/config-item-elastalert.png b/images/config-item-elastalert.png index b127dcbc..70d97e04 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 24fe0714..b0862958 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 17dec8b3..dd0d3ed9 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 e919f3fe..914cb3f2 100644 Binary files a/images/config-item-firewall.png and b/images/config-item-firewall.png differ diff --git a/images/config-item-global.png b/images/config-item-global.png index 0466e97c..5f698722 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 9ed64315..9e26d39b 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 c072ebea..4c968462 100644 Binary files a/images/config-item-idh.png and b/images/config-item-idh.png differ diff --git a/images/config-item-idstools.png b/images/config-item-idstools.png index 452af6af..4836acd7 100644 Binary files a/images/config-item-idstools.png and b/images/config-item-idstools.png differ diff --git a/images/config-item-influxdb.png b/images/config-item-influxdb.png index eaa8a3e8..9bae6171 100644 Binary files a/images/config-item-influxdb.png and b/images/config-item-influxdb.png differ diff --git a/images/config-item-kibana.png b/images/config-item-kibana.png index 72a4a6fa..4c0599fa 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 e118b82c..78d08a8d 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 10dac219..c75b6c7b 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 ef19f69c..bbac1d8a 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 ae1207b4..c96a21b8 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 99d2e746..76c87656 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 51c3c677..3185fc19 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 2340fa07..a5434d84 100644 Binary files a/images/config-item-pcap.png and b/images/config-item-pcap.png differ diff --git a/images/config-item-playbook.png b/images/config-item-playbook.png deleted file mode 100644 index 3d727df7..00000000 Binary files a/images/config-item-playbook.png and /dev/null differ diff --git a/images/config-item-redis.png b/images/config-item-redis.png index 1dc4ed70..08bd1578 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 13567471..a76ae2ef 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 8bf46110..adc1427f 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 new file mode 100644 index 00000000..81bab82d Binary files /dev/null and b/images/config-item-soc-additionalAlerters.png differ diff --git a/images/config-item-soc.png b/images/config-item-soc.png index 0ac6fd30..751dbdb1 100644 Binary files a/images/config-item-soc.png and b/images/config-item-soc.png differ diff --git a/images/config-item-soctopus.png b/images/config-item-soctopus.png deleted file mode 100644 index 1fcda4f5..00000000 Binary files a/images/config-item-soctopus.png and /dev/null differ diff --git a/images/config-item-strelka.png b/images/config-item-strelka.png index 359ce25e..ebdbeee4 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 c1ef9ac6..42137dca 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 2ba53bbb..4c50e1f4 100644 Binary files a/images/config-item-telegraf.png and b/images/config-item-telegraf.png differ diff --git a/images/config-item-zeek.png b/images/config-item-zeek.png index 6f41305d..72764948 100644 Binary files a/images/config-item-zeek.png and b/images/config-item-zeek.png differ diff --git a/images/dashboards-basic-metrics.png b/images/dashboards-basic-metrics.png deleted file mode 100644 index 6890bc46..00000000 Binary files a/images/dashboards-basic-metrics.png and /dev/null differ diff --git a/images/dashboards-group-metrics-sankey.png b/images/dashboards-group-metrics-sankey.png deleted file mode 100644 index b11b8515..00000000 Binary files a/images/dashboards-group-metrics-sankey.png and /dev/null differ diff --git a/images/dashboards-group-metrics-table.png b/images/dashboards-group-metrics-table.png deleted file mode 100644 index b35032fa..00000000 Binary files a/images/dashboards-group-metrics-table.png and /dev/null differ diff --git a/images/dashboards-group-metrics.png b/images/dashboards-group-metrics.png deleted file mode 100644 index cf14d6aa..00000000 Binary files a/images/dashboards-group-metrics.png and /dev/null differ diff --git a/images/dashboards-statistics.png b/images/dashboards-statistics.png deleted file mode 100644 index 9b5a72d3..00000000 Binary files a/images/dashboards-statistics.png and /dev/null differ diff --git a/images/desktop.png b/images/desktop.png deleted file mode 100644 index 5b43d8cb..00000000 Binary files a/images/desktop.png and /dev/null differ diff --git a/images/hunt-expanded.png b/images/hunt-expanded.png deleted file mode 100644 index cf241705..00000000 Binary files a/images/hunt-expanded.png and /dev/null differ diff --git a/images/jupyter-python.png b/images/jupyter-python.png deleted file mode 100644 index 4035715a..00000000 Binary files a/images/jupyter-python.png and /dev/null differ diff --git a/images/jupyter-targeted.png b/images/jupyter-targeted.png deleted file mode 100644 index 66f08071..00000000 Binary files a/images/jupyter-targeted.png and /dev/null differ diff --git a/images/jupyter-user.png b/images/jupyter-user.png deleted file mode 100644 index 40e8391f..00000000 Binary files a/images/jupyter-user.png and /dev/null differ diff --git a/images/jupyter-warning.png b/images/jupyter-warning.png deleted file mode 100644 index 61b3fee4..00000000 Binary files a/images/jupyter-warning.png and /dev/null differ diff --git a/images/password.png b/images/password.png deleted file mode 100644 index 3e362d95..00000000 Binary files a/images/password.png and /dev/null differ diff --git a/images/pcap-add-job.png b/images/pcap-add-job.png deleted file mode 100644 index e9bc4c37..00000000 Binary files a/images/pcap-add-job.png and /dev/null differ diff --git a/images/pcap-cyberchef.png b/images/pcap-cyberchef.png deleted file mode 100644 index 73f05c74..00000000 Binary files a/images/pcap-cyberchef.png and /dev/null differ diff --git a/images/pcap-download.png b/images/pcap-download.png deleted file mode 100644 index 9a17c96c..00000000 Binary files a/images/pcap-download.png and /dev/null differ diff --git a/images/pcap-select-pivot.png b/images/pcap-select-pivot.png deleted file mode 100644 index ada15e1b..00000000 Binary files a/images/pcap-select-pivot.png and /dev/null differ diff --git a/images/soc-events-table.png b/images/soc-events-table.png deleted file mode 100644 index a84ea8af..00000000 Binary files a/images/soc-events-table.png and /dev/null differ diff --git a/images/soc-logins.png b/images/soc-logins.png deleted file mode 100644 index e18f007e..00000000 Binary files a/images/soc-logins.png and /dev/null differ diff --git a/images/users.png b/images/users.png deleted file mode 100644 index b07d7e02..00000000 Binary files a/images/users.png and /dev/null differ diff --git a/index.rst b/index.rst index c30ca9d2..e96e9e3f 100644 --- a/index.rst +++ b/index.rst @@ -17,7 +17,10 @@ Security Onion Documentation soc desktop network + additional-network host + third-party-integrations + rules logs updating accounts @@ -27,6 +30,7 @@ Security Onion Documentation tricks utilities help + pro security release-notes appendix diff --git a/ingest.rst b/ingest.rst index 57a56fd2..921cae45 100644 --- a/ingest.rst +++ b/ingest.rst @@ -7,60 +7,66 @@ Here's an overview of how logs are ingested in various deployment types. Import ------ + | Core Pipeline: Elastic Agent [IMPORT Node] --> Elasticsearch Ingest [IMPORT Node] | Logs: Zeek, Suricata Eval ---- + | Core Pipeline: Elastic Agent [EVAL Node] --> Elasticsearch Ingest [EVAL Node] -| Logs: Zeek, Suricata, Osquery/Fleet -| -| Osquery Shipper Pipeline: Osquery [Endpoint] --> Fleet [EVAL Node] --> Elasticsearch Ingest via Core Pipeline -| Logs: WEL, Osquery, syslog +| Logs: Zeek, Suricata Standalone ---------- + | Core Pipeline: Elastic Agent [SA Node] --> Logstash [SA Node] --> Redis [SA Node] <--> Logstash [SA Node] --> Elasticsearch Ingest [SA Node] -| Logs: Zeek, Suricata, Osquery/Fleet, syslog +| Logs: Zeek, Suricata, syslog | -| WinLogbeat: Winlogbeat [Windows Endpoint]--> Logstash [SA Node] --> Redis [SA Node] <--> Logstash [SA Node] --> Elasticsearch Ingest [SA Node] +| Elastic Agent: Elastic Agent [Windows Endpoint]--> Logstash [SA Node] --> Redis [SA Node] <--> Logstash [SA Node] --> Elasticsearch Ingest [SA Node] | Logs: WEL, Sysmon Fleet Standalone ---------------- + | Pipeline: Elastic Agent [Fleet Node] --> Logstash [M | MS] --> Elasticsearch Ingest [S | MS] -| Logs: Osquery +| Logs: Elastic Agent Manager (separate search nodes) ------------------------------- + | Core Pipeline: Elastic Agent [Fleet | Forward] --> Logstash [Manager] --> Redis [Manager] -| Logs: Zeek, Suricata, Osquery/Fleet, syslog +| Logs: Zeek, Suricata, syslog | -| WinLogbeat: Winlogbeat [Windows Endpoint]--> Logstash [Manager] --> Redis [Manager] -| Logs: WEL +| Elastic Agent: Elastic Agent [Windows Endpoint]--> Logstash [Manager] --> Redis [Manager] +| Logs: WEL, Sysmon Manager Search -------------- + | Core Pipeline: Elastic Agent [Fleet | Forward] --> Logstash [MS] --> Redis [MS] <--> Logstash [MS] --> Elasticsearch Ingest [MS] -| Logs: Zeek, Suricata, Osquery/Fleet, syslog +| Logs: Zeek, Suricata, syslog | | Pipeline: Elastic Agent [MS] --> Logstash [MS] --> Elasticsearch Ingest [MS] -| Logs: Local Osquery/Fleet +| Logs: Local Elastic Agent | -| WinLogbeat: Winlogbeat [Windows Endpoint]--> Logstash [MS] --> Elasticsearch Ingest [MS] -| Logs: WEL +| Elastic Agent: Elastic Agent [Windows Endpoint]--> Logstash [MS] --> Elasticsearch Ingest [MS] +| Logs: WEL, Sysmon Heavy ----- + | Pipeline: Elastic Agent [Heavy Node] --> Logstash [Heavy] --> Redis [Heavy] <--> Logstash [Heavy] --> Elasticsearch Ingest [Heavy] -| Logs: Zeek, Suricata, Osquery/Fleet, syslog +| Logs: Zeek, Suricata, syslog Search ------ + | Pipeline: Redis [Manager] --> Logstash [Search] --> Elasticsearch Ingest [Search] -| Logs: Zeek, Suricata, Osquery/Fleet, syslog +| Logs: Zeek, Suricata, syslog Forward ------- + | Pipeline: Elastic Agent [Forward] --> Logstash [M | MS] --> Elasticsearch Ingest [S | MS] | Logs: Zeek, Suricata, syslog diff --git a/introduction.rst b/introduction.rst index 4d5495cc..b8822c17 100644 --- a/introduction.rst +++ b/introduction.rst @@ -5,7 +5,7 @@ Introduction Security Onion is a free and open platform built by defenders for defenders. It includes :ref:`network visibility`, :ref:`host visibility`, :ref:`intrusion detection honeypots`, :ref:`log management`, and :ref:`case management`. -For network visibility, we offer signature based detection via :ref:`suricata`, rich protocol metadata and file extraction using your choice of either :ref:`zeek` or :ref:`suricata`, full packet capture, and file analysis. For host visibility, we offer the :ref:`elastic-agent` which provides data collection, live queries via :ref:`osquery`, and centralized management using :ref:`elastic-fleet`. :ref:`Intrusion detection honeypots` based on OpenCanary can be added to your deployment for even more enterprise visibility. All of these logs flow into :ref:`elasticsearch` and we've built our own user interfaces for :ref:`alerts`, :ref:`dashboards`, :ref:`threat hunting`, :ref:`case management`, and :ref:`grid management`. +For network visibility, we offer signature based detection via :ref:`suricata`, rich protocol metadata and file extraction using either :ref:`zeek` or :ref:`suricata`, full packet capture using either :ref:`stenographer` or :ref:`suricata`, and file analysis. For host visibility, we offer the :ref:`elastic-agent` which provides data collection, live queries via :ref:`osquery`, and centralized management using :ref:`elastic-fleet`. :ref:`Intrusion detection honeypots` based on OpenCanary can be added to your deployment for even more enterprise visibility. All of these logs flow into :ref:`elasticsearch` and we've built our own user interfaces for :ref:`alerts`, :ref:`dashboards`, :ref:`threat hunting`, :ref:`case management`, and :ref:`grid management`. In the diagram below, we see Security Onion in a traditional enterprise network with a firewall, workstations, and servers. You can use Security Onion to monitor north/south traffic to detect an adversary entering an environment, establishing command-and-control (C2), or perhaps data exfiltration. You'll probably also want to monitor east/west traffic to detect lateral movement. As more and more of our network traffic becomes encrypted, it's important to fill in those blind spots with additional visibility in the form of endpoint telemetry. Security Onion can consume logs from your servers and workstations so that you can then hunt across all of your network and host logs at the same time. @@ -20,7 +20,7 @@ From a network visibility standpoint, Security Onion seamlessly weaves together Intrusion Detection ~~~~~~~~~~~~~~~~~~~ -Security Onion generates NIDS (Network Intrusion Detection System) alerts by monitoring your network traffic and looking for specific fingerprints and identifiers that match known malicious, anomalous, or otherwise suspicious traffic. This is signature-based detection so you might say that it's similar to antivirus signatures for the network, but it's a bit deeper and more flexible than that. NIDS alerts are generated by :ref:`suricata`. +Security Onion generates :ref:`nids` (Network Intrusion Detection System) alerts by monitoring your network traffic and looking for specific fingerprints and identifiers that match known malicious, anomalous, or otherwise suspicious traffic. This is signature-based detection so you might say that it's similar to antivirus signatures for the network, but it's a bit deeper and more flexible than that. :ref:`nids` alerts are generated by :ref:`suricata`. Network Metadata ~~~~~~~~~~~~~~~~ @@ -30,7 +30,7 @@ Unlike signature-based intrusion detection that looks for specific needles in th Full Packet Capture ~~~~~~~~~~~~~~~~~~~ -Full packet capture is like a video camera for your network, but better because not only can it tell us who came and went, but also exactly where they went and what they brought or took with them (exploit payloads, phishing emails, file exfiltration). It’s a crime scene recorder that can tell us a lot about the victim and the white chalk outline of a compromised host on the ground. There is certainly valuable evidence to be found on the victim’s body, but evidence at the host can be destroyed or manipulated; the camera doesn't lie, is hard to deceive, and can capture a bullet in transit. Full packet capture is recorded by :ref:`stenographer`. +Full packet capture is like a video camera for your network, but better because not only can it tell us who came and went, but also exactly where they went and what they brought or took with them (exploit payloads, phishing emails, file exfiltration). It’s a crime scene recorder that can tell us a lot about the victim and the white chalk outline of a compromised host on the ground. There is certainly valuable evidence to be found on the victim’s body, but evidence at the host can be destroyed or manipulated; the camera doesn't lie, is hard to deceive, and can capture a bullet in transit. Full packet capture can be written to disk using either :ref:`stenographer` or :ref:`suricata`. File Analysis ~~~~~~~~~~~~~ @@ -57,38 +57,43 @@ With all of the data sources mentioned above, there is an incredible amount of d Security Onion Console (SOC) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:ref:`soc` is the first thing you see when you log into Security Onion. It includes our :ref:`alerts` interface which allows you to see all of your NIDS alerts from :ref:`suricata`. +:ref:`soc` is the first thing you see when you log into Security Onion. It includes our :ref:`alerts` interface which allows you to see all of your :ref:`nids` alerts from :ref:`suricata`. .. image:: images/50_alerts.png :target: _images/50_alerts.png -:ref:`soc` also includes our :ref:`dashboards` interface which gives you a nice overview of not only your NIDS alerts but also network metadata logs from :ref:`zeek` or :ref:`suricata` and any other logs that you may be collecting. +:ref:`soc` also includes our :ref:`dashboards` interface which gives you a nice overview of not only your :ref:`nids` alerts but also network metadata logs from :ref:`zeek` or :ref:`suricata` and any other logs that you may be collecting. -.. image:: images/51_dashboards.png - :target: _images/51_dashboards.png +.. image:: images/53_dashboards.png + :target: _images/53_dashboards.png :ref:`hunt` is similar to :ref:`dashboards` but its default queries are more focused on threat hunting. -.. image:: images/52_hunt.png - :target: _images/52_hunt.png +.. image:: images/56_hunt.png + :target: _images/56_hunt.png :ref:`cases` is the case management interface. As you are working in :ref:`alerts`, :ref:`dashboards`, or :ref:`hunt`, you may find alerts or logs that are interesting enough to send to :ref:`cases` and create a case. Other analysts can collaborate with you as you work to close that case. -.. image:: images/cases.png - :target: _images/cases.png +.. image:: images/57_0_cases.png + :target: _images/57_0_cases.png :ref:`soc` also includes an interface for full packet capture (:ref:`pcap`) retrieval. -.. image:: images/53_pcap.png - :target: _images/53_pcap.png +.. image:: images/62_pcap.png + :target: _images/62_pcap.png + +Starting in Security Onion 2.4.70, :ref:`soc` includes :ref:`detections` which makes it quick and easy to tune your :ref:`nids`, :ref:`sigma`, and :ref:`yara` rules. + +.. image:: images/57_detections.png + :target: _images/57_detections.png CyberChef ~~~~~~~~~ :ref:`cyberchef` allows you to decode, decompress, and analyze artifacts. :ref:`alerts`, :ref:`dashboards`, :ref:`hunt`, and :ref:`pcap` all allow you to quickly and easily send data to :ref:`cyberchef` for further analysis. -.. image:: images/55_cyberchef.png - :target: _images/55_cyberchef.png +.. image:: images/68_cyberchef.png + :target: _images/68_cyberchef.png Playbook ~~~~~~~~ @@ -101,6 +106,7 @@ Workflow All of these analysis tools work together to provide efficient and comprehensive analysis capabilities. For example, here's one potential workflow: - Go to the :ref:`alerts` page and review any unacknowledged alerts. + - Use :ref:`detections` to tune your rules to increase the signal-to-noise ratio. - Review :ref:`dashboards` for anything that looks suspicious. - Once you've found something that you want to investigate, you might want to pivot to :ref:`hunt` to expand your search and look for additional logs relating to the source and destination IP addresses. - If any of those alerts or logs look interesting, you might want to pivot to :ref:`pcap` to review the full packet capture for the entire stream. diff --git a/jupyter.rst b/jupyter.rst index 5431a9c4..a4d21c51 100644 --- a/jupyter.rst +++ b/jupyter.rst @@ -11,10 +11,7 @@ Security Onion Setup **Create Jupyter User** -As a best practice, you'll want to create a dedicated Jupyter notebook user with just read-only access to the data inside of :ref:`elasticsearch`. In :ref:`kibana`, navigate to Stack Management -> Users and create the user with appropriate permissions: - -.. image:: images/jupyter-user.png - :target: _images/jupyter-user.png +As a best practice, you'll want to create a dedicated Jupyter notebook user with just read-only access to the data inside of :ref:`elasticsearch`. In :ref:`kibana`, navigate to Stack Management -> Users and create the user with appropriate permissions. **Security Onion Firewall** @@ -76,10 +73,7 @@ In the next cell, we'll specify the :ref:`elasticsearch` instance address and po Again, we'll execute the code within the cell, by pressing **Shift+ENTER**. -We may see a warning like the following due to the fact that we are not performing verification for certificates: - -.. image:: images/jupyter-warning.png - :target: _images/jupyter-warning.png +We may see a certificate warning due to the fact that we are not performing verification for certificates. For convenience during our testing, we can disable the warning in future runs, by pasting the following the next cell and executing it with **Shift+ENTER**: @@ -105,10 +99,7 @@ Finally, we'll submit our query in the next cell using the following: df = pd.DataFrame((d.to_dict() for d in s.scan())) df -The above code simply takes the results and converts them to a Python dict: - -.. image:: images/jupyter-python.png - :target: _images/jupyter-python.png +The above code simply takes the results and converts them to a Python dict. We can select a few fields, and modify the column values if we like: @@ -120,9 +111,6 @@ We can select a few fields, and modify the column values if we like: df.columns=['Dataset','Executable', 'Target'] df -Then we end up with something a little bit more targeted (you may need to adjust ``pd.options.display.max_colwidth`` for it to display appropriately) : - -.. image:: images/jupyter-targeted.png - :target: _images/jupyter-targeted.png +Then we end up with something a little bit more targeted (you may need to adjust ``pd.options.display.max_colwidth`` for it to display appropriately). Obviously, there is much more we can do with this data other than just running the above example code. Happy hunting! diff --git a/kibana.rst b/kibana.rst index bf3f76f3..8c109c90 100644 --- a/kibana.rst +++ b/kibana.rst @@ -36,7 +36,7 @@ If you try to modify a default Kibana dashboard, your change will get overwritte Search Results -------------- -In Kibana, search results are limited to the first ``100`` results for a particular query. If you don't feel like this is adequate after narrowing your search, you can adjust the value for ``discover:sampleSize`` in Kibana by navigating to ``Stack Management`` -> ``Advanced Settings`` and changing the value. It may be best to change this value incrementally to see how it affects performance for your deployment. +In Kibana, search results are limited to the first ``100`` results for a particular query. If you don't feel like this is adequate after narrowing your search, you can adjust the value for ``discover:sampleSize`` in Kibana by navigating to ``Stack Management`` --> ``Advanced Settings`` and changing the value. It may be best to change this value incrementally to see how it affects performance for your deployment. Timestamps ---------- @@ -83,7 +83,7 @@ If you then are able to login to Kibana but your dashboards don't look right, yo Features -------- -You can enable or disable specific features by clicking the main menu in the upper left corner, then click ``Stack Management``, then click ``Spaces``, then click ``Default``. For more information, please see https://www.elastic.co/guide/en/kibana/master/xpack-spaces.html#spaces-control-feature-visibility. +You can enable or disable specific features by clicking the main menu in the upper left corner, then click ``Stack Management``, then click ``Spaces``, then click ``Default``. For more information, please see https://www.elastic.co/guide/en/kibana/current/xpack-spaces.html#spaces-control-feature-visibility. More Information ---------------- diff --git a/listing-accounts.rst b/listing-accounts.rst index 659c3ddc..62859017 100644 --- a/listing-accounts.rst +++ b/listing-accounts.rst @@ -23,7 +23,12 @@ SOC You can get a list of users in :ref:`soc` by navigating to the :ref:`administration` interface and then clicking ``Users``: -.. image:: images/users.png - :target: _images/users.png +.. image:: images/81_users.png + :target: _images/81_users.png + +To see detail on an individual user account, click the button on the left side of the row to expand the user account: + +.. image:: images/82_users_detail.png + :target: _images/82_users_detail.png For more information about the Users page, please see the :ref:`administration` section. diff --git a/logstash.rst b/logstash.rst index 997fae8f..b47a7c4b 100644 --- a/logstash.rst +++ b/logstash.rst @@ -74,7 +74,7 @@ For example, to forward all :ref:`zeek` events from the ``dns`` dataset, we coul Also keep in mind that when forwarding logs from the manager, some fields may not be set as expected since the events have not yet been processed by the Ingest Node configuration. -In :ref:`soc`, navigate to :ref:`administration` -> Configuration. At the top of the page, click the ``Options`` menu and then enable the ``Show all configurable settings, including advanced settings.`` option. Then navigate to logstash -> defined_pipelines -> manager and append the name of your newly created file to the list of config files used for the ``manager`` pipeline: +In :ref:`soc`, navigate to :ref:`administration` --> Configuration. At the top of the page, click the ``Options`` menu and then enable the ``Show all configurable settings, including advanced settings.`` option. Then navigate to logstash --> defined_pipelines --> manager and append the name of your newly created file to the list of config files used for the ``manager`` pipeline: :: diff --git a/luks.rst b/luks.rst new file mode 100644 index 00000000..40b26860 --- /dev/null +++ b/luks.rst @@ -0,0 +1,27 @@ +.. _luks: + +LUKS +==== + +LUKS stands for Linux Unified Key Setup and you can read more about it at https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup. + +LUKS disk encryption is a feature that requires the use of the Security Onion Pro license. + +.. note:: + + This is an enterprise-level feature of Security Onion. Contact Security Onion Solutions, LLC via our website at https://securityonionsolutions.com for more information about purchasing a Security Onion Pro license to enable this feature. + +Enabling LUKS During the ISO Install +------------------------------------ + +The recommended way to use LUKS with Security Onion is to install via our Security Onion ISO image. At the ISO boot menu, you'll need to modify the boot command. This can be done using the ``e`` key in UEFI boot mode or the ``Tab`` key in BIOS boot mode before it automatically boots. Then append ``luks=1`` (and possibly other options like :ref:`fips` and :ref:`stig`) to the boot parameters and continue the boot process. + +LUKS Install without a TPM +-------------------------- + +During the initial install of the ISO, the user will be prompted to enter a password to use to encrypt the LUKS partitions. If multiple drives are detected then the user has the option of just encrypting /nsm. Please note that this password will be required at each boot. + +LUKS Install Options with a TPM +------------------------------- + +If a TPM module is installed in the system you will have the option of storing the key in the TPM to unlock the drives automatically at boot. This process uses clevis in order to manage this process. diff --git a/mfa.rst b/mfa.rst index 0c93f16a..a482805f 100644 --- a/mfa.rst +++ b/mfa.rst @@ -3,7 +3,7 @@ MFA === -You can enable Multi-Factor Authentication (MFA) to further protect your account. This can be enabled in :ref:`soc` by clicking the user icon in the upper right corner, clicking ``Settings``, and then going to the ``Security`` tab. +You can enable Multi-Factor Authentication (MFA) to further protect your account. This can be enabled in :ref:`soc` by clicking the user icon in the upper-right corner, clicking ``Settings``, and then going to the ``Security`` tab. TOTP ---- diff --git a/netflow.rst b/netflow.rst new file mode 100644 index 00000000..eace6c0d --- /dev/null +++ b/netflow.rst @@ -0,0 +1,42 @@ +.. _netflow: + +NetFlow +======= + +You may have devices on your network such as firewalls, routers, and switches that are capable of exporting NetFlow records. If you would like to collect these NetFlow records, add the Elastic integration for ``NetFlow Records`` and then allow the Netflow traffic through the firewall. + +Add the NetFlow Records integration +--------------------------------------- + +First, add the Elastic integration for ``NetFlow Records``. + +.. note:: + + For more information about the ``NetFlow Records`` integration, please see https://docs.elastic.co/en/integrations/netflow. + +#. Go to :ref:`elastic-fleet`, click the ``Agent policies`` tab, and then click the desired policy (for example ``so-grid-nodes_general``). +#. Click the ``Add integration`` button. +#. Search for ``netflow`` and then click on the ``NetFlow Records`` integration. +#. The Elastic Integration page will show an overview of the NetFlow Integration. Review all information on the page and then click the ``Add NetFlow Records`` button. +#. On the ``Add NetFlow Records integration`` screen, go to the ``UDP host to listen on`` field and change ``localhost`` to ``0.0.0.0``. Verify the ``UDP port to listen on`` field matches what your NetFlow exporter will be sending to. Click the ``Save and continue`` button and then click ``Save and deploy changes``. + +Allow NetFlow traffic through firewall +-------------------------------------- + +Next, allow the traffic from the NetFlow exporter through the firewall to the NetFlow listener port. + +.. note:: + + The following instructions assume that this is the first firewall change you have made and therefore refer to ``customhostgroup0`` and ``customportgroup0``. If those have already been used, you can select the next available hostgroup and portgroup. + +#. Navigate to :ref:`administration` --> Configuration. +#. At the top of the page, click the ``Options`` menu and then enable the ``Show all configurable settings, including advanced settings.`` option. +#. On the left side, go to ``firewall``, select ``hostgroups``, and click the ``customhostgroup0`` group. On the right side, enter the IP address of the NetFlow exporter and click the checkmark to save. +#. On the left side, go to ``firewall``, select ``portgroups``, select the ``customportgroup0`` group, and then click ``udp``. On the right side, enter your desired NetFlow listener port (2055 by default) and click the checkmark to save. +#. On the left side, go to ``firewall``, select ``role``, and then select the node type that will receive the NetFlow records. Then drill into ``chain`` --> ``INPUT`` --> ``hostgroups`` --> ``customhostgroup0`` --> ``portgroups``. On the right side, enter ``customportgroup0`` and click the checkmark to save. +#. If you would like to apply the rules immediately, click the ``SYNCHRONIZE GRID`` button under the ``Options`` menu at the top of the page. + +NetFlow dashboard +----------------- + +Once all configuration is complete, you should be able to go to :ref:`dashboards` and select the ``NetFlow`` dashboard to see your NetFlow records. diff --git a/network-installation.rst b/network-installation.rst index 2aed12b2..2e2ba582 100644 --- a/network-installation.rst +++ b/network-installation.rst @@ -3,7 +3,11 @@ Network Installation ==================== -For most use cases, we HIGHLY recommend using our official Security Onion images as shown in the :ref:`installation` section. Our official images are the only fully supported installation method and you should use them if any of the following apply to you: +.. warning:: + + Network installations are not supported and should only be used as a last resort in case there is some reason you can't use our official Security Onion ISO image as shown in the :ref:`installation` section. + +Our official Security Onion ISO image is the only fully supported installation method and you should use it if any of the following apply to you: - You are deploying in an enterprise environment. - You are deploying in an airgap environment. @@ -11,7 +15,7 @@ For most use cases, we HIGHLY recommend using our official Security Onion images - You want the quickest and easiest installation with the fewest issues. - You need full support. -If NONE of the above apply to you, you may be able to install one of the following operating systems and then perform a network installation: +If NONE of the above apply to you, you MAY be able to install one of the following operating systems and then perform a network installation: - Oracle Linux 9 - Rocky Linux 9 diff --git a/network.rst b/network.rst index 4b3dde9f..81957303 100644 --- a/network.rst +++ b/network.rst @@ -3,7 +3,7 @@ Network Visibility ================== -When you log into :ref:`soc`, you may see alerts from :ref:`suricata` or :ref:`idh`, protocol metadata logs from :ref:`zeek` or :ref:`suricata`, file analysis logs from :ref:`strelka`, or full packet capture from :ref:`stenographer`. How is that data generated and stored? This section covers the various processes that Security Onion uses to analyze and log network traffic. +When you log into :ref:`soc`, you may see alerts from :ref:`suricata` or :ref:`idh`, protocol metadata logs from :ref:`zeek` or :ref:`suricata`, file analysis logs from :ref:`strelka`, or full packet capture from :ref:`stenographer` or :ref:`suricata`. How is that data generated and stored? This section covers the various processes that Security Onion uses to analyze and log network traffic. .. image:: images/diagrams/sniffing.png :target: _images/sniffing.png diff --git a/nids.rst b/nids.rst new file mode 100644 index 00000000..6a945094 --- /dev/null +++ b/nids.rst @@ -0,0 +1,128 @@ +.. _nids: + +NIDS +==== + +NIDS (Network Intrusion Detection System) rules are loaded into :ref:`suricata` to monitor network traffic for suspicious or noteworthy activity. Active NIDS rules generate alerts that can be found in :ref:`alerts`. + +Managing Existing NIDS Rules +---------------------------- + +You can manage existing NIDS rules using :ref:`detections`. There are two ways to do so: + +- From the main :ref:`detections` interface, you can search for the desired detection and click the binoculars icon. +- From the :ref:`alerts` interface, you can click an alert and then click the ``Tune Detection`` menu item. + +Once you've used one of these methods to reach the detection detail page, you can check the Status field in the upper-right corner and use the slider to enable or disable the detection. + +.. image:: images/60_detection_nids.png + :target: _images/60_detection_nids.png + +To tune the detection: + +- click the TUNING tab +- click the blue + button +- select the type of tuning (Modify, Suppress, or Threshold) +- fill out the requested values +- click the ``CREATE`` button + +.. image:: images/60_detection_nids_2_tuning_2_add.png + :target: _images/60_detection_nids_2_tuning_2_add.png + +Adding New NIDS Rules +--------------------- + +To add a new NIDS rule, go to the main :ref:`detections` page and click the blue + button between Options and the query bar. A form will appear where you will: + +- click the Language drop-down and select ``Suricata`` +- optionally specify a license +- add the signature +- click the ``CREATE`` button and the detection should deploy to your grid at the next 15-minute cycle + +.. image:: images/58_detection_create.png + :target: _images/58_detection_create.png + +Update Frequency +---------------- + +By default, Security Onion checks for new NIDS rules every 24 hours. You can change this value as follows: + +- Navigate to :ref:`administration` --> Configuration. +- At the top of the page, click the ``Options`` menu and then enable the ``Show all configurable settings, including advanced settings.`` option. +- Navigate to soc --> config --> server --> modules --> suricataengine --> communityRulesImportFrequencySeconds. + +Changing to a Different Ruleset +------------------------------- + +Security Onion includes the Emerging Threats Open (ETOPEN) ruleset by default. If you would like to change to a different ruleset, you can do this via :ref:`administration` --> Configuration --> idstools --> config --> ruleset. + +.. image:: images/config-item-idstools.png + :target: _images/config-item-idstools.png + +Security Onion offers the following choices for NIDS rulesets. The main options are ETOPEN (free) and ETPRO (commercial) but advanced users may choose a Snort ruleset if they understand the caveats as shown below. + +ETOPEN +~~~~~~ + +- default ruleset included in Security Onion +- optimized for :ref:`suricata` +- **free** + +| For more information, see: +| https://rules.emergingthreats.net/open/ + +ETPRO +~~~~~ + +- includes ETOPEN and additional rules +- optimized for :ref:`suricata` +- rules retrievable as released +- license fee per sensor (you are responsible for purchasing enough licenses for your entire deployment) + +| For more information, see: +| https://www.proofpoint.com/us/threat-insight/et-pro-ruleset + +Snort Community +~~~~~~~~~~~~~~~ + +- NOT optimized for :ref:`suricata` +- community-contributed rules +- **free** + +| For more information, see: +| https://www.snort.org/downloads/#rule-downloads +| https://www.snort.org/faq/what-are-community-rules + +Snort Registered +~~~~~~~~~~~~~~~~ + +- NOT optimized for :ref:`suricata` +- Snort SO (Shared Object) rules do NOT work with :ref:`suricata` +- same rules as Snort Subscriber ruleset, except rules only retrievable after 30 days past release +- **free** + +Since Shared Object rules won't work with :ref:`suricata`, you may want to disable them using a regex like ``'re:soid [0-9]+'``. + +| For more information, see: +| https://www.snort.org/downloads/#rule-downloads +| https://snort.org/documents/registered-vs-subscriber + +Snort Subscriber (Talos) +~~~~~~~~~~~~~~~~~~~~~~~~ + +- NOT optimized for :ref:`suricata` +- Snort SO (Shared Object) rules do NOT work with :ref:`suricata` +- rules retrievable as released +- license fee per sensor (you are responsible for purchasing enough licenses for your entire deployment) + +Since Shared Object rules won't work with :ref:`suricata`, you may want to disable them using a regex like ``'re:soid [0-9]+'``. + +| For more information, see: +| https://www.snort.org/downloads/#rule-downloads +| https://snort.org/documents/registered-vs-subscriber + +Other +~~~~~ + +- not officially managed/supported by Security Onion +- license fee may or may not apply diff --git a/notifications.rst b/notifications.rst new file mode 100644 index 00000000..01bf93c0 --- /dev/null +++ b/notifications.rst @@ -0,0 +1,77 @@ +.. _notifications: + +Notifications +============= + +.. note:: + + This is an enterprise-level feature of Security Onion. Contact Security Onion Solutions, LLC via our website at https://securityonionsolutions.com for more information about purchasing a Security Onion Pro license to enable this feature. + +The :ref:`detections` module, specifically :ref:`sigma` rules, can be enabled to send outbound notifications upon an alert being created. By default, no outbound notifications are enabled in a Security Onion installation. However, with the Pro license applied to a grid, notifications can be quickly configured via the Configuration screen. + +Configuration +------------- + +Configuring notifications involves adjusting configuration in two areas: + +1. ElastAlert 2 Alerters +2. SOC Detections + +ElastAlert 2 Alerters +~~~~~~~~~~~~~~~~~~~~~ + +:ref:`elastalert` includes a large number of alerters that can reach out to remote systems to deliver notifications. As each alerter supports a unique protocol the alerter requires its own set of supporting parameters in order for the alerter to know how to reach out to the remote endpoint. For example, to send a notification to a Slack channel, a webhook URL must be provided. + +Navigate to the :ref:`administration` -> Configuration screen. Next, locate the ``elastalert`` settings. + +.. image:: images/config-item-elastalert-alerter.png + :target: _images/config-item-elastalert-alerter.png + +Notice there are special settings for Jira and SMTP notifications. These are unique in that :ref:`elastalert` requires those two alerters to read their credentials from a file. Security Onion has simplified this process by presenting these Configuration fields to enter the optional credential data, and the backend process will take care of generating the required files for :ref:`elastalert`. + +The files subtree includes a list of several file settings, which allows for populating the contents of certain files that the alerters can optionally utilize. Most alerters use the files for specifying a custom Certificate Authority, so that :ref:`elastalert` can securely and confidently connect to remote servers that may be using custom SSL/TLS certificates. Again, Security Onion's backend process will handle generating these files from the supplied configuration data provided in the user interface. + +Next, the **Alerter Parameters** setting is used to customize each alerter's own parameters. As :ref:`elastalert` already provides detailed documentation on the required parameters for each alerter, this documentation will not cover the same information, but instead will focus on two popular alerters: Slack and SMTP. + +.. note:: + + Reference the alerter parameters at https://elastalert2.readthedocs.io/en/latest/alerts.html#alert-types. + +Slack +~~~~~ + +To have :ref:`sigma` rules send notifications to Slack, add the following line to the **Alerter Parameters** configuration setting: + +:: + + slack_webhook_url: "https://hooks.slack.com/services/YOUR_WEBHOOK_URI" + +Email (SMTP) +~~~~~~~~~~~~ + +To have :ref:`sigma` rules send notifications via email, add the following lines to the **Alerter Parameters** configuration setting: + +:: + + email: youremail@yourcompany.com + smtp_host: "your_company_smtp_server" + from_addr: "elastalert@yourcompany.com" + +If the SMTP server requires authentication make sure the special **SMTP Username** and **SMTP Password** configuration settings are also specified. + +SOC Detections +~~~~~~~~~~~~~~ + +Once the alerter parameters are configured, as described above, the next step is to configure :ref:`detections` in order to activate one or more notification alerters. + +Navigate to the :ref:`administration` -> Configuration screen. Next, locate the ``soc -> config -> server -> modules -> elastalertengine`` settings. + +In the **Additional Alerters** configuration setting, add the name of each alerter that should be activated, one alerter name per line. + +.. image:: images/config-item-soc-additionalAlerters.png + :target: _images/config-item-soc-additionalAlerters.png + +Important! After activating (or removing) an alerter from this setting, the :ref:`elastalert` engine must be fully updated. This can be done via the :ref:`detections` screen, under the Options dropdown. + +.. image:: images/58_detections_options.png + :target: _images/58_detections_options.png diff --git a/ntp.rst b/ntp.rst index b55770fe..61978004 100644 --- a/ntp.rst +++ b/ntp.rst @@ -7,8 +7,3 @@ Depending on how you installed, the underlying operating system may be configure .. image:: images/config-item-ntp.png :target: _images/config-item-ntp.png - -IDS Alerts ----------- - -Anybody can join the NTP Pool Project and provide NTP service. Occasionally, somebody provides NTP service from a residential DHCP address that at some point in time may have also been used for Tor. This results in IDS alerts for Tor nodes where the port is 123 (NTP). This is another good reason to modify the NTP configuration to pull time updates from your preferred NTP provider. diff --git a/oidc.rst b/oidc.rst index 52a2813d..7d7b5b6e 100644 --- a/oidc.rst +++ b/oidc.rst @@ -7,7 +7,7 @@ Starting with Security Onion version 2.4.30, SOC supports single sign-on (SSO) a .. note:: - The OIDC feature is an enterprise-level feature of Security Onion. Contact Security Onion Solutions, LLC via our website at https://securityonionsolutions.com for more information about purchasing a license to enable this feature. + This is an enterprise-level feature of Security Onion. Contact Security Onion Solutions, LLC via our website at https://securityonionsolutions.com for more information about purchasing a Security Onion Pro license to enable this feature. .. warning:: diff --git a/passwords.rst b/passwords.rst index a2a80bf1..7cced27f 100644 --- a/passwords.rst +++ b/passwords.rst @@ -26,12 +26,7 @@ Password Logins to SOC Log into :ref:`soc` using the username and password you created in the Setup wizard or the username and password provided by your administrator. -You can change your password in :ref:`soc` by clicking the user icon in the upper right corner, clicking ``Settings``, and then going to the ``Security`` tab: - -.. image:: images/password.png - :target: _images/password.png - -Please note that, due to technical limitations, if you change your SOC password here it will not update your password in :ref:`influxdb`. However, resetting your password via :ref:`administration` will reset your :ref:`influxdb` password. +You can change your password in :ref:`soc` by clicking the user icon in the upper-right corner, clicking ``Settings``, and then going to the ``Security`` tab. Please note that, due to technical limitations, if you change your SOC password here it will not update your password in :ref:`influxdb`. However, resetting your password via :ref:`administration` will reset your :ref:`influxdb` password. If you've forgotten your SOC password, an administrator can change it using the :ref:`administration` interface. @@ -43,7 +38,7 @@ Once logged in to SOC using the username and password method, users can optional .. image:: images/37_login.png :target: _images/37_login.png -Activate passwordless login for your :ref:`soc` user by clicking the user icon in the upper right corner, clicking ``Settings``, and then going to the ``Security`` tab. Scroll down to the ``Security Keys`` section and follow the provided instructions. +Activate passwordless login for your :ref:`soc` user by clicking the user icon in the upper-right corner, clicking ``Settings``, and then going to the ``Security`` tab. Scroll down to the ``Security Keys`` section and follow the provided instructions. Similarly, disable passwordless logins by returning to the ``Security`` tab and clicking the delete icon next to any previously-created Security Key. diff --git a/pcap.rst b/pcap.rst index 3339ca5c..6e731b10 100644 --- a/pcap.rst +++ b/pcap.rst @@ -3,49 +3,33 @@ PCAP ==== -:ref:`soc` includes a PCAP interface which allows you to access your full packet capture that was written to disk by :ref:`stenographer`. +:ref:`soc` includes a PCAP interface which allows you to access your full packet capture that was written to disk by :ref:`stenographer` or :ref:`suricata`. -In most cases, you'll pivot to PCAP from a particular event in :ref:`alerts`, :ref:`dashboards`, or :ref:`hunt` by choosing the PCAP action on the action menu. +You can access PCAP in two different ways. The first and most common option is to pivot to PCAP from a particular event in :ref:`alerts`, :ref:`dashboards`, or :ref:`hunt` by choosing the PCAP action on the action menu. The second and less common option is to go directly to the PCAP interface, click the blue + button, and then put in your search criteria to search for a particular stream. -.. image:: images/soc-events-table.png - :target: _images/soc-events-table.png +.. image:: images/73_jobs_add.png + :target: _images/73_jobs_add.png -Alternatively, you can go directly to the PCAP interface, click the blue + button, and then put in your search criteria to search for a particular stream. +Regardless of which of these two options you choose, Security Onion should then locate the stream and render a high level overview of the packets. -.. image:: images/pcap-add-job.png - :target: _images/pcap-add-job.png - -Security Onion will then locate the stream and render a high level overview of the packets. - -.. image:: images/53_pcap.png - :target: _images/53_pcap.png +.. image:: images/62_pcap.png + :target: _images/62_pcap.png If there are many packets in the stream, you can use the ``LOAD MORE`` button, ``Rows per page`` setting, and arrows to navigate through the list of packets. -You can drill into individual rows to see the actual payload data. There are buttons at the top of the table that control what data is displayed in the individual rows. By disabling ``Show all packet data`` and ``HEX``, we can get an ASCII transcript. +You can drill into individual rows to see the actual payload data. There are buttons at the top of the table that control what data is displayed in the individual rows. If you disable the ``Show all packet data`` and ``HEX`` buttons, then you get an ASCII transcript. -.. image:: images/54_pcap_details.png - :target: _images/54_pcap_details.png +.. image:: images/65_pcap_details.png + :target: _images/65_pcap_details.png You can select text with your mouse and then use the context menu to send that selected text to :ref:`cyberchef`, Google, or other destinations defined in the actions list. -.. image:: images/pcap-select-pivot.png - :target: _images/pcap-select-pivot.png - -You can send all of the visible packet data to :ref:`cyberchef` by clicking the CyberChef icon on the right side of the table header. Please note that this only sends packet data that is currently being displayed, so if you are looking at a large stream you may need to use the ``LOAD MORE`` button to display all packets in the stream. - -.. image:: images/pcap-cyberchef.png - :target: _images/pcap-cyberchef.png - -Finally, you can download the full pcap file by clicking the download button on the far right side of the table header. If you are using :ref:`desktop`, then the pcap will automatically open in :ref:`networkminer`. Alternatively, you could open the pcap in :ref:`wireshark`. - -.. image:: images/pcap-download.png - :target: _images/pcap-download.png +There are two buttons on the right side of the table header. The first will send all visible packet data to :ref:`cyberchef`. Please note that this only sends packet data that is currently being displayed, so if you are looking at a large stream you may need to use the ``LOAD MORE`` button to display all packets in the stream. The second button on the far right allows you to download the full pcap file. You can then open the pcap file using :ref:`networkminer`, :ref:`wireshark`, or any other standard libpcap tool. You should typically avoid doing pcap analysis on your normal desktop environment, so you may want to consider opening the pcap file in a :ref:`desktop` instance. Once you've viewed one or more PCAPs, you will see them listed on the main PCAP page. -.. image:: images/56_jobs.png - :target: _images/56_jobs.png +.. image:: images/72_jobs.png + :target: _images/72_jobs.png When you are done with a PCAP, you may want to delete it using the ``X`` button on the far right. This deletes the cached PCAP file saved at ``/nsm/soc/jobs/``. @@ -54,8 +38,8 @@ Troubleshooting If you have trouble retrieving PCAP, here are some things to check: -- Verify that :ref:`stenographer` is enabled. +- Verify that full packet capture is enabled via either :ref:`stenographer` or :ref:`suricata`. +- Check to see if you have any :ref:`bpf` configuration that may cause :ref:`stenographer` or :ref:`suricata` to ignore the traffic. - Check :ref:`grid` and verify that all services are running properly. - Check :ref:`influxdb` and verify that PCAP Retention is long enough to include the stream you're looking for. -- Check to see if you have any :ref:`bpf` configuration that may cause :ref:`stenographer` to ignore the traffic. -- Make sure that there is plenty of free space on ``/nsm`` so that :ref:`stenographer` can carve the stream and write the output to disk. +- Make sure that there is plenty of free space on ``/nsm`` to carve the stream and write the output to disk. diff --git a/performance.rst b/performance.rst index 0f64342b..7cd64d7e 100644 --- a/performance.rst +++ b/performance.rst @@ -25,7 +25,8 @@ RSS Disk/Memory ----------- -If you have plenty of RAM, disable swap altogether. +| If you have plenty of RAM, disable swap altogether: +| https://www.elastic.co/guide/en/elasticsearch/reference/current/setup-configuration-memory.html#disable-swap-files | Use ``hdparm`` to gather drive statistics and alter settings, as described here: | https://www.linux-magazine.com/Online/Features/Tune-Your-Hard-Disk-with-hdparm diff --git a/pfsense.rst b/pfsense.rst index c78b5577..173fe8ea 100644 --- a/pfsense.rst +++ b/pfsense.rst @@ -40,7 +40,8 @@ First, add the pfSense integration and configure the pfSense firewall: #. On the ``Edit pfSense integration`` screen, go to the ``Syslog Host`` field and change ``localhost`` to ``0.0.0.0``. #. Click the ``Save and continue`` button and then click ``Save and deploy changes``. -Next, we need to allow the traffic from the pfSense firewall to port 9001: +Next, allow the traffic from the pfSense firewall to port 9001. These instructions assume that this is the first firewall change you have made and therefore refer to ``customhostgroup0`` and ``customportgroup0``. If those have already been +used, select the next available hostgroup and portgroup. #. Navigate to :ref:`administration` --> Configuration. #. At the top of the page, click the ``Options`` menu and then enable the ``Show all configurable settings, including advanced settings.`` option. diff --git a/post-installation.rst b/post-installation.rst index e6a88963..39e0a627 100644 --- a/post-installation.rst +++ b/post-installation.rst @@ -34,10 +34,10 @@ SSH You should be able to do most administration from :ref:`soc` but if you need access to the command line then we recommend using :ref:`ssh` rather than the :ref:`console`. -Data Retention --------------- +Data +---- -- Review the :ref:`elasticsearch` section to see if you need to change any of the default index retention settings. +- Review the :ref:`elasticsearch` section to see if you need to change any of the default settings. - Review the :ref:`stenographer` section to see if you need to change the Disk Free Percentage or Maximum Files settings. diff --git a/pro.rst b/pro.rst new file mode 100644 index 00000000..085157c1 --- /dev/null +++ b/pro.rst @@ -0,0 +1,21 @@ +.. _pro: + +Security Onion Pro +================== + +In 2022, we announced that we would be releasing enterprise features that would only be available to paid users of the platform. You can read the announcement at https://blog.securityonion.net/2022/08/security-onion-enterprise-features-and.html. + +Starting in Security Onion 2.4.70, licensed users of Security Onion Pro can activate the following features: :ref:`oidc` 3rd-party authentication, :ref:`luks` disk encryption, :ref:`fips` OS compliance, :ref:`stig` OS compliance, :ref:`notifications`, and time tracking inside of :ref:`cases`. In a future release, we will add guaranteed message delivery as a Pro feature. + +.. note:: + + Contact Security Onion Solutions, LLC via our website at https://securityonionsolutions.com for more information about purchasing a Security Onion Pro license to enable these features. + +.. toctree:: + :maxdepth: 2 + + oidc + luks + fips + stig + notifications diff --git a/proxmox.rst b/proxmox.rst index d18d04da..2572df6e 100644 --- a/proxmox.rst +++ b/proxmox.rst @@ -18,7 +18,7 @@ If you plan to use :ref:`networkminer` or other Mono-based applications in a Pro NIC --- -If you're going to install Security Onion in Proxmox and sniff live network traffic, you may need to do some additional configuration in Proxmox itself. +If you're going to install Security Onion in Proxmox and sniff live network traffic, you may need to do some additional configuration in Proxmox itself. You can either passthrough a physical NIC to the VM or you can use a virtual NIC. Passthrough Physical NIC ~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/rbac.rst b/rbac.rst index 9ceea708..8dcf2c70 100644 --- a/rbac.rst +++ b/rbac.rst @@ -45,6 +45,18 @@ See the table below which explains the specific Security Onion privileges grante - X - - + * - View detections + - X + - X + - X + - X + - X + * - Modify (and Delete) detections + - X + - X + - + - + - * - View events in Hunt - X - X @@ -244,11 +256,11 @@ These steps will guide you through an example where we wish to introduce a new r sudo so-elasticsearch-query _security/privilege/kibana-.kibana | jq '. | map_values(keys)' -3. Run a salt highstate from the manager: +3. Run so-checkin from the manager: :: - sudo salt-call state.highstate + sudo so-checkin Defining Security Onion Roles diff --git a/release-notes.rst b/release-notes.rst index ed931f3f..9dfa4fb7 100644 --- a/release-notes.rst +++ b/release-notes.rst @@ -22,6 +22,78 @@ To resolve the issue, run the following command for each affected index (replaci After running the command, the index should no longer use replicas and the status should change from "Pending" to "OK" once all indices have been successfully modified. +2.4.70 [20240529] Changes +---------------------------------- + +- FEATURE: Add confirmation dialog for "revert to default" button in Configuration +- FEATURE: Add dashboard for NetFlow `#13009 `_ +- FEATURE: Add dashboard for SOC Login Failures `#12738 `_ +- FEATURE: Add dashboards specific to Elastic Agent `#12746 `_ +- FEATURE: Add event.dataset to all Events table layouts `#12641 `_ +- FEATURE: Add Events table columns for event.module elastic_agent `#12666 `_ +- FEATURE: Add Events table columns for event.module kratos `#12740 `_ +- FEATURE: Add Events table columns for event.module opencanary `#12655 `_ +- FEATURE: Add Events table columns for event.module playbook `#12703 `_ +- FEATURE: Add Events table columns for event.module sigma `#12743 `_ +- FEATURE: Add Events table columns for event.module strelka `#12716 `_ +- FEATURE: Add Events table columns for event.module system `#12628 `_ +- FEATURE: Add Events table columns for stun logs `#12940 `_ +- FEATURE: Add Events table columns for tunnel logs `#12937 `_ +- FEATURE: Add Events table columns for zeek ssl and suricata ssl `#12697 `_ +- FEATURE: Add groupby fields to Dashboards relating to sankey diagrams `#12657 `_ +- FEATURE: Add hyperlink to airgap screen in setup `#12925 `_ +- FEATURE: Add individual dashboards for Zeek SSL and Suricata SSL logs `#12699 `_ +- FEATURE: Additional Supported Integrations #6 +- FEATURE: Add more fields to the SOC Dashboards URL for so-import-pcap `#12972 `_ +- FEATURE: Add process.command_line to Process Info and Process Ancestry dashboards `#12694 `_ +- FEATURE: Add queue=True to so-checkin so that it will wait for any running states `#12815 `_ +- FEATURE: Add SOC Quick Link for Elasticsearch ILM Deletion `#12854 `_ +- FEATURE: Allow duplication of certain config settings +- FEATURE: Allow users to disable Elasticsearch cleanup script `#12856 `_ +- FEATURE: Change default timeout period for Elastic Agent installation +- FEATURE: Continuation of new Detections module rollout `#12903 `_ +- FEATURE: Delayed enrollment for Elastic Agents +- FEATURE: Enable license checks for enterprise features `#12839 `_ +- FEATURE: Eval use Suricata for PCAP by default `#12878 `_ +- FEATURE: Hunting for SOC logs should show relevant columns +- FEATURE: Introduce new readOnlyUi annotation +- FEATURE: Kismet integration `#12849 `_ +- FEATURE: Lower EVAL memory requirement to 8GB RAM `#12896 `_ +- FEATURE: pfSense Suricata logs `#12653 `_ +- FEATURE: SOC Telemetry to provide feature usage feedback to dev team +- FEATURE: SOS Sigma ruleset +- FIX: Add annotations for BPF and Suricata PCAP `#12626 `_ +- FIX: Add missing options to Suricata af-packet config `#12637 `_ +- FIX: Add the write privilege to the analyst and limited-analyst roles to enable acking of alerts `#12770 `_ +- FIX: Adjust so-import-pcap so that suricata works when it is pcapengine `#12969 `_ +- FIX: Change Elasticsearch min_age setting for cold phase `#12890 `_ +- FIX: Configuration screen search filter causes long delays `#12923 `_ +- FIX: Detections alerts indices `#13005 `_ +- FIX: Detections alerts template not being loaded because load script is trying to match names `#13048 `_ +- FIX: Elastic retention setting not being honored when manager hostname is a subset of search node hostname `#12819 `_ +- FIX: Elasticsearch annotation file for ILM index settings `#12726 `_ +- FIX: Elasticsearch cleanup script should avoid Suricata alerts `#12855 `_ +- FIX: Elasticsearch min_age regex `#12885 `_ +- FIX: GitHub discussion/issue curator workflows fail on repo forks +- FIX: IDH node installs, but won't configure `#12991 `_ +- FIX: idh.services is displayed in SOC Grid Configuration as an advanced setting `#13012 `_ +- FIX: Improve File dashboard `#12914 `_ +- FIX: Input Validation for IPv6 addresses in Zeek and Suricata vars `#12675 `_ +- FIX: mapping conflict with field http.response.status_code `#12543 `_ +- FIX: Remove errant max_age setting from Elastic SOC config `#12851 `_ +- FIX: Rendering SLS 'base:elasticsearch.enabled' failed: Jinja error: Cannot update using non-dict types in dictupdate.update() `#13030 `_ +- FIX: Resetting a customized file to default should restore the default `#13008 `_ +- FIX: so-elasticsearch-ilm-policy-load trying to set policy for indices not managed by ILM `#13021 `_ +- FIX: so-index-list not working correctly `#12988 `_ +- FIX: Sorting for older and newer indices in Elasticsearch cleanup `#12857 `_ +- FIX: so-verify detects rare false error `#12811 `_ +- FIX: Specify that static IP address is recommended `#12643 `_ +- FIX: Update expected timestamp formats in ingest pipeline `#12887 `_ +- FIX: Update so-whiptail to make installation screen more consistent `#12921 `_ +- UPGRADE: CyberChef 10.17.0 `#12798 `_ +- UPGRADE: Suricata 7.0.5 `#12843 `_ +- UPGRADE: Zeek 6.0.4 `#13027 `_ + 2.4.60 [20240320] Changes ------------------------- diff --git a/removing-a-node.rst b/removing-a-node.rst index 7d8aa979..f9dba77a 100644 --- a/removing-a-node.rst +++ b/removing-a-node.rst @@ -10,8 +10,8 @@ Removing from Salt You can remove a node from :ref:`salt` by going to :ref:`administration` --> Grid Members. -.. image:: images/60_gridmembers.png - :target: _images/60_gridmembers.png +.. image:: images/84_gridmembers.png + :target: _images/84_gridmembers.png Find the Grid Member you would like to remove, click the ``REVIEW`` button, and then click the ``DELETE`` button. diff --git a/sigma.rst b/sigma.rst new file mode 100644 index 00000000..9a4e880a --- /dev/null +++ b/sigma.rst @@ -0,0 +1,95 @@ +.. _sigma: + +Sigma +===== + +Sigma rules are loaded into :ref:`elastalert` to monitor incoming logs for suspicious or noteworthy activity. Active sigma rules generate alerts that can then be found in :ref:`alerts`. + +From https://github.com/SigmaHQ/sigma: + + Sigma is a generic and open signature format that allows you to describe relevant log events in a straightforward manner. The rule format is very flexible, easy to write and applicable to any type of log file. The main purpose of this project is to provide a structured form in which researchers or analysts can describe their once developed detection methods and make them shareable with others. Sigma is for log files what Snort is for network traffic and YARA is for files. + +Managing Existing Sigma Rules +----------------------------- + +You can manage existing Sigma rules via :ref:`detections`. There are two ways to do so: + +- From the main :ref:`detections` interface, you can search for the desired detection and click the binoculars icon. +- From the :ref:`alerts` interface, you can click an alert and then click the ``Tune Detection`` menu item. + +Once you've used one of these methods to reach the detection detail page, you can check the Status field in the upper-right corner and use the slider to enable or disable the detection. + +.. image:: images/60_detection_sigma.png + :target: _images/60_detection_sigma.png + +To tune the detection: + +- click the TUNING tab +- click the blue + button +- select the type of tuning (Custom Filter) +- enter your custom filter in the Custom Filter field +- click the ``CREATE`` button to create and enable the Override + +.. image:: images/60_detection_sigma_2_tuning_2_add.png + :target: _images/60_detection_sigma_2_tuning_2_add.png + +Custom Filters are Sigma Search Identifiers and will be applied like so: ``"($ORIGINAL_CONDITION) and not 1 of sofilter*"`` + +For example, suppose that you have an :ref:`idh` node installed with the HTTP webserver enabled. Your nightly vulnerablity scan is connecting to it and generating an alert from the ``Security Onion IDH - HTTP Access`` detection. To filter out connection attempts from this scanner, you would add the following Custom Filter to this detection: + +:: + + sofilter: + src_ip|cidr: 192.168.55.45/32 + +Once you save this filter, it is enabled by default for this detection. Clicking on the ``Detection Source`` tab and then on ``Convert`` will show you what the new EQL query looks like, which should include a filter for the IP address. + +For more information on Sigma rule syntax, please see the Sigma documentation at https://sigmahq.io/docs/basics/rules.html#detection. + +Adding New Sigma Rules +---------------------- + +To add a new Sigma rule, go to the main :ref:`detections` page and click the blue + button between Options and the query bar. A form will appear where you will: + +- click the Language drop-down and select ``Sigma`` +- optionally specify a license +- add the signature +- click the ``CREATE`` button and the detection should deploy to your grid at the next 15-minute cycle + +.. image:: images/58_detection_create.png + :target: _images/58_detection_create.png + +Sigma Configuration +------------------- + +- Navigate to :ref:`administration` --> Configuration. +- At the top of the page, click the ``Options`` menu and then enable the ``Show all configurable settings, including advanced settings.`` option. +- Navigate to soc --> config --> server --> modules --> elastalertengine. + +Once you've reached this location, here are some common settings. + +Sigma Update Frequency +~~~~~~~~~~~~~~~~~~~~~~ + +By default, Security Onion checks for new Sigma rules every 24 hours. You can change this value at elastalertengine --> communityRulesImportFrequencySeconds. + +Sigma Packages +~~~~~~~~~~~~~~ + +You can choose from different Sigma packages: + +https://github.com/SigmaHQ/sigma/blob/master/Releases.md + +You can modify this setting via elastalertengine --> sigmaRulePackages. + +Custom Sigma Repositories +~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can configure Security Onion to pull Sigma rules from custom git repos via elastalertengine --> rulesRepos --> default. + +Repos can be accessed via https or from the local filesystem. For example: + +:: + + file:///nsm/rules/detect-sigma/repos/my-custom-rep + diff --git a/so-elasticsearch-query.rst b/so-elasticsearch-query.rst index fb567002..9ecc6c53 100644 --- a/so-elasticsearch-query.rst +++ b/so-elasticsearch-query.rst @@ -31,9 +31,3 @@ Here's a more complicated example that includes piping the output to :ref:`jq`: :: sudo so-elasticsearch-query '*:so-*/_search' -d '{"query": {"match_all": {}},"size": 1}' | jq - -If you want to delete an old index, you can do that using the ``-XDELETE`` option. For example, to delete the :ref:`zeek` index for 2022/05/07: - -:: - - sudo so-elasticsearch-query so-zeek-2022.05.07 -XDELETE diff --git a/so-import-pcap.rst b/so-import-pcap.rst index 468331e5..e262c1f4 100644 --- a/so-import-pcap.rst +++ b/so-import-pcap.rst @@ -17,12 +17,6 @@ In addition to viewing alerts and logs in :ref:`soc`, you can also find logs in You can run this command manually, but for most use cases it's easier to upload a pcap via :ref:`grid` and it will automatically run ``so-import-pcap`` for you. -Screenshot ----------- - -.. image:: images/36_so-import-pcap.png - :target: _images/36_so-import-pcap.png - Configuration ------------- diff --git a/soc-customization.rst b/soc-customization.rst index 2973f611..66c1c9da 100644 --- a/soc-customization.rst +++ b/soc-customization.rst @@ -10,6 +10,9 @@ You can customize :ref:`soc` by going to :ref:`administration` --> Configuration Below are some ways in which you can customize SOC. Once all customizations are complete, you can make the changes take effect by clicking the ``Options`` bar at the top and then clicking the ``SYNCHRONIZE GRID`` button. +.. image:: images/88_config_options.png + :target: _images/88_config_options.png + Login Page ---------- @@ -20,6 +23,12 @@ Overview Page After logging into SOC, you'll start on the main SOC Overview page which can be customized as well. You can customize this by going to :ref:`administration` --> Configuration --> soc --> files --> soc --> Overview Page. This uses Markdown format as mentioned above. +You can add images but they must be hosted from another host that is accessible by the user's browser. For example, let's use one of the images from our online documentation. The markdown to add that image would look like this: + +:: + + ![SOC Dashboards](https://docs.securityonion.net/en/2.4/_images/51_dashboards.png) + Links ----- diff --git a/soc-logs.rst b/soc-logs.rst index 81608cb0..bda52126 100644 --- a/soc-logs.rst +++ b/soc-logs.rst @@ -14,10 +14,7 @@ SOC auth is handled by Kratos and you can read more about that at https://github sudo zgrep "Identity authenticated successfully and was issued an Ory Kratos Session Cookie" /opt/so/log/kratos/* -Those logs should be ingested into :ref:`elasticsearch` and available for searching in :ref:`dashboards`, :ref:`hunt`, and :ref:`kibana`. Both :ref:`dashboards` and :ref:`hunt` have pre-defined queries for SOC auth logs. - -.. image:: images/soc-logins.png - :target: _images/soc-logins.png +Those logs are ingested into :ref:`elasticsearch` and available for searching in :ref:`dashboards`, :ref:`hunt`, and :ref:`kibana`. Both :ref:`dashboards` and :ref:`hunt` have pre-defined queries for SOC auth logs. identity_id ~~~~~~~~~~~ diff --git a/soc.rst b/soc.rst index 07b3f668..d4bba737 100644 --- a/soc.rst +++ b/soc.rst @@ -13,12 +13,12 @@ Depending on the options you chose in the installer, connect to the IP address o .. image:: images/37_login.png :target: _images/37_login.png -Once logged in, you'll notice the user menu in the upper right corner. This allows you to manage your user settings and access documentation and other resources. +Once logged in, you'll notice the user menu in the upper-right corner. This allows you to manage your user settings and access documentation and other resources. -.. image:: images/63_usermenu.png - :target: _images/63_usermenu.png +.. image:: images/94_usermenu.png + :target: _images/94_usermenu.png -On the left side of the page, you'll see links for analyst tools like :ref:`alerts`, :ref:`dashboards`, :ref:`hunt`, :ref:`cases`, :ref:`pcap`, :ref:`kibana`, :ref:`cyberchef`, :ref:`playbook`, and :ref:`attack-navigator`. While :ref:`alerts`, :ref:`dashboards`, :ref:`hunt`, :ref:`cases`, and :ref:`pcap` are built into SOC itself, the remaining tools are external and will spawn separate browser tabs. +On the left side of the page, you'll see links for analyst tools like :ref:`alerts`, :ref:`dashboards`, :ref:`hunt`, :ref:`cases`, :ref:`detections`, :ref:`pcap`, :ref:`kibana`, :ref:`cyberchef`, and :ref:`attack-navigator`. While :ref:`alerts`, :ref:`dashboards`, :ref:`hunt`, :ref:`cases`, :ref:`detections`, and :ref:`pcap` are built into SOC itself, the remaining tools are external and will spawn separate browser tabs. If you'd like to customize SOC, please see the :ref:`soc-customization` section. If you'd like to learn more about SOC logs, please see the :ref:`soc-logs` section. diff --git a/soup.rst b/soup.rst index 7abc8866..c3fb2e6f 100644 --- a/soup.rst +++ b/soup.rst @@ -11,11 +11,11 @@ soup If necessary, ``soup`` will update itself and then ask you to run ``soup`` again. Once ``soup`` is fully updated, it will then check for other updates. This includes Security Onion version updates, Security Onion hotfixes, and operating system (OS) updates. -After running ``soup`` or rebooting a Security Onion node, it may take a few minutes for services to display an ``OK`` status when running :ref:`so-status`. This may be due to the intial on-boot :ref:`salt` highstate running. If services do not appear to be fully up and running within 15 minutes, try running the following command: +After running ``soup`` or rebooting a Security Onion node, it may take a few minutes for services to display an ``OK`` status on the :ref:`grid` screen. This may be due to the intial on-boot :ref:`salt` highstate running. If services do not appear to be fully up and running within 15 minutes, try running the following command: :: - sudo salt-call state.highstate + sudo so-checkin .. warning:: @@ -165,7 +165,7 @@ and/or There is a problem downloading the so-xyz:2.4.0 image. Details: gpg: Signature made Thu 18 Feb 2021 02:26:10 PM UTC using RSA key ID FE507013 gpg: BAD signature from "Security Onion Solutions, LLC " -If you see these errors, it most likely means that a salt highstate process was already running when ``soup`` began. You can wait a few minutes and then try ``soup`` again. Alternatively, you can run ``sudo salt-call state.highstate`` and wait for it to complete before running ``soup`` again. +If you see these errors, it most likely means that a salt highstate process was already running when ``soup`` began. You can wait a few minutes and then try ``soup`` again. Alternatively, you can run ``sudo so-checkin`` and wait for it to complete before running ``soup`` again. Distributed deployments ----------------------- @@ -178,7 +178,7 @@ If you have a distributed deployment with a manager node and separate sensor nod Each minion is on a random 15 minute check-in period and things like network bandwidth can be a factor in how long the actual upgrade takes. If you have a heavy node on a slow link, it is going to take a while to get the containers to it. Depending on what changes happened between the versions, :ref:`elasticsearch` might not be able to talk to said heavy node until the update is complete. - If it looks like you're missing data after the upgrade, please avoid restarting services and instead make sure at least one search node has completed its upgrade. The best way to do this is to run ``sudo salt-call state.highstate`` from a search node and make sure there are no errors. Typically if it works on one node it will work on the rest. Forward nodes are less complex and will update as they check in so you can monitor those from the :ref:`grid` section of :ref:`soc`. + If it looks like you're missing data after the upgrade, please avoid restarting services and instead make sure at least one search node has completed its upgrade. The best way to do this is to run ``sudo so-checkin`` from a search node and make sure there are no errors. Typically if it works on one node it will work on the rest. Forward nodes are less complex and will update as they check in so you can monitor those from the :ref:`grid` section of :ref:`soc`. When you run ``soup`` on the manager, it does the following: diff --git a/stenographer.rst b/stenographer.rst index 73214da9..88019290 100644 --- a/stenographer.rst +++ b/stenographer.rst @@ -7,7 +7,7 @@ Security Onion uses Stenographer to write network traffic to disk. From https:// Stenographer is a full-packet-capture utility for buffering packets to disk for intrusion detection and incident response purposes. It provides a high-performance implementation of NIC-to-disk packet writing, handles deleting those files as disk fills up, and provides methods for reading back specific sets of packets quickly and easily. -Stenographer uses :ref:`af-packet` for packet acquisition. It's important to note that Stenographer is totally independent from :ref:`suricata` and :ref:`zeek`. This means that Stenographer has no impact on your NIDS alerts and protocol metadata. +Stenographer uses :ref:`af-packet` for packet acquisition. It's important to note that Stenographer is totally independent from :ref:`suricata` and :ref:`zeek`. This means that Stenographer has no impact on your :ref:`nids` alerts and protocol metadata. Output ------ @@ -19,8 +19,8 @@ Analysis You can access full packet capture via the :ref:`pcap` interface: -.. image:: images/54_pcap_details.png - :target: _images/54_pcap_details.png +.. image:: images/65_pcap_details.png + :target: _images/65_pcap_details.png :ref:`alerts`, :ref:`dashboards`, :ref:`hunt`, and :ref:`kibana` allow you to easily pivot to the :ref:`pcap` interface. diff --git a/stig.rst b/stig.rst new file mode 100644 index 00000000..b3a483b9 --- /dev/null +++ b/stig.rst @@ -0,0 +1,15 @@ +.. _stig: + +STIG +==== + +STIG stands for Security Technical Implementation Guide. For more information about STIGs, please see https://public.cyber.mil/stigs/. + +.. note:: + + This is an enterprise-level feature of Security Onion. Contact Security Onion Solutions, LLC via our website at https://securityonionsolutions.com for more information about purchasing a Security Onion Pro license to enable this feature. + +Enabling STIG During the ISO Install +------------------------------------ + +The recommended way to use STIG with Security Onion is to install via our Security Onion ISO image. At the ISO boot menu, you'll need to modify the boot command. This can be done using the ``e`` key in UEFI boot mode or the ``Tab`` key in BIOS boot mode before it automatically boots. Then append ``stig=1`` (and possibly other options like :ref:`fips` and :ref:`luks`) to the boot parameters and continue the boot process. diff --git a/strelka.rst b/strelka.rst index bd110f86..accf1520 100644 --- a/strelka.rst +++ b/strelka.rst @@ -14,7 +14,7 @@ Security Onion checks file hashes before sending to Strelka to avoid analyzing t Alerts ------ -Strelka scans files using YARA rules. If it detects a match, then it will generate an alert that can be found in :ref:`alerts`, :ref:`dashboards`, or :ref:`hunt`. You can read more about YARA rules in the :ref:`local-rules` section. +Strelka scans files using :ref:`yara` rules. If it detects a match, then it will generate an alert that can be found in :ref:`alerts`, :ref:`dashboards`, or :ref:`hunt`. You can configure :ref:`yara` rules via :ref:`detections`. Logs ---- diff --git a/suricata.rst b/suricata.rst index d7633da6..5e18aae6 100644 --- a/suricata.rst +++ b/suricata.rst @@ -81,7 +81,7 @@ By default, Security Onion uses :ref:`zeek` to record protocol metadata. If you - SSL -If you later find that some of that metadata is unnecessary, you can filter out the unnecessary metadata by writing rules. We have included some examples at https://github.com/Security-Onion-Solutions/securityonion/blob/dev/salt/idstools/sorules/filters.rules. +If you later find that some of that metadata is unnecessary, you can filter out the unnecessary metadata by writing rules. We have included some examples at https://raw.githubusercontent.com/Security-Onion-Solutions/securityonion/2.4/main/salt/idstools/rules/filters.rules. To change your grid's metadata engine from :ref:`zeek` to Suricata, go to :ref:`administration` --> Configuration --> global --> mdengine and change the value from ``ZEEK`` to ``SURICATA``: @@ -91,12 +91,12 @@ To change your grid's metadata engine from :ref:`zeek` to Suricata, go to :ref:` File Extraction --------------- -If you choose Suricata for metadata, it will extract files from network traffic and :ref:`strelka` will then analyze those extracted files. If you would like to extract additional file types, then you can add file types as shown at https://github.com/Security-Onion-Solutions/securityonion/blob/dev/salt/idstools/sorules/extraction.rules. +If you choose Suricata for metadata, it will extract files from network traffic and :ref:`strelka` will then analyze those extracted files. If you would like to extract additional file types, then you can add file types as shown at https://raw.githubusercontent.com/Security-Onion-Solutions/securityonion/2.4/main/salt/idstools/rules/extraction.rules. PCAP ---- -Starting in Security Onion 2.4.60, you now have the option of switching full packet capture from :ref:`stenographer` to Suricata. +For most modes, full packet capture is written to disk by :ref:`stenographer` but you can optionally switch this to Suricata. .. warning:: diff --git a/telemetry.rst b/telemetry.rst new file mode 100644 index 00000000..cb3d8ebf --- /dev/null +++ b/telemetry.rst @@ -0,0 +1,89 @@ +.. _telemetry: + +Telemetry +========= + +SOC Telemetry +------------- + +Starting in Security Onion 2.4.70, :ref:`soc` will send telemetry data to Google Analytics. The purpose of this change is to help the Security Onion development team improve the product. Specifically, by knowing which user-interface features are being used, and how the user interacts with the SOC user interface, the development team can better prioritize new features, improvements to the existing user interface, and begin deprecating features that are rarely used. Deprecating unused features will help developers avoid spending their time and effort maintaining and upgrading areas of the product that aren't widely used. This allows more time to be spent on new features and bug fixes, directly benefiting Security Onion users. + +Configuring +~~~~~~~~~~~ + +During setup, or during non-automated :ref:`soup` invocations, the user must choose to enable or disable SOC telemetry collection. + +After installation, grid administrators can enable or disable SOC Telemetry via the configuration interface. Search for ``SOC Telemetry`` in the Configuration screen. + +After changing the ``SOC Telemetry`` configuration setting, the grid must be resynchronized. This happens automatically once every 15 minutes, or manually if the grid administrator clicks the Synchronize Grid option, at the top of the Configuration screen. Grid synchronization can take several minutes to complete. + +Also, the browser will cache the previous configuration setting. Therefore, to ensure the browser is using the new setting value, make sure grid synchronization completes, and then perform a hard browser refresh on the SOC UI. This can be performed via CTRL+SHIFT+R or CMD+SHIFT+R. + +Included Data +~~~~~~~~~~~~~ + +The primary objective of the SOC Telemetry data collection is to understand what features are being used in :ref:`soc`. Specifically, the data being collected relates to user interface navigation flows. Additional context data, such as the version of the software, the viewed page path, etc. may also be included. + +Grid-specific data is intentionally excluded from the data collection, where possible. + +Due to the nature of how internet web requests work, the originating IP address and User-Agent information of the web browser as well as host referrer information is known at the time of the data collection. + +See the Retention Period section below to learn more about how long this data is retained. + +Network Parameters +~~~~~~~~~~~~~~~~~~ + +The SOC Telemetry data originates from the :ref:`soc` browser running on the analyst workstation. The domains being accessed from the :ref:`soc` browser are: + +- ``www.googletagmanager.com`` +- ``www.google-analytics.com`` + +The telemetry data is sent using TLS encryption. + +Retention Period +~~~~~~~~~~~~~~~~ + +Data stored in Google Analytics is configured to be automatically removed after two months. This is the shortest interval that Google Analytics provides. + +Operating System Updates Telemetry +---------------------------------- + +Security Onion periodically checks for package updates to ensure the operating system (OS) and related applications are kept patched and updated. These updates are critical to protecting the OS and installed packages from recently exposed vulnerabilities. This is different from Security Onion product upgrades via :ref:`soup`, which is manually invoked. When the OS package updates begin, the request to the Security Onion repository server(s) can include a limited set of telemetry data. + +Configuring +~~~~~~~~~~~ + +Automatic package updates can be enabled or disabled via the configuration interface. Search for ``patch`` in the Configuration screen. + +After changing this configuration setting, the grid must be resynchronized. This happens automatically once every 15 minutes, or manually if the grid administrator clicks the Synchronize Grid option, at the top of the Configuration screen. Grid synchronization can take several minutes to complete. + +Included Data +~~~~~~~~~~~~~ + +The primary objective of the included telemetry data is to understand which versions of Security Onion are deployed and on which platforms. This information helps the Security Onion development team determine how to prioritize support for older versions, and whether there is justification to start testing or stop testing on various operating systems and architectures. + +Additional data may be included to provide the development team with information about which features have been enabled. This data can change from release to release as it often relates to new development work. + +Also, grids with license keys installed will include the license key identifier. Grids using the standard unprovisioned license do not have a license key identifier. + +Due to the nature of how internet web requests work, the originating IP address and User-Agent information of the web browser as well as host referrer information is known at the time of the data collection. + +Network Parameters +~~~~~~~~~~~~~~~~~~ + +The OS Updates Telemetry data originates from the manager node. The domains being accessed from the manager node are: + +- ``sigs.securityonion.net`` +- ``repo.securityonion.net`` +- ``repo-alt.securityonion.net`` + +The telemetry data is sent using TLS encryption. + +Airgap +------ + +Grids installed within airgapped environments will automatically disable telemetry. In this scenario, the ``SOC Telemetry`` configuration setting will have no effect and the automatic package updates will be disabled. See the :ref:`airgap` section for more information about environments detached from the internet. + +.. note:: + + If a grid is switched from airgap to non-airgap, and if the SOC Telemetry is not explicitly disabled in the grid by an administrator, the SOC app running in the browser will send telemetry. diff --git a/third-party-integrations.rst b/third-party-integrations.rst new file mode 100644 index 00000000..14727573 --- /dev/null +++ b/third-party-integrations.rst @@ -0,0 +1,240 @@ +.. _third-party-integrations: + +Third Party Integrations +======================== + +In addition to :ref:`network` and :ref:`host`, you may want to pull in data from other third party systems. You can do that via Elastic integrations which support many of the most common products and services. You can read more about Elastic integrations at https://docs.elastic.co/integrations. + +Adding an Integration +--------------------- + +New integrations can be added to existing policies to provide increased visibility and more comprehensive monitoring. + +.. tip:: + + When adding a new integration, it is important that you add it to an appropriate policy. + + If an integration pulls the data, you should add it to the Fleet Server policy. Depending on complexity and log volume, it might make sense to stand up a Fleet Node and add your integrations to it. + + If an integration receives data pushed to it (for example: receiving syslog), consider adding it to the Fleet Server policy. If that is not feasible, then you can add it to the Grid Nodes policy but make sure to set the firewall rules correctly so that you are not opening ports on all of your nodes. + +To add an integration to an existing policy: + +- From the main Fleet page, click the ``Agent policies`` tab. +- Select the desired agent policy. +- Click the ``Add Integration`` button. +- Follow the steps for adding the integration. + +.. note:: + + If the integration is designed to listen on a port to receive data, it will most likely default to listening on ``localhost`` only. Depending on how you are sending data to the integration, you may need to change that to ``0.0.0.0`` so that it can receive data from other hosts. + +For examples of this process, please see the :ref:`netflow` and :ref:`pfsense` sections. + +Adding a Custom Integration +--------------------------- + +A custom integration can be added by adding an integration such as the ``Custom Logs`` integration. You can specify various settings relative to the data source and define additional actions to be performed. + +Supported Integrations +---------------------- + +The current release of Security Onion supports the following Elastic integrations: + +============================== ========================================================== +Elastic Integration Elastic Documentation +============================== ========================================================== +1password https://docs.elastic.co/en/integrations/1password +apache https://docs.elastic.co/en/integrations/apache +auditd https://docs.elastic.co/en/integrations/auditd +auth0 https://docs.elastic.co/en/integrations/auth0 +aws https://docs.elastic.co/en/integrations/aws +azure https://docs.elastic.co/en/integrations/azure +barracuda https://docs.elastic.co/en/integrations/barracuda +carbonblack_edr https://docs.elastic.co/en/integrations/carbonblack_edr +cef https://docs.elastic.co/en/integrations/cef +checkpoint https://docs.elastic.co/en/integrations/checkpoint +cisco_asa https://docs.elastic.co/en/integrations/cisco_asa +cisco_duo https://docs.elastic.co/en/integrations/cisco_duo +cisco_ftd https://docs.elastic.co/en/integrations/cisco_ftd +cisco_ios https://docs.elastic.co/en/integrations/cisco_ios +cisco_ise https://docs.elastic.co/en/integrations/cisco_ise +cisco_meraki https://docs.elastic.co/en/integrations/cisco_meraki +cisco_umbrella https://docs.elastic.co/en/integrations/cisco_umbrella +citrix_adc https://docs.elastic.co/en/integrations/citrix_adc +citrix_waf https://docs.elastic.co/en/integrations/citrix_waf +cloudflare https://docs.elastic.co/en/integrations/cloudflare +crowdstrike https://docs.elastic.co/en/integrations/crowdstrike +darktrace https://docs.elastic.co/en/integrations/darktrace +elasticsearch https://docs.elastic.co/en/integrations/elasticsearch +endpoint https://docs.elastic.co/en/integrations/endpoint +f5_bigip https://docs.elastic.co/en/integrations/f5_bigip +fim https://docs.elastic.co/en/integrations/fim +fireeye https://docs.elastic.co/en/integrations/fireeye +fleet_server https://docs.elastic.co/en/integrations/fleet_server +fortinet https://docs.elastic.co/en/integrations/fortinet +fortinet_fortigate https://docs.elastic.co/en/integrations/fortinet_fortigate +gcp https://docs.elastic.co/en/integrations/gcp +github https://docs.elastic.co/en/integrations/github +google_workspace https://docs.elastic.co/en/integrations/google_workspace +http_endpoint https://docs.elastic.co/en/integrations/http_endpoint +httpjson https://docs.elastic.co/en/integrations/httpjson +iis https://docs.elastic.co/en/integrations/iis +journald https://docs.elastic.co/en/integrations/journald +juniper_srx https://docs.elastic.co/en/integrations/juniper_srx +kafka_log https://docs.elastic.co/en/integrations/kafka_log +lastpass https://docs.elastic.co/en/integrations/lastpass +log https://docs.elastic.co/en/integrations/log +m365_defender https://docs.elastic.co/en/integrations/m365_defender +microsoft_defender_endpoint https://docs.elastic.co/en/integrations/microsoft_defender_endpoint +microsoft_dhcp https://docs.elastic.co/en/integrations/microsoft_dhcp +microsoft_sqlserver https://docs.elastic.co/en/integrations/microsoft_sqlserver +mimecast https://docs.elastic.co/en/integrations/mimecast +mysql https://docs.elastic.co/en/integrations/mysql +:ref:`netflow` https://docs.elastic.co/en/integrations/netflow +nginx https://docs.elastic.co/en/integrations/nginx +o365 https://docs.elastic.co/en/integrations/o365 +okta https://docs.elastic.co/en/integrations/okta +osquery_manager https://docs.elastic.co/en/integrations/osquery_manager +panw https://docs.elastic.co/en/integrations/panw +:ref:`pfsense` https://docs.elastic.co/en/integrations/pfsense +proofpoint_tap https://docs.elastic.co/en/integrations/proofpoint_tap +pulse_connect_secure https://docs.elastic.co/en/integrations/pulse_connect_secure +redis https://docs.elastic.co/en/integrations/redis +sentinel_one https://docs.elastic.co/en/integrations/sentinel_one +snort https://docs.elastic.co/en/integrations/snort +snyk https://docs.elastic.co/en/integrations/snyk +sonicwall_firewall https://docs.elastic.co/en/integrations/sonicwall_firewall +sophos https://docs.elastic.co/en/integrations/sophos +sophos_central https://docs.elastic.co/en/integrations/sophos_central +symantec_endpoint https://docs.elastic.co/en/integrations/symantec_endpoint +system https://docs.elastic.co/en/integrations/system +tcp https://docs.elastic.co/en/integrations/tcp +tenable_sc https://docs.elastic.co/en/integrations/tenable_sc +ti_abusech https://docs.elastic.co/en/integrations/ti_abusech +ti_anomali https://docs.elastic.co/en/integrations/ti_anomali +ti_cybersixgill https://docs.elastic.co/en/integrations/ti_cybersixgill +ti_misp https://docs.elastic.co/en/integrations/ti_misp +ti_otx https://docs.elastic.co/en/integrations/ti_otx +ti_recordedfuture https://docs.elastic.co/en/integrations/ti_recordedfuture +ti_threatq https://docs.elastic.co/en/integrations/ti_threatq +udp https://docs.elastic.co/en/integrations/udp +vsphere https://docs.elastic.co/en/integrations/vsphere +windows https://docs.elastic.co/en/integrations/windows +winlog https://docs.elastic.co/en/integrations/winlog +zscaler_zia https://docs.elastic.co/en/integrations/zscaler_zia +zscaler_zpa https://docs.elastic.co/en/integrations/zscaler_zpa +============================== ========================================================== + +.. note:: + + These integrations have been added over the course of several different releases. + + Security Onion 2.4.10 supports the following Elastic integrations: + + - aws + - azure + - cloudflare + - elasticsearch + - endpoint + - fleet_server + - fim + - github + - google_workspace + - log + - osquery_manager + - redis + - system + - tcp + - udp + - windows + - 1password + + Security Onion 2.4.20 supports these additional Elastic integrations: + + - apache + - auditd + - barracuda + - cisco_asa + - crowdstrike + - darktrace + - f5_bigip + - fortinet + - fortinet_fortigate + - gcp + - http_endpoint + - httpjson + - juniper + - juniper_srx + - kafka_log + - lastpass + - m365_defender + - microsoft_defender_endpoint + - microsoft_dhcp + - netflow + - o365 + - okta + - panw + - pfsense + - sentinel_one + - sonicwall_firewall + - symantec_endpoint + - ti_abusech + - ti_misp + - ti_otx + - ti_recordedfuture + - zscaler_zia + - zscaler_zpa + + Security Onion 2.4.30 supports these additional Elastic integrations: + + - auth0 + - carbonblack_edr + - checkpoint + - cisco_duo + - cisco_meraki + - cisco_umbrella + - fireeye + - mimecast + - pulse_connect_secure + - snyk + - sophos + - sophos_central + - tenable_sc + - vsphere + + Security Onion 2.4.40 supports these additional Elastic integrations: + + - cisco_ftd + - cisco_ios + - cisco_ise + - iis + - microsoft_sqlserver + - mysql + - proofpoint_tap + - snort + - ti_anomali + - ti_threatq + + Security Onion 2.4.50 supports these additional Elastic integrations: + + - citrix_adc + - citrix_waf + - nginx + - winlog + + Security Onion 2.4.60 supports these additional Elastic integrations: + + - journald + - ti_cybersixgill + + Security Onion 2.4.70 supports these additional Elastic integrations: + + - CEF + +More Information +---------------- + +.. note:: + + You can read more about Elastic integrations at https://docs.elastic.co/integrations. diff --git a/tricks.rst b/tricks.rst index d85cdcdf..8e8c2aad 100644 --- a/tricks.rst +++ b/tricks.rst @@ -17,5 +17,4 @@ This section is a collection of miscellaneous tricks and tips for Security Onion removing-a-node syslog-output timezones - pfsense endgame diff --git a/yara.rst b/yara.rst new file mode 100644 index 00000000..9bd0dec9 --- /dev/null +++ b/yara.rst @@ -0,0 +1,64 @@ +.. _yara: + +YARA +==== + +YARA rules are loaded into :ref:`strelka` to monitor files for suspicious or noteworthy characteristics. Active YARA rules generate alerts that can be found in :ref:`alerts`. + +From https://virustotal.github.io/yara/: + + YARA is a tool aimed at (but not limited to) helping malware researchers to identify and classify malware samples. With YARA you can create descriptions of malware families (or whatever you want to describe) based on textual or binary patterns. Each description, a.k.a rule, consists of a set of strings and a boolean expression which determine its logic. + +Managing Existing YARA Rules +---------------------------- + +You can manage existing YARA rules via :ref:`detections`. There are two ways to do so: + +- From the main :ref:`detections` interface, you can search for the desired detection and click the binoculars icon. +- From the :ref:`alerts` interface, you can click an alert and then click the ``Tune Detection`` menu item. + +Once you've used one of these methods to reach the detection detail page, you can check the Status field in the upper-right corner and use the slider to enable or disable the detection. + +.. image:: images/60_detection_yara.png + :target: _images/60_detection_yara.png + +Adding New YARA Rules +--------------------- + +To add a new YARA rule, go to the main :ref:`detections` page and click the blue + button between Options and the query bar. A form will appear where you will: + +- click the Language drop-down and select ``YARA`` +- optionally specify a license +- add the signature +- click the ``CREATE`` button and the detection should deploy to your grid at the next 15-minute cycle + +.. image:: images/58_detection_create.png + :target: _images/58_detection_create.png + +YARA Rules Options +------------------ + +You can configure YARA rules options as follows: + +- Navigate to :ref:`administration` --> Configuration. +- At the top of the page, click the ``Options`` menu and then enable the ``Show all configurable settings, including advanced settings.`` option. +- Navigate to soc --> config --> server --> modules --> strelkaengine. + +Once you've reached this location, here are some common settings. + +YARA Update Frequency +~~~~~~~~~~~~~~~~~~~~~ + +By default, Security Onion checks for new YARA rules every 24 hours. You can change this via the strelkaengine --> communityRulesImportFrequencySeconds setting. + +Custom YARA Repositories +~~~~~~~~~~~~~~~~~~~~~~~~ + +You can configure Security Onion to pull YARA rules from custom git repos via strelkaengine --> rulesRepos --> default. + +Repos can be accessed via https or from the local filesystem. For example: + +:: + + file:///nsm/rules/detect-yara/repos/my-custom-rep + diff --git a/zeek.rst b/zeek.rst index a5bc5bba..9beb2819 100644 --- a/zeek.rst +++ b/zeek.rst @@ -9,8 +9,8 @@ Security Onion includes Zeek for network protocol analysis and metadata. From h Zeek logs are sent to :ref:`elasticsearch` for parsing and storage and can then be found in :ref:`dashboards`, :ref:`hunt`, and :ref:`kibana`. Here's an example of Zeek logs in :ref:`hunt`: -.. image:: images/52_hunt.png - :target: _images/52_hunt.png +.. image:: images/56_hunt.png + :target: _images/56_hunt.png Community ID ------------