Placeholder fields and Osquery UI updates (#3045)

Co-authored-by: Joe Peeples <[email protected]> Co-authored-by: Benjamin Ironside Goldstein <[email protected]> Co-authored-by: Janeen Mikell Roberts <[email protected]>
elastic · Mar 28, 2023 · 2cf53b7 · 2cf53b7
1 parent 3c52d03
commit 2cf53b7
Show file tree

Hide file tree

Showing 5 changed files with 41 additions and 1 deletion.
diff --git a/docs/osquery/alerts-run-osquery.asciidoc b/docs/osquery/alerts-run-osquery.asciidoc
@@ -23,6 +23,9 @@ NOTE: The host associated with the alert is automatically selected. You can spec
 
 . Specify the query or pack to run:
 ** *Query*: Select a saved query or enter a new one in the text box. After you enter the query, you can expand the **Advanced** section to view or set {kibana-ref}/osquery.html#osquery-map-fields[mapped ECS fields] included in the results from the live query. Mapping ECS fields is optional.
++
+TIP: Use <<osquery-placeholder-fields,placeholder fields>> to dynamically add existing alert data to your query. 
+
 ** *Pack*: Select from available query packs. After you select a pack, all of the queries in the pack are displayed.
 +
 TIP: Refer to {kibana-ref}/osquery.html#osquery-prebuilt-packs-queries[prebuilt packs] to learn about using and managing Elastic prebuilt packs.

diff --git a/docs/osquery/invest-guide-run-osquery.asciidoc b/docs/osquery/invest-guide-run-osquery.asciidoc
@@ -24,6 +24,9 @@ NOTE: You can only add Osquery to investigation guides for custom rules because
 . Scroll down to the Investigation guide section. In the toolbar, click the *Osquery* button (image:images/osquery-button.png[Click the Osquery button,20,20]).
 .. Add a descriptive label for the query; for example, `Search for executables`.
 .. Select a saved query or enter a new one.
++
+TIP: Use <<osquery-placeholder-fields,placeholder fields>> to dynamically add existing alert data to your query. 
+
 .. Expand the **Advanced** section to view or set {kibana-ref}/osquery.html#osquery-map-fields[mapped ECS fields] included in the results from the live query (optional).
 +
 [role="screenshot"]

diff --git a/docs/osquery/osquery-index.asciidoc b/docs/osquery/osquery-index.asciidoc
@@ -6,4 +6,6 @@ include::invest-guide-run-osquery.asciidoc[][leveloffset=+1]
 
 include::alerts-run-osquery.asciidoc[][leveloffset=+1]
 
-include::view-osquery-results.asciidoc[][leveloffset=+1]
+include::view-osquery-results.asciidoc[][leveloffset=+1]
+
+include::osquery-placeholder-fields.asciidoc[][leveloffset=+1]
diff --git a/docs/osquery/osquery-placeholder-fields.asciidoc b/docs/osquery/osquery-placeholder-fields.asciidoc
@@ -0,0 +1,29 @@
+[[osquery-placeholder-fields]]
+== Use placeholder fields in Osquery queries 
+
+Instead of hard-coding alert and event values into Osquery queries, you can use placeholder fields to dynamically pass this data into queries. Placeholder fields function like parameters. You can use placeholder fields to build flexible and reusable queries. 
+
+Placeholder fields work in single queries or query packs. They're also supported in the following features:
+
+* <<alerts-run-osquery,Live queries>>
+* <<osquery-response-action,Osquery Response Actions>>
++
+* <<invest-guide-run-osquery,Investigation guides using Osquery queries>> 
+
+[float]
+[[placeholder-field-syntax]]
+=== Placeholder field syntax and requirements
+
+Placeholder fields use http://mustache.github.io/[mustache syntax] and must be wrapped in double curly brackets (`{{example.field}}`). You can use any field within an event or alert document as a placeholder field. 
+
+Queries with placeholder fields can only run against alerts or events. Otherwise, they will lack the necessary values and the query status will be `error`. 
+
+[float]
+[[placeholder-field-example]]
+==== Example query with a placeholder field
+
+The following query uses the `{{host.name}}` placeholder field: 
+
+`SELECT * FROM os_version WHERE name = `{{host.os.name}}``
+
+When you run the query, the value that's stored in the alert or event's `host.name` field will be transferred to the `{{host.os.name}}` placeholder field. 
diff --git a/docs/osquery/osquery-response-action.asciidoc b/docs/osquery/osquery-response-action.asciidoc
@@ -27,6 +27,9 @@ You can add Osquery Response Actions to new or existing custom query rules. Quer
 ** *Existing rule*: Edit the rule's settings, then go to the *Actions* tab. In the tab, click the *osquery* icon under the Response Actions section.
 . Specify whether you want to set up a single live query or a pack:
 ** *Query*: Select a saved query or enter a new one. After you enter the query, you can expand the **Advanced** section to view or set {kibana-ref}/osquery.html#osquery-map-fields[mapped ECS fields] included in the results from the live query. Mapping ECS fields is optional.
++
+TIP: You can use <<osquery-placeholder-fields,placeholder fields>> to dynamically add alert data to your query. 
+
 ** *Pack*: Select from available query packs. After you select a pack, all of the queries in the pack are displayed.
 +
 TIP: Refer to {kibana-ref}/osquery.html#osquery-prebuilt-packs-queries[prebuilt packs] to learn about using and managing Elastic prebuilt packs.