Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[8.16] Updates CSPM guides to include agentless option #5863

Merged
merged 17 commits into from
Nov 11, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ This page describes what each solution does and provides links to more informati
== Cloud Security Posture Management (CSPM)
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.

To learn more, refer to <<cspm, Read the CSPM docs>>.
<<cspm, Read the CSPM docs>>.

[discrete]
== Kubernetes Security Posture Management (KSPM)
Expand Down
49 changes: 35 additions & 14 deletions docs/cloud-native-security/cspm-get-started-aws.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,31 @@ This page explains how to get started monitoring the security posture of your cl
[[cspm-setup]]
== Set up CSPM for AWS

You can set up CSPM for AWS either by enrolling a single cloud account, or by enrolling an organization containing multiple accounts. Either way, first you will add the CSPM integration, then enable cloud account access.
You can set up CSPM for AWS either by enrolling a single cloud account, or by enrolling an organization containing multiple accounts. Either way, first you will add the CSPM integration, then enable cloud account access. Two deployment technologies are available: agentless, and agent-based. <<cspm-aws-agentless, Agentless deployment>> allows you to collect cloud posture data without having to manage the deployment of {agent} in your cloud. <<cspm-aws-agent-based, Agent-based deployment>> requires you to deploy and manage {agent} in the cloud account you want to monitor.

[discrete]
[[cspm-aws-agentless]]
== Agentless deployment
beta::[]

. 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)*.
. 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`.
. Click **Advanced options**, then select **Agentless (BETA)**.
. Next, you'll need to authenticate to AWS. Two methods are available:
.. Option 1: Direct access keys/CloudFormation (Recommended). Under **Preferred method**, select **Direct access keys**. Expand the **Steps to Generate AWS Account Credentials** section, then follow the displayed instructions to automatically create the necessary credentials using CloudFormation.
.. Option 2: Temporary keys. To authenticate using temporary keys, refer to the instructions for <<cspm-use-temp-credentials, temporary keys>>.
. Once you've selected an authentication method and provided all necessary credentials, click **Save and continue** to finish deployment. Your data should start to appear within a few minutes.

[discrete]
[[cspm-aws-agent-based]]
== Agent-based deployment

[discrete]
[[cspm-add-and-name-integration]]
== Add the 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)*.
Expand All @@ -42,11 +62,12 @@ You can set up CSPM for AWS either by enrolling a single cloud account, or by en

[discrete]
[[cspm-set-up-cloud-access-section]]
== Set up cloud account access
The CSPM integration requires access to AWSs 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.
=== 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 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)
Expand All @@ -68,7 +89,7 @@ When you return to {kib}, click *View assets* to review the data being collected

[discrete]
[[cspm-setup-organization-manual]]
== Manual authentication for organization-level onboarding
=== Manual authentication for organization-level onboarding

NOTE: If you're onboarding a single account instead of an organization, skip this section.

Expand Down Expand Up @@ -168,7 +189,7 @@ IMPORTANT: When deploying to an organization using any of the authentication met

[discrete]
[[cspm-set-up-manual]]
== Manual authentication methods
=== Manual authentication methods

* <<cspm-use-instance-role,Default instance role (recommended)>>
* <<cspm-use-keys-directly,Direct access keys>>
Expand All @@ -180,7 +201,7 @@ IMPORTANT: Whichever method you use to authenticate, make sure AWS’s built-in

[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.

Expand Down Expand Up @@ -208,11 +229,11 @@ image::images/cspm-aws-auth-3.png[The EC2 page in AWS, showing the Modify IAM ro
.. Click *Update IAM role*.
.. Return to {kib} and <<cspm-finish-manual, finish manual setup>>.

IMPORTANT: Make sure to deploy the CSPM integration to this EC2 instance. When completing setup in {kib}, in the *Setup Access* section, select *Assume role* and leave *Role ARN* empty. Click *Save and continue*.
IMPORTANT: Make sure to deploy the CSPM integration to this EC2 instance. When completing setup in {kib}, in the **Setup Access* section, select *Assume role**. Leave **Role ARN** empty for agentless deployments. For agent-based deployments, leave it empty unless you want to specify a role the {agent} should assume instead of the default role for your EC2 instance. Click **Save and continue**.

[discrete]
[[cspm-use-keys-directly]]

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@smriti0321 I think there are a few callouts or troubleshooting guide for missing regarding Agentless Onboarding.

  • Once agentless integration has been created, then the status column which takes a few refreshes to see the updated agent count. A callout message talking about the agentless deployment experience taking a minute or two before agent is enrolled and/or ingesting data could be useful here.
  • Customer enters the wrong credentials with deployed agent. Maybe guide the customer through that experience to rectify an issue with the Edit Flow or restarting with the deletion flow then creation flow again.
  • Agent is offline or unhealthy then inform customer can still access fleets agents page or explore errors in Logs Explorer.
  • Deletion flow - warn the customer that deletion will remove resources and stop data ingestion
  • Changing the fleet server will cause breaking changes. @smriti0321 See comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great inputs @Omolola-Akinleye
@benironside is it possible to cover these in the FAQ for CSPM or you recommend any other place for troubleshooting agentless integrations?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the FAQ seems like a good option. Let's cover this in our next sync

=== 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].
Expand All @@ -221,8 +242,8 @@ IMPORTANT: You must select *Programmatic access* when creating the IAM user.

[discrete]
[[cspm-use-temp-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`.
==== 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 session 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.

