API documentation to enable audit logging (#927)
* fix#816-Audit_Logs_API Signed-off-by: cwillum <cwmmoore@amazon.com> * “fix#816-Audit_Logs_API” Signed-off-by: cwillum <cwmmoore@amazon.com> * fix#816-Audit_Logs_API Signed-off-by: cwillum <cwmmoore@amazon.com> * API-audit-log-review Signed-off-by: cwillum <cwmmoore@amazon.com> * API-audit-log-review Signed-off-by: cwillum <cwmmoore@amazon.com> * fix#816-Audit_Logs_API Signed-off-by: cwillum <cwmmoore@amazon.com> * fix#816-Audit_Logs_API Signed-off-by: cwillum <cwmmoore@amazon.com> * fix#816-Audit_Logs_API Signed-off-by: cwillum <cwmmoore@amazon.com> Signed-off-by: cwillum <cwmmoore@amazon.com>
This commit is contained in:
Chris Moore
GitHub
parent
483ba35282
commit
f1fd58b026
@ -1412,3 +1412,187 @@ GET _plugins/_security/health
|
|||||||
"status": "UP"
|
"status": "UP"
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Audit logs
|
||||||
|
|
||||||
|
The following API is available for audit logging in the security plugin.
|
||||||
|
|
||||||
|
### Enable Audit Logs
|
||||||
|
|
||||||
|
This API allows you to enable or disable audit logging, define the configuration for audit logging and compliance, and make updates to settings.
|
||||||
|
|
||||||
|
For details on using audit logging to track access to OpenSearch clusters, as well as information on further configurations, see [Audit logs](https://opensearch.org/docs/latest/security-plugin/audit-logs/index/).
|
||||||
|
|
||||||
|
You can do an initial configuration of audit logging in the `audit.yml` file, found in the `opensearch-project/security/config` directory. Thereafter, you can use the REST API or Dashboards for further changes to the configuration.
|
||||||
|
{: note.}
|
||||||
|
|
||||||
|
#### Request fields
|
||||||
|
|
||||||
|
Field | Data Type | Description
|
||||||
|
:--- | :--- | :---
|
||||||
|
`enabled` | Boolean | Enables or disables audit logging. Default is `true`.
|
||||||
|
`audit` | Object | Contains fields for audit logging configuration.
|
||||||
|
`audit`<br> `ignore_users` | Array | Users to be excluded from auditing. Wildcard patterns are supported<br>Example: `ignore_users: ["test-user", employee-*"]`
|
||||||
|
`audit`<br> `ignore_requests` | Array | Requests to be excluded from auditing. Wildcard patterns are supported.<br>Example: `ignore_requests: ["indices:data/read/*", "SearchRequest"]`
|
||||||
|
`audit`<br> `disabled_rest_categories` | Array | Categories to exclude from REST API auditing. Default categories are `AUTHENTICATED`, `GRANTED_PRIVILEGES`.
|
||||||
|
`audit`<br> `disabled_transport_categories` | Array | Categories to exclude from Transport API auditing. Default categories are `AUTHENTICATED`, `GRANTED_PRIVILEGES`.
|
||||||
|
`audit`<br> `log_request_body` | Boolean | Includes the body of the request (if available) for both REST and the transport layer. Default is `true`.
|
||||||
|
`audit`<br> `resolve_indices` | Boolean | Logs all indexes affected by a request. Resolves aliases and wildcards/date patterns. Default is `true`.
|
||||||
|
`audit`<br> `resolve_bulk_requests` | Boolean | Logs individual operations in a bulk request. Default is `false`.
|
||||||
|
`audit`<br> `exclude_sensitive_headers` | Boolean | Excludes sensitive headers from being included in the logs. Default is `true`.
|
||||||
|
`audit`<br> `enable_transport` | Boolean | Enables/disables Transport API auditing. Default is `true`.
|
||||||
|
`audit`<br> `enable_rest` | Boolean | Enables/disables REST API auditing. Default is `true`.
|
||||||
|
`compliance` | Object | Contains fields for compliance configuration.
|
||||||
|
`compliance`<br> `enabled` | Boolean | Enables or disables compliance. Default is `true`.
|
||||||
|
`compliance`<br> `write_log_diffs` | Boolean | Logs only diffs for document updates. Default is `false`.
|
||||||
|
`compliance`<br> `read_watched_fields` | Object | Map of indexes and fields to monitor for read events. Wildcard patterns are supported for both index names and fields.
|
||||||
|
`compliance`<br> `read_ignore_users` | Array | List of users to ignore for read events. Wildcard patterns are supported.<br>Example: `read_ignore_users: ["test-user", "employee-*"]`
|
||||||
|
`compliance`<br> `write_watched_indices` | Array | List of indexes to watch for write events. Wildcard patterns are supported.<br>Example: `write_watched_indices: ["twitter", "logs-*"]`
|
||||||
|
`compliance`<br> `write_ignore_users` | Array | List of users to ignore for write events. Wildcard patterns are supported.<br>Example: `write_ignore_users: ["test-user", "employee-*"]`
|
||||||
|
`compliance`<br> `read_metadata_only` | Boolean | Logs only metadata of the document for read events. Default is `true`.
|
||||||
|
`compliance`<br> `write_metadata_only` | Boolean | Log only metadata of the document for write events. Default is `true`.
|
||||||
|
`compliance`<br> `external_config` | Boolean | Logs external configuration files for the node. Default is `false`.
|
||||||
|
`compliance`<br> `internal_config` | Boolean | Logs updates to internal security changes. Default is `true`.
|
||||||
|
|
||||||
|
Changes to the `_readonly` property result in a 409 error, as indicated in the response below.
|
||||||
|
{: .note}
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status" : "error",
|
||||||
|
"reason" : "Invalid configuration",
|
||||||
|
"invalid_keys" : {
|
||||||
|
"keys" : "_readonly,config"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Sample request
|
||||||
|
|
||||||
|
**GET**
|
||||||
|
|
||||||
|
A GET call retrieves the audit configuration.
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /_opendistro/_security/api/audit
|
||||||
|
```
|
||||||
|
|
||||||
|
**PUT**
|
||||||
|
|
||||||
|
A PUT call updates the audit configuration.
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT /_opendistro/_security/api/audit/config
|
||||||
|
{
|
||||||
|
"enabled": true,
|
||||||
|
"audit": {
|
||||||
|
"ignore_users": [],
|
||||||
|
"ignore_requests": [],
|
||||||
|
"disabled_rest_categories": [
|
||||||
|
"AUTHENTICATED",
|
||||||
|
"GRANTED_PRIVILEGES"
|
||||||
|
],
|
||||||
|
"disabled_transport_categories": [
|
||||||
|
"AUTHENTICATED",
|
||||||
|
"GRANTED_PRIVILEGES"
|
||||||
|
],
|
||||||
|
"log_request_body": false,
|
||||||
|
"resolve_indices": false,
|
||||||
|
"resolve_bulk_requests": false,
|
||||||
|
"exclude_sensitive_headers": true,
|
||||||
|
"enable_transport": false,
|
||||||
|
"enable_rest": true
|
||||||
|
},
|
||||||
|
"compliance": {
|
||||||
|
"enabled": true,
|
||||||
|
"write_log_diffs": false,
|
||||||
|
"read_watched_fields": {},
|
||||||
|
"read_ignore_users": [],
|
||||||
|
"write_watched_indices": [],
|
||||||
|
"write_ignore_users": [],
|
||||||
|
"read_metadata_only": true,
|
||||||
|
"write_metadata_only": true,
|
||||||
|
"external_config": false,
|
||||||
|
"internal_config": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**PATCH**
|
||||||
|
|
||||||
|
A PATCH call is used to update specified fields in the audit configuration. The PATCH method requires an operation, a path, and a value to complete a valid request. For details on using the PATCH method, see the following [Patching resources](https://en.wikipedia.org/wiki/PATCH_%28HTTP%29#Patching_resources) description at Wikipedia.
|
||||||
|
|
||||||
|
Using the PATCH method also requires a user to have a security configuration that includes admin certificates for encryption. To find out more about these certificates, see [Configure admin certificates](https://opensearch.org/docs/latest/security-plugin/configuration/tls/#configure-admin-certificates).
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -X PATCH -k -i --cert <admin_cert file name> --key <admin_cert_key file name> <domain>/_opendistro/_security/api/audit -H 'Content-Type: application/json' -d'[{"op":"add","path":"/config/enabled","value":"true"}]'
|
||||||
|
```
|
||||||
|
|
||||||
|
The OpenSearch Dashboards dev tool does not currently support the PATCH method. You can use [curl](https://curl.se/), [Postman](https://www.postman.com/), or another alternative process to update the configuration using this method. To follow the GitHub issue for support of the PATCH method in Dashboards, see [issue #2343](https://github.com/opensearch-project/OpenSearch-Dashboards/issues/2343).
|
||||||
|
{: .note}
|
||||||
|
|
||||||
|
#### Sample response
|
||||||
|
|
||||||
|
The GET call produces a response that appears similar to the following:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"_readonly" : [
|
||||||
|
"/audit/exclude_sensitive_headers",
|
||||||
|
"/compliance/internal_config",
|
||||||
|
"/compliance/external_config"
|
||||||
|
],
|
||||||
|
"config" : {
|
||||||
|
"compliance" : {
|
||||||
|
"enabled" : true,
|
||||||
|
"write_log_diffs" : false,
|
||||||
|
"read_watched_fields" : { },
|
||||||
|
"read_ignore_users" : [ ],
|
||||||
|
"write_watched_indices" : [ ],
|
||||||
|
"write_ignore_users" : [ ],
|
||||||
|
"read_metadata_only" : true,
|
||||||
|
"write_metadata_only" : true,
|
||||||
|
"external_config" : false,
|
||||||
|
"internal_config" : true
|
||||||
|
},
|
||||||
|
"enabled" : true,
|
||||||
|
"audit" : {
|
||||||
|
"ignore_users" : [ ],
|
||||||
|
"ignore_requests" : [ ],
|
||||||
|
"disabled_rest_categories" : [
|
||||||
|
"AUTHENTICATED",
|
||||||
|
"GRANTED_PRIVILEGES"
|
||||||
|
],
|
||||||
|
"disabled_transport_categories" : [
|
||||||
|
"AUTHENTICATED",
|
||||||
|
"GRANTED_PRIVILEGES"
|
||||||
|
],
|
||||||
|
"log_request_body" : true,
|
||||||
|
"resolve_indices" : true,
|
||||||
|
"resolve_bulk_requests" : true,
|
||||||
|
"exclude_sensitive_headers" : true,
|
||||||
|
"enable_transport" : true,
|
||||||
|
"enable_rest" : true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
The PUT request produces a response that appears similar to the following:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status" : "OK",
|
||||||
|
"message" : "'config' updated."
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The PATCH request produces a response similar to the following:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
content-type: application/json; charset=UTF-8
|
||||||
|
content-length: 45
|
||||||
|
```
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user