4.61 documentation changes (#24833)

Co-authored-by: Ian Littman <[email protected]> Co-authored-by: Zach Wasserman <[email protected]> Co-authored-by: Lucas Manuel Rodriguez <[email protected]> Co-authored-by: Konstantin Sykulev <[email protected]> Co-authored-by: Marko Lisica <[email protected]> Co-authored-by: Noah Talerman <[email protected]>
fleetdm · Dec 17, 2024 · c4a2bb4 · c4a2bb4
1 parent ce8bcaa
commit c4a2bb4
Show file tree

Hide file tree

Showing 9 changed files with 197 additions and 43 deletions.
diff --git a/articles/fleet-usage-statistics.md b/articles/fleet-usage-statistics.md
@@ -17,6 +17,7 @@ Below is the JSON payload that is sent to Fleet Device Management Inc:
   "numHostsEnrolled": 999,
   "numUsers": 999,
   "numTeams": 999,
+  "numQueries": 999,
   "numPolicies": 999,
   "numQueries": 999,
   "numLabels": 999,

diff --git a/articles/fleetctl.md b/articles/fleetctl.md
@@ -102,9 +102,9 @@ Password:
 
 Once your local context is configured, you can use fleetctl normally.
 
-### Log in with SAML (SSO) authentication
+#### Users with single sign-on (SSO) or email two-factor authentication (2FA)
 
-Users that authenticate to Fleet via SSO should retrieve their API token from the UI and manually set it in their fleetctl configuration (instead of logging in via `fleetctl login`).
+Users that log into Fleet with SSO or email 2FA can't log in with `fleetctl login`. Instead they can retrieve their API token from the UI and manually set it in their fleetctl configuration (instead of logging in via `fleetctl login`).
 
 **Fleet UI:**
 1. Go to the **My account** page (https://fleet.example.com/profile)

diff --git a/articles/remote-yara-rules.md b/articles/remote-yara-rules.md
@@ -0,0 +1,91 @@
+# Remote deployment of YARA rules
+
+Fleetd with osquery can scan files using
+[YARA](https://virustotal.github.io/yara/), a matching engine particularly useful for
+identifying malicious patterns in binary files. The rule contents have typically been provided
+either through files placed on the filesystem, or in unauthenticated HTTP endpoints such as public
+GitHub repositories.
+
+We heard concerns from customers about making the rules publically available, so in osquery 5.14
+we [added the capability](https://github.com/osquery/osquery/pull/8437) for osquery to make
+authenticated requests for YARA rules. Fleet is (as of this writing) the only osquery HTTP server
+implementation that supports serving authenticated YARA rules.
+
+In this guide we demonstrate how to configure the agent and server to use this more secure remote
+YARA functionality. This is supported for live queries and saved queries to the
+[`yara`](https://fleetdm.com/tables/yara) table.
+
+## Configuration
+
+Configuration is performed in 3 steps.
+
+1) Configure agent options to enable authenticated requests to the Fleet server.
+2) Configure YARA rules in Fleet.
+3) Use YARA rules in queries.
+
+### 1 - Agent options
+
+Configure agent options to enable YARA rule request authentication in osquery and allowlist requests
+to the Fleet server. This can be perfomed via the Fleet UI, GitOps, or the API. Set the agent
+options as below, replacing `FLEET_SERVER_URL` with the URL of your Fleet server (eg.
+`example.fleetdm.com`):
+
+```
+config:
+  options:
+    # other options omitted
+    yara_sigurl_authenticate: true # "on" switch for using YARA rules in Fleet
+  yara:
+    signature_urls:
+    - https://<FLEET_SERVER_URL>/api/osquery/yara/.*  # (Fleet server URL) Also required for using YARA rules in Fleet
+ ```
+
+ ### 2 - YARA rules
+
+ Provide YARA rules to Fleet that will be served to agents. This can be performed via GitOps, or the
+ API. Reference each rule file by path under the main `org_settings` configuration. In this example,
+ we assume the rule files are in a `/lib/` subdirectory. This is a directory structure like the
+ [Fleet GitOps recommendations](https://github.com/fleetdm/fleet-gitops).
+
+```
+org_settings:
+  yara_rules:
+    - path: ./lib/rule1.yar
+    - path: ./lib/rule2.yar
+```
+
+Apply this configuration with `fleetctl apply` or with your GitOps CI job.
+
+Because rules are stored as separate files in the repository, other tools like
+[YARA-CI](https://yara-ci.cloud.virustotal.com/) may be used before applying the rules to Fleet.
+
+### 3 - Use in queries
+
+Now the provided rules may be referenced in queries utilizing the `yara` table. Rules are available at
+`https://<FLEET_SERVER_URL>/api/osquery/yara/<RULE_FILENAME>`. For example:
+
+```
+SELECT * FROM yara WHERE path="/bin/ls" AND sigurl='https://example.fleetdm.com/api/osquery/yara/rule1.yar'
+```
+
+This works for both live and saved queries. Each time osquery runs the query, an authenticated HTTP
+request will be made to the Fleet server requesting the referenced rule(s).
+
+## Targeting rules with teams (Fleet Premium)
+
+It is often desirable to run different sets of YARA rules on different devices within the
+organization. To achieve this, target the _queries_ to the desired team.
+
+For example, with `rule1.yar` and `rule2.yar` configured in the `org_settings`:
+
+1. Ensure the agent options are configured for "No team" and/or the desired teams.
+
+2. Target queries to the appropriate team, referencing the desired rules. For example, target a
+   query referencing `rule1.yar` to the "Workstations" team and a query referencing `rule2.yar` to
+   the Servers team.
+
+<meta name="authorGitHubUsername" value="zwass">
+<meta name="authorFullName" value="Zach Wasserman">
+<meta name="publishedOn" value="2024-12-09">
+<meta name="articleTitle" value="Remote deployment of YARA rules">
+<meta name="category" value="guides">
diff --git a/docs/Configuration/fleet-server-configuration.md b/docs/Configuration/fleet-server-configuration.md
@@ -1856,6 +1856,9 @@ By default, the SMTP backend is enabled and no additional configuration is requi
 SMTP through the [Fleet console UI](https://fleetdm.com/docs/using-fleet/configuration-files#smtp-settings). However, you can also
 configure Fleet to use AWS SES natively rather than through SMTP.
 
+A configured email backend is required for sending user invites, resetting passwords, verifying user email address changes,
+and multi-factor authentication within Fleet (without using an SSO identity provider).
+
 ### backend
 
 Enable SES support for Fleet. You must also configure the ses configurations such as `ses.source_arn`

diff --git a/docs/Configuration/yaml-files.md b/docs/Configuration/yaml-files.md
@@ -384,7 +384,7 @@ org_settings:
 
 ### fleet_desktop
 
-Direct end users to a custom URL when they select **Transparency** in the Fleet Desktop dropdown (default: [https://fleetdm.com/transparency](https://fleetdm.com/transparency)).
+Direct end users to a custom URL when they select **About Fleet** in the Fleet Desktop dropdown (default: [https://fleetdm.com/transparency](https://fleetdm.com/transparency)).
 
 Can only be configured for all teams (`org_settings`).
 
@@ -710,6 +710,26 @@ org_settings:
 
 Can only be configured for all teams (`org_settings`).
 
+#### yara_rules
+
+The `yara_rules` section lets you define [YARA rules](https://virustotal.github.io/yara/) that will be served by Fleet's authenticated
+YARA rule functionality. Learn more about authenticated YARA rules in Fleet
+[here](https://fleetdm.com/guides/remote-yara-rules).
+
+Each entry should be the relative path to a valid YARA rule file.
+
+##### Example
+
+```yaml
+org_settings:
+  yara_rules:
+    - path: ./lib/rule1.yar
+    - path: ./lib/rule2.yar
+```
+
+Can only be configured for all teams (`org_settings`). To target rules to specific teams, target the
+queries referencing the rules to the desired teams.
+
 <meta name="title" value="YAML files">
 <meta name="description" value="Reference documentation for Fleet's GitOps workflow. See examples and configuration options.">
 <meta name="pageOrderInSection" value="1500">
diff --git a/docs/Contributing/API-for-contributors.md b/docs/Contributing/API-for-contributors.md
@@ -1,5 +1,6 @@
 # API for contributors
 
+- [Authentication](#authentication)
 - [Packs](#packs)
 - [Mobile device management (MDM)](#mobile-device-management-mdm)
 - [Get or apply configuration files](#get-or-apply-configuration-files)
@@ -18,6 +19,22 @@ This document includes the internal Fleet API routes that are helpful when devel
 
 If you are interested in gathering information from Fleet in a production environment, please see the [public Fleet REST API documentation](https://fleetdm.com/docs/using-fleet/rest-api).
 
+## Authentication
+
+### Create session
+
+`POST /api/v1/fleet/sessions`
+
+#### Parameters
+
+| Name | Type | In | Description |
+| token | string | body | **Required**. The token retrieved from the magic link email. |
+
+#### Response
+
+See [the Log in endpoint](https://fleetdm.com/docs/rest-api/rest-api#log-in) for the current
+successful response format.
+
 ## Packs
 
 Scheduling queries in Fleet is the best practice for collecting data from hosts. To learn how to schedule queries, [check out the docs here](https://fleetdm.com/docs/using-fleet/fleet-ui#schedule-a-query).
@@ -2396,15 +2413,15 @@ Runs the specified saved query as a live query on the specified targets. Returns
 
 After the query has been initiated, [get results via WebSocket](#retrieve-live-query-results-standard-websocket-api).
 
-`POST /api/v1/fleet/queries/run_by_names`
+`POST /api/v1/fleet/queries/run_by_identifiers`
 
 #### Parameters
 
 | Name     | Type    | In   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | -------- | ------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | query    | string  | body | The SQL of the query.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | query_id | integer | body | The saved query (if any) that will be run. The `observer_can_run` property on the query effects which targets are included.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| selected | object  | body | **Required.** The object includes lists of selected hostnames (`selected.hosts`), label names (`labels`). When provided, builtin label names and custom label names become `AND` filters. Within each selector, selecting two or more builtin labels, or two or more custom labels, behave as `OR` filters. There's one special case for the builtin label `"All hosts"`, if such label is selected, then all other label and team selectors are ignored (and all hosts will be selected). If a host's hostname is explicitly included in `selected.hosts`, then it is assured that the query will be selected to run on it (no matter the contents of `selected.labels`). See examples below. |
+| selected | object  | body | **Required.** The object includes lists of selected hostnames (`selected.hosts`), label names (`labels`). When provided, builtin label names and custom label names become `AND` filters. Within each selector, selecting two or more builtin labels, or two or more custom labels, behave as `OR` filters. If a label provided could not be found in the database, a 400 bad request will be returned specifying which label is invalid. There's one special case for the builtin label `"All hosts"`, if such label is selected, then all other label and team selectors are ignored (and all hosts will be selected). If a host's hostname is explicitly included in `selected.hosts`, then it is assured that the query will be selected to run on it (no matter the contents of `selected.labels`). See examples below. |
 
 One of `query` and `query_id` must be specified.
 

diff --git a/docs/Get started/FAQ.md b/docs/Get started/FAQ.md
@@ -45,7 +45,7 @@ When you collect data with Fleet, the [performance impact](https://fleetdm.com/r
 
 You can test changes on a small subset of hosts first, then roll them out to the rest of your organization.
 
-## What browsers does Fleet supported?
+## What browsers does Fleet support?
 
 Fleet supports the latest, stable releases of all major browsers and platforms.