fix conflicts in docs about unified_logs vs macadmins_unified_logs (#9214)

As raised by a community member in [Slack](https://osquery.slack.com/archives/C01DXJL16D8/p1672751794862639), this updates our documentation to account for both `unified_log` and `macadmins_unified_log`. Per my testing, it should also help with the #9158 bug in Fleet's UI. I have updated the columns of `macadmins_unified_log` according to what's in the [source code](https://github.com/macadmins/osquery-extension/blob/50f94d0d7001c048e0a5564911e46d1952420a80/tables/unifiedlog/unified_log.go#L47-L69), and modified the example to work. Since I was there I have also updated the osquery version we use to pull the JSON to `5.6.0` and fixed a small bug related to the examples we pull from there. . . . . . . . Co-authored-by: Mike McNeil <mikermcneil@users.noreply.github.com>
2023-01-10 17:45:53 -06:00
parent 93f39f40c2
commit 5919931a4c
4 changed files with 3703 additions and 787 deletions
@@ -0,0 +1,82 @@
+name: macadmins_unified_log
+notes: Requires [macadmins-extension](https://github.com/macadmins/osquery-extension/), which is included by default on osquery packages built with [fleetctl](https://fleetdm.com/docs/using-fleet/adding-hosts#osquery-installer).
+description: Allows querying macOS [unified logs](https://developer.apple.com/documentation/os/logging).
+platforms: darwin
+evented: false
+examples: >-
+  Select the log entries that happened during the last minute and are related to `LaunchServices`. Convert the UNIX time to a human readable format,  and the signature table to verify its cryptographic signature.
+
+  ```
+  
+  SELECT u.category, u.event_message, u.process_id, datetime(u.timestamp, 'unixepoch') AS human_time, p.path, s.signed, s.identifier, s.authority FROM macadmins_unified_log u JOIN processes p ON u.process_id = p.pid JOIN signature s ON p.path = s.path WHERE u.sender_image_path LIKE '%LaunchServices%' AND last = "1m";
+  
+  ```
+columns:
+  - name: trace_id
+    description: The ID of a trace event
+    required: false
+    type: string
+  - name: event_type
+    description: The type of event, this can be logEvent, signpostEvent or stateEvent.
+    required: false
+    type: string
+  - name: format_string
+    description: The format string used to convert variable content into a string for output.
+    required: false
+    type: string
+  - name: activity_identifier
+    description: The identifier of the log activity.
+    required: false
+    type: int
+  - name: subsystem
+    description: The subsystem responsible for this activity.
+    required: false
+    type: text
+  - name: category
+    description: The category of the log activity.
+    required: false
+    type: text
+  - name: thread_id
+    description: The ID of the thread that originated the event.
+    required: false
+    type: bigint
+  - name: sender_image_uuid
+    description: The UUID of the library, framework, kernel extension, or mach-o image, that originated the event.
+    required: false
+    type: string
+  - name: sender_image_path
+    description: The full path of the library, framework, kernel extension, or mach-o image, that originated the event.
+    required: false
+    type: string
+  - name: boot_uuid
+    description: The boot UUID of the event.
+    required: false
+    type: string
+  - name: process_id
+    description: Process ID of the process that generated this log item, which can be joined to multiple other tables including a *PID*.
+    required: false
+    type: bigint
+  - name: process_image_path
+    description: The full path of the process that originated the event.
+    required: false
+    type: string
+  - name: timestamp
+    description: Timestamp in [UNIX time format](https://en.wikipedia.org/wiki/Unix_time).
+    required: false
+    type: bigint
+  - name: event_message
+    description: The message of the log entry.
+    required: false
+    type: string
+  - name: sender_program_counter
+    description: The program counter of the library, framework, kernel extension, or mach-o image, that originated the event.
+    required: false
+    type: uint
+  - name: parent_activity_identifier
+    description: ID of the parent activity
+    required: false
+    type: uint
+  - name: log_level
+    description: The log level of this item, such as `default`, `info`, `fault`, etc.
+    required: false
+    type: text
@@ -1,59 +0,0 @@
-name: unified_log
-notes: Requires [macadmins-extension](https://github.com/macadmins/osquery-extension/), which is included by default on osquery packages built with [fleetctl](https://fleetdm.com/docs/using-fleet/adding-hosts#osquery-installer).
-description: Allows querying macOS [unified logs](https://developer.apple.com/documentation/os/logging).
-platforms: darwin
-evented: false
-examples: >-
-  Select the latest 100 log items related to `LaunchServices` and convert the UNIX time to a human readable format,  and the signature table to verify its cryptographic signature.
-
-  ```
-  
-  SELECT u.category, u.level, u.message, u.pid, datetime(u.timestamp, 'unixepoch') AS human_time, p.path, s.signed, s.identifier, s.authority FROM unified_log u JOIN processes p ON u.pid = p.pid JOIN signature s ON p.path=s.path WHERE sender='LaunchServices' LIMIT 100;  
-  
-  ```
-columns:
-  - name: activity
-    description: The identifier of the log activity.
-    required: false
-    type: text
-  - name: category
-    description: The category of the log activity.
-    required: false
-    type: text
-  - name: level
-    description: The log level of this item, such as `default`, `info`, `fault`, etc.
-    required: false
-    type: text
-  - name: message
-    description: The log message.
-    required: false
-    type: text
-  - name: pid
-    description: Process ID of the process that generated this log item, which can be joined to multiple other tables including a *PID*.
-    required: false
-    type: bigint
-  - name: process
-    description: Name of the process that generated this log activity.
-    required: false
-    type: text
-  - name: sender
-    description: System that sent this activity.
-    required: false
-    type: text
-  - name: storage
-    description: TBD.
-    required: false
-    type: text
-  - name: subsystem
-    description: The subsystem responsible for this activity.
-    required: false
-    type: text
-  - name: tid
-    description: TBD.
-    required: false
-    type: bigint
-  - name: timestamp
-    description: Timestamp in [UNIX time format](https://en.wikipedia.org/wiki/Unix_time).
-    required: false
-    type: bigint
-  
@@ -23,7 +23,7 @@ module.exports = {
    let YAML = require('yaml');
    let topLvlRepoPath = path.resolve(sails.config.appPath, '../');

-    let VERSION_OF_OSQUERY_SCHEMA_TO_USE = '5.4.0';
+    let VERSION_OF_OSQUERY_SCHEMA_TO_USE = '5.6.0';
    // Getting the specified osquery schema from the osquery/osquery-site GitHub repo.
    let rawOsqueryTables = await sails.helpers.http.get('https://raw.githubusercontent.com/osquery/osquery-site/source/src/data/osquery_schema_versions/'+VERSION_OF_OSQUERY_SCHEMA_TO_USE+'.json');

@@ -73,6 +73,21 @@ module.exports = {

        expandedTableToPush.fleetRepoUrl = 'https://github.com/fleetdm/fleet/new/main/schema/tables/?filename='+encodeURIComponent('/tables/'+expandedTableToPush.name)+'.yml&value='+encodeURIComponent(sampleYamlSchemaForThisTable);

+        // As the table might have multiple examples, we grab only one until we
+        // adjust the UI to better display multiple examples (paddings, UX,
+        // etc.)
+        //
+        // We pick the last example in the array as they progressively build in
+        // complexity and the last is usually the richest.
+        //
+        // TODO: adjust the UI to show all examples.
+        let examplesFromOsquerySchema = expandedTableToPush.examples;
+        if (examplesFromOsquerySchema.length > 0) {
+          // Examples are parsed as markdown, so we wrap the example in a code
+          // fence so it renders as a code block.
+          expandedTableToPush.examples = '```\n' + examplesFromOsquerySchema[examplesFromOsquerySchema.length - 1] + '\n```';
+        }
+
        expandedTables.push(expandedTableToPush);
      } else { // If this table exists in the Fleet overrides schema, we'll override the values
        if(fleetOverridesForTable.platforms !== undefined) {