From e644f5333520fc46e936ceb9c09329f6dee1da5e Mon Sep 17 00:00:00 2001 From: Noah Talerman <47070608+noahtalerman@users.noreply.github.com> Date: Wed, 26 Jun 2024 16:48:58 -0400 Subject: [PATCH] Update docs: Webhooks for global activity (#19863) Docs for the "Webhooks for global activity feed" story (#14722) - Add item to permissions table - Clean up and simplify Audit logs top section. It's a reference page - Link to Audit logs reference from Automations page --- docs/Using Fleet/Audit-logs.md | 34 +--------- docs/Using Fleet/Automations.md | 6 ++ docs/Using Fleet/Understanding-host-vitals.md | 63 ++++++++++++++++--- docs/Using Fleet/manage-access.md | 1 + server/fleet/gen_activity_doc.go | 34 +--------- 5 files changed, 66 insertions(+), 72 deletions(-) diff --git a/docs/Using Fleet/Audit-logs.md b/docs/Using Fleet/Audit-logs.md index 05f64a0c5b..ab16e6970d 100644 --- a/docs/Using Fleet/Audit-logs.md +++ b/docs/Using Fleet/Audit-logs.md @@ -1,39 +1,11 @@ # Audit logs -Fleet logs the following information for administrative activities (in JSON): +Fleet logs activities. -- `created_at`: Timestamp of the event. -- `id`: Unique ID of the generated event in Fleet. -- `actor_full_name`: Author user name (missing if the user was deleted). -- `actor_id`: Unique ID of the author in Fleet (missing if the user was deleted). -- `actor_gravatar`: Gravatar URL of the author (missing if the user was deleted). -- `actor_email`: E-mail of the author (missing if the user was deleted). -- `type`: Type of the activity (see all types below). -- `details`: Specific details depending on the type of activity (see details for each activity type below). +To see activities in Fleet, select the Fleet icon in the top navigation and see the **Activity** section. -Example: -```json -{ - "created_at": "2022-12-20T14:54:17Z", - "id": 6, - "actor_full_name": "Gandalf", - "actor_id": 2, - "actor_gravatar": "foo@example.com", - "actor_email": "foo@example.com", - "type": "edited_saved_query", - "details":{ - "query_id": 42, - "query_name": "Some query name" - } -} -``` - -You can automatically send these logs to your log destination. Learn how to configure this [here](https://fleetdm.com/docs/configuration/fleet-server-configuration#external-activity-audit-logging). - -To view activities in the UI, click the Fleet icon in the top navigation bar and locate the **Activity** section. - -Following is a summary of the types of administrative activities logged by Fleet: +This page includes a list of activities. ## created_pack diff --git a/docs/Using Fleet/Automations.md b/docs/Using Fleet/Automations.md index 12d6e0b524..9666024d48 100644 --- a/docs/Using Fleet/Automations.md +++ b/docs/Using Fleet/Automations.md @@ -4,6 +4,12 @@ You can configure Fleet to trigger automations that reserve time in your end use To learn how to use Fleet's maintenance windows, head to this [article](https://fleetdm.com/announcements/fleet-in-your-calendar-introducing-maintenance-windows). +## Activity automations + +Activity automations are triggered when an activity happens in Fleet (queries, scripts, logins, etc). See a list of all activities [here](https://fleetdm.com/docs/using-fleet/audit-logs). + +You can automatically send activites to a webhook URL or a [log destination](https://fleetdm.com/docs/configuration/fleet-server-configuration#external-activity-audit-logging). + ## Policy automations Policy automations are triggered if a policy is newly failing on at least one host. diff --git a/docs/Using Fleet/Understanding-host-vitals.md b/docs/Using Fleet/Understanding-host-vitals.md index 5fd09052be..77b9e68ca9 100644 --- a/docs/Using Fleet/Understanding-host-vitals.md +++ b/docs/Using Fleet/Understanding-host-vitals.md @@ -85,7 +85,7 @@ FROM logical_drives WHERE file_system = 'NTFS' LIMIT 1; - Discovery query: ```sql -SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'google_chrome_profiles'; +SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'google_chrome_profiles' ``` - Query: @@ -99,7 +99,7 @@ SELECT email FROM google_chrome_profiles WHERE NOT ephemeral AND email <> '' - Discovery query: ```sql -SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'kubernetes_info'; +SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'kubernetes_info' ``` - Query: @@ -113,7 +113,7 @@ SELECT * from kubernetes_info - Discovery query: ```sql -SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'mdm'; +SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'mdm' ``` - Query: @@ -127,7 +127,7 @@ select enrolled, server_url, installed_from_dep, payload_identifier from mdm; - Discovery query: ```sql -SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'macos_profiles'; +SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'macos_profiles' ``` - Query: @@ -141,7 +141,7 @@ SELECT display_name, identifier, install_date FROM macos_profiles where type = " - Discovery query: ```sql -SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'filevault_prk'; +SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'filevault_prk' ``` - Query: @@ -216,7 +216,7 @@ WITH registry_keys AS ( - Discovery query: ```sql -SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'munki_info'; +SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'munki_info' ``` - Query: @@ -315,7 +315,7 @@ LIMIT 1; - Discovery query: ```sql -SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'orbit_info'; +SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'orbit_info' ``` - Query: @@ -674,13 +674,56 @@ SELECT FROM homebrew_packages; ``` +## software_macos_firefox + +- Description: A software override query[^1] to differentiate between Firefox and Firefox ESR on macOS. Requires `fleetd` + +- Platforms: darwin + +- Discovery query: +```sql +SELECT 1 WHERE EXISTS (SELECT 1 FROM apps WHERE bundle_identifier = 'org.mozilla.firefox' LIMIT 1) AND EXISTS (SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'parse_ini') +``` + +- Query: +```sql +WITH app_paths AS ( + SELECT path + FROM apps + WHERE bundle_identifier = 'org.mozilla.firefox' + ), + remoting_name AS ( + SELECT value, path + FROM parse_ini + WHERE key = 'RemotingName' + AND path IN (SELECT CONCAT(path, '/Contents/Resources/application.ini') FROM app_paths) + ) + SELECT + CASE + WHEN remoting_name.value = 'firefox-esr' THEN 'Firefox ESR.app' + ELSE 'Firefox.app' + END AS name, + COALESCE(NULLIF(apps.bundle_short_version, ''), apps.bundle_version) AS version, + 'Application (macOS)' AS type, + apps.bundle_identifier AS bundle_identifier, + '' AS extension_id, + '' AS browser, + 'apps' AS source, + '' AS vendor, + apps.last_opened_time AS last_opened_at, + apps.path AS installed_path + FROM apps + LEFT JOIN remoting_name ON apps.path = REPLACE(remoting_name.path, '/Contents/Resources/application.ini', '') + WHERE apps.bundle_identifier = 'org.mozilla.firefox' +``` + ## software_vscode_extensions - Platforms: linux, ubuntu, debian, rhel, centos, sles, kali, gentoo, amzn, pop, arch, linuxmint, void, nixos, endeavouros, manjaro, opensuse-leap, opensuse-tumbleweed, tuxedo, darwin, windows - Discovery query: ```sql -SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'vscode_extensions'; +SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'vscode_extensions' ``` - Query: @@ -825,7 +868,7 @@ SELECT uid, username, email FROM users - Discovery query: ```sql -SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'windows_update_history'; +SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND name = 'windows_update_history' ``` - Query: @@ -833,6 +876,6 @@ SELECT 1 FROM osquery_registry WHERE active = true AND registry = 'table' AND na SELECT date, title FROM windows_update_history WHERE result_code = 'Succeeded' ``` - +

[^1]: Software override queries write over the default queries. They are used to populate the software inventory. \ No newline at end of file diff --git a/docs/Using Fleet/manage-access.md b/docs/Using Fleet/manage-access.md index 90655ea260..fa4a241af6 100644 --- a/docs/Using Fleet/manage-access.md +++ b/docs/Using Fleet/manage-access.md @@ -36,6 +36,7 @@ GitOps is an API-only and write-only role that can be used on CI/CD pipelines. | **Action** | Observer | Observer+* | Maintainer | Admin | GitOps* | | ------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ---------- | ---------- | ----- | ------- | | View all [activity](https://fleetdm.com/docs/using-fleet/rest-api#activities) | ✅ | ✅ | ✅ | ✅ | | +| Manage [activity automations](https://fleetdm.com/docs/using-fleet/audit-logs) | | | | ✅ | ✅ | | View all hosts | ✅ | ✅ | ✅ | ✅ | | | View a host by identifier | ✅ | ✅ | ✅ | ✅ | ✅ | | Filter hosts using [labels](https://fleetdm.com/docs/using-fleet/rest-api#labels) | ✅ | ✅ | ✅ | ✅ | | diff --git a/server/fleet/gen_activity_doc.go b/server/fleet/gen_activity_doc.go index 4adde51d6b..d71c8fa371 100644 --- a/server/fleet/gen_activity_doc.go +++ b/server/fleet/gen_activity_doc.go @@ -17,39 +17,11 @@ func main() { b.WriteString(` # Audit logs -Fleet logs the following information for administrative activities (in JSON): +Fleet logs activities. -- ` + "`" + `created_at` + "`" + `: Timestamp of the event. -- ` + "`" + `id` + "`" + `: Unique ID of the generated event in Fleet. -- ` + "`" + `actor_full_name` + "`" + `: Author user name (missing if the user was deleted). -- ` + "`" + `actor_id` + "`" + `: Unique ID of the author in Fleet (missing if the user was deleted). -- ` + "`" + `actor_gravatar` + "`" + `: Gravatar URL of the author (missing if the user was deleted). -- ` + "`" + `actor_email` + "`" + `: E-mail of the author (missing if the user was deleted). -- ` + "`" + `type` + "`" + `: Type of the activity (see all types below). -- ` + "`" + `details` + "`" + `: Specific details depending on the type of activity (see details for each activity type below). +To see activities in Fleet, select the Fleet icon in the top navigation and see the **Activity** section. -Example: -` + "```" + `json -{ - "created_at": "2022-12-20T14:54:17Z", - "id": 6, - "actor_full_name": "Gandalf", - "actor_id": 2, - "actor_gravatar": "foo@example.com", - "actor_email": "foo@example.com", - "type": "edited_saved_query", - "details":{ - "query_id": 42, - "query_name": "Some query name" - } -} -` + "```" + ` - -You can automatically send these logs to your log destination. Learn how to configure this [here](https://fleetdm.com/docs/configuration/fleet-server-configuration#external-activity-audit-logging). - -To view activities in the UI, click the Fleet icon in the top navigation bar and locate the **Activity** section. - -Following is a summary of the types of administrative activities logged by Fleet: +This page includes a list of activities. `)