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"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 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…
Reference in New Issue