fleetdm
Show when and which constraints are required in osquery schema
Problem
Many osquery tables have at least one required column, wherein a query featuring that table must reference the column in order to run the query. Otherwise, it would result in a constraint failed error. This is to cut down on the quantity of results and thereby reduce computational complexity and enable scale.
Regardless, information about constraints are not displayed anywhere on the schema pages. To know what this means, the user must 1. google to find out what constraint failed means and then 2. go through osquery's source spec files for the relevant table to see that a column is required.
The following tables have this issue:
- magic
- mdfind
- mdls
- package_bom
- plist
- signature
- yara
- curl
- curl_certificate
- device_file
- device_hash
- device_partitions
- docker_container_fs_changes
- docker_container_processes
- docker_container_stats
- extended_attributes
- file
- hash
Solution
We should find a way to scalably/dynamically generate documentation that would show to a user:
- that a constraint exists
- which column(s) the constraint exists on
- how to overcome a constraint (i.e. how to write a query to satisfy the constraint)
PR
- https://github.com/osquery/osquery-site/pull/257
- https://github.com/osquery/osquery-site/pull/259
Related
- Parent epic: #4973
- osquery team used to have a plan to put icons in the documentation, but it never got done. We could piggyback/drive forward that effort: https://github.com/osquery/osquery-site/issues/189
Related issue which should be resolved when this issue is
https://github.com/osquery/osquery-site/issues/189
A Wayback machine snapshot of how the schema tables looks
https://web.archive.org/web/20170809185932/https://osquery.io/docs/tables/
@zhumo, the PR addressing this issue on https://osquery.io has been merged. Is it okay to close now?
Here is an example.
https://osquery.io/schema/5.4.0/#hash
@DominusKelvin maybe you can show this to me, but I am wondering how do I know what the pin means? Is there a legend somewhere?
@zhumo good point. I thought about that myself.
What can happen is we need to see if we can implement a sort of legend based on the current design of the osquery.io/schema page. I see a redesign was done to the website perhaps we can have eyes on the intended design so I can implement it on the website, which should be another issue/PR altogether.
What do you think @zhumo?
Hey Kelvin, that seems fine, but let's keep the same issue open to represent that work. We can do multiple PRs on the osquery-site side if necessary.
Luke -- I'm re-opening this one. This is more osquery-oriented work, not in fleet, so to keep it from screwing up your milestone label, I'm gonna remove it from the milestone.
@zhumo do you think a tool tip for such icons which will activate on hover or when clicked on mobile will be ideal to show what they represent?
Great. PR opened @zhumo
https://github.com/osquery/osquery-site/pull/259
