Skip to content

Commit

Permalink
Add Team Schedule documentation (#1576)
Browse files Browse the repository at this point in the history 
* Add Team Schedule documentation

* Update docs/1-Using-Fleet/3-REST-API.md

Co-authored-by: noahtalerman <47070608+noahtalerman@users.noreply.github.com>

Co-authored-by: noahtalerman <47070608+noahtalerman@users.noreply.github.com>
  • Loading branch information
@chiiph @noahtalerman
chiiph and noahtalerman authored Aug 6, 2021
1 parent 9eac51c commit ccd5298
Showing 1 changed file with 202 additions and 0 deletions.
202 changes: 202 additions & 0 deletions docs/1-Using-Fleet/3-REST-API.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3254,6 +3254,208 @@ None.

---

### Team schedule
- [Get team schedule](#get-team-schedule)
- [Add query to team schedule](#add-query-to-team-schedule)
- [Edit query in team schedule](#edit-query-in-team-schedule)
- [Remove query from team schedule](#remove-query-from-team-schedule)

`In Fleet 4.2.0, the Team Schedule feature was introduced.`

This allows you to easily configure scheduled queries that will impact a whole team of devices.

#### Get team schedule

`GET /api/v1/fleet/team/{id}/schedule`

#### Parameters

| Name | Type | In | Description |
| --------------- | ------- | ----- | ----------------------------------------------------------------------------------------------------------------------------- |
| id | integer | path | **Required**. The team's ID. |
| page | integer | query | Page number of the results to fetch. |
| per_page | integer | query | Results per page. |
| order_key | string | query | What to order results by. Can be any column in the `activites` table. |
| order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `asc` and `desc`. Default is `asc`. |

#### Example

`GET /api/v1/fleet/team/2/schedule`

##### Default response

`Status: 200`

```
{
"scheduled": [
{
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "0001-01-01T00:00:00Z",
"id": 4,
"pack_id": 2,
"name": "arp_cache",
"query_id": 2,
"query_name": "arp_cache",
"query": "select * from arp_cache;",
"interval": 120,
"snapshot": true,
"removed": null,
"shard": null,
"denylist": null
},
{
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "0001-01-01T00:00:00Z",
"id": 5,
"pack_id": 3,
"name": "disk_encryption",
"query_id": 7,
"query_name": "disk_encryption",
"query": "select * from disk_encryption;",
"interval": 86400,
"snapshot": true,
"removed": null,
"shard": null,
"denylist": null
}
]
}
```

#### Add query to team schedule

`POST /api/v1/fleet/team/{id}/schedule`

#### Parameters

| Name | Type | In | Description |
| -------- | ------- | ---- | -------------------------------------------------------------------------------------------------------------------------------- |
| id | integer | path | **Required.** The teams's ID. |
| query_id | integer | body | **Required.** The query's ID. |
| interval | integer | body | **Required.** The amount of time, in seconds, the query waits before running. |
| snapshot | boolean | body | **Required.** Whether the queries logs show everything in its current state. |
| removed | boolean | body | Whether "removed" actions should be logged. Default is `null`. |
| platform | string | body | The computer platform where this query will run (other platforms ignored). Empty value runs on all platforms. Default is `null`. |
| shard | integer | body | Restrict this query to a percentage (1-100) of target hosts. Default is `null`. |
| version | string | body | The minimum required osqueryd version installed on a host. Default is `null`. |

#### Example

`POST /api/v1/fleet/team/2/schedule`

##### Request body

```
{
"interval": 86400,
"query_id": 2,
"snapshot": true,
}
```

##### Default response

`Status: 200`

```
{
"scheduled": {
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "0001-01-01T00:00:00Z",
"id": 1,
"pack_id": 5,
"name": "arp_cache",
"query_id": 2,
"query_name": "arp_cache",
"query": "select * from arp_cache;",
"interval": 86400,
"snapshot": true,
"removed": null,
"shard": null,
"denylist": null
}
}
```

#### Edit query in team schedule

`PATCH /api/v1/fleet/team/{team_id}/schedule/{scheduled_query_id}`

#### Parameters

| Name | Type | In | Description |
| ------------------ | ------- | ---- | ------------------------------------------------------------------------------------------------------------- |
| team_id | integer | path | **Required.** The team's ID. |
| scheduled_query_id | integer | path | **Required.** The scheduled query's ID. |
| interval | integer | body | The amount of time, in seconds, the query waits before running. |
| snapshot | boolean | body | Whether the queries logs show everything in its current state. |
| removed | boolean | body | Whether "removed" actions should be logged. |
| platform | string | body | The computer platform where this query will run (other platforms ignored). Empty value runs on all platforms. |
| shard | integer | body | Restrict this query to a percentage (1-100) of target hosts. |
| version | string | body | The minimum required osqueryd version installed on a host. |

#### Example

`PATCH /api/v1/fleet/team/2/schedule/5`

##### Request body

```
{
"interval": 604800,
}
```

##### Default response

`Status: 200`

```
{
"scheduled": {
"created_at": "2021-07-16T14:40:15Z",
"updated_at": "2021-07-16T14:40:15Z",
"id": 5,
"pack_id": 1,
"name": "arp_cache",
"query_id": 2,
"query_name": "arp_cache",
"query": "select * from arp_cache;",
"interval": 604800,
"snapshot": true,
"removed": null,
"platform": "",
"shard": null,
"denylist": null
}
}
```

#### Remove query from team schedule

`DELETE /api/v1/fleet/team/{team_id}/schedule/{scheduled_query_id}`

#### Parameters

| Name | Type | In | Description |
| ------------------ | ------- | ---- | ------------------------------------------------------------------------------------------------------------- |
| team_id | integer | path | **Required.** The team's ID. |
| scheduled_query_id | integer | path | **Required.** The scheduled query's ID. |

#### Example

`DELETE /api/v1/fleet/team/2/schedule/5`

##### Default response

`Status: 200`

```
{}
```
---

## Packs

- [Create pack](#create-pack)
Expand Down

0 comments on commit ccd5298

Please sign in to comment.