Auditing events for Continuous Delivery

As a security officer, auditor, or manager, you can use the Activity Tracker service to track how users and applications interact with the IBM Cloud® Continuous Delivery service and toolchain instances in IBM Cloud®.

IBM Cloud Activity Tracker records user-initiated activities that change the state of a service in IBM Cloud. You can use this service to investigate abnormal activity and critical actions and to comply with regulatory audit requirements. In addition, you can be alerted about actions as they happen. The events that are collected comply with the Cloud Auditing Data Federation (CADF) standard. For more information, see the getting started tutorial for IBM Cloud Activity Tracker.

Continuous Delivery automatically generates events for specific actions and forwards these event logs to IBM Cloud Activity Tracker. To access these logs, you must provision an instance of IBM Cloud Activity Tracker.

Events for Continuous Delivery

The following table lists the actions that generate Continuous Delivery data events:

Table 1. Actions that generate Continuous Delivery data events
Action	Description
`continuous-delivery.auth-user.create`	Manually or automatically add authorized users. For more information about automatically adding authorized users, see How are users counted for instances of Continuous Delivery in resource groups?
`continuous-delivery.auth-user.read`	View the list of authorized users from the Manage tab of a Continuous Delivery service instance
`continuous-delivery.auth-user.delete`	Delete authorized users from the Continuous Delivery service instance

Events for toolchains

The following table lists the actions that generate toolchain management events:

Table 2. Actions that generate toolchain management events
Action	Description
`toolchain.instance.create`	Create a toolchain
`toolchain.instance.update`	Rename a toolchain. This event is not sent when tool integrations are added to (`toolchain.tool-instance.deploy`) or removed from (`toolchain.tool-instance.undeploy`) a toolchain. If the toolchain is secured by a customer root key in a professional plan, the event contains the root key identifier.
`toolchain.instance.delete`	Delete a toolchain
`toolchain.tool-instance.deploy`	Add a tool integration to a toolchain
`toolchain.tool-instance.undeploy`	Remove a tool integration from a toolchain
`toolchain.instance-key-state.update`	Update the root key in the key management service (KMS) provider that the toolchain uses. For example, enable, disable, or rotate a root key in a KMS provider.
`toolchain.instance.unwrap`	Unwrap a wrapped Data Encryption Key (wDEK) in order to encrypt or decrypt customer personal information

The following table lists the actions that generate toolchain data events:

Table 3. Actions that generate toolchain data events
Action	Description
`toolchain.event.send`	Send a client bespoke toolchain event. The Activity Tracker event's metadata includes the bespoke toolchain event's `title` and `description` values.
`toolchain.tool-instance.create`	Add a tool integration to a toolchain. This event is always followed by the toolchain.tool-instance.deploy event.
`toolchain.tool-instance.read`	View the configuration of a tool integration
`toolchain.tool-instance.update`	Save configuration changes to a tool integration
`toolchain.tool-instance.delete`	Remove a tool integration from a toolchain. This event is always preceded by the toolchain.tool-instance.undeploy event.

Activity Tracker events are different from client bespoke toolchain events. When you invoke the POST /toolchains/{toolchain_id}/events API to send a bespoke toolchain event, the toolchain sends a notification event to any instances of Event Notifications that are integrated into the toolchain. In addition, the toolchain sends an Activity Tracker event that serves as a record of the API having been invoked.

Events for DevOps Insights

The following table lists the actions that generate DevOps Insights management events:

Table 4. Actions that generate DevOps Insights management events
Action	Description
`toolchain.insights-tag.create`	Create a tag
`toolchain.insights-tag.read`	View a tag
`toolchain.insights-tag.update`	Update a tag
`toolchain.insights-tag.delete`	Delete a tag
`toolchain.insights-decision.evaluate`	Make a gate decision on a build

The following table lists the actions that generate DevOps Insights data events:

Table 5. Actions that generate DevOps Insights data events
Action	Description
`toolchain.insights.read`	View any build, deploy, or test record
`toolchain.insights.update`	Publish a new build, deploy, or test record. The event's metadata includes `toolchainId` (unique identifier for toolchain) and might also contain the `build_artifact` (name of application), `build_id` (id of build), `branch` (Git branch of build), `environment_name` (name of environment where the test ran), and `operationId` (indicates how the update was completed, such as `postBuild`, `postResults`, `postDeployment`, `postResultsById`, `postLifeCycleStage`, `postBuildArtifactMetaData`, `putLifeCycleStage`, `putLifeCycleStagesOrder`, and `resultsMultipart`) values. The values that are included in the event's metadata is determined by the type of record (build, deployment, or test) that is published.
`toolchain.insights-policy.create`	Create a policy
`toolchain.insights-policy.read`	View a policy
`toolchain.insights-policy.update`	Update a policy. The event's metadata might include the `toolchainId` (unique identifier for toolchain) and `policyName` (name of policy that was updated) values.
`toolchain.insights-policy.delete`	Delete a policy
`toolchain.insights-data-toolchain.delete`	Delete data for a toolchain
`toolchain.insights-data-environment.delete`	Delete data for a specific environment
`toolchain.insights-data-application.delete`	Delete data for a specific application
`toolchain.insights-data-branch.delete`	Delete data for a specific application and branch

