Merge pull request #1084 from gravwell/dev

Release/v5.5.0: Merge dev to main

.github/workflows/build-html.yml

@@ -42,6 +42,7 @@ jobs:
               nix-build
               cp -r ./result/html $BUILD_DEST/html/$v
               chmod --recursive +w $BUILD_DEST
+              echo "Disallow: /$v/" >> $BUILD_DEST/html/robots.txt
           done
 
           tar -C $BUILD_DEST -czf ${{ env.HTML_BUILD }} html

_static/versions.json

@@ -1,10 +1,14 @@
 [
   {
-    "name": "v5.4.11 (latest)",
-    "version": "v5.4.11",
+    "name": "v5.5.0 (latest)",
+    "version": "v5.5.0",
     "url": "https://docs.gravwell.io/",
     "preferred": true
   },
+  {
+    "version": "v5.4.11",
+    "url": "https://docs.gravwell.io/v5.4.11/"
+  },
   {
     "version": "v5.4.10",
     "url": "https://docs.gravwell.io/v5.4.10/"

architecture/architecture.md

@@ -43,6 +43,7 @@ maxdepth: 1
 caption: Securing Gravwell
 hidden: true
 ---
+Multi-Factor Authentication </configuration/mfa/mfa>
 Hardening a Gravwell Installation </configuration/hardening>
 Configuring TLS Certificates </configuration/certificates>
 ```

changelog/5.5.0.md

@@ -0,0 +1,66 @@
+# Changelog for version 5.5.0
+
+## Released 13 August 2024
+
+## Gravwell
+
+### Additions
+
+* Added [multi-factor authentication (MFA)](/configuration/mfa/mfa) using TOTP and recovery codes.
+* Added the ability to specify [time constraints](#specify-search-timeframe-in-query) in the query itself.
+* Added a new [top/bottom](/search/topbottom/topbottom) search module.
+* Added acceleration hinting for eval `in()` function.
+* Added the ability to share a template URL.
+* Added the ability to share results for Persistent Searches. 
+* Added a state filter to the Persistent Searches list page.
+* Added a Last 24h ingest total in Systems & Health.
+* Added a warning to Alerts to inform users if the alert owner does not have ingest capability.
+* Added unknown groups to the group permissions selector to inform user if his asset is shared by an admin with a group that the user does not have access to.
+* Added a warning acknowledgement for granting write access to automations.
+* Added buttons on License Upload page to navigate if license has already been uploaded. 
+* Added a default sort order to Kit assets.
+* Added the ability to set notification ID to 0 to allow duplicate notifications.
+* Implemented undo history with element filter requests in Query Studio.
+* Packaged the [Account Unlock](#account-unlock-tool) tool to ship with Gravwell tools.
+* Replaced Dashboard advanced editor with import/export buttons.
+* Replaced Dashboard autosaving with a save button.
+
+### Bug Fixes
+
+* Fixed syntax highlighting for special characters (double pipe, backtick, escaped quotes) in query editor.
+* Fixed an issue with passing non-string inputs to the eval `time()` function.
+* Fixed an issue with filter request logic in queries when field names needed quotes.
+* Fixed an issue where XML extractions were not being removed when they were not requested from AX.
+* Fixed an issue where gravlength would drop entries with missing EVs.
+* Fixed an issue where the Share Query URL in Query Studio would not update on zoom.
+* Fixed an issue where the overview chart would resize during live updates.
+* Fixed an issue with overview chart width sizing when re-sizing the browser window.
+* Fixed notifications to properly display body variable from Flows Notification node.
+* Fixed an issue with the Flows Resource node that caused memory exhaustion.
+* Fixed an issue accessing Alerts by GUID for nonexistent users.
+* Fixed an issue where Alert simple schema validation could not be scrolled.
+* Fixed an issue with uploading a Kit with an overlapping Resource.
+* Fixed an issue where a malformed Dashboard would continually send PUT requests.
+* Fixed an issue where adding to a Dashboard from Query Studio could be overwritten by Dashboard data open in another tab.
+* Fixed an issue where the ignore changes button would actually save changes in Dashboards.
+* Fixed an issue where creating a new Dashboard tile pointing at an existing search would duplicate the search. 
+* Fixed an issue where a Dashboard tile could cover the settings button if live update was enabled.
+* Fixed an issue where the save button in Dashboard settings may cover other text.
+* Fixed an issue where SSO login may fail to redirect to home page for user that previously logged in and logged out. 
+* Fixed an issue with webserver startup when an indexer is down.
+* Fixed an issue with rapid unplanned ageout.
+* Fixed an issue with chart rendering in Systems & Health when browser is zoomed.
+* Improved performance for getting Systems & Health stats.
+* Improved display of Systems & Health calendar to better understand ingestion of historical data.
+* Improved validation for live update interval in Dashboards.
+* Removed logic for creating directories when running the `-validate` command for well configuration. Running `-validate` should only inform the user.
+
+## Ingester Changes
+
+### Additions
+
+* Added a custom endpoint option for the Kinesis ingester.
+
+### Bug Fixes
+
+* Updated HTTP ingester systemd service to remove unnecessary PIDFile setting to squash possible error message.

changelog/list.md

@@ -7,7 +7,7 @@
 maxdepth: 1
 caption: Current Release
 ---
-5.4.11 <5.4.11>
+5.5.0 <5.5.0>
 ```
 
 ## Previous Versions
@@ -18,6 +18,7 @@ maxdepth: 1
 caption: Previous Releases
 ---
 
+5.4.11 <5.4.11>
 5.4.10 <5.4.10>
 5.4.9 <5.4.9>
 5.4.8 <5.4.8>

conf.py

@@ -21,7 +21,7 @@
 project = "Gravwell"
 copyright = f"Gravwell, Inc. {date.today().year}"
 author = "Gravwell, Inc."
-release = "v5.4.11"
+release = "v5.5.0"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

configuration/hardening.md

@@ -42,7 +42,7 @@ Gravwell users and groups loosely follow the Unix patterns.  At a high level, Gr
 
 User and group management is the sole responsibility of admin users. Non-admins cannot modify users or change user group memberships.
 
-## Default Accounts
+### Default Accounts
 
 Default Gravwell installations have a single user named `admin` with the password `changeme`.  This default account uses the coveted UID of 1.  Gravwell treats UID 1 in the same way that Unix treats UID 0.  It is special and cannot be deleted, locked, or otherwise disabled.  You should protect this account carefully!
 
@@ -56,6 +56,10 @@ Gravwell uses the [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) hashing system
 
 We start with a pretty aggressive bcrypt hash cost of 12 and routinely re-evaluate whether we need to increase that cost. 
 
+## Enforcing MFA
+
+[Requiring MFA](/configuration/mfa/mfa) will force all Gravwell users (except [SSO](/configuration/sso) users, who authenticate separately) to configure a second authentication method for login, e.g. an authenticator app. This makes brute-forcing logins essentially impossible and is highly recommended if the Gravwell server is exposed to the Internet.
+
 ## Installation Components
 
 By default, Gravwell is installed in `/opt/gravwell`.  The installers create the user and group `gravwell`:`gravwell`.  Neither the user nor the group is installed with login privileges.  All components execute under the `gravwell` user, and almost all execute under the `gravwell` group.

configuration/mfa/mfa.md

@@ -0,0 +1,97 @@
+# Multi-Factor Authentication
+
+Gravwell supports Multi-Factor Authentication, also known as Two-Factor Authentication, for added security on local (non-SSO) accounts. When enabled, users must provide their password *and* a valid additional factor (either a [TOTP](https://en.wikipedia.org/wiki/Time-based_one-time_password) "authenticator app" code or a recovery code) to login.
+
+As of Gravwell 5.5.0, any user may choose to enable MFA for their account, or administrators may require it explicitly.
+
+## Requiring MFA
+
+To require all users to configure and use MFA, add the following line to the `[Global]` block of your webserver's `gravwell.conf`:
+
+```
+MFA-Required=true
+```
+
+Then restart the webserver:
+
+```
+sudo systemctl restart gravwell_webserver.service
+```
+
+## Configuring MFA
+
+If MFA is required, users will be prompted to set it up the next time they log in:
+
+![](mfa-login-setup.png)
+
+Those who use authenticator apps on their smartphones can simply scan the QR code to set it up; users of PC-based systems such as KeePassXC will need to click "Or enter code manually" and copy the code into their authenticator program by hand.
+
+Once the authenticator is set up, use it to get a one-time code and enter it into the verification field, then click "Verify". Assuming everything was configured correctly, the login process will complete and a list of one-time-use recovery codes will be displayed:
+
+![](mfa-setup-recovery.png)
+
+These should be printed or copied to a secure place; they can be used in the future if the user loses access to their authenticator application.
+
+## Logging in with MFA
+
+Once MFA has been configured, logging in will include an additional step. Once the user has entered their username and password, a second dialog will be displayed prompting for an authentication code. By default, it will expect a code from the authentication app:
+
+![](login-mfa-totp.png)
+
+Clicking "Try another way" gives a menu of other MFA options the user may try:
+
+![](try-another-way.png)
+
+If "Recovery code" is selected, the user will then be prompted to enter one of the single-use recovery codes generated during MFA setup:
+
+![](recovery-code.png)
+
+## Modifying MFA Configuration
+
+The Security tab of the user account page provides options for setting up or modifying MFA configurations:
+
+![](user-mfa.png)
+
+In the screenshot above, a notification informs the user that at least one form of MFA is required. The user is allowed to delete the authenticator application (TOTP) configuration, because they still have 20 remaining recovery codes -- although this is not a good idea, it is permitted to log in using recovery codes each time.
+
+If MFA is not *required*, the user may click the Reset button to disable all forms of MFA on their account.
+
+### Reconfiguring Auth App (TOTP)
+
+Clicking "Edit" on the Authenticator Application section will first prompt the user to re-authenticate for security:
+
+![](totp-edit.png)
+
+Then the auth application configuration dialog will be shown again:
+
+![](totp-reconfigure.png)
+
+```{note}
+Entering this dialog generates a *new* secret key for TOTP authentication. If you complete the process, any previously-configured authentication apps will stop working. Clicking "Go back" will cancel the process and preserve any existing configurations.
+```
+
+### Regenerating Recovery Codes
+
+Clicking "Regenerate" on the Recovery Codes section will first prompt the user to make sure they wish to regenerate their codes:
+
+![](regenerate-confirm.png)
+
+Then it will require the user to fully authenticate themself for security:
+
+![](totp-edit.png)
+
+Once the user authenticates, a new set of recovery codes will be generated and displayed to the user:
+
+![](mfa-setup-regenerated.png)
+
+## Admin Actions
+
+Administrators can reset a user's MFA configuration from the Security tab of the user editor (found under the Administrator > Users menu):
+
+![](admin-mfa-reset.png)
+
+Selecting the checkbox and clicking "Save" on the page will fully reset the user's MFA configuration. If MFA is required on the system, the user will be prompted to reconfigure MFA at their next login.
+
+```{note}
+In general, it is best to let users manage their own MFA configuration, but an administrative reset may be necessary if a user loses their recovery codes and cannot log in.
+```

configuration/parameters.md

@@ -674,6 +674,18 @@ Default Value:	false
 Example:	`Disable-Indexer-Overload-Warning=true`  
 Description: If this parameter is set, the indexer will not send notifications when it considers itself 'overloaded'.
 
+### **MFA-Required**
+Applies to: Webserver
+Default Value: false
+Example: `MFA-Required=true`
+Description: If set to true, all local (non-SSO) users will be required to configure and use MFA for authentication.
+
+### **MFA-Issuer-Name**
+Applies to: Webserver
+Default Value: Gravwell
+Example: `MFA-Issuer-Name="BigCo Gravwell Cluster"`
+Description: Sets the "issuer" field for TOTP MFA authentication. This controls the name which will appear in your authentication application. The default, "Gravwell", is suitable for most cases.
+
 ## Password Control
 
 The `[Password-Control]` configuration section can be used to enforce password complexity rules when users are created or passwords are changed. Options set in this block apply only to webservers. These complexity configuration rules do not apply when using Single Sign On.