Discharge7443/fleet
1
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

Add /scripts/run and scripts/run/sync API endpoints to run scripts (part 1) (#13417)

Browse Source
This commit is contained in:
Martin Angers
2023-08-21 14:47:19 -04:00
committed by GitHub
parent 3b61adf7a4
commit de32faefdb
23 changed files with 1252 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/REST API/rest-api.md
+84 -11
View File
@@ -10,6 +10,7 @@
- [Policies](#policies)
- [Queries](#queries)
- [Schedule (deprecated)](#schedule)
- [Scripts](#scripts)
- [Sessions](#sessions)
- [Software](#software)
- [Targets](#targets)
@@ -3126,7 +3127,7 @@ Retrieves the disk encryption key for a host.
}
```
### Get configuration profiles assigned to a host
### Get configuration profiles assigned to a host
Requires Fleet's MDM properly [enabled and configured](https://fleetdm.com/docs/using-fleet/mdm-setup).
@@ -5626,7 +5627,7 @@ load balancer timeout.
## Schedule
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> Please use the [queries](#queries) endpoints, which as of 4.35 have attributes such as `interval` and `platform` that enable scheduling.
- [Get schedule (deprecated)](#get-schedule)
@@ -5641,7 +5642,7 @@ These API routes let you control your scheduled queries.
### Get schedule
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> Please use the [queries](#queries) endpoints, which as of 4.35 have attributes such as `interval` and `platform` that enable scheduling.
`GET /api/v1/fleet/global/schedule`
@@ -5715,7 +5716,7 @@ None.
### Add query to schedule
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> Please use the [queries](#queries) endpoints, which as of 4.35 have attributes such as `interval` and `platform` that enable scheduling.
`POST /api/v1/fleet/global/schedule`
@@ -5776,7 +5777,7 @@ None.
### Edit query in schedule
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> Please use the [queries](#queries) endpoints, which as of 4.35 have attributes such as `interval` and `platform` that enable scheduling.
`PATCH /api/v1/fleet/global/schedule/{id}`
@@ -5832,7 +5833,7 @@ None.
### Remove query from schedule
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> Please use the [queries](#queries) endpoints, which as of 4.35 have attributes such as `interval` and `platform` that enable scheduling.
`DELETE /api/v1/fleet/global/schedule/{id}`
@@ -5854,7 +5855,7 @@ None.
### Team schedule
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> Please use the [queries](#queries) endpoints, which as of 4.35 have attributes such as `interval` and `platform` that enable scheduling.
- [Get team schedule (deprecated)](#get-team-schedule)
@@ -5866,7 +5867,7 @@ This allows you to easily configure scheduled queries that will impact a whole t
#### Get team schedule
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> Please use the [queries](#queries) endpoints, which as of 4.35 have attributes such as `interval` and `platform` that enable scheduling.
`GET /api/v1/fleet/teams/{id}/schedule`
@@ -5946,7 +5947,7 @@ This allows you to easily configure scheduled queries that will impact a whole t
#### Add query to team schedule
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> Please use the [queries](#queries) endpoints, which as of 4.35 have attributes such as `interval` and `platform` that enable scheduling.
`POST /api/v1/fleet/teams/{id}/schedule`
@@ -6004,7 +6005,7 @@ This allows you to easily configure scheduled queries that will impact a whole t
#### Edit query in team schedule
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> Please use the [queries](#queries) endpoints, which as of 4.35 have attributes such as `interval` and `platform` that enable scheduling.
`PATCH /api/v1/fleet/teams/{team_id}/schedule/{scheduled_query_id}`
@@ -6061,7 +6062,7 @@ This allows you to easily configure scheduled queries that will impact a whole t
#### Remove query from team schedule
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> The schedule API endpoints are deprecated as of Fleet 4.35. They are maintained for backwards compatibility.
> Please use the [queries](#queries) endpoints, which as of 4.35 have attributes such as `interval` and `platform` that enable scheduling.
`DELETE /api/v1/fleet/teams/{team_id}/schedule/{scheduled_query_id}`
@@ -6083,6 +6084,78 @@ This allows you to easily configure scheduled queries that will impact a whole t
---
## Scripts
- [Run script asynchronously](#run-script-asynchronously)
- [Run script synchronously](#run-script-synchronously)
### Run script asynchronously
_Available in Fleet Premium_
Creates a script execution request and returns the execution identifier to retrieve results at a later time.
`POST /api/v1/fleet/scripts/run`
#### Parameters
| Name | Type | In | Description |
| ---- | ------- | ---- | -------------------------------------------- |
| host_id | integer | body | **Required**. The host id to run the script on. |
| script_contents | string | body | **Required**. The contents of the script to run. |
#### Example
`POST /api/v1/fleet/scripts/run`
##### Default response
`Status: 202`
```json
{
"host_id": 1227,
"execution_id": "e797d6c6-3aae-11ee-be56-0242ac120002"
}
```
### Run script synchronously
_Available in Fleet Premium_
Creates a script execution request and waits for a result to return (up to a 1 minute timeout).
`POST /api/v1/fleet/scripts/run/sync`
#### Parameters
| Name | Type | In | Description |
| ---- | ------- | ---- | -------------------------------------------- |
| host_id | integer | body | **Required**. The host id to run the script on. |
| script_contents | string | body | **Required**. The contents of the script to run. |
#### Example
`POST /api/v1/fleet/scripts/run/sync`
##### Default response
`Status: 200`
```json
{
"host_id": 1227,
"execution_id": "e797d6c6-3aae-11ee-be56-0242ac120002",
"script_contents": "echo 'hello'",
"output": "hello",
"runtime": 1,
"exit_code": 0
}
```
---
## Sessions
- [Get session info](#get-session-info)
docs/Using Fleet/manage-access.md
+3 -1
View File
@@ -87,6 +87,7 @@ GitOps is an API-only and write-only role that can be used on CI/CD pipelines.
| View metadata of MDM macOS bootstrap packages\* | | | ✅ | ✅ | |
| Edit/upload MDM macOS bootstrap packages\* | | | ✅ | ✅ | ✅ |
| Enable/disable MDM macOS setup end user authentication\* | | | ✅ | ✅ | ✅ |
| Run scripts on hosts\* | | | ✅ | ✅ | |
\* Applies only to Fleet Premium
@@ -149,6 +150,7 @@ Users that are members of multiple teams can be assigned different roles for eac
| View metadata of MDM macOS bootstrap packages | | | ✅ | ✅ | |
| Edit/upload MDM macOS bootstrap packages | | | ✅ | ✅ | ✅ |
| Enable/disable MDM macOS setup end user authentication | | | ✅ | ✅ | ✅ |
| Run scripts on hosts | | | ✅ | ✅ | |
\* Applies only to [Fleet REST API](https://fleetdm.com/docs/using-fleet/rest-api)
@@ -156,4 +158,4 @@ Users that are members of multiple teams can be assigned different roles for eac
<meta name="pageOrderInSection" value="900">
<meta name="description" value="Learn about the different roles and permissions in Fleet.">
<meta name="navSection" value="The basics">
<meta name="navSection" value="The basics">