Skip to content

Commit

Permalink
API design: Uninstall software (#22318)
Browse files Browse the repository at this point in the history 
API design for: #20320
  • Loading branch information
@noahtalerman
noahtalerman authored Sep 23, 2024
1 parent bda6921 commit be0374c
Showing 1 changed file with 111 additions and 10 deletions.
121 changes: 111 additions & 10 deletions docs/REST API/rest-api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -484,6 +484,22 @@ for pagination. For a comprehensive list of activity types and detailed informat
```json
{
"activities": [
{
"created_at": "2023-07-27T14:35:08Z",
"id": 25,
"actor_full_name": "Anna Chao",
"actor_id": 3,
"actor_gravatar": "",
"actor_email": "",
"type": "uninstalled_software",
"details": {
"host_id": 1,
"host_display_name": "Marko's MacBook Pro",
"software_title": "Adobe Acrobat.app",
"script_execution_id": "eeeddb94-52d3-4071-8b18-7322cd382abb",
"status": "failed"
}
},
{
"created_at": "2021-07-30T13:41:07Z",
"id": 24,
Expand Down Expand Up @@ -4249,7 +4265,7 @@ Resends a configuration profile for the specified host.
"last_install": {
"install_uuid": "8bbb8ac2-b254-4387-8cba-4d8a0407368b",
"installed_at": "2024-05-15T15:23:57Z"
},
}
},
"app_store_app": null
"source": "apps",
Expand All @@ -4270,10 +4286,16 @@ Resends a configuration profile for the specified host.
"name": "FalconSensor-6.44.pkg"
"self_service": false,
"last_install": null
"last_install": null,
"last_uninstall": {
"script_execution_id": "ed579e73-0f41-46c8-aaf4-3c1e5880ed27",
"uninstalled_at": "2024-05-15T15:23:57Z"
}
},
"app_store_app": null
"source": "",
"status": null,
"status": "pending_uninstall",
"installed_versions": [],
},
{
Expand Down Expand Up @@ -4554,6 +4576,38 @@ To wipe a macOS, iOS, iPadOS, or Windows host, the host must have MDM turned on.
```json
{
"activities": [
{
"created_at": "2023-07-27T14:35:08Z",\
"actor_id": 1,
"actor_full_name": "Anna Chao",
"id": 4,
"actor_gravatar": "",
"actor_email": "",
"type": "uninstalled_software",
"details": {
"host_id": 1,
"host_display_name": "Marko’s MacBook Pro",
"software_title": "Adobe Acrobat.app",
"script_execution_id": "ecf22dba-07dc-40a9-b122-5480e948b756",
"status": "failed"
}
},
{
"created_at": "2023-07-27T14:35:08Z",\
"actor_id": 1,
"actor_full_name": "Anna Chao",
"id": 3,
"actor_gravatar": "",
"actor_email": "",
"type": "uninstalled_software",
"details": {
"host_id": 1,
"host_display_name": "Marko’s MacBook Pro",
"software_title": "Adobe Acrobat.app",
"script_execution_id": "ecf22dba-07dc-40a9-b122-5480e948b756",
"status": "uninstalled"
}
},
{
"created_at": "2023-07-27T14:35:08Z",
"id": 2,
Expand Down Expand Up @@ -4618,6 +4672,23 @@ To wipe a macOS, iOS, iPadOS, or Windows host, the host must have MDM turned on.
{
"count": 3,
"activities": [
{
"created_at": "2023-07-27T14:35:08Z",
"actor_id": 1,
"actor_full_name": "Anna Chao",
"uuid": "cc081637-fdf9-4d44-929f-96dfaec00f67",
"actor_gravatar": "",
"actor_email": "",
"type": "uninstalled_software",
"fleet_initiated_activity": false,
"details": {
"host_id": 1,
"host_display_name": "Marko's MacBook Pro",
"software_title": "Adobe Acrobat.app",
"script_execution_id": "ecf22dba-07dc-40a9-b122-5480e948b756",
"status": "pending_uninstall",
}
},
{
"created_at": "2023-07-27T14:35:08Z",
"uuid": "d6cffa75-b5b5-41ef-9230-15073c8a88cf",
Expand Down Expand Up @@ -8279,12 +8350,15 @@ Gets the result of a script that was executed.
"host_timeout": false,
"host_id": 1,
"execution_id": "e797d6c6-3aae-11ee-be56-0242ac120002",
"runtime": 20
"runtime": 20,
"created_at": "2024-09-11T20:30:24Z"
}
```

> Note: `exit_code` can be `null` if Fleet hasn't heard back from the host yet.
> Note: `created_at` is the creation timestamp of the script execution request.
### Add script

Uploads a script, making it available to run on hosts assigned to the specified team (or no team).
Expand Down Expand Up @@ -8828,14 +8902,17 @@ Returns information about the specified software. By default, `versions` are sor
"installer_id": 23,
"team_id": 3,
"uploaded_at": "2024-04-01T14:22:58Z",
"install_script": "sudo installer -pkg /temp/FalconSensor-6.44.pkg -target /",
"install_script": "sudo installer -pkg '$INSTALLER_PATH' -target /",
"pre_install_query": "SELECT 1 FROM macos_profiles WHERE uuid='c9f4f0d5-8426-4eb8-b61b-27c543c9d3db';",
"post_install_script": "sudo /Applications/Falcon.app/Contents/Resources/falconctl license 0123456789ABCDEFGHIJKLMNOPQRSTUV-WX",
"uninstall_script": "/Library/CS/falconctl uninstall",
"self_service": true,
"status": {
"installed": 3,
"pending": 1,
"failed": 2,
"pending_install": 1,
"failed_install": 0,
"pending_uninstall": 2,
"failed_uninstall": 1
}
},
"app_store_app": null,
Expand Down Expand Up @@ -9041,7 +9118,7 @@ Add a package (.pkg, .msi, .exe, .deb) to install on macOS, Windows, or Linux (U
| ---- | ------- | ---- | -------------------------------------------- |
| software | file | form | **Required**. Installer package file. Supported packages are PKG, MSI, EXE, and DEB. |
| team_id | integer | form | **Required**. The team ID. Adds a software package to the specified team. |
| install_script | string | form | Command that Fleet runs to install software. If not specified Fleet runs [default install command](https://github.com/fleetdm/fleet/tree/f71a1f183cc6736205510580c8366153ea083a8d/pkg/file/scripts) for each package type. |
| install_script | string | form | Script that Fleet runs to install software. If not specified Fleet runs [default install script](https://github.com/fleetdm/fleet/tree/f71a1f183cc6736205510580c8366153ea083a8d/pkg/file/scripts) for each package type. |
| pre_install_query | string | form | Query that is pre-install condition. If the query doesn't return any result, Fleet won't proceed to install. |
| post_install_script | string | form | The contents of the script to run after install. If the specified script fails (exit code non-zero) software install will be marked as failed and rolled back. |
| self_service | boolean | form | Self-service software is optional and can be installed by the end user. |
Expand Down Expand Up @@ -9293,7 +9370,31 @@ _Available in Fleet Premium._

Install software (package or App Store app) on a macOS, iOS, iPadOS, Windows, or Linux (Ubuntu) host. Software title must have a `software_package` or `app_store_app` added to be installed.

`POST /api/v1/fleet/hosts/:id/software/install/:software_title_id`
`POST /api/v1/fleet/hosts/:id/software/:software_title_id/install`

#### Parameters

| Name | Type | In | Description |
| --------- | ---------- | ---- | -------------------------------------------- |
| id | integer | path | **Required**. The host's ID. |
| software_title_id | integer | path | **Required**. The software title's ID. |

#### Example

`POST /api/v1/fleet/hosts/123/software/3435/install`

##### Default response

`Status: 202`

### Uninstall package

> **Experimental feature**. This feature is undergoing rapid improvement, which may result in breaking changes to the API or configuration surface. It is not recommended for use in automated workflows.
_Available in Fleet Premium._

Uninstall software (package) on a macOS, Windows, or Linux (Ubuntu) host. Software title must have a `software_package` added to be uninstalled.

`POST /api/v1/fleet/hosts/:id/software/:software_title_id/uninstall`

#### Parameters

Expand All @@ -9304,7 +9405,7 @@ Install software (package or App Store app) on a macOS, iOS, iPadOS, Windows, or

#### Example

`POST /api/v1/fleet/hosts/123/software/install/3435`
`POST /api/v1/fleet/hosts/123/software/3435/uninstall`

##### Default response

Expand All @@ -9316,7 +9417,7 @@ Install software (package or App Store app) on a macOS, iOS, iPadOS, Windows, or
_Available in Fleet Premium._

`GET /api/v1/fleet/software/install/results/:install_uuid`
`GET /api/v1/fleet/software/install/:install_uuid/results`

Get the results of a software package install.

Expand All @@ -9328,7 +9429,7 @@ To get the results of an App Store app install, use the [List MDM commands](#lis

#### Example

`GET /api/v1/fleet/software/install/results/b15ce221-e22e-4c6a-afe7-5b3400a017da`
`GET /api/v1/fleet/software/install/b15ce221-e22e-4c6a-afe7-5b3400a017da/results`

##### Default response

Expand Down

0 comments on commit be0374c

Please sign in to comment.