Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

API design: Policy automations: install software #21418

Closed
wants to merge 10 commits into from
Closed

API design: Policy automations: install software #21418

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
ba58703
Update rest-api.md
marko-lisica Aug 20, 2024
4b3dc74
Update docs/REST API/rest-api.md
marko-lisica Aug 20, 2024
c6be7c2
Update rest-api.md
marko-lisica Aug 20, 2024
d642a4e
Update rest-api.md
marko-lisica Aug 20, 2024
896405e
Update docs/REST API/rest-api.md
marko-lisica Aug 22, 2024
d65a8c7
Update rest-api.md
marko-lisica Aug 22, 2024
5625219
Update docs/REST API/rest-api.md
jacobshandling Aug 28, 2024
6f17c99
Update rest-api.md
marko-lisica Aug 30, 2024
733ffca
Update API-for-contributors.md
marko-lisica Sep 5, 2024
af17c98
Update API-for-contributors.md
marko-lisica Sep 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 20 additions & 1 deletion docs/Contributing/API-for-contributors.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1189,12 +1189,14 @@ NOTE: when updating a policy, team and platform will be ignored.
"name": "new policy",
"description": "This will be a new policy because a policy with the name 'new policy' doesn't exist in Fleet.",
"query": "SELECT * FROM osquery_info",
"team": "No team",
"resolution": "some resolution steps here",
"critical": false
},
{
"name": "Is FileVault enabled on macOS devices?",
"query": "SELECT 1 FROM disk_encryption WHERE user_uuid IS NOT “” AND filevault_status = ‘on’ LIMIT 1;",
"team": "Workstations",
"description": "Checks to make sure that the FileVault feature is enabled on macOS devices.",
"resolution": "Choose Apple menu > System Preferences, then click Security & Privacy. Click the FileVault tab. Click the Lock icon, then enter an administrator name and password. Click Turn On FileVault.",
"platform": "darwin",
Expand Down Expand Up @@ -3040,7 +3042,24 @@ If both `team_id` and `team_name` parameters are included, this endpoint will re

##### Default response

`Status: 204`
`Status: 200`

```json
{
"packages": [
{
"team_id": 3,
"software_title_id": 6690,
"url": "https://dl.tailscale.com/stable/tailscale-setup-1.72.0.exe"
},
{
"team_id": 3,
"software_title_id": 10412,
"url": "https://ftp.mozilla.org/pub/firefox/releases/129.0.2/win64/en-US/Firefox%20Setup%20129.0.2.msi"
}
]
}
```

### Run live script

Expand Down
39 changes: 37 additions & 2 deletions docs/REST API/rest-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6756,6 +6756,29 @@ Team policies work the same as policies, but at the team level.
"failing_host_count": 0,
"host_count_updated_at": "2023-12-20T15:23:57Z",
"calendar_events_enabled": false
},
{
"id": 3,
"name": "macOS - install/update Adobe Acrobat",
"query": "SELECT 1 FROM apps WHERE name = \"Adobe Acrobat.app\" AND bundle_short_version != \"24.002.21005\";",
"description": "Checks if the hard disk is encrypted on Windows devices",
"critical": false,
"author_id": 43,
"author_name": "Alice",
"author_email": "[email protected]",
"team_id": 1,
"resolution": "Resolution steps",
"platform": "darwin",
"created_at": "2021-12-16T14:37:37Z",
"updated_at": "2021-12-16T16:39:00Z",
"passing_host_count": 2300,
"failing_host_count": 3,
"host_count_updated_at": "2023-12-20T15:23:57Z",
"calendar_events_enabled": false,
"install_software": {
jacobshandling marked this conversation as resolved.
Show resolved Hide resolved
"name": "Adobe Acrobat.app",
"software_title_id": 1234
}
}
],
"inherited_policies": [
Expand Down Expand Up @@ -6937,6 +6960,7 @@ The semantics for creating a team policy are the same as for global policies, se
| resolution | string | body | The resolution steps for the policy. |
| platform | string | body | Comma-separated target platforms, currently supported values are "windows", "linux", "darwin". The default, an empty string means target all platforms. |
| critical | boolean | body | _Available in Fleet Premium_. Mark policy as critical/high impact. |
| software_title_id | integer | body | _Available in Fleet Premium_. ID of software title to install if the policy fails. |

Either `query` or `query_id` must be provided.

Expand Down Expand Up @@ -6980,7 +7004,11 @@ Either `query` or `query_id` must be provided.
"passing_host_count": 0,
"failing_host_count": 0,
"host_count_updated_at": null,
"calendar_events_enabled": false
"calendar_events_enabled": false,
"install_software": {
"name": "Adobe Acrobat.app",
"software_title_id": 1234
}
}
}
```
Expand Down Expand Up @@ -7035,6 +7063,7 @@ Either `query` or `query_id` must be provided.
| platform | string | body | Comma-separated target platforms, currently supported values are "windows", "linux", "darwin". The default, an empty string means target all platforms. |
| critical | boolean | body | _Available in Fleet Premium_. Mark policy as critical/high impact. |
| calendar_events_enabled | boolean | body | _Available in Fleet Premium_. Whether to trigger calendar events when policy is failing. |
| software_title_id | integer | body | _Available in Fleet Premium_. ID of software title to install if the policy fails. |
Copy link
Member

@lucasmrod lucasmrod Aug 23, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jacobshandling How do we allow users to unset the title from a policy? ("software_title_id": null?)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can do whatever we want. I like the explicit clarity of null.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, then:

  • "software_title_id" not set in the PATCH request, won't change the value.
  • "software_title_id": null will unset the software title from the policy.
  • "software_title_id": X will set the value to the given integer.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good!

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lucasmrod @jacobshandling What do we do in other PATCH endpoints when we want to unset some option? Do we use null?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When it's a string it's just about using the empty string, maybe this is the first time we have the need to unset a integer on a PATCH request? Cannot find an example.

Another alternative is: if "software_title_id" is NOT set in the PATCH request then the backend will unset it from the policy. But this one is less explicit, and if you don't want to change the value of "software_title_id" for a policy on a PATCH request you'd have to send it with the current value (different than the other fields where if you don't set a field on the PATCH then you don't want the backend to modify it).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lucasmrod I think it makes sense to be explicit and specify null if you want to unset value.

Copy link
Contributor

@jacobshandling jacobshandling Aug 28, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

"software_title_id" not set in the PATCH request, won't change the value.
"software_title_id": null will unset the software title from the policy.
"software_title_id": X will set the value to the given integer.

@lucasmrod fyi the first case should never come from the UI, since it won't make a call for unchanged policies


#### Example

Expand Down Expand Up @@ -7076,7 +7105,11 @@ Either `query` or `query_id` must be provided.
"passing_host_count": 0,
"failing_host_count": 0,
"host_count_updated_at": null,
"calendar_events_enabled": true
"calendar_events_enabled": true,
"install_software": {
"name": "Adobe Acrobat.app",
"software_title_id": 1234
}
}
}
```
Expand Down Expand Up @@ -8806,6 +8839,7 @@ Returns information about the specified software. By default, `versions` are sor
"source": "apps",
"browser": "",
"hosts_count": 48,
"versions_updated_at": "2024-04-01T14:22:58Z",
"versions": [
{
"id": 123,
Expand Down Expand Up @@ -8859,6 +8893,7 @@ Returns information about the specified software. By default, `versions` are sor
"source": "apps",
"browser": "",
"hosts_count": 48,
"versions_updated_at": "2024-04-01T14:22:58Z",
"versions": [
{
"id": 123,
Expand Down
Loading