diff --git a/docs/application/README.md b/docs/application/README.md index 83d36866a5..ef7762cc55 100644 --- a/docs/application/README.md +++ b/docs/application/README.md @@ -5,14 +5,10 @@ Kolide is an application that allows you to take advantage of the power of osque ## Using The Kolide application -- For information on running osquery queries on hosts in your infrastructure, you can refer to the [Running Queries](.running-queries.md) page. +- For information on running osquery queries on hosts in your infrastructure, you can refer to the [Running Queries](./running-queries.md) page. - To learn more about scheduling queries for periodic execution on select hosts, managing query packs, etc, you can refer to the [Scheduling Queries](./scheduling-queries.md) page. - Kolide also allows you to configure osquery options so that you can endlessly customize your osquery usage. For information on how to customize osquery using Kolide as well as thoughts on what customization you might consider performing, see the [Configuring Osquery Options](./configuring-osquery-options.md) documentation. -## Kolide for the osquery user - -If you have extensive existing osquery experience, we've supplied a document which briefly discusses the features, intentions, and philosophies of Kolide's osquery management capabilities. For more information, see the [Kolide For The Osquery User](./kolide-for-the-osquery-user.md) documentation. - ## Working With osquery logs -Kolide makes it easy to schedule queries, curate packs, and generate a lot of osquery logs. For more information on how you can access these logs as well as examples on what you can do with them, see the [Working With Osquery Logs](./working-with-osquery-logs.md) documentation. \ No newline at end of file +Kolide makes it easy to schedule queries, curate packs, and generate a lot of osquery logs. For more information on how you can access these logs as well as examples on what you can do with them, see the [Working With Osquery Logs](./working-with-osquery-logs.md) documentation. diff --git a/docs/application/configuring-osquery-options.md b/docs/application/configuring-osquery-options.md index e3b734dd06..3fd1ee1d21 100644 --- a/docs/application/configuring-osquery-options.md +++ b/docs/application/configuring-osquery-options.md @@ -1,2 +1,8 @@ Configuring Osquery Options -=========================== \ No newline at end of file +=========================== + +To connect a host to Kolide, you have to launch `osqueryd` with some very specific options (which are further outlined in the [Adding Hosts To Kolide](../infrastructure/adding-hosts-to-kolide.md) documentation). Once a host has connected, many global osquery configuration options can be changed without necessitating a reboot of osquery. These options can be edited and managed by selecting the "Config" sidebar. + +![Manage Osquery Options](../images/manage-osquery-options.png) + +Note that this is a more advanced feature. The Kolide application will not allow you to configure osquery such that it can't talk to Kolide anymore, but you can significantly modify the behavior of osquery via configuration. diff --git a/docs/application/kolide-for-the-osquery-user.md b/docs/application/kolide-for-the-osquery-user.md deleted file mode 100644 index 3f2c2b2b23..0000000000 --- a/docs/application/kolide-for-the-osquery-user.md +++ /dev/null @@ -1,2 +0,0 @@ -Kolide For The Osquery User -=========================== \ No newline at end of file diff --git a/docs/application/running-queries.md b/docs/application/running-queries.md index 0c326a1454..fe0e7dae31 100644 --- a/docs/application/running-queries.md +++ b/docs/application/running-queries.md @@ -1,2 +1,16 @@ Running Queries -=============== \ No newline at end of file +=============== + +The Kolide application allows you to query hosts which you have installed osquery on. To run a new query, use the "Query" sidebar and select "New Query". From this page, you can compose your query, view SQL table documentation via the sidebar, select arbitrary hosts (or groups of hosts), and execute your query. As results are returned, they will populate the interface in real time. You can use the integrated filtering tool to perform useful initial analytics and easily export the entire dataset for offline analysis. + +![Distributed new query with local filter](../images/distributed-new-query-with-local-filter.png) + +After you've composed a query that returns the information you were looking for, you may choose to save the query. You can still continue to execute the query on whatever set of hosts you would like after you have saved the query. + +![Distributed saved query with local filter](../images/distributed-saved-query-with-local-filter.png) + +Saved queries can be accessed if you select "Manage Queries" from the "Query" section of the sidebar. Here, you will find all of the queries you've ever saved. You can filter the queries by query name, so name your queries something memorable! + +![Manage Queries](../images/manage-queries.png) + +To learn more about scheduling queries so that they run on an on-going basis, see the [Scheduling Queries](./scheduling-queries.md) guide. diff --git a/docs/application/scheduling-queries.md b/docs/application/scheduling-queries.md index 33c9b2e36d..0864f5d612 100644 --- a/docs/application/scheduling-queries.md +++ b/docs/application/scheduling-queries.md @@ -1,2 +1,28 @@ Scheduling Queries -================== \ No newline at end of file +================== + +As discussed in the [Running Queries Documentation](./running-queries.md), you can use the Kolide application to create, execute, and save osquery queries. You can organize these queries into "Query Packs". To view all saved packs and perhaps create a new pack, select "Manage Packs" from the "Packs" sidebar. Packs are usually organized by the general class of instrumentation that you're trying to perform. + +![Manage Packs](../images/manage-packs.png) + +If you select a pack from the list, you can quickly enable and disable the entire pack, or you can configure it further. + +![Manage Packs With Pack Selected](../images/manage-packs-with-pack-selected.png) + +When you edit a pack, you can decide which targets you would like to execute the pack. This is a similar selection experience to the target selection process that you use to execute a new query. + +![Edit Pack Targets](../images/edit-pack-targets.png) + +To add queries to a pack, use the right-hand sidebar. You can take an existing scheduled query and add it to the pack. You must also define a few key details such as: + +- interval: how often should the query be executed? +- logging: which osquery logging format would you like to use? +- platform: which operating system platforms should execute this query? +- minimum osquery version: if the table was introduced in a newer version of osquery, you may want to ensure that only sufficiently recent version of osquery execute the query. +- shard: from 0 to 100, what percent of hosts should execute this query? + +![Schedule Query Sidebar](../images/schedule-query-sidebar.png) + + +Once you've scheduled queries and curated your packs, you can read our guide to [Working With Osquery Logs](./working-with-osquery-logs.md). + diff --git a/docs/application/working-with-osquery-logs.md b/docs/application/working-with-osquery-logs.md index 59b0d9e7eb..d38214734c 100644 --- a/docs/application/working-with-osquery-logs.md +++ b/docs/application/working-with-osquery-logs.md @@ -1,2 +1,13 @@ Working With Osquery Logs -========================= \ No newline at end of file +========================= + +The `kolide` binary accepts two flags: + +- `--osquery_result_log_file`: Path for osqueryd result logs (default: `/tmp/osquery_result`) +- `--osquery_status_log_file`: Path for osqueryd status logs (default `/tmp/osquery_status`) + +You can also configure the path which logs are written via environment variables or a config file. See the documentation on [Configuring The Kolide Binary](../infrastructure/configuring-the-kolide-binary.md) for more information on this. + +As the Kolide server ingests logs from osquery, it will write them to the paths described using the above flags. You are encouraged to forward these logs into your company's log aggregation/alerting pipeline directly. For more information on configuring various systems to ingest osquery logs, consider reviewing the [Log Aggregation](https://osquery.readthedocs.io/en/stable/deployment/log-aggregation/) documentation on the official osquery wiki. + +As the Kolide application grows, we are going to expand this feature based on customer feedback. If you would like direct integrations with a specific third-party application, please let us know at [support@kolide.co](mailto:support@kolide.co). diff --git a/docs/images/admin-settings.png b/docs/images/admin-settings.png new file mode 100644 index 0000000000..cd1ff4ed1f Binary files /dev/null and b/docs/images/admin-settings.png differ diff --git a/docs/images/distributed-new-query-with-local-filter.png b/docs/images/distributed-new-query-with-local-filter.png new file mode 100644 index 0000000000..41b0df39aa Binary files /dev/null and b/docs/images/distributed-new-query-with-local-filter.png differ diff --git a/docs/images/distributed-saved-query-with-local-filter.png b/docs/images/distributed-saved-query-with-local-filter.png new file mode 100644 index 0000000000..4a11b823cc Binary files /dev/null and b/docs/images/distributed-saved-query-with-local-filter.png differ diff --git a/docs/images/edit-pack-targets.png b/docs/images/edit-pack-targets.png new file mode 100644 index 0000000000..6c689632a1 Binary files /dev/null and b/docs/images/edit-pack-targets.png differ diff --git a/docs/images/manage-hosts-grid.png b/docs/images/manage-hosts-grid.png new file mode 100644 index 0000000000..5364cac96b Binary files /dev/null and b/docs/images/manage-hosts-grid.png differ diff --git a/docs/images/manage-hosts-list.png b/docs/images/manage-hosts-list.png new file mode 100644 index 0000000000..325c350a4b Binary files /dev/null and b/docs/images/manage-hosts-list.png differ diff --git a/docs/images/manage-osquery-options.png b/docs/images/manage-osquery-options.png new file mode 100644 index 0000000000..8f30981541 Binary files /dev/null and b/docs/images/manage-osquery-options.png differ diff --git a/docs/images/manage-packs-with-pack-selected.png b/docs/images/manage-packs-with-pack-selected.png new file mode 100644 index 0000000000..b4713417c7 Binary files /dev/null and b/docs/images/manage-packs-with-pack-selected.png differ diff --git a/docs/images/manage-packs.png b/docs/images/manage-packs.png new file mode 100644 index 0000000000..fb6680d6ad Binary files /dev/null and b/docs/images/manage-packs.png differ diff --git a/docs/images/manage-queries.png b/docs/images/manage-queries.png new file mode 100644 index 0000000000..d42f9e1c00 Binary files /dev/null and b/docs/images/manage-queries.png differ diff --git a/docs/images/manage-users.png b/docs/images/manage-users.png new file mode 100644 index 0000000000..8b1793a2ab Binary files /dev/null and b/docs/images/manage-users.png differ diff --git a/docs/images/schedule-query-sidebar.png b/docs/images/schedule-query-sidebar.png new file mode 100644 index 0000000000..614a4c626d Binary files /dev/null and b/docs/images/schedule-query-sidebar.png differ