[DOCS] Update osquery page for changes in 7.16 #117031

melissaburpo · 2021-11-01T21:00:24Z

Summary

This PR updates the Osquery doc for the 7.16 release. For details of the updates, see the related issue below.

Preview:
https://kibana_117031.docs-preview.app.elstc.co/guide/en/kibana/master/osquery.html

Related issue

[DOCS] Add the 7.16 Osquery docs #116969

…s, and ECS mapping

…tom tables, and other copy edits

melissaburpo · 2021-11-01T23:12:36Z

Hi @aleksmaus, @patrykkopycinski, @james-elastic - this is an early draft of doc changes for 7.16. Can you all please do a technical review, before we pass it off to the docs team for some more general edits? Thanks for any feedback!

docs/osquery/osquery.asciidoc

…e other minor copy edits

melissaburpo · 2021-11-10T00:30:52Z

Hi @gchaps - There may be a few more minor changes coming, but overall, I think this is ready for review!

A few questions:

Should I add any other Kibana writers to the review?
Can you confirm whether I've applied the correct labels to this PR? I want to make sure this update is included for the 7.16 release docs as well as going forward into 8.0.

Thanks for any tips!

elasticmachine · 2021-11-10T00:34:07Z

Pinging @elastic/kibana-docs (Team:Docs)

gchaps · 2021-11-10T00:39:54Z

@elasticmachine merge upstream

gchaps · 2021-11-11T17:37:23Z

docs/osquery/osquery.asciidoc


 * Run live queries for one or more agents
- * Schedule queries to capture changes to OS state over time
+ * Schedule query packs to capture changes to OS state over time
 * View a history of past queries and their results
 * Save queries and build a library of queries for specific use cases


This sentence appears after the bulleted list. but it doesn't seem to fit in with the flow of the text. Can it be removed?

Osquery results are stored in Elasticsearch, so that you can search, analyze, and visualize Osquery data in Kibana.

I think it's an important thing to note somewhere, because we've received some questions about it. But I definitely see your point. I'll try to find a better spot for it.

I ended up moving it to the "Osquery results" section - seems like a better fit there.

docs/osquery/osquery.asciidoc

gchaps · 2021-11-11T17:43:37Z

docs/osquery/osquery.asciidoc

@@ -51,14 +51,15 @@ and you'll get suggestions for agents by name, ID, platform, and policy.
 [role="screenshot"]
 image::images/enter-query.png[Select saved query dropdown name showing query name and description]

+. (Optional) Expand the **Advanced** section to view or set <<osquery-map-fields,mapped ECS fields>>. The results from the live query include the mapped fields.
+
 . Click **Submit**.

 . Review the results in a table, or navigate to *Discover* to dive deeper into the response,
 or to the drag-and-drop *Lens* editor to create visualizations.
 . To view more information about the request, such as failures, open the *Status* tab.
 . To optionally save the query for future use, click *Save for later* and define the ID,


Let's remove "optionally" from this sentence for consistency.

gchaps · 2021-11-11T17:45:56Z

docs/osquery/osquery.asciidoc

 . Click **Submit**.

 . Review the results in a table, or navigate to *Discover* to dive deeper into the response,
 or to the drag-and-drop *Lens* editor to create visualizations.
 . To view more information about the request, such as failures, open the *Status* tab.
 . To optionally save the query for future use, click *Save for later* and define the ID,
-description, and other
-<<osquery-manage-query,details>>.
+description, and other <<osquery-manage-query,details>>. 

 To view a history of the past queries you have run, open the *Live queries history*.


should this be step 10?

I ended up making it an independent sub-section, because I think it's a bit of a separate process from running a live query. Take a look and let me know whether you think the latest update works.

docs/osquery/osquery.asciidoc

gchaps · 2021-11-11T18:01:03Z

docs/osquery/osquery.asciidoc


-. To save changes to the query, click *Save*.
+** **Osquery value**: Select an Osquery field. The fields available are based on the SQL query entered, and only include fields that the query returns. When the query runs, the ECS field is set dynamically to the value of the osquery field selected.


osquery field selected > Osquery field selected?

gchaps · 2021-11-11T18:03:09Z

docs/osquery/osquery.asciidoc


-* The unique identifier.
+Note:


Use our NOTE format. Instructions are here.

docs/osquery/osquery.asciidoc

gchaps · 2021-11-11T20:17:53Z

docs/osquery/osquery.asciidoc

 you can create roles for users who can only run live or saved queries, but who cannot save or schedule queries.
 This is useful for teams who need in-depth and detailed control.

 [float]