Expand All @@ -245,7 +266,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:
Expand All @@ -264,14 +285,14 @@ 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
=== 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}:
Expand Down
19 changes: 18 additions & 1 deletion docs/cloud-native-security/cspm-get-started-azure.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,25 @@ This page explains how to get started monitoring the security posture of your cl
[[cspm-setup-azure]]
== Set up CSPM for Azure

You can set up CSPM for Azure by by enrolling an Azure organization (management group) containing multiple subscriptions, or by enrolling a single subscription. Either way, first add the CSPM integration, then enable cloud account access.
You can set up CSPM for Azure by by enrolling an Azure organization (management group) containing multiple subscriptions, or by enrolling a single subscription. Either way, first add the CSPM integration, then enable cloud account access. Two deployment technologies are available: agentless, and agent-based. <<cspm-azure-agentless, Agentless deployment>> allows you to collect cloud posture data without having to manage the deployment of an agent in your cloud. <<cspm-azure-agent-based, Agent-based deployment>> requires you to deploy and manage an agent in the cloud account you want to monitor.

[discrete]
[[cspm-azure-agentless]]
== Agentless deployment
beta::[]

. 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)*.
. Select *Azure*, then either *Azure Organization* to onboard your whole organization, or *Single Subscription* to onboard an individual subscription.
. Give your integration a name that matches the purpose or team of the Azure subscription/organization you want to monitor, for example, `dev-azure-account`.
. Click **Advanced options**, then select **Agentless (BETA)**.
. Next, you'll need to authenticate to Azure by providing a **Client ID**, **Tenant ID**, and **Client Secret**. To learn how to generate them, refer to <<cspm-azure-client-secret, Service principal with client secret>>.
. Once you've provided the necessary credentials, click **Save and continue** to finish deployment. Your data should start to appear within a few minutes.

[discrete]
[[cspm-azure-agent-based]]
== Agent-based deployment

[discrete]
[[cspm-add-and-name-integration-azure]]
Expand Down
22 changes: 20 additions & 2 deletions docs/cloud-native-security/cspm-get-started-gcp.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,28 @@ This page explains how to get started monitoring the security posture of your GC

[discrete]
[[cspm-setup-gcp]]
== Initial setup
== Set up CSPM for GCP

You can set up CSPM for GCP either by enrolling a single project, or by enrolling an organization containing multiple projects. Either way, you need to first add the CSPM integration, then enable cloud account access.
You can set up CSPM for GCP either by enrolling a single project, or by enrolling an organization containing multiple projects. Either way, you need to first add the CSPM integration, then enable cloud account access. Two deployment technologies are available: agentless, and agent-based. <<cspm-gcp-agentless, Agentless deployment>> allows you to collect cloud posture data without having to manage the deployment of an agent in your cloud. <<cspm-gcp-agent-based, Agent-based deployment>> requires you to deploy and manage an agent in the cloud account you want to monitor.

[discrete]
[[cspm-gcp-agentless]]
== Agentless deployment
beta::[]

. 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)*.
. Select *GCP*, then either *GCP Organization* to onboard your whole organization, or *Single Account* to onboard an individual account.
. Give your integration a name that matches the purpose or team of the GCP subscription/organization you want to monitor, for example, `dev-gcp-account`.
. Click **Advanced options**, then select **Agentless (BETA)**.
. Next, you'll need to authenticate to GCP. Expand the **Steps to Generate GCP Account Credentials** section, then follow the instructions that appear to automatically create the necessary credentials using Google Cloud Shell.
. Once you've provided the necessary credentials, click **Save and continue** to finish deployment. Your data should start to appear within a few minutes.


[discrete]
[[cspm-gcp-agent-based]]
== Agent-based deployment

[discrete]
[[cspm-add-and-name-integration-gcp]]
Expand Down
2 changes: 1 addition & 1 deletion docs/cloud-native-security/cspm.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

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), Google Cloud Platform (GCP), and Microsoft Azure. For step-by-step getting started guides, refer to <<cspm-get-started,Get started with CSPM for AWS>>, <<cspm-get-started-gcp, Get started with CSPM for GCP>>, or <<cspm-get-started-azure, Get started with CSPM for Azure>>.
This feature currently supports agentless and agent-based deployments on Amazon Web Services (AWS), Google Cloud Platform (GCP), and Microsoft Azure. For step-by-step getting started guides, refer to <<cspm-get-started,Get started with CSPM for AWS>>, <<cspm-get-started-gcp, Get started with CSPM for GCP>>, or <<cspm-get-started-azure, Get started with CSPM for Azure>>.

