API documentation to enable audit logging (#927) (#2004)

* fix#816-Audit_Logs_API Signed-off-by: cwillum <[email protected]> * “fix#816-Audit_Logs_API” Signed-off-by: cwillum <[email protected]> * fix#816-Audit_Logs_API Signed-off-by: cwillum <[email protected]> * API-audit-log-review Signed-off-by: cwillum <[email protected]> * API-audit-log-review Signed-off-by: cwillum <[email protected]> * fix#816-Audit_Logs_API Signed-off-by: cwillum <[email protected]> * fix#816-Audit_Logs_API Signed-off-by: cwillum <[email protected]> * fix#816-Audit_Logs_API Signed-off-by: cwillum <[email protected]> Signed-off-by: cwillum <[email protected]> (cherry picked from commit f1fd58b) Co-authored-by: Chris Moore <[email protected]>
opensearch-project · Nov 21, 2022 · 0cdd979 · 0cdd979
1 parent 2eb694b
commit 0cdd979
Showing 1 changed file with 184 additions and 0 deletions.
diff --git a/_security-plugin/access-control/api.md b/_security-plugin/access-control/api.md
@@ -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>&nbsp;&nbsp;&nbsp;&nbsp;`ignore_users` | Array | Users to be excluded from auditing. Wildcard patterns are supported<br>Example: `ignore_users: ["test-user", employee-*"]`
+`audit`<br>&nbsp;&nbsp;&nbsp;&nbsp;`ignore_requests` | Array | Requests to be excluded from auditing. Wildcard patterns are supported.<br>Example: `ignore_requests: ["indices:data/read/*", "SearchRequest"]`
+`audit`<br>&nbsp;&nbsp;&nbsp;&nbsp;`disabled_rest_categories` | Array | Categories to exclude from REST API auditing. Default categories are `AUTHENTICATED`, `GRANTED_PRIVILEGES`.
+`audit`<br>&nbsp;&nbsp;&nbsp;&nbsp;`disabled_transport_categories` | Array | Categories to exclude from Transport API auditing. Default categories are `AUTHENTICATED`, `GRANTED_PRIVILEGES`.
+`audit`<br>&nbsp;&nbsp;&nbsp;&nbsp;`log_request_body` | Boolean | Includes the body of the request (if available) for both REST and the transport layer. Default is  `true`.
+`audit`<br>&nbsp;&nbsp;&nbsp;&nbsp;`resolve_indices` | Boolean | Logs all indexes affected by a request. Resolves aliases and wildcards/date patterns. Default is `true`.
+`audit`<br>&nbsp;&nbsp;&nbsp;&nbsp;`resolve_bulk_requests` | Boolean | Logs individual operations in a bulk request. Default is `false`.
+`audit`<br>&nbsp;&nbsp;&nbsp;&nbsp;`exclude_sensitive_headers` | Boolean | Excludes sensitive headers from being included in the logs. Default is `true`.
+`audit`<br>&nbsp;&nbsp;&nbsp;&nbsp;`enable_transport` | Boolean | Enables/disables Transport API auditing. Default is `true`.
+`audit`<br>&nbsp;&nbsp;&nbsp;&nbsp;`enable_rest` | Boolean | Enables/disables REST API auditing. Default is `true`.
+`compliance` | Object | Contains fields for compliance configuration. 
+`compliance`<br>&nbsp;&nbsp;&nbsp;&nbsp;`enabled` | Boolean | Enables or disables compliance. Default is `true`.
+`compliance`<br>&nbsp;&nbsp;&nbsp;&nbsp;`write_log_diffs` | Boolean | Logs only diffs for document updates. Default is `false`.
+`compliance`<br>&nbsp;&nbsp;&nbsp;&nbsp;`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>&nbsp;&nbsp;&nbsp;&nbsp;`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>&nbsp;&nbsp;&nbsp;&nbsp;`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>&nbsp;&nbsp;&nbsp;&nbsp;`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>&nbsp;&nbsp;&nbsp;&nbsp;`read_metadata_only` | Boolean | Logs only metadata of the document for read events. Default is `true`.
+`compliance`<br>&nbsp;&nbsp;&nbsp;&nbsp;`write_metadata_only` | Boolean | Log only metadata of the document for write events. Default is `true`.
+`compliance`<br>&nbsp;&nbsp;&nbsp;&nbsp;`external_config` | Boolean | Logs external configuration files for the node. Default is `false`.
+`compliance`<br>&nbsp;&nbsp;&nbsp;&nbsp;`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
+```