-== Upgrade Osquery versions
+=== Customize Osquery configuration
+By default, all Osquery Manager integrations share the same osquery configuration. However, you can customize how osquery is configured by editing the Osquery Manager integration for each agent policy


osquery is lowercase here. Is that ok?

I decided to just be consistent throughout and use caps in all instances.

docs/osquery/osquery.asciidoc

gchaps · 2021-11-11T20:24:19Z

docs/osquery/osquery.asciidoc

+
+* Some fields are protected and cannot be set. A warning is displayed with details about which fields should be removed.
+
+* (Optional) To load a full configuration file, drag and drop an osquery `.conf` file into the area at the bottom of the page.


osquery lower case?

Co-authored-by: gchaps <[email protected]>

gchaps · 2021-11-12T00:11:59Z

@elasticmachine merge upstream

gchaps

A few minor comments.

docs/osquery/osquery.asciidoc

gchaps · 2021-11-19T18:46:52Z

docs/osquery/osquery.asciidoc

+Optionally, set the minimum Osquery version and platform,
+or <<osquery-map-fields,map ECS fields>>. When you add a saved query to a pack, this adds a copy of the query. A connection is not maintained between saved queries and packs.
+
+* To upload queries from a .conf query pack, drag the pack to the drop zone under the query table. To explore the community packs that Osquery publishes, click *Example packs*.


should conf be in a different font: .conf?

agreed - updated

gchaps · 2021-11-19T18:51:31Z

docs/osquery/osquery.asciidoc

+
+. Click *Test configuration* to test the query and any mapped fields: 
+
+* From the *Test query* panel, select agents or groups to test the query, then click *Submit*. This runs a live query. Result columns that are mapped are marked with image:images/mapped-icon.png[mapping icon]. Hover over the icon to see the mapped ECS field.


The period after to icon wraps to the next line. Not sure how to fix other than to remove a word. You could do "then click Submit to run a live query.

@gchaps - did the update commit fix what you were seeing? Thanks!

Co-authored-by: gchaps <[email protected]>

gchaps · 2021-11-22T21:31:10Z

@elasticmachine merge upstream

kibana-ci · 2021-11-22T21:31:42Z

💚 Build Succeeded

Buildkite Build
Commit: 6fa3e8b

History

💚 Build #8146 succeeded 294e36c
💚 Build #8145 succeeded d62cc4a
💚 Build #6437 succeeded dc96e50
💚 Build #6435 succeeded 82f7209
💚 Build #6431 succeeded d5246f7
💚 Build #5905 succeeded 8108302

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

* update usage section for changes to live queries, saved queries, packs, and ECS mapping * add info about custom configuration, ECS mapping for date fields, custom tables, and other copy edits * address pr comment, add info about static values for ecs mapping, make other minor copy edits * add more info about the new k8s tables * Apply suggestions from code review Co-authored-by: gchaps <[email protected]> * update per code review comments * Update docs/osquery/osquery.asciidoc Co-authored-by: gchaps <[email protected]> * address review comments Co-authored-by: Kibana Machine <[email protected]> Co-authored-by: gchaps <[email protected]>

* update usage section for changes to live queries, saved queries, packs, and ECS mapping * add info about custom configuration, ECS mapping for date fields, custom tables, and other copy edits * address pr comment, add info about static values for ecs mapping, make other minor copy edits * add more info about the new k8s tables * Apply suggestions from code review Co-authored-by: gchaps <[email protected]> * update per code review comments * Update docs/osquery/osquery.asciidoc Co-authored-by: gchaps <[email protected]> * address review comments Co-authored-by: Kibana Machine <[email protected]> Co-authored-by: gchaps <[email protected]> Co-authored-by: Melissa Burpo <[email protected]> Co-authored-by: Kibana Machine <[email protected]>

* update usage section for changes to live queries, saved queries, packs, and ECS mapping * add info about custom configuration, ECS mapping for date fields, custom tables, and other copy edits * address pr comment, add info about static values for ecs mapping, make other minor copy edits * add more info about the new k8s tables * Apply suggestions from code review Co-authored-by: gchaps <[email protected]> * update per code review comments * Update docs/osquery/osquery.asciidoc Co-authored-by: gchaps <[email protected]> * address review comments Co-authored-by: Kibana Machine <[email protected]> Co-authored-by: gchaps <[email protected]>

update usage section for changes to live queries, saved queries, pack…

ba9aa0c

…s, and ECS mapping

melissaburpo added release_note:skip Skip the PR/issue when compiling release notes v7.16.0 v8.0.0 labels Nov 1, 2021

add info about custom configuration, ECS mapping for date fields, cus…

