Docs/Add documentation for standalone audit logging settings - #12922
Docs/Add documentation for standalone audit logging settings#12922Taiwo435 wants to merge 4 commits into
Conversation
Document all cluster settings changes from the standalone audit logging project across three files: - _security/audit-logs/index.md: Add standalone mode intro, new tracked events (REQUEST_AUDIT, TRANSPORT_AUDIT, RESOURCE_* categories), unified disabled_categories with deprecation warning, body_logging_ exclusions with action groups, MDC routing, and dynamic audit.enabled - _security/audit-logs/standalone.md: New page covering standalone mode setup, requirements, tracked events, dynamic configuration, compliance tracking, and OpenSearch Dashboards UI integration - security-settings.md: Add body_logging_exclusions, action_groups, log4j.enable_mdc_routing, enable_standalone settings, and Setting.Property.Sensitive note Related PRs: opensearch-project/security#6304, opensearch-project#6271, opensearch-project#6321, opensearch-project#6341, opensearch-project#6347, opensearch-project#6349, opensearch-project#6352, opensearch-project#6368 Signed-off-by: Muzzamil Jolaade <muzzajol@amazon.com>
- Remove out-of-scope/inaccurate OpenSearch Dashboards section from standalone.md - Scope the dynamic and Sensitive claims to the registered filter/compliance settings (body_logging_exclusions and action_groups are static/not sensitive; many config.* settings are static) - Correct compliance.enabled default (true) and read_watched_fields shape (List<String>, comma-separated entries) - Fix .warning callout placement and default audit index name - Clarify that COMPLIANCE_DOC_READ/WRITE events are emitted and that disabled_categories does not suppress COMPLIANCE_* categories - Document previously-missing dynamic settings (ignore_headers, external_config, internal_config, read_ignore_users, write_ignore_users) and add a consolidated dynamic settings reference Signed-off-by: Muzzamil Jolaade <muzzajol@amazon.com>
Give standalone mode a linked management-API reference for parity with the standard-mode Audit logs API link, and clarify that the Audit logs REST API and audit.yml do not apply in standalone mode (they require FGAC). Signed-off-by: Muzzamil Jolaade <muzzajol@amazon.com>
Head off the misreading that standalone audit logging is a separate plugin or process. It is independent of fine-grained access control but runs inside the Security plugin and reuses the standard audit pipeline. Signed-off-by: Muzzamil Jolaade <muzzajol@amazon.com>
|
Thank you for submitting your PR. The PR states are In progress (or Draft) -> Tech review -> Doc review -> Merged. Before you submit your PR for doc review, make sure the content is technically accurate. If you need help finding a tech reviewer, tag a maintainer. When you're ready for doc review, tag the assignee of this PR. The doc reviewer may push edits to the PR directly or leave comments and editorial suggestions for you to address (let us know in a comment if you have a preference). |
Taiwo435
changed the title
|
@cwperks Could you please review this PR? |
DarshitChanpura
left a comment
DarshitChanpura
left a comment
There was a problem hiding this comment.
Blocker: this documents the read-back of standalone audit config via GET _cluster/settings, but that behavior comes from opensearch-project/security#6392, which isn't merged yet. In current main, getSettingsFilter() strips the whole plugins.security.audit.* subtree from settings responses in SSL-only mode, so the read path here doesn't work. Hold this until #6392 is merged and released, and pin it to the same version.
Otherwise the settings, defaults, tracked events, body-logging exclusions, MDC keys, and compliance behavior all match the merged code. Couple of inline fixes below.
|
|
||
| - `opendistro_security.audit.config.disabled_transport_categories` (Dynamic): A list of transport layer categories to be ignored by the logger. Valid values are `AUTHENTICATED` and `GRANTED_PRIVILEGES`. | ||
|
|
||
| The dynamic audit filter settings and all `plugins.security.audit.compliance.*` settings are marked with `Setting.Property.Sensitive`. This means only security admin users can view or modify their values via the cluster settings API; values are masked for non-admin users. The `plugins.security.audit.config.body_logging_exclusions` and `plugins.security.audit.config.action_groups.<NAME>` settings are exceptions and are not marked sensitive. |
There was a problem hiding this comment.
This needs #6392 for the SSL-only read path, so it can't merge before that.
The role wording is incorrect regardless of #6392. The settings filter isn't role-aware. After #6392, SSL-only returns the non-secret config to any caller (no roles exist there), and FGAC keeps the whole audit.* subtree filtered for everyone. There's no "admins can view, non-admins masked" behavior.
Suggest something like: "These settings are registered Setting.Property.Sensitive, which keeps their values out of diagnostics and logs. In standalone SSL-only mode the non-secret dynamic config (…config.* and …compliance.*) is readable via GET _cluster/settings; credential-bearing sink settings (endpoint/route credentials, PEM keys, salt) stay hidden. body_logging_exclusions and action_groups.<NAME> aren't marked sensitive."
| ### Settings in opensearch.yml | ||
|
|
||
| The following settings are stored in the `opensearch.yml` file. | ||
| The following settings are stored in the `opensearch.yml` file. The audit filter and compliance settings---for example, `log_request_body`, `resolve_indices`, `disabled_categories`, and the `plugins.security.audit.compliance.*` settings---are dynamic: they can be changed at runtime using the [Cluster settings API]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-settings/) without a node restart. Most of these dynamic settings are also marked as sensitive, meaning only security admin users can view or modify them via the cluster settings API (`body_logging_exclusions` and `action_groups.<NAME>` are exceptions and are not sensitive). Other audit settings---such as `action_groups.<NAME>`, `log4j.enable_mdc_routing`, `config.index`, the thread pool settings, and the sink connection settings---are static and require a node restart. |
There was a problem hiding this comment.
Same as the security-settings.md note: needs #6392, and "only security admin users can view or modify them via the cluster settings API" is incorrect in either mode (SSL-only is readable by any caller; FGAC is filtered for everyone). Reword to describe Property.Sensitive instead of role-based masking.
Also, action_groups.<NAME> is listed here as a dynamic setting but it's static (groupSetting(..., NodeScope)) — the next sentence already says so. Drop it from this parenthetical; only body_logging_exclusions is a dynamic non-sensitive exception.
| `BAD_HEADERS` | Yes | Yes | An attempt was made to spoof a request to OpenSearch with the Security plugin internal headers. | ||
| `CLUSTER_SETTINGS_CHANGED` | No | Yes | A persistent or transient cluster setting was changed. Disabled by default. | ||
| `INDEX_SETTINGS_CHANGED` | No | Yes | An index setting was changed. Disabled by default. | ||
| `REQUEST_AUDIT` | Yes | No | A REST-layer request was received and processed. Generated in [standalone audit logging]({{site.url}}{{site.baseurl}}/security/audit-logs/standalone/) mode only. |
There was a problem hiding this comment.
REQUEST_AUDIT has origin=REST but request_layer=TRANSPORT internally and can be suppressed via disabled_transport_categories. "No" is fine for a REST-origin event, but a footnote would be more accurate. Non-blocking.
|
|
||
| ##### How it works | ||
|
|
||
| Each audit event's action name and REST path are matched against a set of exclusion patterns. When a match is found, the request body field is omitted from the audit event---all other fields (user, IP address, indices, timestamp, etc.) are preserved. |
There was a problem hiding this comment.
The : / / / * split reads like it drives matching, but in the code it's only used for the warning heuristic — matching is a single combined WildcardMatcher tested per layer. Outcome you describe is right, just the framing. Non-blocking.
| layout: default | ||
| title: Standalone audit logging | ||
| parent: Audit logs | ||
| nav_order: 130 |
There was a problem hiding this comment.
Collides with field-reference.md, which is also 130. Use 128, or 133 to land between field-reference and storage-types (135).
|
|
||
| ## Configuration | ||
|
|
||
| All standalone audit settings are configured in `opensearch.yml` for initial values and can be dynamically updated at runtime using the [Cluster settings API]({{site.url}}{{site.baseurl}}/api-reference/cluster-api/cluster-settings/). No security index is required. |
3 participants
Description
Add comprehensive documentation for the standalone audit logging feature and all associated cluster settings changes introduced across multiple Security plugin PRs.
Changes:
_security/audit-logs/index.md(updated):REQUEST_AUDIT,TRANSPORT_AUDIT,RESOURCE_ACCESS_GRANTED,RESOURCE_ACCESS_DENIED,RESOURCE_SHARING_CHANGEDdisabled_categoriessetting with deprecation warning for split settingsbody_logging_exclusionswith action groups (full section: pattern types, group naming, bulk behavior, interaction withlog_request_body, examples)log4j.enable_mdc_routingsettingaudit.enabledtoggle via cluster settings API_security/audit-logs/standalone.md(new page):enable_standalone: true+audit.type)_install-and-configure/configuring-opensearch/security-settings.md(updated):body_logging_exclusions,action_groups.<NAME>,log4j.enable_mdc_routing,enable_standalonesettingsSetting.Property.Sensitiveon all audit/compliance settingsIssues Resolved
Closes opensearch-project/security#6303
Closes opensearch-project/security#6340
Related Security plugin PRs:
enable_standalonedisabled_categoriessettingVersion
3.8
Frontend features
N/A - these are backend cluster settings, not Dashboards UI features.
Checklist