Move audit logging docs to new docs system (#134499)

* Forklift of existing audit logging docs into new docs system

* Add introduction

* Remove old content

* Update dev_docs/key_concepts/audit_logging.mdx

dev_docs/key_concepts/audit_logging.mdx

@@ -0,0 +1,119 @@
+---
+id: kibAuditLogging
+slug: /kibana-dev-docs/key-concepts/audit-logging
+title: Audit Logging
+summary: Audit Logging
+date: 2022-06-15
+tags: ['kibana', 'onboarding', 'dev', 'logging', 'audit']
+---
+
+## Audit logging
+
+Audit logging is a subscription feature that users can enable to keep track of security-related events, such as authorization success and failures. Logging these events enables you to monitor Kibana for suspicious activity and provides evidence in the event of an attack.
+
+Use the Kibana audit logs in conjunction with Elasticsearch audit logging to get a holistic view of all security related events. Kibana defers to the Elasticsearch security model for authentication, data index authorization, and features that are driven by cluster-wide privileges.
+
+### Automatic audit logging
+
+The Kibana Platform automatically records audit events for the following operations:
+- Calling HTTP endpoints
+- CRUD operations on Saved Objects [1]
+- CRUD operations on Spaces
+- Login / Logout events
+
+<DocCallOut color="warning">
+  [1] Saved Object operations are only audited when using the Scoped Saved Objects Client. Audit logging will not be performed if you create an unscoped client, or choose to exclude the `security` wrapper.
+</DocCallOut>
+
+More information on these events can be found in our [audit logging documentation](https://www.elastic.co/guide/en/kibana/current/xpack-security-audit-logging.html#xpack-security-ecs-audit-logging)
+
+### Custom audit logging
+
+There may be times when it makes sense for a feature to implement its own audit logging, in order to suppliment our automatic audit logging.
+Access to the audit logging service is exposed through the `security` plugin.
+
+#### Example
+
+```typescript
+const auditLogger = securitySetup.audit.asScoped(request);
+auditLogger.log({
+  message: 'User is updating dashboard [id=123]',
+  event: {
+    action: 'saved_object_update',
+    category: ['database'],
+    type: ['change'],
+    outcome: 'unknown',
+  },
+  kibana: {
+    saved_object: { type: 'dashboard', id: '123' },
+  },
+});
+```
+
+### What events should be logged?
+
+The purpose of an audit log is to support compliance, accountability and
+security by capturing who performed an action, what action was performed and
+when it occurred. It is not the purpose of an audit log to aid with debugging
+the system or provide usage statistics.
+
+**Kibana guidelines:**
+
+Each API call to Kibana will result in a record in the audit log that captures
+general information about the request (`http_request` event).
+
+In addition to that, any operation that is performed on a resource owned by
+Kibana (e.g. saved objects) and that falls in the following categories, should
+be included in the audit log:
+
+- System access (incl. failed attempts due to authentication errors)
+- Data reads (incl. failed attempts due to authorisation errors)
+- Data writes (incl. failed attempts due to authorisation errors)
+
+If Kibana does not own the resource (e.g. when running queries against user
+indices), then auditing responsibilities are deferred to Elasticsearch and no
+additional events will be logged.
+
+**Examples:**
+
+For a list of audit events that Kibana currently logs see:
+`docs/user/security/audit-logging.asciidoc`
+
+### When should an event be logged?
+
+Due to the asynchronous nature of most operations in Kibana, there is an
+inherent tradeoff between the following logging approaches:
+
+- Logging the **intention** before performing an operation, leading to false
+  positives if the operation fails downstream.
+- Logging the **outcome** after completing an operation, leading to missing
+  records if Kibana crashes before the response is received.
+- Logging **both**, intention and outcome, leading to unnecessary duplication
+  and noisy/difficult to analyse logs.
+
+**Kibana guidelines:**
+
+- **Write operations** should be logged immediately after all authorisation
+  checks have passed, but before the response is received (logging the
+  intention). This ensures that a record of every operation is persisted even in
+  case of an unexpected error.
+- **Read operations**, on the other hand, should be logged after the operation
+  completed (logging the outcome) since we won't know what resources were
+  accessed before receiving the response.
+- Be explicit about the timing and outcome of an action in your messaging. (e.g.
+  "User has logged in" vs. "User is creating dashboard")
+
+### Can an action trigger multiple events?
+
+- A request to Kibana can perform a combination of different operations, each of
+  which should be captured as separate events.
+- Operations that are performed on multiple resources (**bulk operations**)
+  should be logged as separate events, one for each resource.
+- Actions that kick off **background tasks** should be logged as separate
+  events, one for creating the task and another one for executing it.
+- **Internal checks**, which have been carried out in order to perform an
+  operation, or **errors** that occured as a result of an operation should be
+  logged as an outcome of the operation itself, using the ECS `event.outcome`
+  and `error` fields, instead of logging a separate event.
+- Multiple events that were part of the same request can be correlated in the
+  audit log using the ECS `trace.id` property.

nav-kibana-dev.docnav.json

@@ -8,210 +8,515 @@
     {
       "label": "Getting started",
       "items": [
-        { "id": "kibDevDocsWelcome" },
+        {
-        { "id": "kibDevTutorialSetupDevEnv" },
+          "id": "kibDevDocsWelcome"
-        { "id": "kibHelloWorldApp" },
+        },
-        { "id": "kibDevAddData" },
+        {
-        { "id": "kibTroubleshooting" }
+          "id": "kibDevTutorialSetupDevEnv"
+        },
+        {
+          "id": "kibHelloWorldApp"
+        },
+        {
+          "id": "kibDevAddData"
+        },
+        {
+          "id": "kibTroubleshooting"
+        }
       ]
     },
     {
       "label": "Contributing",
       "items": [
-        { "id": "kibDevPrinciples" },
+        {
-        { "id": "kibRepoStructure" },
+          "id": "kibDevPrinciples"
-        { "id": "kibStandards" },
+        },
-        { "id": "kibBestPractices" },
+        {
-        { "id": "kibDocumentation" },
+          "id": "kibRepoStructure"
-        { "id": "kibStyleGuide" },
+        },
-        { "id": "ktRFCProcess" },
+        {
-        { "id": "kibGitHub" }
+          "id": "kibStandards"
+        },
+        {
+          "id": "kibBestPractices"
+        },
+        {
+          "id": "kibDocumentation"
+        },
+        {
+          "id": "kibStyleGuide"
+        },
+        {
+          "id": "ktRFCProcess"
+        },
+        {
+          "id": "kibGitHub"
+        }
       ]
     },
     {
       "label": "Key concepts",
       "items": [
-        { "id": "kibPlatformIntro" },
+        {
-        { "id": "kibDevAnatomyOfAPlugin" },
+          "id": "kibPlatformIntro"
-        { "id": "kibDevPerformance" },
+        },
-        { "id": "kibBuildingBlocks" },
+        {
-        { "id": "kibDevDocsSavedObjectsIntro", "label": "Saved objects" },
+          "id": "kibDevAnatomyOfAPlugin"
-        { "id": "kibDevDocsPersistableStateIntro" },
+        },
-        { "id": "kibDataPlugin", "label": "Data" },
+        {
-        { "id": "kibCoreLogging" },
+          "id": "kibDevPerformance"
-        { "id": "kibUsageCollectionPlugin" },
+        },
-        { "id": "kibDataViewsKeyConcepts" },
+        {
-        { "id": "kibDevKeyConceptsNavigation" }
+          "id": "kibBuildingBlocks"
+        },
+        {
+          "id": "kibDevDocsSavedObjectsIntro",
+          "label": "Saved objects"
+        },
+        {
+          "id": "kibDevDocsPersistableStateIntro"
+        },
+        {
+          "id": "kibDataPlugin",
+          "label": "Data"
+        },
+        {
+          "id": "kibCoreLogging"
+        },
+        {
+          "id": "kibAuditLogging"
+        },
+        {
+          "id": "kibUsageCollectionPlugin"
+        },
+        {
+          "id": "kibDataViewsKeyConcepts"
+        },
+        {
+          "id": "kibDevKeyConceptsNavigation"
+        }
       ]
     },
     {
       "label": "Tutorials",
       "items": [
-        { "id": "kibDevTutorialTestingPlugins" },
+        {
-        { "id": "kibDevTutorialSavedObject" },
+          "id": "kibDevTutorialTestingPlugins"
-        { "id": "kibDevTutorialSubmitPullRequest" },
+        },
-        { "id": "kibDevTutorialExpressions" },
+        {
-        { "id": "kibDevDocsKPTTutorial" },
+          "id": "kibDevTutorialSavedObject"
-        { "id": "kibDevTutorialDataSearchAndSessions", "label": "data.search" },
+        },
-        { "id": "kibDevTutorialDataViews" },
+        {
-        { "id": "kibDevTutorialDebugging" },
+          "id": "kibDevTutorialSubmitPullRequest"
+        },
+        {
+          "id": "kibDevTutorialExpressions"
+        },
+        {
+          "id": "kibDevDocsKPTTutorial"
+        },
+        {
+          "id": "kibDevTutorialDataSearchAndSessions",
+          "label": "data.search"
+        },
+        {
+          "id": "kibDevTutorialDataViews"
+        },
+        {
+          "id": "kibDevTutorialDebugging"
+        },
         {
           "id": "kibDevTutorialBuildingDistributable",
           "label": "Building a Kibana distributable"
         },
-        { "id": "kibDevTutorialCI" },
+        {
-        { "id": "kibDevTutorialServerEndpoint" },
+          "id": "kibDevTutorialCI"
-        { "id": "kibDevTutorialAdvancedSettings" },
+        },
-        { "id": "kibDevSharePluginReadme" },
+        {
-        { "id": "kibDevTutorialScreenshotting" }
+          "id": "kibDevTutorialServerEndpoint"
+        },
+        {
+          "id": "kibDevTutorialAdvancedSettings"
+        },
+        {
+          "id": "kibDevSharePluginReadme"
+        },
+        {
+          "id": "kibDevTutorialScreenshotting"
+        }
       ]
     },
     {
       "label": "Contributors Newsletters",
       "items": [
-        { "id": "kibMay2022ContributorNewsletter" },
+        {
-        { "id": "kibApril2022ContributorNewsletter" },
+          "id": "kibMay2022ContributorNewsletter"
-        { "id": "kibMarch2022ContributorNewsletter" },
+        },
-        { "id": "kibFebruary2022ContributorNewsletter" },
+        {
-        { "id": "kibJanuary2022ContributorNewsletter" },
+          "id": "kibApril2022ContributorNewsletter"
-        { "id": "kibDecember2021ContributorNewsletter" },
+        },
-        { "id": "kibNovember2021ContributorNewsletter" },
+        {
-        { "id": "kibOctober2021ContributorNewsletter" },
+          "id": "kibMarch2022ContributorNewsletter"
-        { "id": "kibSeptember2021ContributorNewsletter" },
+        },
-        { "id": "kibAugust2021ContributorNewsletter" },
+        {
-        { "id": "kibJuly2021ContributorNewsletter" },
+          "id": "kibFebruary2022ContributorNewsletter"
-        { "id": "kibJune2021ContributorNewsletter" },
+        },
-        { "id": "kibMay2021ContributorNewsletter" },
+        {
-        { "id": "kibApril2021ContributorNewsletter" },
+          "id": "kibJanuary2022ContributorNewsletter"
-        { "id": "kibMarch2021ContributorNewsletter" }
+        },
+        {
+          "id": "kibDecember2021ContributorNewsletter"
+        },
+        {
+          "id": "kibNovember2021ContributorNewsletter"
+        },
+        {
+          "id": "kibOctober2021ContributorNewsletter"
+        },
+        {
+          "id": "kibSeptember2021ContributorNewsletter"
+        },
+        {
+          "id": "kibAugust2021ContributorNewsletter"
+        },
+        {
+          "id": "kibJuly2021ContributorNewsletter"
+        },
+        {
+          "id": "kibJune2021ContributorNewsletter"
+        },
+        {
+          "id": "kibMay2021ContributorNewsletter"
+        },
+        {
+          "id": "kibApril2021ContributorNewsletter"
+        },
+        {
+          "id": "kibMarch2021ContributorNewsletter"
+        }
       ]
     },
     {
       "label": "API documentation",
       "items": [
-        { "id": "kibDevDocsApiWelcome" },
+        {
-        { "id": "kibDevDocsPluginDirectory" },
+          "id": "kibDevDocsApiWelcome"
-        { "id": "kibDevDocsDeprecationsDueByTeam" },
+        },
-        { "id": "kibDevDocsDeprecationsByPlugin" },
+        {
-        { "id": "kibDevDocsDeprecationsByApi" },
+          "id": "kibDevDocsPluginDirectory"
-        { "id": "kibCorePluginApi" },
+        },
-        { "id": "kibCoreApplicationPluginApi" },
+        {
-        { "id": "kibCoreChromePluginApi" },
+          "id": "kibDevDocsDeprecationsDueByTeam"
-        { "id": "kibCoreHttpPluginApi" },
+        },
-        { "id": "kibCoreSavedObjectsPluginApi" },
+        {
-        { "id": "kibFieldFormatsPluginApi" },
+          "id": "kibDevDocsDeprecationsByPlugin"
-        { "id": "kibDataPluginApi" },
+        },
-        { "id": "kibDataViewsPluginApi" },
+        {
-        { "id": "kibDataQueryPluginApi" },
+          "id": "kibDevDocsDeprecationsByApi"
-        { "id": "kibDataSearchPluginApi" },
+        },
-        { "id": "kibBfetchPluginApi" },
+        {
-        { "id": "kibAlertingPluginApi" },
+          "id": "kibCorePluginApi"
-        { "id": "kibTaskManagerPluginApi" },
+        },
-        { "id": "kibActionsPluginApi" },
+        {
-        { "id": "kibEventLogPluginApi" },
+          "id": "kibCoreApplicationPluginApi"
-        { "id": "kibTriggersActionsUiPluginApi" },
+        },
-        { "id": "kibCasesPluginApi" },
+        {
-        { "id": "kibChartsPluginApi" },
+          "id": "kibCoreChromePluginApi"
-        { "id": "kibDashboardPluginApi" },
+        },
-        { "id": "kibDevToolsPluginApi" },
+        {
-        { "id": "kibDiscoverPluginApi" },
+          "id": "kibCoreHttpPluginApi"
-        { "id": "kibEmbeddablePluginApi" },
+        },
-        { "id": "kibEncryptedSavedObjectsPluginApi" },
+        {
-        { "id": "kibEnterpriseSearchPluginApi" },
+          "id": "kibCoreSavedObjectsPluginApi"
-        { "id": "kibEsUiSharedPluginApi" },
+        },
-        { "id": "kibExpressionsPluginApi" },
+        {
-        { "id": "kibFeaturesPluginApi" },
+          "id": "kibFieldFormatsPluginApi"
-        { "id": "kibFileUploadPluginApi" },
+        },
-        { "id": "kibFleetPluginApi" },
+        {
-        { "id": "kibGlobalSearchPluginApi" },
+          "id": "kibDataPluginApi"
-        { "id": "kibHomePluginApi" },
+        },
-        { "id": "kibInspectorPluginApi" },
+        {
-        { "id": "kibKibanaReactPluginApi" },
+          "id": "kibDataViewsPluginApi"
-        { "id": "kibKibanaUtilsPluginApi" },
+        },
-        { "id": "kibLensPluginApi" },
+        {
-        { "id": "kibLicenseManagementPluginApi" },
+          "id": "kibDataQueryPluginApi"
-        { "id": "kibLicensingPluginApi" },
+        },
-        { "id": "kibListsPluginApi" },
+        {
-        { "id": "kibManagementPluginApi" },
+          "id": "kibDataSearchPluginApi"
-        { "id": "kibMapsPluginApi" },
+        },
-        { "id": "kibMlPluginApi" },
+        {
-        { "id": "kibMonitoringPluginApi" },
+          "id": "kibBfetchPluginApi"
-        { "id": "kibNavigationPluginApi" },
+        },
-        { "id": "kibNewsfeedPluginApi" },
+        {
-        { "id": "kibObservabilityPluginApi" },
+          "id": "kibAlertingPluginApi"
-        { "id": "kibRemoteClustersPluginApi" },
+        },
-        { "id": "kibReportingPluginApi" },
+        {
-        { "id": "kibRollupPluginApi" },
+          "id": "kibTaskManagerPluginApi"
-        { "id": "kibRuntimeFieldsPluginApi" },
+        },
-        { "id": "kibSavedObjectsManagementPluginApi" },
+        {
-        { "id": "kibSavedObjectsTaggingOssPluginApi" },
+          "id": "kibActionsPluginApi"
-        { "id": "kibSavedObjectsTaggingPluginApi" },
+        },
-        { "id": "kibSavedObjectsPluginApi" },
+        {
-        { "id": "kibScreenshottingPluginApi" },
+          "id": "kibEventLogPluginApi"
-        { "id": "kibSecuritySolutionPluginApi" },
+        },
-        { "id": "kibSecurityPluginApi" },
+        {
-        { "id": "kibSharePluginApi" },
+          "id": "kibTriggersActionsUiPluginApi"
-        { "id": "kibSnapshotRestorePluginApi" },
+        },
-        { "id": "kibSpacesPluginApi" },
+        {
-        { "id": "kibStackAlertsPluginApi" },
+          "id": "kibCasesPluginApi"
-        { "id": "kibTelemetryCollectionManagerPluginApi" },
+        },
-        { "id": "kibTelemetryCollectionXpackPluginApi" },
+        {
-        { "id": "kibTelemetryManagementSectionPluginApi" },
+          "id": "kibChartsPluginApi"
-        { "id": "kibTelemetryPluginApi" },
+        },
-        { "id": "kibUiActionsEnhancedPluginApi" },
+        {
-        { "id": "kibUiActionsPluginApi" },
+          "id": "kibDashboardPluginApi"
-        { "id": "kibUrlForwardingPluginApi" },
+        },
-        { "id": "kibUsageCollectionPluginApi" },
+        {
-        { "id": "kibVisTypeTimeseriesPluginApi" },
+          "id": "kibDevToolsPluginApi"
-        { "id": "kibVisualizationsPluginApi" }
+        },
+        {
+          "id": "kibDiscoverPluginApi"
+        },
+        {
+          "id": "kibEmbeddablePluginApi"
+        },
+        {
+          "id": "kibEncryptedSavedObjectsPluginApi"
+        },
+        {
+          "id": "kibEnterpriseSearchPluginApi"
+        },
+        {
+          "id": "kibEsUiSharedPluginApi"
+        },
+        {
+          "id": "kibExpressionsPluginApi"
+        },
+        {
+          "id": "kibFeaturesPluginApi"
+        },
+        {
+          "id": "kibFileUploadPluginApi"
+        },
+        {
+          "id": "kibFleetPluginApi"
+        },
+        {
+          "id": "kibGlobalSearchPluginApi"
+        },
+        {
+          "id": "kibHomePluginApi"
+        },
+        {
+          "id": "kibInspectorPluginApi"
+        },
+        {
+          "id": "kibKibanaReactPluginApi"
+        },
+        {
+          "id": "kibKibanaUtilsPluginApi"
+        },
+        {
+          "id": "kibLensPluginApi"
+        },
+        {
+          "id": "kibLicenseManagementPluginApi"
+        },
+        {
+          "id": "kibLicensingPluginApi"
+        },
+        {
+          "id": "kibListsPluginApi"
+        },
+        {
+          "id": "kibManagementPluginApi"
+        },
+        {
+          "id": "kibMapsPluginApi"
+        },
+        {
+          "id": "kibMlPluginApi"
+        },
+        {
+          "id": "kibMonitoringPluginApi"
+        },
+        {
+          "id": "kibNavigationPluginApi"
+        },
+        {
+          "id": "kibNewsfeedPluginApi"
+        },
+        {
+          "id": "kibObservabilityPluginApi"
+        },
+        {
+          "id": "kibRemoteClustersPluginApi"
+        },
+        {
+          "id": "kibReportingPluginApi"
+        },
+        {
+          "id": "kibRollupPluginApi"
+        },
+        {
+          "id": "kibRuntimeFieldsPluginApi"
+        },
+        {
+          "id": "kibSavedObjectsManagementPluginApi"
+        },
+        {
+          "id": "kibSavedObjectsTaggingOssPluginApi"
+        },
+        {
+          "id": "kibSavedObjectsTaggingPluginApi"
+        },
+        {
+          "id": "kibSavedObjectsPluginApi"
+        },
+        {
+          "id": "kibScreenshottingPluginApi"
+        },
+        {
+          "id": "kibSecuritySolutionPluginApi"
+        },
+        {
+          "id": "kibSecurityPluginApi"
+        },
+        {
+          "id": "kibSharePluginApi"
+        },
+        {
+          "id": "kibSnapshotRestorePluginApi"
+        },
+        {
+          "id": "kibSpacesPluginApi"
+        },
+        {
+          "id": "kibStackAlertsPluginApi"
+        },
+        {
+          "id": "kibTelemetryCollectionManagerPluginApi"
+        },
+        {
+          "id": "kibTelemetryCollectionXpackPluginApi"
+        },
+        {
+          "id": "kibTelemetryManagementSectionPluginApi"
+        },
+        {
+          "id": "kibTelemetryPluginApi"
+        },
+        {
+          "id": "kibUiActionsEnhancedPluginApi"
+        },
+        {
+          "id": "kibUiActionsPluginApi"
+        },
+        {
+          "id": "kibUrlForwardingPluginApi"
+        },
+        {
+          "id": "kibUsageCollectionPluginApi"
+        },
+        {
+          "id": "kibVisTypeTimeseriesPluginApi"
+        },
+        {
+          "id": "kibVisualizationsPluginApi"
+        }
       ]
     },
     {
       "label": "Operations",
       "items": [
-        { "id": "kibDevDocsOpsOverview", "label": "Overview" },
+        {
+          "id": "kibDevDocsOpsOverview",
+          "label": "Overview"
+        },
         {
           "label": "CI",
           "items": [
-            { "id": "kibDevDocsOpsCiStats" }
+            {
+              "id": "kibDevDocsOpsCiStats"
+            }
           ]
         },
         {
           "label": "Build tooling",
           "items": [
-            { "id": "kibDevDocsOpsOptimizer" },
+            {
-            { "id": "kibDevDocsOpsBabelPreset" },
+              "id": "kibDevDocsOpsOptimizer"
-            { "id": "kibDevDocsOpsTypeSummarizer" },
+            },
-            { "id": "kibDevDocsOpsBabelPluginSyntheticPackages" },
+            {
-            { "id": "kibDevDocsOpsUiSharedDepsNpm" },
+              "id": "kibDevDocsOpsBabelPreset"
-            { "id": "kibDevDocsOpsUiSharedDepsSrc" },
+            },
-            { "id": "kibDevDocsOpsPluginDiscovery" }
+            {
+              "id": "kibDevDocsOpsTypeSummarizer"
+            },
+            {
+              "id": "kibDevDocsOpsBabelPluginSyntheticPackages"
+            },
+            {
+              "id": "kibDevDocsOpsUiSharedDepsNpm"
+            },
+            {
+              "id": "kibDevDocsOpsUiSharedDepsSrc"
+            },
+            {
+              "id": "kibDevDocsOpsPluginDiscovery"
+            }
           ]
         },
         {
           "label": "Linting & Validation",
           "items": [
-            { "id": "kibDevDocsOpsEslintConfig" },
+            {
-            { "id": "kibDevDocsOpsEslintPluginEslint" },
+              "id": "kibDevDocsOpsEslintConfig"
-            { "id": "kibDevDocsOpsEslintWithTypes" },
+            },
-            { "id": "kibDevDocsOpsEslintPluginImports" }
+            {
+              "id": "kibDevDocsOpsEslintPluginEslint"
+            },
+            {
+              "id": "kibDevDocsOpsEslintWithTypes"
+            },
+            {
+              "id": "kibDevDocsOpsEslintPluginImports"
+            }
           ]
         },
         {
           "label": "Utilities",
           "items": [
-            { "id": "kibDevDocsToolingLog" },
+            {
-            { "id": "kibDevDocsOpsJestSerializers" },
+              "id": "kibDevDocsToolingLog"
-            { "id": "kibDevDocsOpsExpect" },
+            },
-            { "id": "kibDevDocsOpsAmbientStorybookTypes" },
+            {
-            { "id": "kibDevDocsOpsAmbientUiTypes" },
+              "id": "kibDevDocsOpsJestSerializers"
-            { "id": "kibDevDocsOpsTestSubjSelector" },
+            },
-            { "id": "kibDevDocsOpsBazelRunner" },
+            {
-            { "id": "kibDevDocsOpsCliDevMode" },
+              "id": "kibDevDocsOpsExpect"
-            { "id": "kibDevDocsOpsEs" }
+            },
+            {
+              "id": "kibDevDocsOpsAmbientStorybookTypes"
+            },
+            {
+              "id": "kibDevDocsOpsAmbientUiTypes"
+            },
+            {
+              "id": "kibDevDocsOpsTestSubjSelector"
+            },
+            {
+              "id": "kibDevDocsOpsBazelRunner"
+            },
+            {
+              "id": "kibDevDocsOpsCliDevMode"
+            },
+            {
+              "id": "kibDevDocsOpsEs"
+            }
           ]
         }
       ]
     }
   ]
-}
+}