.Requirements
[sidebar]
Expand Down
10 changes: 10 additions & 0 deletions docs/getting-started/agentless-integrations.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
[[agentless-integrations]]
= Agentless integrations

beta::[]

Agentless integrations provide a means to ingest data while avoiding the orchestration, management, and maintenance needs associated with standard ingest infrastructure. Using agentless integrations makes manual agent deployment unnecessary, allowing you to focus on your data instead of the agent that collects it.

We currently support one agentless integration: cloud security posture management (CSPM). Using this integration's agentless deployment option, you can enable Elastic's CSPM capabilities just by providing the necessary credentials. Agentless CSPM deployments support AWS, Azure, and GCP accounts.

To learn more about agentless CSPM deployments, refer to the getting started guides for CSPM on <<cspm-get-started, AWS>>, <<cspm-get-started-azure, Azure>>, or <<cspm-get-started-gcp, GCP>>.
1 change: 1 addition & 0 deletions docs/getting-started/index.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ include::security-ui.asciidoc[leveloffset=+1]
include::ingest-data.asciidoc[leveloffset=+1]
include::threat-intel-integrations.asciidoc[leveloffset=+2]
include::automatic-import.asciidoc[leveloffset=+2]
include::agentless-integrations.asciidoc[leveloffset=+2]

include::security-spaces.asciidoc[leveloffset=+1]

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,26 @@ This page explains how to get started monitoring the security posture of your cl
[[cspm-setup-azure]]
== Set up CSPM for Azure

You can set up CSPM for Azure by by enrolling an Azure organization (management group) containing multiple subscriptions, or by enrolling a single subscription. Either way, first add the CSPM integration, then enable cloud account access.
You can set up CSPM for Azure by by enrolling an Azure organization (management group) containing multiple subscriptions, or by enrolling a single subscription. Either way, first add the CSPM integration, then enable cloud account access. Two deployment technologies are available: agentless, and agent-based. <<cspm-azure-agentless,Agentless deployment>> allows you to collect cloud posture data without having to manage the deployment of an agent in your cloud. <<cspm-azure-agent-based,Agent-based deployment>> requires you to deploy and manage an agent in the cloud account you want to monitor.

[discrete]
[[cspm-azure-agentless]]
== Agentless deployment

beta:[]

. 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)**.
. Select **Azure**, then either **Azure Organization** to onboard your whole organization, or **Single Subscription** to onboard an individual subscription.
. Give your integration a name that matches the purpose or team of the Azure subscription/organization you want to monitor, for example, `dev-azure-account`.
. Click **Advanced options**, then select **Agentless (BETA)**.
. Next, you'll need to authenticate to Azure by providing a **Client ID**, **Tenant ID**, and **Client Secret**. To learn how to generate them, refer to <<cspm-azure-client-secret,Service principal with client secret>>.
. Once you've provided the necessary credentials, click **Save and continue** to finish deployment. Your data should start to appear within a few minutes.

[discrete]
[[cspm-azure-agent-based]]
== Agent-based deployment

[discrete]
[[cspm-add-and-name-integration-azure]]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,28 @@ This page explains how to get started monitoring the security posture of your cl

[discrete]
[[cspm-setup-gcp]]
== Initial setup
== Set up CSPM for GCP

You can set up CSPM for GCP either by enrolling a single project, or by enrolling an organization containing multiple projects. Either way, you need to first add the CSPM integration, then enable cloud account access.
You can set up CSPM for GCP either by enrolling a single project, or by enrolling an organization containing multiple projects. Either way, you need to first add the CSPM integration, then enable cloud account access. Two deployment technologies are available: agentless, and agent-based. <<cspm-gcp-agentless,Agentless deployment>> allows you to collect cloud posture data without having to manage the deployment of an agent in your cloud. <<cspm-gcp-agent-based,Agent-based deployment>> requires you to deploy and manage an agent in the cloud account you want to monitor.

[discrete]
[[cspm-gcp-agentless]]
== Agentless deployment

beta:[]

. 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)**.
. Select **GCP**, then either **GCP Organization** to onboard your whole organization, or **Single Account** to onboard an individual account.
. Give your integration a name that matches the purpose or team of the GCP subscription/organization you want to monitor, for example, `dev-gcp-account`.
. Click **Advanced options**, then select **Agentless (BETA)**.
. Next, you'll need to authenticate to GCP. Expand the **Steps to Generate GCP Account Credentials** section, then follow the instructions that appear to automatically create the necessary credentials using Google Cloud Shell.
. Once you've provided the necessary credentials, click **Save and continue** to finish deployment. Your data should start to appear within a few minutes.

[discrete]
[[cspm-gcp-agent-based]]
== Agent-based deployment

[discrete]
[[cspm-add-and-name-integration-gcp]]
Expand Down
Loading