8.10 CSPM onboarding updates (#3806)

* First draft. TOC updates and GCP instructions * fixes filename * adds details to Findings pages * minor edit * Updated tags * minor title change * Update docs/cloud-native-security/cspm-get-started-gcp.asciidoc Co-authored-by: Uri Weisman <[email protected]> * Update docs/cloud-native-security/cspm-get-started-gcp.asciidoc Co-authored-by: Uri Weisman <[email protected]> * updating the main CSPM page to be more accurate with the required agent version * adds CSPM for AWS organization steps, addresses CSPM for GCP feedback * formatting update * minor edits * test code blocks * test * test * format * minor edits * minor formatting update * Incorporates Tinsae's feedback * image updates * minor edits * edit finish manual setup section * Update docs/cloud-native-security/cspm-get-started-aws.asciidoc * Update docs/cloud-native-security/cspm-get-started-gcp.asciidoc * Update docs/cloud-native-security/cspm-get-started-gcp.asciidoc * minor edit * minor edit --------- Co-authored-by: nastasha.solomon <[email protected]> Co-authored-by: Tin <[email protected]> Co-authored-by: Uri Weisman <[email protected]> Co-authored-by: tinnytintin10 <[email protected]> (cherry picked from commit b3a83a6)
elastic · Sep 12, 2023 · c396e6b · c396e6b
1 parent 6b5389a
commit c396e6b
Show file tree

Hide file tree

Showing 9 changed files with 239 additions and 30 deletions.
diff --git a/docs/cloud-native-security/cloud-native-security-index.asciidoc b/docs/cloud-native-security/cloud-native-security-index.asciidoc
@@ -38,7 +38,8 @@ Helps you monitor and protect your Linux VMs. It uses {elastic-defend} to instan
 include::security-posture-management.asciidoc[leveloffset=+1]
 
 include::cspm.asciidoc[leveloffset=+1]
-include::cspm-get-started.asciidoc[leveloffset=+2]
+include::cspm-get-started-aws.asciidoc[leveloffset=+2]
+include::cspm-get-started-gcp.asciidoc[leveloffset=+2]
 include::cspm-findings.asciidoc[leveloffset=+2]
 include::cspm-benchmark-rules.asciidoc[leveloffset=+2]
 include::cspm-cloud-posture-dashboard.asciidoc[leveloffset=+2]

diff --git a/docs/cloud-native-security/cspm-findings.asciidoc b/docs/cloud-native-security/cspm-findings.asciidoc
@@ -37,8 +37,17 @@ You can filter findings data in two ways:
 == Remediate failed findings
 To remediate failed findings and reduce your attack surface:
 
-. Navigate to the Findings page and <<findings-page-filter-findings,filter for failed findings>>.
-. Click a failed finding to open the findings flyout.
+. First, <<cspm-findings-page-filter-findings,filter for failed findings>>.
+. Click the arrow to the left of a failed finding to open the findings flyout.
 . Follow the steps under *Remediation*.
 +
 NOTE: Remediation steps typically include commands for you to execute. These sometimes contain placeholder values that you must replace before execution.
+
+[discrete]
+[[cspm-create-rule-from-finding]]
+== Generate alerts for failed Findings
+You can create detection rules that detect specific failed findings directly from the Findings page.
+
+. Click the arrow to the left of a Finding to open the findings flyout.
+. Click **Take action**, then **Create a detection rule**. This automatically creates a detection rule that creates alerts when the associated benchmark rule generates a failed finding.
+. To review or customize the new rule, click **View rule**.
diff --git a/...native-security/cspm-get-started.asciidoc → ...ve-security/cspm-get-started-aws.asciidoc b/...native-security/cspm-get-started.asciidoc → ...ve-security/cspm-get-started-aws.asciidoc
@@ -1,14 +1,12 @@
 [[cspm-get-started]]
-= Get started with CSPM
+= Get started with CSPM for AWS
 
 [discrete]
 [[cspm-overview]]
 == Overview
 
 This page explains how to get started monitoring the security posture of your cloud assets using the Cloud Security Posture Management (CSPM) feature.
 
-NOTE: The CSPM feature currently only supports posture evaluations for Amazon Web Service (AWS).
-
 .Requirements
 [sidebar]
 --
@@ -24,32 +22,34 @@ NOTE: The CSPM feature currently only supports posture evaluations for Amazon We
 [[cspm-setup]]
 == Set up CSPM for AWS
 
-To set up CSPM for AWS, first add the CSPM integration, then enable cloud account access.
-
+You can set up CSPM for AWS either by enroling a single cloud account, or by enroling an organization containing multiple accounts. Either way, first you will add the CSPM integration, then enable cloud account access.
 
 [discrete]
 [[cspm-add-and-name-integration]]
-=== Add your CSPM integration
+== Add the CSPM integration
 . From the Elastic Security *Get started* page, click *Add integrations*.
 . Search for `CSPM`, then click on the result.
 . Click *Add Cloud Security Posture Management (CSPM)*.
-. Give your integration a name that matches the purpose or team of the AWS account you want to monitor, for example, `dev-aws-account`.
+. Select *AWS*, then either *AWS Organization* to onboard multiple accounts, or *Single Account* to onboard an individual account.
+. Give your integration a name that matches the purpose or team of the AWS account/organization you want to monitor, for example, `dev-aws-account`.
+
 
 [discrete]
 [[cspm-set-up-cloud-access-section]]
-=== Set up cloud account access
+== Set up cloud account access
 The CSPM integration requires access to AWS’s built-in https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions.html#jf_security-auditor[`SecurityAudit` IAM policy] in order to discover and evaluate resources in your cloud account. There are several ways to provide access.
 
-For most users, the simplest option is to use AWS CloudFormation to automatically provision the necessary resources and permissions in your AWS account. This method, as well as several manual options, are described below.
+For most use cases, the simplest option is to use AWS CloudFormation to automatically provision the necessary resources and permissions in your AWS account. This method, as well as several manual options, are described below.
 
 [discrete]
 [[cspm-set-up-cloudformation]]
 === CloudFormation (recommended)
 . In the *Add Cloud Security Posture Management (CSPM) integration* menu, under *Setup Access*, select *CloudFormation*.
-. In a new browser tab or window, log in as an admin to the AWS account you want to onboard.
+. In a new browser tab or window, log in as an admin to the AWS account or organization you want to onboard.
 . Return to your {kib} tab. Click *Save and continue* at the bottom of the page.
 . Review the information, then click *Launch CloudFormation*.
-. A CloudFormation template appears in a new browser tab. You don't need to modify its configuration.
+. A CloudFormation template appears in a new browser tab.
+. For organization-level deployments only, you must enter the ID of the organizational unit where you want to deploy into the `OrganizationalUnitIds` field in the CloudFormation template. You can find it in the AWS console under *AWS Organizations -> AWS Accounts* (it appears under the organization name).
 . (Optional) Switch to the AWS region where you want to deploy using the controls in the upper right corner.
 . Tick the checkbox under *Capabilities* to authorize the creation of necessary resources.
 +
@@ -59,21 +59,123 @@ image::images/cspm-cloudformation-template.png[The Add permissions screen in AWS
 
 When you return to {kib}, click *View assets* to review the data being collected by your new integration.
 
+
+[discrete]
+[[cspm-setup-organization-manual]]
+=== Manual authentication for organization-level onboarding
+
+NOTE: If you're onboarding a single account instead of an organization, skip this section.
+
+When using manual authentication to onboard at the organization level, you need to configure the necessary permissions using the AWS console for the organization where you want to deploy:
+
+* In the organization's management account (root account), create an IAM role called `cloudbeat-root` (the name is important). The role needs several policies:
+
+** The following inline policy:
+
+.Click to expand policy
+[%collapsible]
+====
+```
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Action": [
+                "organizations:List*",
+                "organizations:Describe*"
+            ],
+            "Resource": "*",
+            "Effect": "Allow"
+        },
+        {
+            "Action": [
+                "sts:AssumeRole"
+            ],
+            "Resource": "*",
+            "Effect": "Allow"
+        }
+    ]
+}
+```
+====
+
+** The following trust policy:
+
+.Click to expand policy
+[%collapsible]
+====
+```
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Principal": {
+                "AWS": "arn:aws:iam::<Management Account ID>:root"
+            },
+            "Action": "sts:AssumeRole"
+        },
+        {
+            "Effect": "Allow",
+            "Principal": {
+                "Service": "ec2.amazonaws.com"
+            },
+            "Action": "sts:AssumeRole"
+        }
+    ]
+}
+```
+====
+
+** The AWS-managed `SecurityAudit` policy.
+
+IMPORTANT: You must replace `<Management account ID>` in the trust policy with your AWS account ID.
+
+* Next, for each account you want to scan in the organization, create an IAM role named `cloudbeat-securityaudit` with the following policies:
+** The AWS-managed `SecurityAudit` policy.
+** The following trust policy:
+
+.Click to expand policy
+[%collapsible]
+====
+```
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Principal": {
+                "AWS": "arn:aws:iam::<Management Account ID>:role/cloudbeat-root"
+            },
+            "Action": "sts:AssumeRole"
+        }
+    ]
+}
+```
+====
+
+IMPORTANT: You must replace `<Management account ID>` in the trust policy with your AWS account ID.
+
+After creating the necessary roles, authenticate using the <<cspm-use-instance-role, default instance role>> method.
+
 [discrete]
 [[cspm-set-up-manual]]
-=== Manual options
+== Manual authentication methods
 
 * <<cspm-use-instance-role,Default instance role (recommended)>>
 * <<cspm-use-keys-directly,Direct access keys>>
 * <<cspm-use-temp-credentials,Temporary security credentials>>
 * <<cspm-use-a-shared-credentials-file,Shared credentials file>>
 * <<cspm-use-iam-arn, IAM role Amazon Resource Name (ARN)>>
 
-IMPORTANT: Regardless of which option you use, you’ll need to attach AWS’s built-in https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions.html#jf_security-auditor[`SecurityAudit` IAM policy].
+IMPORTANT: Whichever method you use to authenticate, make sure AWS’s built-in https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions.html#jf_security-auditor[`SecurityAudit` IAM policy] is attached.
 
 [discrete]
 [[cspm-use-instance-role]]
-==== Option 1 - Default instance role
+=== Option 1 - Default instance role
+
+NOTE: If you are deploying to an AWS organization instead of an AWS account, you should already have <<cspm-setup-organization-manual, created a new role>>, `cloudbeat-root`. Skip to step 2 "Attach your new IAM role to an EC2 instance", and attach this role. You can use either an existing or new EC2 instance.
+
 Follow AWS's https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html[IAM roles for Amazon EC2] documentation to create an IAM role using the IAM console, which automatically generates an instance profile.
 
 . Create an IAM role:
@@ -102,7 +204,7 @@ IMPORTANT: Make sure to deploy the CSPM integration to this EC2 instance. When c
 
 [discrete]
 [[cspm-use-keys-directly]]
-==== Option 2 - Direct access keys
+=== Option 2 - Direct access keys
 Access keys are long-term credentials for an IAM user or AWS account root user. To use access keys as credentials, you must provide the `Access key ID` and the `Secret Access Key`. After you provide credentials, <<cspm-finish-manual, finish manual setup>>.
 
 For more details, refer to https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html[Access Keys and Secret Access Keys].
@@ -111,7 +213,7 @@ IMPORTANT: You must select *Programmatic access* when creating the IAM user.
 
 [discrete]
 [[cspm-use-temp-credentials]]
-==== Option 3 - Temporary security credentials
+=== Option 3 - Temporary security credentials
 You can configure temporary security credentials in AWS to last for a specified duration. They consist of an access key ID, a secret access key, and a security token, which is typically found using `GetSessionToken`.
 
 Because temporary security credentials are short term, once they expire, you will need to generate new ones and manually update the integration's configuration to continue collecting cloud posture data. Update the credentials before they expire to avoid data loss.
@@ -135,7 +237,7 @@ After you provide credentials, <<cspm-finish-manual, finish manual setup>>.
 
 [discrete]
 [[cspm-use-a-shared-credentials-file]]
-==== Option 4 - Shared credentials file
+=== Option 4 - Shared credentials file
 If you use different AWS credentials for different tools or applications, you can use profiles to define multiple access keys in the same configuration file. For more details, refer to AWS' https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html[Shared Credentials Files] documentation.
 
 Instead of providing the `Access key ID` and `Secret Access Key` to the integration, provide the information required to locate the access keys within the shared credentials file:
@@ -154,16 +256,24 @@ After providing credentials, <<cspm-finish-manual, finish manual setup>>.
 
 [discrete]
 [[cspm-use-iam-arn]]
-==== Option 5 - IAM role Amazon Resource Name (ARN)
+=== Option 5 - IAM role Amazon Resource Name (ARN)
 An IAM role Amazon Resource Name (ARN) is an IAM identity that you can create in your AWS account. You define the role's permissions. Roles do not have standard long-term credentials such as passwords or access keys. Instead, when you assume a role, it provides temporary security credentials for your session.
 
 To use an IAM role ARN, select *Assume role* under *Preferred manual method*, enter the ARN, and continue to Finish manual setup.
 
 [discrete]
 [[cspm-finish-manual]]
-=== Finish manual setup
-Once you’ve provided AWS credentials:
+== Finish manual setup
+Once you’ve provided AWS credentials, under *Where to add this integration*:
+
+If you want to monitor an AWS account or organization where you have not yet deployed {agent}:
 
-* If you want to monitor an AWS account where you have not yet deployed {agent}, select *New Hosts* under *Where to add this integration*.
+* Select *New Hosts*.
 * Name the {agent} policy. Use a name that matches the purpose or team of the cloud account or accounts you want to monitor. For example, `dev-aws-account`.
 * Click *Save and continue*, then *Add {agent} to your hosts*. The *Add agent* wizard appears and provides {agent} binaries, which you can download and deploy to your AWS account.
+
+If you want to monitor an AWS account or organization where you have already deployed {agent}:
+
+* Select **Existing hosts**.
+* Select an agent policy that applies the GCP project you want to monitor.
+* Click **Save and continue**.
diff --git a/docs/cloud-native-security/cspm-get-started-gcp.asciidoc b/docs/cloud-native-security/cspm-get-started-gcp.asciidoc
@@ -0,0 +1,82 @@
+[[cspm-get-started-gcp]]
+= Get started with CSPM for GCP
+
+[discrete]
+[[cspm-overview-gcp]]
+== Overview
+
+This page explains how to get started monitoring the security posture of your cloud assets using the Cloud Security Posture Management (CSPM) feature.
+
+.Requirements
+[sidebar]
+--
+* The CSPM integration is available to all {ecloud} users. On-premise deployments require an https://www.elastic.co/pricing[Enterprise subscription].
+* To view posture data, you need `read` privileges for the following {es} indices:
+** `logs-cloud_security_posture.findings_latest-*`
+** `logs-cloud_security_posture.scores-*`
+** `Logs-cloud_security_posture.findings`
+* The user who gives the CSPM integration GCP permissions must be a GCP project `admin`.
+--
+
+[discrete]
+[[cspm-setup-gcp]]
+== Set up CSPM for GCP
+
+To set up CSPM for GCP, first add the CSPM integration, then enable cloud account access.
+
+
+[discrete]
+[[cspm-add-and-name-integration-gcp]]
+=== Add your CSPM integration
+. From the Elastic Security *Get started* page, click *Add integrations*.
+. Search for `CSPM`, then click on the result.
+. Click *Add Cloud Security Posture Management (CSPM)*.
+. Give your integration a name that matches the purpose or team of the GCP account you want to monitor, for example, `dev-gcp-project`.
+
+[discrete]
+[[cspm-set-up-cloud-access-section-gcp]]
+=== Set up cloud account access
+To setup CSPM for a GCP project, you will need to have admin privileges for the project.
+
+For most users, the simplest option is to use a Google Cloud Shell script to automatically provision the necessary resources and permissions in your GCP account. This method, as well as two manual options, are described below.
+
+[discrete]
+[[cspm-set-up-cloudshell]]
+=== Cloud Shell script setup (recommended)
+
+. Under **Setup Access**, select **Google Cloud Shell**.
+. Under **Where to add this integration**:
+.. Select **New Hosts**.
+.. Name the {agent} policy. Use a name that matches the purpose or team of the cloud account or accounts you want to monitor. For example, `dev-gcp-account`.
+.. Click **Save and continue**, then **Add {agent} to your hosts**. The **Add agent** wizard appears and provides {agent} binaries, which you can download and deploy to a VM in your GCP account.
+. Click **Save and continue**.
+. Copy the command that appears, then click **Launch Google Cloud Shell**. It opens in a new window.
+. Check the box to trust Elastic's `cloudbeat` repo, then click **Confirm**
++
+image::images/cspm-cloudshell-trust.png[The cloud shell confirmation popup]
++
+. In Google Cloud Shell, execute the command you copied earlier. Once it finishes, return to {kib} and wait for the confirmation of data received from your new integration. Then you can click **View Assets** to see your data.
+
+NOTE: During Cloud Shell setup, the CSPM integration adds roles to Google's default service account, which enables custom role creation and attachment of the service account to a compute instance.
+After setup, these roles are removed from the service account. If you attempt to delete the deployment but find the deployment manager lacks necessary permissions, consider adding the missing roles to the service account:
+https://cloud.google.com/iam/docs/understanding-roles#resourcemanager.projectIamAdmin[Project IAM Admin], https://cloud.google.com/iam/docs/understanding-roles#iam.roleAdmin[Role Administrator].
+
+[discrete]
+[[cspm-set-up-manual-gcp]]
+=== Manual setup
+
+. Under **Setup Access** select **Manual**.
+. Enter your GCP **Project ID**.
+. Select either **Credentials File** or **Credentials JSON**.
+. Enter the credentials information in your selected format.
+. Under **Where to add this integration**,
+.. If you want to monitor a GCP project where you have not yet deployed {agent}:
+... Select **New Hosts**.
+... Name the {agent} policy. Use a name that matches the purpose or team of the cloud account or accounts you want to monitor. For example, `dev-gcp-account`.
+... Click **Save and continue**, then **Add {agent} to your hosts**. The **Add agent** wizard appears and provides {agent} binaries, which you can download and deploy to a VM in your GCP account.
+.. If you want to monitor a GCP project where you have already deployed {agent}:
+... Select **Existing hosts**.
+... Select an agent policy that applies the GCP project you want to monitor.
+. Click **Save and continue**.
+
+Wait for the confirmation that {kib} received data from your new integration. Then you can click **View Assets** to see your data.
diff --git a/docs/cloud-native-security/cspm.asciidoc b/docs/cloud-native-security/cspm.asciidoc
@@ -3,20 +3,18 @@
 
 The Cloud Security Posture Management (CSPM) feature discovers and evaluates the services in your cloud environment — like storage, compute, IAM, and more — against configuration security guidelines defined by the https://www.cisecurity.org/[Center for Internet Security] (CIS) to help you identify and remediate risks that could undermine the confidentiality, integrity, and availability of your cloud data.
 
-This feature currently supports Amazon Web Services (AWS). For a step-by-step getting started guide, refer to <<cspm-get-started,Get started with CSPM>>.
+This feature currently supports Amazon Web Services (AWS) and Google Cloud Platform (GCP). For step-by-step getting started guides, refer to <<cspm-get-started,Get started with CSPM for AWS>> or <<cspm-get-started-gcp, Get started with CSPM for GCP>>.
 
 .Requirements
 [sidebar]
 --
 * The CSPM integration is available to all {ecloud} users. On-premise deployments require an https://www.elastic.co/pricing[Enterprise subscription].
-* {stack} version 8.7 or greater.
+* {stack} version 8.10 or greater.
 --
 
 [discrete]
 [[cspm-how-it-works]]
 == How CSPM works
 
-To set up the CSPM feature, you'll install the CSPM integration for {agent} in your cloud account(s).
-
 Using the read-only credentials you will provide during the setup process, it will evaluate the configuration of resources in your environment every 4 hours.
 After each evaluation, the integration sends findings to Elastic. A high-level summary of the findings appears on the <<cloud-nat-sec-posture-dashboard,Cloud posture dashboard>>, and detailed findings appear on the <<findings-page,Findings page>>.
diff --git a/docs/cloud-native-security/images/cspm-cloudshell-trust.png b/docs/cloud-native-security/images/cspm-cloudshell-trust.png