Events for Delivery Pipeline

The following table lists the actions that generate Delivery Pipeline management events:

Table 6. Actions that generate Delivery Pipeline management events
Action	Description
`toolchain.pipeline.create`	Create a delivery pipeline or a Tekton pipeline for a toolchain
`toolchain.pipeline-run.create`	Trigger a delivery pipeline or a Tekton pipeline to run manually or by using Git or a timer

The following table lists the actions that generate Delivery Pipeline data events:

Table 7. Actions that generate Delivery Pipeline data events
Action	Description
`toolchain.pipeline.read`	View the delivery pipeline or the Tekton pipeline from a Continuous Delivery service instance
`toolchain.pipeline.update`	Rename the delivery pipeline or a Tekton pipeline. Update pipeline properties. Add, edit, or delete stages. This event is triggered by a change to a tool integration configuration. Because the customer data that is included in a typical update might contain secret data, job scripts, and more, this event does not include the `InitialValue` and `newValue` values.
`toolchain.pipeline.delete`	Delete the delivery pipeline or Tekton pipeline from the Continuous Delivery toolchain instance
`toolchain.pipeline-run.read`	View the run logs for a delivery pipeline or a Tekton pipeline in the Tekton dashboard
`toolchain.pipeline-run.update`	Update the delivery pipeline when a job completes within a stage or a user cancels a stage. Because the customer data that is included in a typical update might contain secret data, log output, large data, and more, this event does not include the `InitialValue` and `newValue` values.
`toolchain.pipeline-run.delete`	Delete the delivery pipeline when a pipeline job run is deleted by the Continuous Delivery service. The delivery pipeline retains a limited number of runs.

Viewing events

Events that are generated by an instance of the Continuous Delivery service are automatically forwarded to the IBM Cloud Activity Tracker service instance that is available in the same location.

IBM Cloud Activity Tracker can have only one instance per location. To view events, you must access the web UI of the IBM Cloud Activity Tracker service in the same location where your service instance is available. For more information, see Launching the web UI through the IBM Cloud UI.

Analyzing events

When user emails are added to or removed from the authorized users list of a Continuous Delivery service instance in a resource group, Continuous Delivery sends events to IBM Cloud Activity Tracker when either of the following methods are used.

An administrator manually adds or removes a user email from the Manage tab of the Continuous Delivery service.
The system automatically adds one or more user emails in response to user-initiated or service-initiated actions with Continuous Delivery toolchains.

The following authorized user events are displayed in IBM Cloud Activity Tracker:

Continuous Delivery: create auth-user [service name] (auth-user(s): [EMAILS])
Continuous Delivery: delete auth-user [service name] (auth-user(s): [EMAILS])
Continuous Delivery: create auth-user [service name] (auth-user(s): [EMAILS]; root-action: [ACTION]; root-action-service-instance: [CRN])
Continuous Delivery: delete auth-user [service name] (auth-user(s): [EMAILS]; root-action: [ACTION]; root-action-service-instance: [CRN])

Where:

[EMAILS] is a comma-separated list of the user email IDs that are added to or removed from the list of authorized users.
[ACTION] identifies the action that prompted the automatic addition or removal of user emails from the list of authorized users. If a root-action is not specified, the addition or removal of the user emails was performed directly by a user from the Manage tab of the Continuous Delivery service dashboard.
[CRN] specifies the Cloud Resource Name of the resource to which the root-action was applied. This resource can either be a toolchain or the Continuous Delivery service instance itself.

The following table lists and describes the root actions that prompt user emails to automatically be added to or removed from the authorized users list.

Table 8. Actions that add or remove user emails from the authorized users list
Root action	Description
`continuous-delivery.instance.create`	Add a user email when the Continuous Delivery service is provisioned. This email belongs to the user who created the service instance. The `root-action-service-instance` CRN identifies the Continuous Delivery service instance.
`continuous-delivery.instance.delete`	Remove user emails when the Continuous Delivery service is de-provisioned. The `root-action-service-instance` CRN identifies the Continuous Delivery service instance.
`toolchain.git-repos-and-issue-tracking-repo.evaluate`	Add user emails after system evaluation of a Git Repos and Issue Tracking repo. Multiple emails that correspond to users with Developer (or greater) access to the repo might be added. The `root-action-service-instance` CRN identifies the toolchain that contains the Git Repos and Issue Tracking tool integration.
`toolchain.pipeline-stage.start`	Add user emails when a delivery pipeline stage starts. If the pipeline stage is manually started, the email of the user who started the pipeline is added. If a pipeline stage is triggered by a change to a repository (repo) in the Git Repos and Issue Tracking tool integration, multiple emails that correspond to users with Developer (or greater) access to the repo might be added. The `root-action-service-instance` CRN identifies the toolchain that contains the pipeline.
`toolchain.pipeline.read`	Add a user email when the user views a delivery pipeline. The `root-action-service-instance` CRN identifies the toolchain that contains the pipeline.
`toolchain.pipeline.update`	Add a user email when the user edits a delivery pipeline. The `root-action-service-instance` CRN identifies the toolchain that contains the pipeline.