b1f3317

…tom tables, and other copy edits

melissaburpo requested a review from a team November 1, 2021 23:10

james-elastic reviewed Nov 2, 2021

View reviewed changes

docs/osquery/osquery.asciidoc Outdated Show resolved Hide resolved

docs/osquery/osquery.asciidoc Show resolved Hide resolved

docs/osquery/osquery.asciidoc Outdated Show resolved Hide resolved

address pr comment, add info about static values for ecs mapping, mak…

31520dc

…e other minor copy edits

melissaburpo requested a review from gchaps November 10, 2021 00:28

gchaps added the Team:Docs label Nov 10, 2021

kibanamachine and others added 2 commits November 9, 2021 19:39

Merge branch 'main' into update-osquery-doc

9dcf0c0

add more info about the new k8s tables

8108302

gchaps reviewed Nov 11, 2021

View reviewed changes

Apply suggestions from code review

d5246f7

Co-authored-by: gchaps <[email protected]>

elastic deleted a comment from kibanamachine Nov 11, 2021

update per code review comments

82f7209

melissaburpo requested review from james-elastic and gchaps November 11, 2021 23:59

Merge branch 'main' into update-osquery-doc

dc96e50

gchaps approved these changes Nov 19, 2021

View reviewed changes

melissaburpo and others added 2 commits November 19, 2021 15:30

Update docs/osquery/osquery.asciidoc

d62cc4a

Co-authored-by: gchaps <[email protected]>

address review comments

294e36c

Merge branch 'main' into update-osquery-doc

6fa3e8b

melissaburpo merged commit 90fdbf4 into elastic:main Nov 22, 2021

melissaburpo deleted the update-osquery-doc branch November 22, 2021 21:41

gchaps mentioned this pull request Nov 22, 2021

[8.0] [DOCS] Update osquery page for changes in 7.16 (#117031) #119397

Merged

gchaps mentioned this pull request Nov 22, 2021

[7.16] [DOCS] Update osquery page for changes in 7.16 (#117031) #119398

Merged

melissaburpo mentioned this pull request Nov 23, 2021

[DOCS] Add the 7.16 Osquery docs #116969

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOCS] Update osquery page for changes in 7.16 #117031

[DOCS] Update osquery page for changes in 7.16 #117031

melissaburpo commented Nov 1, 2021 •

edited by gchaps

Loading

melissaburpo commented Nov 1, 2021

melissaburpo commented Nov 10, 2021

elasticmachine commented Nov 10, 2021

gchaps commented Nov 10, 2021

gchaps Nov 11, 2021

melissaburpo Nov 11, 2021

melissaburpo Nov 11, 2021

gchaps Nov 11, 2021

gchaps Nov 11, 2021

melissaburpo Nov 11, 2021

gchaps Nov 11, 2021

gchaps Nov 11, 2021

gchaps Nov 11, 2021

melissaburpo Nov 11, 2021

gchaps Nov 11, 2021

gchaps commented Nov 12, 2021

gchaps left a comment

gchaps Nov 19, 2021

melissaburpo Nov 19, 2021

gchaps Nov 19, 2021

melissaburpo Nov 19, 2021

gchaps commented Nov 22, 2021

kibana-ci commented Nov 22, 2021


		. To save changes to the query, click Save.
		Osquery value**: Select an Osquery field. The fields available are based on the SQL query entered, and only include fields that the query returns. When the query runs, the ECS field is set dynamically to the value of the osquery field selected.


		* Some fields are protected and cannot be set. A warning is displayed with details about which fields should be removed.

		* (Optional) To load a full configuration file, drag and drop an osquery `.conf` file into the area at the bottom of the page.


		. Click Test configuration to test the query and any mapped fields:

		* From the Test query panel, select agents or groups to test the query, then click Submit. This runs a live query. Result columns that are mapped are marked with image:images/mapped-icon.png[mapping icon]. Hover over the icon to see the mapped ECS field.

[DOCS] Update osquery page for changes in 7.16 #117031

[DOCS] Update osquery page for changes in 7.16 #117031

Conversation

melissaburpo commented Nov 1, 2021 • edited by gchaps Loading

Summary

Related issue

melissaburpo commented Nov 1, 2021

melissaburpo commented Nov 10, 2021

elasticmachine commented Nov 10, 2021

gchaps commented Nov 10, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gchaps commented Nov 12, 2021

gchaps left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gchaps commented Nov 22, 2021

kibana-ci commented Nov 22, 2021

💚 Build Succeeded

History

melissaburpo commented Nov 1, 2021 •

edited by gchaps

Loading