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

REST API docs: Add policy (#19699)

Browse Source 
- Fix typo in descriptions
- Remove legacy/deprecated way of adding a policy
This commit is contained in:
Noah Talerman
2024-06-12 18:30:28 -04:00
committed by GitHub
parent bac033e0d6
commit 80677d1dd0
1 changed files with 6 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/REST API/rest-api.md
+6 -58
View File
@@ -6026,29 +6026,19 @@ For example, a policy might ask “Is Gatekeeper enabled on macOS devices?“ Th
### Add policy
There are two ways of adding a policy:
1. Preferred: By setting `name`, `query`, and `description`.
2. Legacy: By setting `query_id` to reuse the data of an existing query. If `query_id` is set,
then `query` must not be set, and `name` and `description` are ignored.
An error is returned if both `query` and `query_id` are set on the request.
`POST /api/v1/fleet/global/policies`
#### Parameters
| Name | Type | In | Description |
| ---------- | ------- | ---- | ------------------------------------ |
| name | string | body | The query's name. |
| query | string | body | The query in SQL. |
| description | string | body | The query's description. |
| name | string | body | The policy's name. |
| query | string | body | The policy's query in SQL. |
| description | string | body | The policy's description. |
| resolution | string | body | The resolution steps for the policy. |
| query_id | integer | body | An existing query's ID (legacy). |
| 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. |
Either `query` or `query_id` must be provided.
#### Example (preferred)
`POST /api/v1/fleet/global/policies`
@@ -6093,47 +6083,6 @@ Either `query` or `query_id` must be provided.
}
```
#### Example (legacy)
`POST /api/v1/fleet/global/policies`
#### Request body
```json
{
"query_id": 12
}
```
Where `query_id` references an existing `query`.
##### Default response
`Status: 200`
```json
{
"policy": {
"id": 43,
"name": "Gatekeeper enabled",
"query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
"description": "Checks if gatekeeper is enabled on macOS devices",
"critical": true,
"author_id": 42,
"author_name": "John",
"author_email": "john@example.com",
"team_id": null,
"resolution": "Resolution steps",
"platform": "darwin",
"created_at": "2022-03-17T20:15:55Z",
"updated_at": "2022-03-17T20:15:55Z",
"passing_host_count": 0,
"failing_host_count": 0,
"host_count_updated_at": null
}
}
```
### Remove policies
`POST /api/v1/fleet/global/policies/delete`
@@ -6514,11 +6463,10 @@ The semantics for creating a team policy are the same as for global policies, se
| Name | Type | In | Description |
| ---------- | ------- | ---- | ------------------------------------ |
| id | integer | path | Defines what team ID to operate on. |
| name | string | body | The query's name. |
| query | string | body | The query in SQL. |
| description | string | body | The query's description. |
| name | string | body | The policy's name. |
| query | string | body | The policy's query in SQL. |
| description | string | body | The policy's description. |
| resolution | string | body | The resolution steps for the policy. |
| query_id | integer | body | An existing query's ID (legacy). |
| 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. |