Co-authored-by: Marko Lisica <83164494+marko-lisica@users.noreply.github.com>
Co-authored-by: Konstantin Sykulev <konst@sykulev.com>
Co-authored-by: George Karr <georgekarrv@users.noreply.github.com>
Co-authored-by: Victor Lyuboslavsky <victor.lyuboslavsky@gmail.com>
Co-authored-by: Ian Littman <iansltx@gmail.com>
Co-authored-by: Noah Talerman <47070608+noahtalerman@users.noreply.github.com>
Co-authored-by: Lucas Manuel Rodriguez <lucas@fleetdm.com>
Co-authored-by: Eric <eashaw@sailsjs.com>
Couple changes in advance of API design for #23235 (since certificates
will be available for macOS/iOS/iPadOS):
+ Update "Get host" example response to be a macOS host
+ Update "Get host by device token" example response to be a macOS host
& move weightier items to the bottom for readability
+ Update "Get host" example response to be a macOS host (in advance of
API design for #23235, since certificates will be available for
macOS/iOS/iPadOS)
+ Update formatting of "Get host by identifier" to move weightier items
to the bottom
Updated /automations/reset description to reflect that this endpoint
does not immediately trigger automations, but resets the status of hosts
so that they are seen as newly failing on the next automation run.
Co-authored-by: Ian Littman <iansltx@gmail.com>
Co-authored-by: Zach Wasserman <zach@fleetdm.com>
Co-authored-by: Lucas Manuel Rodriguez <lucas@fleetdm.com>
Co-authored-by: Konstantin Sykulev <konst@sykulev.com>
Co-authored-by: Marko Lisica <83164494+marko-lisica@users.noreply.github.com>
Co-authored-by: Noah Talerman <47070608+noahtalerman@users.noreply.github.com>
Added note to get Setup Experience section warning against setting
custom URL values in custom profile. This was tested by CSA &
customer-starchik.
---------
Co-authored-by: Rachael Shaw <r@rachael.wtf>
This applies some consistency fixes as well (e.g. noting that Mac/Win
enforcement requires MDM). Also removed mention of MDM on iOS/iPadOS
enforcement as if an iOS/iPadOS host is enrolled, it's enrolled via MDM.
See #21998
# Checklist for submitter
If some of the following don't apply, delete the relevant line.
<!-- Note that API documentation changes are now addressed by the
product design team. -->
- [x] Changes file added for user-visible changes in `changes/`,
`orbit/changes/` or `ee/fleetd-chrome/changes`.
See [Changes
files](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Committing-Changes.md#changes-files)
for more information.
- [x] Manual QA for all new/changed functionality
Co-authored-by: Rachael Shaw <r@rachael.wtf>
Co-authored-by: mostlikelee <tim@mostlikelee.com>
Co-authored-by: Tim Lee <timlee@fleetdm.com>
Co-authored-by: Marko Lisica <markol.lisica@gmail.com>
Co-authored-by: Ian Littman <iansltx@gmail.com>
Co-authored-by: Luke Heath <luke@fleetdm.com>
GitOps and API changes for the following story:
- #9956
DONE:
- ~~Contributor API endpoints to support best practice GitOps (`fleetctl
gitops`) and backwards compatibility GitOps (`fleetctl apply`)~~
- https://github.com/fleetdm/fleet/pull/21043#issuecomment-2338218929
---------
Co-authored-by: Martin Angers <martin.n.angers@gmail.com>
Co-authored-by: Dante Catalfamo <43040593+dantecatalfamo@users.noreply.github.com>
Co-authored-by: Marko Lisica <83164494+marko-lisica@users.noreply.github.com>
Co-authored-by: George Karr <georgekarrv@users.noreply.github.com>
Co-authored-by: Gabriel Hernandez <ghernandez345@gmail.com>
Co-authored-by: Rachael Shaw <r@rachael.wtf>
This PR closes https://github.com/fleetdm/fleet/issues/21108
@noahtalerman, I double-checked all redirects, and they are working.
Clicking through the URLs in [this
spreadsheet](https://docs.google.com/spreadsheets/d/1djVynIMuJK4pT5ziJW12CluVqcaoxxnCLaBO3VXfAt4/edit?usp=sharing)
is a pretty quick way to go through them all. Note that "Audit logs" and
"Understanding host vitals" redirect to the contributor docs on GitHub,
so they will throw a 404 until this is merged.
Some new guides benefitted from a name change, so they make more sense
as stand-alone guides, and also so that we don't have to mess around
with more redirects later. Those name changes followed [this
convention](https://fleetdm.com/handbook/company/communications#headings-and-titles),
which was recently documented in the handbook.
Have fun!
---------
Co-authored-by: Eric <eashaw@sailsjs.com>
Co-authored-by: Noah Talerman <noahtal@umich.edu>
- Only one of either `labels_include_all` or `labels_exclude_any` can be
included in the request.
- Add missing labels `id` in `GET /configuration_profiles` and `GET
/configuration_profiles/:uuid`
- Mark new API endpoints or API endpoints that were changed as part of
Fleet's first app management feature (#14921) as experimental.
- Call out what is experimental exactly (the endpoint or new keys/values) and
point to changes
For #19540
Just added the same "exclude_software" functionality that exists in "get
hosts" to the "get host by identifier" function.
- [ ] Changes file added for user-visible changes in `changes/`,
`orbit/changes/` or `ee/fleetd-chrome/changes`.
See [Changes
files](https://fleetdm.com/docs/contributing/committing-changes#changes-files)
for more information.
- [ ] Manual QA for all new/changed functionality
Follow up from https://github.com/fleetdm/fleet/pull/20109: there were a
few descriptions that just said "body" because of some table rows with
an extra column I missed when merging in recent updates.
Since the "Modify config" parameters are mostly a bunch of different
objects, it's a bit unwieldy to document in one table. Trying out a new
format to see if it feels like the right way to document nested objects
in API parameters.
API changes for the "Get unlock PIN immediately after locking macOS
host" story (https://github.com/fleetdm/fleet/issues/19545)
---------
Co-authored-by: Victor Lyuboslavsky <victor.lyuboslavsky@gmail.com>
Noticed several places where the structure of
`mdm.macos_settings.custom_settings` and
`mdm.windows_settings.custom_settings` didn't match the example response
for "Get configuration" (which I think is the most up-to-date).
(Will follow up and update the parameter descriptions for
`mdm.macos_settings.custom_settings`/`mdm.windows_settings.custom_settings`
to clarify they're objects with `path` and `labels` once
https://github.com/fleetdm/fleet/pull/19424 is merged.)
---------
Co-authored-by: Noah Talerman <47070608+noahtalerman@users.noreply.github.com>
`server_settings.enable_analytics` was only documented in the "Get
configuration" endpoint and nowhere else. Added to "Modify
configuration" params and example response.
Fresh PR to avoid product design PRs messing with the PR open time KPI
(original here: https://github.com/fleetdm/fleet/pull/17369)
---------
Co-authored-by: Marko Lisica <83164494+marko-lisica@users.noreply.github.com>
Fresh PR to avoid product design PRs messing with the PR open time KPI
(previously https://github.com/fleetdm/fleet/pull/17711)
---------
Co-authored-by: Marko Lisica <83164494+marko-lisica@users.noreply.github.com>
Co-authored-by: George Karr <georgekarrv@users.noreply.github.com>
Fresh PR to avoid product design PRs messing with the PR open time KPI
(previously https://github.com/fleetdm/fleet/pull/17670)
---------
Co-authored-by: Marko Lisica <83164494+marko-lisica@users.noreply.github.com>
Fresh PR to avoid product design PRs messing with the PR open time KPI
(original: https://github.com/fleetdm/fleet/pull/16982)
---------
Co-authored-by: Noah Talerman <47070608+noahtalerman@users.noreply.github.com>
File carves were moved to their own section in contributor docs
https://github.com/fleetdm/fleet/pull/16877
Fixed link on API page
---------
Co-authored-by: Rachael Shaw <r@rachael.wtf>
Adds `webhook_settings.host_status_webhook` options to team config for
#14916.
Also updated conceptual docs that reference this config (and cut down
some content to make room).
For better readability: add periods as separation between the Fleet
Premium message and parameter descriptions.
✅ _Available in Fleet Premium_. Description text.
❌ _Available in Fleet Premium_ Description text.
- Updated `GET /api/v1/fleet/scripts`: documented `team_id` parameter
that was missing
- Replaced "Upload" with "Add" since that's the language we want to use
across the product and docs.
- Removed articles from headings
---------
Co-authored-by: Noah Talerman <47070608+noahtalerman@users.noreply.github.com>
Co-authored-by: Rachael Shaw <r@rachael.wtf>
Typo: "removing" /past from host's activities API
# Checklist for submitter
If some of the following don't apply, delete the relevant line.
<!-- Note that API documentation changes are now addressed by the
product design team. -->
- [ ] Changes file added for user-visible changes in `changes/` or
`orbit/changes/`.
See [Changes
files](https://fleetdm.com/docs/contributing/committing-changes#changes-files)
for more information.
- [ ] Documented any permissions changes (docs/Using
Fleet/manage-access.md)
- [ ] Input data is properly validated, `SELECT *` is avoided, SQL
injection is prevented (using placeholders for values in statements)
- [ ] Added support on fleet's osquery simulator `cmd/osquery-perf` for
new osquery data ingestion features.
- [ ] Added/updated tests
- [ ] If database migrations are included, checked table schema to
confirm autoupdate
- For database migrations:
- [ ] Checked schema for all modified table for columns that will
auto-update timestamps during migration.
- [ ] Confirmed that updating the timestamps is acceptable, and will not
cause unwanted side effects.
- [ ] Manual QA for all new/changed functionality
- For Orbit and Fleet Desktop changes:
- [ ] Manual QA must be performed in the three main OSs, macOS, Windows
and Linux.
- [ ] Auto-update manual QA, from released version of component to new
version (see [tools/tuf/test](../tools/tuf/test/README.md)).
---------
Co-authored-by: Rachael Shaw <r@rachael.wtf>
REST API changes for #15919
---------
Co-authored-by: Noah Talerman <47070608+noahtalerman@users.noreply.github.com>
Co-authored-by: Tim Lee <timlee@fleetdm.com>
+ Changed a bunch of instances of "member" to "user" to match the
updated UI (https://github.com/fleetdm/fleet/issues/15893)
+ Cut some step-by-step instructions for using the team UI from the
"Segment hosts" docs
+ Add some missing "_Available in Fleet Premium_." flags to `team_id`
parameter descriptions for API endpoints available in Fleet Free.
+ Remove one duplicate instance of `team_id`
API changes for the "Upcoming activities: Run scripts on online/offline
hosts" (#15529) story
Changes:
- Script endpoints are available in Fleet Free and Fleet Premium
- Update `POST /scripts/run` to add a script to the bottom of the
upcoming activities
- Update `POST /scripts/run/sync`
- Add `GET /hosts/:id/activities` to show past activity feed
- Add `GET /hosts/:id/activities/upcoming` to show upcoming activity
feed
- Move docs for `GET /hosts/:id/scripts` to a new "Get host's scripts
section" under "Hosts"
API changes for the following story:
- #14674
- Both `GET /software` and [`GET
/software/versions`](https://github.com/fleetdm/fleet/pull/14831/files#diff-7246bc304b15c8865ed8eaa205e9c244d0a0314e4bae60cf553dc06147c38b64R7035)
will work the same. We're just documenting `GET /software/versions`
- Both `GET /software/{id}` and `GET /software/versions/{id}` will work
the same. We're just documenting `GET /software/versions/{id}`
- `count` added in both `GET /software/versions` and `GET
/software/titles`. `GET / software/count` still available (but removed
from docs).
---------
Co-authored-by: Noah Talerman <47070608+noahtalerman@users.noreply.github.com>
Co-authored-by: Sarah Gillespie <73313222+gillespi314@users.noreply.github.com>
Co-authored-by: Rachael Shaw <r@rachael.wtf>
API changes for the Windows configuration profiles story:
- #13281
It's **ready for review**, but marked as a draft because of KPI (PR open
time)
- DONE: Remove activity types changes before merging (those will be
automatically generated)
#### `profile_id` and `profile_uuid` changes specified in following
ticket:
- #15274
---------
Co-authored-by: Noah Talerman <47070608+noahtalerman@users.noreply.github.com>
Co-authored-by: Rachael Shaw <r@rachael.wtf>
Makes parameter formatting in documented REST API paths consistent.
Previously, we were using a mix of `/foo/:parameter/bar` and
`/foo/{parameter}/bar`. This updates all URLs to use `:` instead of
`{…}`.
Also, opportunistically fixed some other inconsistent formatting I
noticed in a couple places.
- Simplify usage instructions to make it more like a reference
- Move "Run script asynchronously" to contributor docs so that user
facing API docs have one best practice API endpoint for scripts. Call
synchronous endpoint "Run script"
# Checklist for submitter
If some of the following don't apply, delete the relevant line.
- [x] Changes file added for user-visible changes in `changes/` or
`orbit/changes/`.
See [Changes
files](https://fleetdm.com/docs/contributing/committing-changes#changes-files)
for more information.
- [x] Documented any API changes (docs/REST API/rest-api.md or
docs/Contributing/API-for-contributors.md)
- [x] Input data is properly validated, `SELECT *` is avoided, SQL
injection is prevented (using placeholders for values in statements)
- [x] Added/updated tests
- [x] Manual QA for all new/changed functionality
---------
Co-authored-by: Rachael Shaw <r@rachael.wtf>
for #14361 this adds the bits related to saving a slice of strings with
paths to configuration profiles.
---------
Co-authored-by: Martin Angers <martin.n.angers@gmail.com>
Co-authored-by: Marko Lisica <83164494+marko-lisica@users.noreply.github.com>
Changes:
- added backticks to a parameter description ("`"differential", or
"differential_ignore_removals"`" » "`"differential"`, or
`"differential_ignore_removals"`")...
API changes for the Windows MDM command story: #13069
Changes:
- Add cross platform endpoints used for macOS and Windows MDM commands
- Deprecate `/apple` endpoints.
---------
Co-authored-by: Noah Talerman <47070608+noahtalerman@users.noreply.github.com>
Moved "List queries" to the top, to match the order of other sections of
the API. (We usually start with the endpoint to get a list of things,
_then_ the endpoint to get one thing by ID.)
#13998
Cleaned up REST API input validation for hosts, carves, users endpoints.
rest-api.md changes explained:
https://www.loom.com/share/9cd82653bacb4528bdaac117ec85a976
For the following endpoints:
/api/v1/fleet/hosts
/api/v1/fleet/hosts/count
/api/v1/fleet/hosts/report
- converted validation errors from 500 to 400 HTTP status code
- added validation that policy_id must be present when policy_response
is specified
- added validation that policy_response must be `passing` or `failing`
- added validation that `os_name` must be specified with `os_version`
For the following endpoint:
/api/v1/fleet/users
- converted team_id validation error from 500 to 400 HTTP status code
For the following endpoint:
/api/v1/fleet/carves
- added rest-api.md documentation for `page`, `per_page`, `order_key`,
`order_direction`, and `expired`
- converted `expired` validation error from 500 to 400 HTTP status code
# Checklist for submitter
If some of the following don't apply, delete the relevant line.
- [x] Changes file added for user-visible changes in `changes/` or
`orbit/changes/`.
See [Changes
files](https://fleetdm.com/docs/contributing/committing-changes#changes-files)
for more information.
- [x] Documented any API changes (docs/Using-Fleet/REST-API.md or
docs/Contributing/API-for-contributors.md)
- [x] Added/updated tests
- [x] Manual QA for all new/changed functionality
---------
Co-authored-by: Rachael Shaw <r@rachael.wtf>
Move content into a blockquote (since h3s on this page are reserved for
API endpoints), and point users toward how to get errors for a
particular query via the REST API.
Draft PR to show API changes for #7766#13469
---------
Co-authored-by: Lucas Rodriguez <lucas@fleetdm.com>
Co-authored-by: Mike McNeil <mikermcneil@users.noreply.github.com>
# Checklist for submitter
If some of the following don't apply, delete the relevant line.
- [ ] Changes file added for user-visible changes in `changes/` or
`orbit/changes/`.
See [Changes
files](https://fleetdm.com/docs/contributing/committing-changes#changes-files)
for more information.
- [ ] Documented any API changes (docs/Using-Fleet/REST-API.md or
docs/Contributing/API-for-contributors.md)
- [ ] Documented any permissions changes (docs/Using
Fleet/manage-access.md)
- [ ] Input data is properly validated, `SELECT *` is avoided, SQL
injection is prevented (using placeholders for values in statements)
- [ ] Added support on fleet's osquery simulator `cmd/osquery-perf` for
new osquery data ingestion features.
- [ ] Added/updated tests
- [ ] Manual QA for all new/changed functionality
- For Orbit and Fleet Desktop changes:
- [ ] Manual QA must be performed in the three main OSs, macOS, Windows
and Linux.
- [ ] Auto-update manual QA, from released version of component to new
version (see [tools/tuf/test](../tools/tuf/test/README.md)).
- Add new "Windows setup" page to "Device Management" section of docs
- Rename "MDM setup" page to "macOS setup." Update links and add redirect
- Rename existing "macOS setup" page to "macOS setup experience." Update links. Did not add redirect because of conflict with "macOS setup" page
- Remove "MDM" from all MDM doc page titles
