Add new "Run live query" endpoint

[rachaelshaw]

Goal

User story
As a Fleet API user,
I want to send a simple POST request to run a live query on a single host
so that I can use an HTTP client that doesn't support sending a body with GET requests.

• Thread in osquery slack (contents pasted into a comment below, in case it gets deleted in the future)

Changes

Product

• REST API changes: API design draft PR
  • New API endpoint becomes the documented/recommended "Run live query" endpoint
  • Old endpoint is maintained for backwards compatibility, but removed from docs on fleetdm.com
  • Return results as soon as we have results for all hosts targeted. For example, if the user runs the query on 1 host and Fleet has received the results for this host, return the results instead of waiting the full time configured by FLEET_LIVE_QUERY_REST_PERIOD.
• Outdated documentation changes: (See PR linked above)

Engineering

ℹ️  Please read this issue carefully and understand it. Pay special attention to UI wireframes, especially "dev notes".

Context

• Requestor(s): @ksatter

QA

Risk assessment

• Risk level: Low

Manual testing steps

Testing matrix: new API endpoint, old API endpoint -- since code changes refactored old API endpoint, we need to retest it

Test scenarios for both APIs.

1. 1 query 1 host
2. 1 query, multiple hosts
3. 1 query, multiple hosts (some offline)
4. 1 query, multiple hosts (all offline)
5. 1 query, no hosts
6. 1 query, non-existent host
7. Non-existent query
8. Non-authorized query (team user trying to run a query from another team)

Test scenarios for old API:

1. 2 queries, 2 hosts

Testing notes

Confirmation

1. Engineer (@____): Added comment to user story confirming succesful completion of QA.
2. QA (@____): Added comment to user story confirming succesful completion of QA.

[rachaelshaw]

Here's the full conversation for context (apologies for the awkward formatting; copying/pasting directly from Slack):

J.R. Murray
3 months ago
Hi, I'm having issues coding an app in node.js against the Fleet API. The Run Queries endpoint spec shows a GET with a JSON payload, which is against HTTP spec and node is actively refusing to do it.
33 replies

Kathy Satterlee
3 months ago
Hey
@J.R. Murray
. You might have better luck getting advice in a Node space, but I'm happy to see if I can help. What package are you using to handle requests? It should certainly be doable. While sending a body in GET is unconventional, it isn't prohibited by spec.

J.R. Murray
3 months ago
@Kathy Satterlee
thanks for the response. I would say it's contentious at best. node-fetch/node-fetch#795

J.R. Murray
3 months ago
also elastic/elasticsearch#16024

J.R. Murray
3 months ago
the error is Request with GET/HEAD method cannot have body

mikermcneil
:fleet: 3 months ago
We can def help you here. cc
@Eric Shaw

@Rachael Shaw

mikermcneil
:fleet: 3 months ago
While sending a body in GET is unconventional, it isn't prohibited by spec.
💯 Agreed. Also found this weird. Here's how I implemented it in Node recently:
(The TODO on line 167 can be ignored-- it turned out to be all good. I was just a little thrown off like you.) (edited)
image.png

image.png

:ty:
1

J.R. Murray
3 months ago
We are using this as part of a security automation framework we're building... I don't think replacing the whole http architecture with sails is going to work unfortunately. I didn't write any of this code but I'm trying to shoehorn this in without rewriting too much, if possible.

mikermcneil
:fleet: 3 months ago
Def wouldn't suggest that! Just sharing as an example of working code- feel free to implement it however you like.

mikermcneil
:fleet: 3 months ago
Would you be able to share some code?

mikermcneil
:fleet: 3 months ago
@koo
might also have ideas

J.R. Murray
3 months ago
I can't share any code. Not that I don't want to, it's just complex and sprawled across a lot of files and functions. It's react in node.js.

J.R. Murray
3 months ago
honestly I'd just like another means to run a live query besides a get request, or to use the url query string for them

J.R. Murray
3 months ago
as it is, you can't put fleet behind varnish because it ignores any get payload and treats all of the requests the same

mikermcneil
:fleet: 3 months ago
100% agree. And also re querystring. But as a short term workaround, how about switching to require(‘request’) or a different package, even if it’s just for this call? Want to make sure you’re unblocked. (We have a 3 week release cycle, except for security patches, and features get prioritized during the 3 weeks before the start of each sprint)
If you’d like to contribute, an awesome immediate way could be to PR the API docs (“Edit this page”) and propose the API change to the docs themselves, with the context in this convo (where I think you’ve stated the problems with the current design very clearly and concisely)
We need to take semver into account, but I think it’s doable in a backwards compatible way.
Maybe we get that far, then Rachael (DRI) can review, and Kathy or Rachael can bring this up for prioritization at the next feature fest.
Sound ok to you? (edited)

J.R. Murray
3 months ago
I'm ok with waiting 3-4 weeks for a fix. Having a working integration would be nice but I don't want to make a bunch of one-off code in a general-purpose solution. Not to mention I'm not really the developer 🙂

J.R. Murray
3 months ago
the code to make the request itself is relatively simple.
response = await fetch(fetchUrl, {
method: fetchMethod,
headers: fetchHeaders,
body: fetchBody
})
👍
1

mikermcneil
:fleet: 3 months ago
To be clear: more like 6 weeks, if the CX group is able to prioritize it. I think the doc PR helps, since we can get that design worked out first asap; then it’s less scary to prioritize quickly

mikermcneil
:fleet: 3 months ago
Also, super glad you brought this up. It’s a weird design that in retrospect should have been different, but didn’t realize you couldn’t do this kind of request in the most popular http client for at least one language. Def makes it more of a priority. cc
@Rachael Shaw
BOTL for a proposal
👍
1

J.R. Murray
3 months ago
ok, that helps. Thank you 🙂

Kathy Satterlee
3 months ago
Great stuff y'all, thanks!

J.R. Murray
3 months ago
does someone have a github link for the api docs?

Kathy Satterlee
3 months ago
https://github.com/fleetdm/fleet/blob/main/docs/Using-Fleet/REST-API.md
:ty:
1

Kathy Satterlee
3 months ago
You can also hit the "Edit Page" button from the website on any page in the docs to be dropped right into and edit session on GitHub 🙂
image.png

image.png

J.R. Murray
3 months ago
neato

J.R. Murray
3 months ago
#13002
Also sent to the channel

J.R. Murray
3 days ago
@Kathy Satterlee

@mikermcneil
have there been any updates on this?

mikermcneil
:fleet: 3 days ago
@Noah Talerman

@Rachael Shaw
this API design decision was something I disagreed and committed on. It is possible to work around, but just weird and an easy change. I continue to disagree and I’m hearing users have the challenge.

J.R. Murray
3 days ago
FYI I just read that OpenAPI removed support for describing GET request bodies in version 3.0

mikermcneil
:fleet: 3 days ago
As they should

J.R. Murray
3 days ago
apparently they quietly added it back into 3.1 after getting some pushback ... but yeah

mikermcneil
:fleet: 3 days ago
Just a matter of timing. Should be a relatively small change, but would you be up for making a PR, JR?

J.R. Murray
3 days ago
I did a PR on the docs, we have too many backlogged items in our own app for me to commit to that.

mikermcneil
:fleet: 3 days ago
I know the feeling
FYI about the PR
@Noah Talerman
for feature fest.

[noahtalerman]

Feature fest: This is more complex than at first glance, we already have a POST /queries/run: https://github.com/fleetdm/fleet/blob/main/docs/Contributing/API-for-contributors.md#run-live-query

This is core to Fleet. Can't take it on now but we should bring it back.

[noahtalerman]

cc @rachaelshaw ^^