x-pack/plugins/security/README.md

@@ -5,88 +5,4 @@ Kibana](https://www.elastic.co/guide/en/kibana/current/using-kibana-with-securit
 
 ## Audit logging
 
-### Example
+This section has been migrated to the dev docs system: `dev_docs/key_concepts/audit_logging.mdx`
-
-```typescript
-const auditLogger = securitySetup.audit.asScoped(request);
-auditLogger.log({
-  message: 'User is updating dashboard [id=123]',
-  event: {
-    action: 'saved_object_update',
-    category: ['database'],
-    type: ['change'],
-    outcome: 'unknown',
-  },
-  kibana: {
-    saved_object: { type: 'dashboard', id: '123' },
-  },
-});
-```
-
-### What events should be logged?
-
-The purpose of an audit log is to support compliance, accountability and
-security by capturing who performed an action, what action was performed and
-when it occurred. It is not the purpose of an audit log to aid with debugging
-the system or provide usage statistics.
-
-**Kibana guidelines:**
-
-Each API call to Kibana will result in a record in the audit log that captures
-general information about the request (`http_request` event).
-
-In addition to that, any operation that is performed on a resource owned by
-Kibana (e.g. saved objects) and that falls in the following categories, should
-be included in the audit log:
-
-- System access (incl. failed attempts due to authentication errors)
-- Data reads (incl. failed attempts due to authorisation errors)
-- Data writes (incl. failed attempts due to authorisation errors)
-
-If Kibana does not own the resource (e.g. when running queries against user
-indices), then auditing responsibilities are deferred to Elasticsearch and no
-additional events will be logged.
-
-**Examples:**
-
-For a list of audit events that Kibana currently logs see:
-`docs/user/security/audit-logging.asciidoc`
-
-### When should an event be logged?
-
-Due to the asynchronous nature of most operations in Kibana, there is an
-inherent tradeoff between the following logging approaches:
-
-- Logging the **intention** before performing an operation, leading to false
-  positives if the operation fails downstream.
-- Logging the **outcome** after completing an operation, leading to missing
-  records if Kibana crashes before the response is received.
-- Logging **both**, intention and outcome, leading to unnecessary duplication
-  and noisy/difficult to analyse logs.
-
-**Kibana guidelines:**
-
-- **Write operations** should be logged immediately after all authorisation
-  checks have passed, but before the response is received (logging the
-  intention). This ensures that a record of every operation is persisted even in
-  case of an unexpected error.
-- **Read operations**, on the other hand, should be logged after the operation
-  completed (logging the outcome) since we won't know what resources were
-  accessed before receiving the response.
-- Be explicit about the timing and outcome of an action in your messaging. (e.g.
-  "User has logged in" vs. "User is creating dashboard")
-
-### Can an action trigger multiple events?
-
-- A request to Kibana can perform a combination of different operations, each of
-  which should be captured as separate events.
-- Operations that are performed on multiple resources (**bulk operations**)
-  should be logged as separate events, one for each resource.
-- Actions that kick off **background tasks** should be logged as separate
-  events, one for creating the task and another one for executing it.
-- **Internal checks**, which have been carried out in order to perform an
-  operation, or **errors** that occured as a result of an operation should be
-  logged as an outcome of the operation itself, using the ECS `event.outcome`
-  and `error` fields, instead of logging a separate event.
-- Multiple events that were part of the same request can be correlated in the
-  audit log using the ECS `trace.id` property.