From 8383a78ce7d3719c9819b0808db0999f5b5323a0 Mon Sep 17 00:00:00 2001 From: benironside Date: Tue, 4 Oct 2022 12:36:34 -0400 Subject: [PATCH 01/46] KSPM docs reorg --- .../cloud-native-security-index.asciidoc | 4 +- docs/cloud-native-security/findings.asciidoc | 10 +++ docs/cloud-native-security/kspm.asciidoc | 89 +++++++++++++++---- 3 files changed, 83 insertions(+), 20 deletions(-) create mode 100644 docs/cloud-native-security/findings.asciidoc diff --git a/docs/cloud-native-security/cloud-native-security-index.asciidoc b/docs/cloud-native-security/cloud-native-security-index.asciidoc index a1be9eeb34..db2fac1cf1 100644 --- a/docs/cloud-native-security/cloud-native-security-index.asciidoc +++ b/docs/cloud-native-security/cloud-native-security-index.asciidoc @@ -1,7 +1,9 @@ [[cloud-native-security-overview]] = Cloud native security -Elastic’s cloud security capabilities help you to improve your Kubernetes security posture by comparing your configuration to best practices, and help you monitor and investigate your Linux deployments inside and outside of Kubernetes. +Elastic’s cloud security capabilities help you to improve your Kubernetes security posture by comparing your configuration to best practices, and help you monitor and investigate your Linux deployments inside and outside of Kubernetes. include::kspm.asciidoc[leveloffset=+1] +include::cloud-posture-dashboard.asciidoc[leveloffset=+1] +include::findings.asciidoc[leveloffset=+1] include::benchmark-rules.asciidoc[leveloffset=+1] diff --git a/docs/cloud-native-security/findings.asciidoc b/docs/cloud-native-security/findings.asciidoc new file mode 100644 index 0000000000..d575a435b8 --- /dev/null +++ b/docs/cloud-native-security/findings.asciidoc @@ -0,0 +1,10 @@ +[[findings-page]] +== Findings page + +image::images/findings-page.png[The Findings page] + +The Findings page shows how the configuration of your Kubernetes clusters measures up to the standards defined on the <>. + +Findings are organized by the resource IDs of the associated Kubernetes infrastructure and include data about the infrastructure and benchmark rules. Each finding's result (which can be `pass` or `fail`) indicates whether a particular part of your Kubernetes infrastructure meets an active CSP benchmark rule. + +You can filter table data by entering queries into the KQL search bar. diff --git a/docs/cloud-native-security/kspm.asciidoc b/docs/cloud-native-security/kspm.asciidoc index 5f79050df1..f530a7f2ee 100644 --- a/docs/cloud-native-security/kspm.asciidoc +++ b/docs/cloud-native-security/kspm.asciidoc @@ -1,39 +1,90 @@ [[kspm]] = Kubernetes security posture management -The Kubernetes Security Posture Management (KSPM) integration allows you to monitor how your Kubernetes clusters' configuration measures up to security benchmarks. +The Kubernetes Security Posture Management (KSPM) integration allows you to identify security and compliance issues in the configuration of various Kubernetes components. -To set up the integration, you'll need to first add it to an {agent} policy, then deploy the KSPM DaemonSet to the Kubernetes clusters you want to monitor. +This integration is currently supported for use with unmanaged Kubernetes clusters, as well as clusters managed by Amazon EKS. To set it up, you'll need to first add it to an {agent} policy, then deploy the KSPM DaemonSet to the Kubernetes clusters you want to monitor. This process differs slightly depending on whether you intend to monitor unmanaged clusters or EKS-managed clusters. [discrete] -== Set up a KSPM integration -To install the integration: - +[[kspm-setup-eks]] +== Set up KSPM for Amazon EKS clusters 1. Go to *Dashboards -> Cloud Posture*. -2. Click *Add a CIS integration*. -3. Click *Add Kubernetes Security Posture Management*. -4. Name your integration. -5. Select whether to use the CIS or EKS Benchmarks — use CIS unless you're deploying on EKS. -6. Select the {agent} policy where you want to add the integration. -7. Click *Save and continue*, then *Add agent to your hosts*. The *Add agent* wizard appears and provides a DaemonSet manifest `.yaml` file with pre-populated configuration information, such as the `Fleet ID` and`Fleet URL`. +2. Click *Add a KSPM integration*. +3. Read the integration's readme to understand how it works. Then, click *Add Kubernetes Security Posture Management*. +4. Name your integration. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. +5. Select *Unmanaged Kubernetes* from the "Kubernetes Deployment" menu. A new section for AWS credentials will appear. +6. To get the necessary credentials, follow Amazon's instructions to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[create an IAM user], and define its permissions using the JSON permissions policy below. -image::images/kspm-add-agent-wizard.png[The KSPM integration's Add agent wizard] +IMPORTANT: You must select "Programmatic access" when creating the IAM user. + +``` +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": [ + "ecr:GetRegistryPolicy", + "eks:ListTagsForResource", + "elasticloadbalancing:DescribeTags", + "ecr-public:DescribeRegistries", + "ecr:DescribeRegistry", + "elasticloadbalancing:DescribeLoadBalancerPolicyTypes", + "ecr:ListImages", + "ecr-public:GetRepositoryPolicy", + "elasticloadbalancing:DescribeLoadBalancerAttributes", + "elasticloadbalancing:DescribeLoadBalancers", + "ecr-public:DescribeRepositories", + "eks:DescribeNodegroup", + "ecr:DescribeImages", + "elasticloadbalancing:DescribeLoadBalancerPolicies", + "ecr:DescribeRepositories", + "eks:DescribeCluster", + "eks:ListClusters", + "elasticloadbalancing:DescribeInstanceHealth", + "ecr:GetRepositoryPolicy" + ], + "Resource": "*" + } + ] +} +``` + +IMPORTANT: If you choose to use the AWS Shared credential file to provide credentials, make sure the associated role has the permissions listed above. + +* If you want to monitor Kubernetes clusters that aren’t yet enrolled in fleet, select *New Hosts* under “where to add this integration”. +* Name the agent policy. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. +* Click *Save and continue*, then *Add agent to your hosts*. The *Add agent* wizard appears and provides a DaemonSet manifest `.yaml` file with pre-populated configuration information, such as the `Fleet ID` and `Fleet URL`. The *Add agent* wizard helps you deploy a DaemonSet on the Kubernetes clusters you wish to monitor. To do this, for each cluster: 1. Download the manifest and make any necessary revisions to its configuration to suit the needs of your environment. 2. Apply the manifest using the `kubectl apply -f` command. For example: `kubectl apply -f elastic-agent-managed-kubernetes.yaml` -After about a minute, an “Agent enrollment confirmed” message appears, followed by “Incoming data confirmed." You can then click *View assets* to see where the newly-collected configuration information appears throughout {kib}, including the <> and the <>. +After a few minutes, an “Agent enrollment confirmed” message will appear, followed by “Incoming data confirmed." You can then click *View assets* to see where the newly-collected configuration information appears throughout {kib}, including the <> and the <>. +After applying the manifest, it will take about 10 minutes for the posture dashboard and findings page to display data. -[[findings-page]] [discrete] -== Findings page +[[kspm-setup-unmanaged]] +== Set up KSPM for unmanaged Kubernetes clusters + +To install the integration: +1. Go to *Dashboards -> Cloud Posture*. +2. Click *Add a KSPM integration*. +3. Read the integration's readme to understand how it works. Then, click *Add Kubernetes Security Posture Management*. +4. Name your integration. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. +5. Select *Unmanaged Kubernetes* from the "Kubernetes Deployment" menu. +6. If you want to monitor Kubernetes clusters that aren’t yet enrolled in fleet, select *New Hosts* under “where to add this integration”. +6. Select the {agent} policy where you want to add the integration. +7. Click *Save and continue*, then *Add agent to your hosts*. The *Add agent* wizard appears and provides a DaemonSet manifest `.yaml` file with pre-populated configuration information, such as the `Fleet ID` and `Fleet URL`. + +image::images/kspm-add-agent-wizard.png[The KSPM integration's Add agent wizard] -image::images/findings-page.png[The Findings page] -The Findings page shows how the configuration of your Kubernetes clusters measures up to the standards defined on the <>. +The *Add agent* wizard helps you deploy a DaemonSet on the Kubernetes clusters you wish to monitor. To do this, for each cluster: -Findings are organized by the resource IDs of the associated Kubernetes infrastructure and include data about the infrastructure and benchmark rules. Each finding's result (which can be `pass` or `fail`) indicates whether a particular part of your Kubernetes infrastructure meets an active CSP benchmark rule. +1. Download the manifest and make any necessary revisions to its configuration to suit the needs of your environment. +2. Apply the manifest using the `kubectl apply -f` command. For example: `kubectl apply -f elastic-agent-managed-kubernetes.yaml` -You can filter table data by entering queries into the KQL search bar. +After a few minutes, an “Agent enrollment confirmed” message will appear, followed by “Incoming data confirmed." You can then click *View assets* to see where the newly-collected configuration information appears throughout {kib}, including the <> and the <>. From f2e067f73a1f8e060a73736068adf5a0c33d85e3 Mon Sep 17 00:00:00 2001 From: benironside Date: Tue, 4 Oct 2022 13:18:58 -0400 Subject: [PATCH 02/46] Attempts to fix build error and removes outdated part of Benchmarks page --- docs/cloud-native-security/benchmark-rules.asciidoc | 1 - docs/cloud-native-security/cloud-native-security-index.asciidoc | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/cloud-native-security/benchmark-rules.asciidoc b/docs/cloud-native-security/benchmark-rules.asciidoc index 678caa4851..339d7837d5 100644 --- a/docs/cloud-native-security/benchmark-rules.asciidoc +++ b/docs/cloud-native-security/benchmark-rules.asciidoc @@ -8,6 +8,5 @@ image::images/benchmark-rules.png[The Benchmark rules page] You can then click on a benchmark rule's name to see details, including information about how to remediate failures and related links. -You can enable or disable benchmark rules for each integration, either individually or in bulk using the *Bulk Actions* menu. By default, benchmark rules are enabled. NOTE: Benchmark rules are not editable. diff --git a/docs/cloud-native-security/cloud-native-security-index.asciidoc b/docs/cloud-native-security/cloud-native-security-index.asciidoc index db2fac1cf1..25597d045a 100644 --- a/docs/cloud-native-security/cloud-native-security-index.asciidoc +++ b/docs/cloud-native-security/cloud-native-security-index.asciidoc @@ -4,6 +4,6 @@ Elastic’s cloud security capabilities help you to improve your Kubernetes security posture by comparing your configuration to best practices, and help you monitor and investigate your Linux deployments inside and outside of Kubernetes. include::kspm.asciidoc[leveloffset=+1] -include::cloud-posture-dashboard.asciidoc[leveloffset=+1] +include::cloud-posture.asciidoc[leveloffset=+1] include::findings.asciidoc[leveloffset=+1] include::benchmark-rules.asciidoc[leveloffset=+1] From ff54e957c9c64f6252e396a7e9524e7d5f6108d1 Mon Sep 17 00:00:00 2001 From: benironside Date: Tue, 4 Oct 2022 14:51:58 -0400 Subject: [PATCH 03/46] Fixes build error --- docs/cloud-native-security/cloud-native-security-index.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/cloud-native-security-index.asciidoc b/docs/cloud-native-security/cloud-native-security-index.asciidoc index 25597d045a..b5616ca74c 100644 --- a/docs/cloud-native-security/cloud-native-security-index.asciidoc +++ b/docs/cloud-native-security/cloud-native-security-index.asciidoc @@ -4,6 +4,6 @@ Elastic’s cloud security capabilities help you to improve your Kubernetes security posture by comparing your configuration to best practices, and help you monitor and investigate your Linux deployments inside and outside of Kubernetes. include::kspm.asciidoc[leveloffset=+1] -include::cloud-posture.asciidoc[leveloffset=+1] +include::{security-docs-root}/docs/dashboards/cloud-posture.asciidoc[leveloffset=+1] include::findings.asciidoc[leveloffset=+1] include::benchmark-rules.asciidoc[leveloffset=+1] From 1a2af91d4e6a469414e7306075e072166dd10eb7 Mon Sep 17 00:00:00 2001 From: benironside Date: Tue, 4 Oct 2022 15:49:09 -0400 Subject: [PATCH 04/46] testing build error --- docs/cloud-native-security/cloud-native-security-index.asciidoc | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/cloud-native-security/cloud-native-security-index.asciidoc b/docs/cloud-native-security/cloud-native-security-index.asciidoc index b5616ca74c..776b50ea86 100644 --- a/docs/cloud-native-security/cloud-native-security-index.asciidoc +++ b/docs/cloud-native-security/cloud-native-security-index.asciidoc @@ -4,6 +4,5 @@ Elastic’s cloud security capabilities help you to improve your Kubernetes security posture by comparing your configuration to best practices, and help you monitor and investigate your Linux deployments inside and outside of Kubernetes. include::kspm.asciidoc[leveloffset=+1] -include::{security-docs-root}/docs/dashboards/cloud-posture.asciidoc[leveloffset=+1] include::findings.asciidoc[leveloffset=+1] include::benchmark-rules.asciidoc[leveloffset=+1] From e281eef07e5b61687bf399b7b46e8968f947796b Mon Sep 17 00:00:00 2001 From: benironside Date: Tue, 4 Oct 2022 16:05:18 -0400 Subject: [PATCH 05/46] tests docs build --- docs/cloud-native-security/cloud-native-security-index.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/cloud-native-security/cloud-native-security-index.asciidoc b/docs/cloud-native-security/cloud-native-security-index.asciidoc index 776b50ea86..f657322709 100644 --- a/docs/cloud-native-security/cloud-native-security-index.asciidoc +++ b/docs/cloud-native-security/cloud-native-security-index.asciidoc @@ -6,3 +6,4 @@ Elastic’s cloud security capabilities help you to improve your Kubernetes secu include::kspm.asciidoc[leveloffset=+1] include::findings.asciidoc[leveloffset=+1] include::benchmark-rules.asciidoc[leveloffset=+1] +include::{security-docs-root}/docs/dashboards/cloud-posture.asciidoc[leveloffset=+1] From 4a104d43f0ca7d72092b5abecbbed61a68bc5601 Mon Sep 17 00:00:00 2001 From: benironside Date: Wed, 5 Oct 2022 11:56:02 -0400 Subject: [PATCH 06/46] Takes another approach to build problems --- .../cloud-native-security/benchmark-rules.asciidoc | 3 +-- .../cloud-nat-sec-posture-dashboard.asciidoc | 14 ++++++++++++++ .../cloud-native-security-index.asciidoc | 2 +- docs/dashboards/cloud-posture.asciidoc | 5 +++-- 4 files changed, 19 insertions(+), 5 deletions(-) create mode 100644 docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc diff --git a/docs/cloud-native-security/benchmark-rules.asciidoc b/docs/cloud-native-security/benchmark-rules.asciidoc index 339d7837d5..99006c95a7 100644 --- a/docs/cloud-native-security/benchmark-rules.asciidoc +++ b/docs/cloud-native-security/benchmark-rules.asciidoc @@ -1,6 +1,6 @@ [[benchmark-rules]] = Benchmark rules -The Benchmark Integrations page lets you view and manage cloud security posture (CSP) benchmark rules for each of your <>. Enabled benchmark rules define the Kubernetes configuration best practices that form the basis of the data that appears on the <>. +The Benchmark Integrations page lets you view the cloud security posture (CSP) benchmark rules for your <>. Benchmark rules define the Kubernetes configuration best practices that form the basis of the data that appears on the <>. To find the Benchmark Integrations page, go to **Manage -> CSP Benchmarks**. From there, to view the benchmark rules associated with an integration, select that integration's name. @@ -8,5 +8,4 @@ image::images/benchmark-rules.png[The Benchmark rules page] You can then click on a benchmark rule's name to see details, including information about how to remediate failures and related links. - NOTE: Benchmark rules are not editable. diff --git a/docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc b/docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc new file mode 100644 index 0000000000..bcb6751899 --- /dev/null +++ b/docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc @@ -0,0 +1,14 @@ +[[cloud-nat-sec-posture-dashboard]] += Cloud Posture dashboard + +The Cloud Posture dashboard summarizes how your Kubernetes configuration measures up to security benchmarks. + +NOTE: To learn how to collect this data, refer to <>. + +image::images/cloud-sec-dashboard.png[The Cloud Security dashboard] + +The first row of cards (Cloud Posture Score, Failed Findings, and Open Cases) summarizes your overall cloud security posture (CSP) by aggregating data from all monitored Kubernetes clusters. Each subsequent row summarizes the posture of an individual Kubernetes cluster. + +The Cloud Posture Score card shows the percentage of your findings that passed over time. Hover over the card to display when the data was collected. + +The Failed Findings card shows failed findings grouped by Center for Internet Security (CIS) benchmark categories. Click any section name to view its failed findings on the <>. diff --git a/docs/cloud-native-security/cloud-native-security-index.asciidoc b/docs/cloud-native-security/cloud-native-security-index.asciidoc index f657322709..fef5580158 100644 --- a/docs/cloud-native-security/cloud-native-security-index.asciidoc +++ b/docs/cloud-native-security/cloud-native-security-index.asciidoc @@ -6,4 +6,4 @@ Elastic’s cloud security capabilities help you to improve your Kubernetes secu include::kspm.asciidoc[leveloffset=+1] include::findings.asciidoc[leveloffset=+1] include::benchmark-rules.asciidoc[leveloffset=+1] -include::{security-docs-root}/docs/dashboards/cloud-posture.asciidoc[leveloffset=+1] +include::cloud-nat-sec-posture-dashboard.asciidoc[leveloffset=+1] diff --git a/docs/dashboards/cloud-posture.asciidoc b/docs/dashboards/cloud-posture.asciidoc index 081fc4792d..1defa1d54a 100644 --- a/docs/dashboards/cloud-posture.asciidoc +++ b/docs/dashboards/cloud-posture.asciidoc @@ -1,7 +1,8 @@ [[cloud-posture-dashboard]] +// Note: This page is intentionally duplicated by docs/cloud-native-security/cloud-nat-sec-posture.asciidoc. When you update this page, update that page to match. Then, just update the image path for that page, since the image is stored in docs/dashboards/images. = Cloud Posture dashboard -The Cloud Posture dashboard summarizes how your Kubernetes configuration measures up to security benchmarks. +The Cloud Posture dashboard summarizes how your Kubernetes configuration measures up to security benchmarks. NOTE: To learn how to collect this data, refer to <>. @@ -11,4 +12,4 @@ The first row of cards (Cloud Posture Score, Failed Findings, and Open Cases) su The Cloud Posture Score card shows the percentage of your findings that passed over time. Hover over the card to display when the data was collected. -The Failed Findings card shows failed findings grouped by Center for Internet Security (CIS) benchmark categories. Click any section name to view its failed findings on the <>. +The Failed Findings card shows failed findings grouped by Center for Internet Security (CIS) benchmark categories. Click any section name to view its failed findings on the <>. From e21c4e5a24a73049d7e26a99c84e7935df753149 Mon Sep 17 00:00:00 2001 From: benironside Date: Wed, 5 Oct 2022 12:38:20 -0400 Subject: [PATCH 07/46] Updates //comment --- docs/dashboards/cloud-posture.asciidoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/dashboards/cloud-posture.asciidoc b/docs/dashboards/cloud-posture.asciidoc index 1defa1d54a..a3b3545937 100644 --- a/docs/dashboards/cloud-posture.asciidoc +++ b/docs/dashboards/cloud-posture.asciidoc @@ -1,5 +1,6 @@ [[cloud-posture-dashboard]] -// Note: This page is intentionally duplicated by docs/cloud-native-security/cloud-nat-sec-posture.asciidoc. When you update this page, update that page to match. Then, just update the image path for that page, since the image is stored in docs/dashboards/images. +// Note: This page is intentionally duplicated by docs/cloud-native-security/cloud-nat-sec-posture.asciidoc. When you update this page, update that page to match. + = Cloud Posture dashboard The Cloud Posture dashboard summarizes how your Kubernetes configuration measures up to security benchmarks. From 5dd0e916c5642889549a8c99057ce7e5da844072 Mon Sep 17 00:00:00 2001 From: benironside Date: Wed, 5 Oct 2022 12:49:10 -0400 Subject: [PATCH 08/46] Update section headings for subordination --- docs/cloud-native-security/benchmark-rules.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/benchmark-rules.asciidoc b/docs/cloud-native-security/benchmark-rules.asciidoc index 99006c95a7..62ef91305c 100644 --- a/docs/cloud-native-security/benchmark-rules.asciidoc +++ b/docs/cloud-native-security/benchmark-rules.asciidoc @@ -1,5 +1,5 @@ [[benchmark-rules]] -= Benchmark rules +== Benchmark rules The Benchmark Integrations page lets you view the cloud security posture (CSP) benchmark rules for your <>. Benchmark rules define the Kubernetes configuration best practices that form the basis of the data that appears on the <>. To find the Benchmark Integrations page, go to **Manage -> CSP Benchmarks**. From there, to view the benchmark rules associated with an integration, select that integration's name. From d617756a387046ddf2abf1358defaf3574c52c8e Mon Sep 17 00:00:00 2001 From: benironside Date: Wed, 5 Oct 2022 13:12:09 -0400 Subject: [PATCH 09/46] make dashboard page subordinate to KSPM page --- .../cloud-nat-sec-posture-dashboard.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc b/docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc index bcb6751899..21588df311 100644 --- a/docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc +++ b/docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc @@ -1,5 +1,5 @@ [[cloud-nat-sec-posture-dashboard]] -= Cloud Posture dashboard +== Cloud Posture dashboard The Cloud Posture dashboard summarizes how your Kubernetes configuration measures up to security benchmarks. From b0c878d6ec388b0ad434f239937e2b872333ff6e Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Mon, 10 Oct 2022 16:41:53 -0400 Subject: [PATCH 10/46] Update docs/cloud-native-security/kspm.asciidoc Co-authored-by: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com> --- docs/cloud-native-security/kspm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/kspm.asciidoc b/docs/cloud-native-security/kspm.asciidoc index f530a7f2ee..133b0acdf4 100644 --- a/docs/cloud-native-security/kspm.asciidoc +++ b/docs/cloud-native-security/kspm.asciidoc @@ -62,7 +62,7 @@ The *Add agent* wizard helps you deploy a DaemonSet on the Kubernetes clusters y 1. Download the manifest and make any necessary revisions to its configuration to suit the needs of your environment. 2. Apply the manifest using the `kubectl apply -f` command. For example: `kubectl apply -f elastic-agent-managed-kubernetes.yaml` -After a few minutes, an “Agent enrollment confirmed” message will appear, followed by “Incoming data confirmed." You can then click *View assets* to see where the newly-collected configuration information appears throughout {kib}, including the <> and the <>. +After a few minutes, a message confirming the {agent} enrollment appears, followed by a message confirming that data is incoming. You can then click *View assets* to see where the newly-collected configuration information appears throughout {kib}, including the <> and the <>. After applying the manifest, it will take about 10 minutes for the posture dashboard and findings page to display data. [discrete] From c6d0e0da1ddbf8a9c76cae5a9a01ba7166eab10f Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Mon, 10 Oct 2022 16:42:03 -0400 Subject: [PATCH 11/46] Update docs/cloud-native-security/kspm.asciidoc Co-authored-by: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com> --- docs/cloud-native-security/kspm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/kspm.asciidoc b/docs/cloud-native-security/kspm.asciidoc index 133b0acdf4..99360cac1c 100644 --- a/docs/cloud-native-security/kspm.asciidoc +++ b/docs/cloud-native-security/kspm.asciidoc @@ -54,7 +54,7 @@ IMPORTANT: You must select "Programmatic access" when creating the IAM user. IMPORTANT: If you choose to use the AWS Shared credential file to provide credentials, make sure the associated role has the permissions listed above. * If you want to monitor Kubernetes clusters that aren’t yet enrolled in fleet, select *New Hosts* under “where to add this integration”. -* Name the agent policy. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. +* Name the {agent} policy. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. * Click *Save and continue*, then *Add agent to your hosts*. The *Add agent* wizard appears and provides a DaemonSet manifest `.yaml` file with pre-populated configuration information, such as the `Fleet ID` and `Fleet URL`. The *Add agent* wizard helps you deploy a DaemonSet on the Kubernetes clusters you wish to monitor. To do this, for each cluster: From 436351f7f117ef706a94e55df031b4d0b44e1cb3 Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Mon, 10 Oct 2022 16:42:33 -0400 Subject: [PATCH 12/46] Update docs/cloud-native-security/kspm.asciidoc Co-authored-by: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com> --- docs/cloud-native-security/kspm.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/cloud-native-security/kspm.asciidoc b/docs/cloud-native-security/kspm.asciidoc index 99360cac1c..8e0f72dc3a 100644 --- a/docs/cloud-native-security/kspm.asciidoc +++ b/docs/cloud-native-security/kspm.asciidoc @@ -70,6 +70,7 @@ After applying the manifest, it will take about 10 minutes for the posture dashb == Set up KSPM for unmanaged Kubernetes clusters To install the integration: + 1. Go to *Dashboards -> Cloud Posture*. 2. Click *Add a KSPM integration*. 3. Read the integration's readme to understand how it works. Then, click *Add Kubernetes Security Posture Management*. From 94dcdb1c3f3464f77df4637415b46266733a9c55 Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Mon, 10 Oct 2022 16:42:51 -0400 Subject: [PATCH 13/46] Update docs/cloud-native-security/kspm.asciidoc Co-authored-by: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com> --- docs/cloud-native-security/kspm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/kspm.asciidoc b/docs/cloud-native-security/kspm.asciidoc index 8e0f72dc3a..37114ef248 100644 --- a/docs/cloud-native-security/kspm.asciidoc +++ b/docs/cloud-native-security/kspm.asciidoc @@ -12,7 +12,7 @@ This integration is currently supported for use with unmanaged Kubernetes cluste 2. Click *Add a KSPM integration*. 3. Read the integration's readme to understand how it works. Then, click *Add Kubernetes Security Posture Management*. 4. Name your integration. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. -5. Select *Unmanaged Kubernetes* from the "Kubernetes Deployment" menu. A new section for AWS credentials will appear. +5. Select *Unmanaged Kubernetes* from the *Kubernetes Deployment* menu. A new section for AWS credentials will appear. 6. To get the necessary credentials, follow Amazon's instructions to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[create an IAM user], and define its permissions using the JSON permissions policy below. IMPORTANT: You must select "Programmatic access" when creating the IAM user. From 9d91fb5505838e0a5a73da3f9530e441c2911a74 Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Mon, 10 Oct 2022 16:43:07 -0400 Subject: [PATCH 14/46] Update docs/cloud-native-security/kspm.asciidoc Co-authored-by: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com> --- docs/cloud-native-security/kspm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/kspm.asciidoc b/docs/cloud-native-security/kspm.asciidoc index 37114ef248..e0f808b54c 100644 --- a/docs/cloud-native-security/kspm.asciidoc +++ b/docs/cloud-native-security/kspm.asciidoc @@ -75,7 +75,7 @@ To install the integration: 2. Click *Add a KSPM integration*. 3. Read the integration's readme to understand how it works. Then, click *Add Kubernetes Security Posture Management*. 4. Name your integration. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. -5. Select *Unmanaged Kubernetes* from the "Kubernetes Deployment" menu. +5. Select *Unmanaged Kubernetes* from the *Kubernetes Deployment* menu. 6. If you want to monitor Kubernetes clusters that aren’t yet enrolled in fleet, select *New Hosts* under “where to add this integration”. 6. Select the {agent} policy where you want to add the integration. 7. Click *Save and continue*, then *Add agent to your hosts*. The *Add agent* wizard appears and provides a DaemonSet manifest `.yaml` file with pre-populated configuration information, such as the `Fleet ID` and `Fleet URL`. From cc357661dbeb6c46ef064183d80d38ec792136f2 Mon Sep 17 00:00:00 2001 From: benironside Date: Mon, 10 Oct 2022 17:06:56 -0400 Subject: [PATCH 15/46] Adds ToC and creates "Getting started" page --- .../cloud-native-security-index.asciidoc | 1 + .../get-started-with-kspm.asciidoc | 101 ++++++++++++++++++ docs/cloud-native-security/kspm.asciidoc | 85 --------------- 3 files changed, 102 insertions(+), 85 deletions(-) create mode 100644 docs/cloud-native-security/get-started-with-kspm.asciidoc diff --git a/docs/cloud-native-security/cloud-native-security-index.asciidoc b/docs/cloud-native-security/cloud-native-security-index.asciidoc index fef5580158..6b601ca2c9 100644 --- a/docs/cloud-native-security/cloud-native-security-index.asciidoc +++ b/docs/cloud-native-security/cloud-native-security-index.asciidoc @@ -4,6 +4,7 @@ Elastic’s cloud security capabilities help you to improve your Kubernetes security posture by comparing your configuration to best practices, and help you monitor and investigate your Linux deployments inside and outside of Kubernetes. include::kspm.asciidoc[leveloffset=+1] +include::get-started-with-kspm.asciidoc[leveloffest=+1] include::findings.asciidoc[leveloffset=+1] include::benchmark-rules.asciidoc[leveloffset=+1] include::cloud-nat-sec-posture-dashboard.asciidoc[leveloffset=+1] diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc new file mode 100644 index 0000000000..a8c2cc52c3 --- /dev/null +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -0,0 +1,101 @@ +[[get-started-with-kspm]] +== Get started with KSPM +This page explains how to configure the Kubernetes Security Posture Management integration. + +The instructions differ depending on whether you're installing on EKS or on unmanaged clusters. + +1. Install on EKS-managed clusters: + * <> + * << ,Authenticate to AWS>> + +2. Install on unmanaged clusters: + * <> + * <> + +[discrete] +[[kspm-setup-eks]] +== Set up KSPM for Amazon EKS clusters + +1. Go to *Dashboards -> Cloud Posture*. +2. Click *Add a KSPM integration*. +3. Read the integration's readme to understand how it works. Then, click *Add Kubernetes Security Posture Management*. +4. Name your integration. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. +5. Select *Unmanaged Kubernetes* from the *Kubernetes Deployment* menu. A new section for AWS credentials will appear. +6. To get the necessary credentials, follow Amazon's instructions to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[create an IAM user], and define its permissions using the JSON permissions policy below. + +IMPORTANT: You must select "Programmatic access" when creating the IAM user. + +``` +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": [ + "ecr:GetRegistryPolicy", + "eks:ListTagsForResource", + "elasticloadbalancing:DescribeTags", + "ecr-public:DescribeRegistries", + "ecr:DescribeRegistry", + "elasticloadbalancing:DescribeLoadBalancerPolicyTypes", + "ecr:ListImages", + "ecr-public:GetRepositoryPolicy", + "elasticloadbalancing:DescribeLoadBalancerAttributes", + "elasticloadbalancing:DescribeLoadBalancers", + "ecr-public:DescribeRepositories", + "eks:DescribeNodegroup", + "ecr:DescribeImages", + "elasticloadbalancing:DescribeLoadBalancerPolicies", + "ecr:DescribeRepositories", + "eks:DescribeCluster", + "eks:ListClusters", + "elasticloadbalancing:DescribeInstanceHealth", + "ecr:GetRepositoryPolicy" + ], + "Resource": "*" + } + ] +} +``` + +IMPORTANT: If you choose to use the AWS Shared credential file to provide credentials, make sure the associated role has the permissions listed above. + +* If you want to monitor Kubernetes clusters that aren’t yet enrolled in fleet, select *New Hosts* under “where to add this integration”. +* Name the {agent} policy. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. +* Click *Save and continue*, then *Add agent to your hosts*. The *Add agent* wizard appears and provides a DaemonSet manifest `.yaml` file with pre-populated configuration information, such as the `Fleet ID` and `Fleet URL`. + +The *Add agent* wizard helps you deploy a DaemonSet on the Kubernetes clusters you wish to monitor. To do this, for each cluster: + +1. Download the manifest and make any necessary revisions to its configuration to suit the needs of your environment. +2. Apply the manifest using the `kubectl apply -f` command. For example: `kubectl apply -f elastic-agent-managed-kubernetes.yaml` + +After a few minutes, a message confirming the {agent} enrollment appears, followed by a message confirming that data is incoming. You can then click *View assets* to see where the newly-collected configuration information appears throughout {kib}, including the <> and the <>. +After applying the manifest, it will take about 10 minutes for the posture dashboard and findings page to display data. + + + +[discrete] +[[kspm-setup-unmanaged]] +== Set up KSPM for unmanaged Kubernetes clusters + +To install the integration: + +1. Go to *Dashboards -> Cloud Posture*. +2. Click *Add a KSPM integration*. +3. Read the integration's readme to understand how it works. Then, click *Add Kubernetes Security Posture Management*. +4. Name your integration. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. +5. Select *Unmanaged Kubernetes* from the *Kubernetes Deployment* menu. +6. If you want to monitor Kubernetes clusters that aren’t yet enrolled in fleet, select *New Hosts* under “where to add this integration”. +7. Select the {agent} policy where you want to add the integration. +8. Click *Save and continue*, then *Add agent to your hosts*. The *Add agent* wizard appears and provides a DaemonSet manifest `.yaml` file with pre-populated configuration information, such as the `Fleet ID` and `Fleet URL`. + +image::images/kspm-add-agent-wizard.png[The KSPM integration's Add agent wizard] + +[[kspm-setup-unmanaged-step-2]] +The *Add agent* wizard helps you deploy a DaemonSet on the Kubernetes clusters you wish to monitor. To do this, for each cluster: + +1. Download the manifest and make any necessary revisions to its configuration to suit the needs of your environment. +2. Apply the manifest using the `kubectl apply -f` command. For example: `kubectl apply -f elastic-agent-managed-kubernetes.yaml` + +After a few minutes, an “Agent enrollment confirmed” message will appear, followed by “Incoming data confirmed." You can then click *View assets* to see where the newly-collected configuration information appears throughout {kib}, including the <> and the <>. diff --git a/docs/cloud-native-security/kspm.asciidoc b/docs/cloud-native-security/kspm.asciidoc index e0f808b54c..85a498f934 100644 --- a/docs/cloud-native-security/kspm.asciidoc +++ b/docs/cloud-native-security/kspm.asciidoc @@ -4,88 +4,3 @@ The Kubernetes Security Posture Management (KSPM) integration allows you to identify security and compliance issues in the configuration of various Kubernetes components. This integration is currently supported for use with unmanaged Kubernetes clusters, as well as clusters managed by Amazon EKS. To set it up, you'll need to first add it to an {agent} policy, then deploy the KSPM DaemonSet to the Kubernetes clusters you want to monitor. This process differs slightly depending on whether you intend to monitor unmanaged clusters or EKS-managed clusters. - -[discrete] -[[kspm-setup-eks]] -== Set up KSPM for Amazon EKS clusters -1. Go to *Dashboards -> Cloud Posture*. -2. Click *Add a KSPM integration*. -3. Read the integration's readme to understand how it works. Then, click *Add Kubernetes Security Posture Management*. -4. Name your integration. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. -5. Select *Unmanaged Kubernetes* from the *Kubernetes Deployment* menu. A new section for AWS credentials will appear. -6. To get the necessary credentials, follow Amazon's instructions to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[create an IAM user], and define its permissions using the JSON permissions policy below. - -IMPORTANT: You must select "Programmatic access" when creating the IAM user. - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "VisualEditor0", - "Effect": "Allow", - "Action": [ - "ecr:GetRegistryPolicy", - "eks:ListTagsForResource", - "elasticloadbalancing:DescribeTags", - "ecr-public:DescribeRegistries", - "ecr:DescribeRegistry", - "elasticloadbalancing:DescribeLoadBalancerPolicyTypes", - "ecr:ListImages", - "ecr-public:GetRepositoryPolicy", - "elasticloadbalancing:DescribeLoadBalancerAttributes", - "elasticloadbalancing:DescribeLoadBalancers", - "ecr-public:DescribeRepositories", - "eks:DescribeNodegroup", - "ecr:DescribeImages", - "elasticloadbalancing:DescribeLoadBalancerPolicies", - "ecr:DescribeRepositories", - "eks:DescribeCluster", - "eks:ListClusters", - "elasticloadbalancing:DescribeInstanceHealth", - "ecr:GetRepositoryPolicy" - ], - "Resource": "*" - } - ] -} -``` - -IMPORTANT: If you choose to use the AWS Shared credential file to provide credentials, make sure the associated role has the permissions listed above. - -* If you want to monitor Kubernetes clusters that aren’t yet enrolled in fleet, select *New Hosts* under “where to add this integration”. -* Name the {agent} policy. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. -* Click *Save and continue*, then *Add agent to your hosts*. The *Add agent* wizard appears and provides a DaemonSet manifest `.yaml` file with pre-populated configuration information, such as the `Fleet ID` and `Fleet URL`. - -The *Add agent* wizard helps you deploy a DaemonSet on the Kubernetes clusters you wish to monitor. To do this, for each cluster: - -1. Download the manifest and make any necessary revisions to its configuration to suit the needs of your environment. -2. Apply the manifest using the `kubectl apply -f` command. For example: `kubectl apply -f elastic-agent-managed-kubernetes.yaml` - -After a few minutes, a message confirming the {agent} enrollment appears, followed by a message confirming that data is incoming. You can then click *View assets* to see where the newly-collected configuration information appears throughout {kib}, including the <> and the <>. -After applying the manifest, it will take about 10 minutes for the posture dashboard and findings page to display data. - -[discrete] -[[kspm-setup-unmanaged]] -== Set up KSPM for unmanaged Kubernetes clusters - -To install the integration: - -1. Go to *Dashboards -> Cloud Posture*. -2. Click *Add a KSPM integration*. -3. Read the integration's readme to understand how it works. Then, click *Add Kubernetes Security Posture Management*. -4. Name your integration. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. -5. Select *Unmanaged Kubernetes* from the *Kubernetes Deployment* menu. -6. If you want to monitor Kubernetes clusters that aren’t yet enrolled in fleet, select *New Hosts* under “where to add this integration”. -6. Select the {agent} policy where you want to add the integration. -7. Click *Save and continue*, then *Add agent to your hosts*. The *Add agent* wizard appears and provides a DaemonSet manifest `.yaml` file with pre-populated configuration information, such as the `Fleet ID` and `Fleet URL`. - -image::images/kspm-add-agent-wizard.png[The KSPM integration's Add agent wizard] - - -The *Add agent* wizard helps you deploy a DaemonSet on the Kubernetes clusters you wish to monitor. To do this, for each cluster: - -1. Download the manifest and make any necessary revisions to its configuration to suit the needs of your environment. -2. Apply the manifest using the `kubectl apply -f` command. For example: `kubectl apply -f elastic-agent-managed-kubernetes.yaml` - -After a few minutes, an “Agent enrollment confirmed” message will appear, followed by “Incoming data confirmed." You can then click *View assets* to see where the newly-collected configuration information appears throughout {kib}, including the <> and the <>. From 264b9d6dbc27bd654fb07f3c1faa70c2bb2a3fca Mon Sep 17 00:00:00 2001 From: benironside Date: Mon, 10 Oct 2022 17:25:40 -0400 Subject: [PATCH 16/46] troubleshoots ToC issue --- docs/cloud-native-security/get-started-with-kspm.asciidoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index a8c2cc52c3..4c9b0aaf79 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -6,7 +6,9 @@ The instructions differ depending on whether you're installing on EKS or on unma 1. Install on EKS-managed clusters: * <> - * << ,Authenticate to AWS>> + * <> + * <> + 2. Install on unmanaged clusters: * <> @@ -20,7 +22,7 @@ The instructions differ depending on whether you're installing on EKS or on unma 2. Click *Add a KSPM integration*. 3. Read the integration's readme to understand how it works. Then, click *Add Kubernetes Security Posture Management*. 4. Name your integration. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. -5. Select *Unmanaged Kubernetes* from the *Kubernetes Deployment* menu. A new section for AWS credentials will appear. +5. Select *EKS* from the *Kubernetes Deployment* menu. A new section for AWS credentials will appear. 6. To get the necessary credentials, follow Amazon's instructions to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[create an IAM user], and define its permissions using the JSON permissions policy below. IMPORTANT: You must select "Programmatic access" when creating the IAM user. From 2fb9e245feaa75687b40d9d5260d29d73de1dabe Mon Sep 17 00:00:00 2001 From: benironside Date: Mon, 10 Oct 2022 17:38:05 -0400 Subject: [PATCH 17/46] adds missing anchor --- docs/cloud-native-security/get-started-with-kspm.asciidoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index 4c9b0aaf79..7bbea98fb4 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -23,6 +23,9 @@ The instructions differ depending on whether you're installing on EKS or on unma 3. Read the integration's readme to understand how it works. Then, click *Add Kubernetes Security Posture Management*. 4. Name your integration. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. 5. Select *EKS* from the *Kubernetes Deployment* menu. A new section for AWS credentials will appear. + +[[kspm-setup-eks-step-2]] + 6. To get the necessary credentials, follow Amazon's instructions to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[create an IAM user], and define its permissions using the JSON permissions policy below. IMPORTANT: You must select "Programmatic access" when creating the IAM user. From 1b5804a1d741d80bf1af4f868a71d91eb9ad3e89 Mon Sep 17 00:00:00 2001 From: benironside Date: Mon, 10 Oct 2022 17:52:58 -0400 Subject: [PATCH 18/46] fixes build error --- docs/cloud-native-security/get-started-with-kspm.asciidoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index 7bbea98fb4..2325913b4f 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -26,7 +26,7 @@ The instructions differ depending on whether you're installing on EKS or on unma [[kspm-setup-eks-step-2]] -6. To get the necessary credentials, follow Amazon's instructions to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[create an IAM user], and define its permissions using the JSON permissions policy below. +To get the necessary credentials, follow Amazon's instructions to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[create an IAM user], and define its permissions using the JSON permissions policy below. IMPORTANT: You must select "Programmatic access" when creating the IAM user. @@ -70,6 +70,7 @@ IMPORTANT: If you choose to use the AWS Shared credential file to provide creden * Name the {agent} policy. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. * Click *Save and continue*, then *Add agent to your hosts*. The *Add agent* wizard appears and provides a DaemonSet manifest `.yaml` file with pre-populated configuration information, such as the `Fleet ID` and `Fleet URL`. +[[kspm-setup-eks-step-3]] The *Add agent* wizard helps you deploy a DaemonSet on the Kubernetes clusters you wish to monitor. To do this, for each cluster: 1. Download the manifest and make any necessary revisions to its configuration to suit the needs of your environment. From 9aadf029d791ccb96f7a095762a0834ac5d79e02 Mon Sep 17 00:00:00 2001 From: benironside Date: Mon, 10 Oct 2022 20:08:22 -0400 Subject: [PATCH 19/46] Add AWS auth details --- .../get-started-with-kspm.asciidoc | 91 +++++++++++++++++-- 1 file changed, 84 insertions(+), 7 deletions(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index 2325913b4f..a172517551 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -7,7 +7,8 @@ The instructions differ depending on whether you're installing on EKS or on unma 1. Install on EKS-managed clusters: * <> * <> - * <> + * <> + * <> 2. Install on unmanaged clusters: @@ -24,11 +25,18 @@ The instructions differ depending on whether you're installing on EKS or on unma 4. Name your integration. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. 5. Select *EKS* from the *Kubernetes Deployment* menu. A new section for AWS credentials will appear. +[discrete] [[kspm-setup-eks-step-2]] +=== Authenticate to AWS -To get the necessary credentials, follow Amazon's instructions to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[create an IAM user], and define its permissions using the JSON permissions policy below. +There are several options for how to provide AWS credentials, detailed below: -IMPORTANT: You must select "Programmatic access" when creating the IAM user. +* <> +* <> +* <> +* <> + +Regardless of which option you use, you'll need to grant the following permissions: ``` { @@ -64,13 +72,82 @@ IMPORTANT: You must select "Programmatic access" when creating the IAM user. } ``` -IMPORTANT: If you choose to use the AWS Shared credential file to provide credentials, make sure the associated role has the permissions listed above. +[discrete] +[[kspm-use-keys-directly]] +==== Option 1 - Use access keys directly: +Access keys are long-term credentials for an IAM user or the AWS account root user. To use access keys as credentials, you need to provide: + + * `Access key ID`: The first part of the access key. + * `Secret Access Key`: The second part of the access key. + +For more details refer to https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys[AWS Access Keys and Secret Access Keys]. + +IMPORTANT: You must select "Programmatic access" when creating the IAM user. + +[discrete] +[[kspm-use-temp-credentials]] +==== Option 2 - Use temporary security credentials: +Temporary security credentials can be configured in AWS to last for some period of time. They consist of an access key ID, a secret access key, and a security token, which is typically found using `GetSessionToken`. + +NOTE: IAM users with multi-factor authentication (MFA) enabled need to submit an MFA code when calling `GetSessionToken`. For more details refer to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html[AWS Temporary Security Credentials]. + +You can use the AWS CLI to generate temporary credentials. For example, you could use the following command if you have MFA enabled: `sts get-session-token --serial-number arn:aws:iam::1234:mfa/your-email@example.com --duration-seconds 129600 --token-code 123456` + +The output from this command should include the following fields, which you should supply to the KSPM integration: + +`Access key ID`: The first part of the access key. +`Secret Access Key`: The second part of the access key. +`Session Token`: A token required when using temporary security credentials. + +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. + +[discrete] +[[kspm-use-a-shared-credentials-file]] +==== Option 3 - Use a 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 https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds[Create Shared Credentials File] + +Instead of providing the `Access key ID` and `Secret Access Key` to the integration, you will provide the information required to locate the access keys within the shared credentials file: + +`Credential Profile Name`: The profile name in the shared credentials file. +`Shared Credential File`: The directory of the shared credentials file. + +If you don't provide values for all configuration fields, the integration will use these defaults: +- If none of `Access key ID`, `Secret Access Key` and `ARN Role` are provided, then the integration will check for `Credential Profile Name`. +- If there is no `Credential Profile Name`, the default profile will be used. +- If `Shared Credential File` is empty, the default directory will be used. + - For Linux or Unix, the shared credentials file is located at `~/.aws/credentials`. + +IMPORTANT: If you choose this option, make sure the associated role has the permissions listed above. + +[discrete] +[[kspm-use-iam-arn]] +==== Option 4 - Use an IAM role Amazon Resource Name (ARN): +An IAM role 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 you with temporary security credentials for your session. +An IAM role's ARN can be used to specify which AWS IAM role to use to generate temporary credentials. +For more details see the https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html[AssumeRole API documentation]. +Follow Amazon's instructions to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[create an IAM user], and define its permissions using the JSON permissions policy above. +To use an IAM role's ARN, you need to provide either a <> or <> along with the `ARN role`. +The `ARN Role` value specifies which AWS IAM role to use for generating temporary credentials. + +NOTE: If `ARN Role` is present, the integration will check if `Access key ID` and `Secret Access Key` are present. +If not, the package will check for a `Credential Profile Name`. +If a `Credential Profile Name` is not present, the default credential profile will be used. -* If you want to monitor Kubernetes clusters that aren’t yet enrolled in fleet, select *New Hosts* under “where to add this integration”. -* Name the {agent} policy. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. -* Click *Save and continue*, then *Add agent to your hosts*. The *Add agent* wizard appears and provides a DaemonSet manifest `.yaml` file with pre-populated configuration information, such as the `Fleet ID` and `Fleet URL`. [[kspm-setup-eks-step-3]] +[discrete] +==== Finish configuring the integration +Once you've provided AWS credentials, finish configuring the KSPM integration: + +1. If you want to monitor Kubernetes clusters that aren’t yet enrolled in fleet, select *New Hosts* under “where to add this integration”. +2. Name the {agent} policy. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. +3. Click *Save and continue*, then *Add agent to your hosts*. The *Add agent* wizard appears and provides a DaemonSet manifest `.yaml` file with pre-populated configuration information, such as the `Fleet ID` and `Fleet URL`. + +[[kspm-setup-eks-step-4]] +[discrete] +==== Modify and deploy the DaemonSet The *Add agent* wizard helps you deploy a DaemonSet on the Kubernetes clusters you wish to monitor. To do this, for each cluster: 1. Download the manifest and make any necessary revisions to its configuration to suit the needs of your environment. From ea2f5778696a210d1f72e7cc2ccc2c10a8c83609 Mon Sep 17 00:00:00 2001 From: benironside Date: Tue, 11 Oct 2022 09:21:41 -0400 Subject: [PATCH 20/46] troubleshoot headings/docs ToC --- .../get-started-with-kspm.asciidoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index a172517551..cfa2904e93 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -1,5 +1,5 @@ [[get-started-with-kspm]] -== Get started with KSPM +=== Get started with KSPM This page explains how to configure the Kubernetes Security Posture Management integration. The instructions differ depending on whether you're installing on EKS or on unmanaged clusters. @@ -17,7 +17,7 @@ The instructions differ depending on whether you're installing on EKS or on unma [discrete] [[kspm-setup-eks]] -== Set up KSPM for Amazon EKS clusters +=== Set up KSPM for Amazon EKS clusters 1. Go to *Dashboards -> Cloud Posture*. 2. Click *Add a KSPM integration*. @@ -27,7 +27,7 @@ The instructions differ depending on whether you're installing on EKS or on unma [discrete] [[kspm-setup-eks-step-2]] -=== Authenticate to AWS +==== Authenticate to AWS There are several options for how to provide AWS credentials, detailed below: @@ -74,7 +74,7 @@ Regardless of which option you use, you'll need to grant the following permissio [discrete] [[kspm-use-keys-directly]] -==== Option 1 - Use access keys directly: +===== Option 1 - Use access keys directly: Access keys are long-term credentials for an IAM user or the AWS account root user. To use access keys as credentials, you need to provide: * `Access key ID`: The first part of the access key. @@ -86,7 +86,7 @@ IMPORTANT: You must select "Programmatic access" when creating the IAM user. [discrete] [[kspm-use-temp-credentials]] -==== Option 2 - Use temporary security credentials: +===== Option 2 - Use temporary security credentials: Temporary security credentials can be configured in AWS to last for some period of time. They consist of an access key ID, a secret access key, and a security token, which is typically found using `GetSessionToken`. NOTE: IAM users with multi-factor authentication (MFA) enabled need to submit an MFA code when calling `GetSessionToken`. For more details refer to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html[AWS Temporary Security Credentials]. @@ -103,7 +103,7 @@ Because temporary security credentials are short term, once they expire you will [discrete] [[kspm-use-a-shared-credentials-file]] -==== Option 3 - Use a shared credentials file: +===== Option 3 - Use a 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 https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds[Create Shared Credentials File] Instead of providing the `Access key ID` and `Secret Access Key` to the integration, you will provide the information required to locate the access keys within the shared credentials file: @@ -121,7 +121,7 @@ IMPORTANT: If you choose this option, make sure the associated role has the perm [discrete] [[kspm-use-iam-arn]] -==== Option 4 - Use an IAM role Amazon Resource Name (ARN): +===== Option 4 - Use an IAM role Amazon Resource Name (ARN): An IAM role 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 you with temporary security credentials for your session. @@ -160,7 +160,7 @@ After applying the manifest, it will take about 10 minutes for the posture dashb [discrete] [[kspm-setup-unmanaged]] -== Set up KSPM for unmanaged Kubernetes clusters +=== Set up KSPM for unmanaged Kubernetes clusters To install the integration: From ed45fbf98314518dc6b8b6a38259496cc2388345 Mon Sep 17 00:00:00 2001 From: benironside Date: Tue, 11 Oct 2022 10:25:53 -0400 Subject: [PATCH 21/46] Minor fixes --- .../get-started-with-kspm.asciidoc | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index cfa2904e93..f9a316b25b 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -5,10 +5,10 @@ This page explains how to configure the Kubernetes Security Posture Management i The instructions differ depending on whether you're installing on EKS or on unmanaged clusters. 1. Install on EKS-managed clusters: - * <> + * <> * <> - * <> - * <> + * <> + * <> 2. Install on unmanaged clusters: @@ -19,6 +19,9 @@ The instructions differ depending on whether you're installing on EKS or on unma [[kspm-setup-eks]] === Set up KSPM for Amazon EKS clusters +[discrete] +==== Start configuring the KSPM integration + 1. Go to *Dashboards -> Cloud Posture*. 2. Click *Add a KSPM integration*. 3. Read the integration's readme to understand how it works. Then, click *Add Kubernetes Security Posture Management*. @@ -112,6 +115,7 @@ Instead of providing the `Access key ID` and `Secret Access Key` to the integrat `Shared Credential File`: The directory of the shared credentials file. If you don't provide values for all configuration fields, the integration will use these defaults: + - If none of `Access key ID`, `Secret Access Key` and `ARN Role` are provided, then the integration will check for `Credential Profile Name`. - If there is no `Credential Profile Name`, the default profile will be used. - If `Shared Credential File` is empty, the default directory will be used. @@ -138,7 +142,7 @@ If a `Credential Profile Name` is not present, the default credential profile wi [[kspm-setup-eks-step-3]] [discrete] -==== Finish configuring the integration +==== Finish configuring the KSPM integration Once you've provided AWS credentials, finish configuring the KSPM integration: 1. If you want to monitor Kubernetes clusters that aren’t yet enrolled in fleet, select *New Hosts* under “where to add this integration”. @@ -147,15 +151,13 @@ Once you've provided AWS credentials, finish configuring the KSPM integration: [[kspm-setup-eks-step-4]] [discrete] -==== Modify and deploy the DaemonSet +==== Modify and deploy the DaemonSet to your clusters The *Add agent* wizard helps you deploy a DaemonSet on the Kubernetes clusters you wish to monitor. To do this, for each cluster: 1. Download the manifest and make any necessary revisions to its configuration to suit the needs of your environment. 2. Apply the manifest using the `kubectl apply -f` command. For example: `kubectl apply -f elastic-agent-managed-kubernetes.yaml` After a few minutes, a message confirming the {agent} enrollment appears, followed by a message confirming that data is incoming. You can then click *View assets* to see where the newly-collected configuration information appears throughout {kib}, including the <> and the <>. -After applying the manifest, it will take about 10 minutes for the posture dashboard and findings page to display data. - [discrete] @@ -181,4 +183,4 @@ The *Add agent* wizard helps you deploy a DaemonSet on the Kubernetes clusters y 1. Download the manifest and make any necessary revisions to its configuration to suit the needs of your environment. 2. Apply the manifest using the `kubectl apply -f` command. For example: `kubectl apply -f elastic-agent-managed-kubernetes.yaml` -After a few minutes, an “Agent enrollment confirmed” message will appear, followed by “Incoming data confirmed." You can then click *View assets* to see where the newly-collected configuration information appears throughout {kib}, including the <> and the <>. +After a few minutes, a message confirming the {agent} enrollment appears, followed by a message confirming that data is incoming. You can then click *View assets* to see where the newly-collected configuration information appears throughout {kib}, including the <> and the <>. From 04494ad034a367e9a6b0d3a3a79c61408c07bf44 Mon Sep 17 00:00:00 2001 From: benironside Date: Tue, 11 Oct 2022 14:29:22 -0400 Subject: [PATCH 22/46] minor updates --- .../get-started-with-kspm.asciidoc | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index f9a316b25b..d7e6caa065 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -4,16 +4,16 @@ This page explains how to configure the Kubernetes Security Posture Management i The instructions differ depending on whether you're installing on EKS or on unmanaged clusters. -1. Install on EKS-managed clusters: - * <> - * <> - * <> - * <> +* Install on EKS-managed clusters: + 1. <> + 2. <> + 3. <> + 4. <> -2. Install on unmanaged clusters: - * <> - * <> +* Install on unmanaged clusters: + 1. <> + 2. <> [discrete] [[kspm-setup-eks]] @@ -142,7 +142,7 @@ If a `Credential Profile Name` is not present, the default credential profile wi [[kspm-setup-eks-step-3]] [discrete] -==== Finish configuring the KSPM integration +==== Finish configuring the KSPM integration for EKS Once you've provided AWS credentials, finish configuring the KSPM integration: 1. If you want to monitor Kubernetes clusters that aren’t yet enrolled in fleet, select *New Hosts* under “where to add this integration”. From 906ee12e7c6eb3695e6a3cd7b71dab7b1ccd0dfc Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Fri, 14 Oct 2022 10:40:41 -0400 Subject: [PATCH 23/46] Update docs/cloud-native-security/benchmark-rules.asciidoc Co-authored-by: Joe Peeples --- docs/cloud-native-security/benchmark-rules.asciidoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/cloud-native-security/benchmark-rules.asciidoc b/docs/cloud-native-security/benchmark-rules.asciidoc index 62ef91305c..c96749f624 100644 --- a/docs/cloud-native-security/benchmark-rules.asciidoc +++ b/docs/cloud-native-security/benchmark-rules.asciidoc @@ -4,7 +4,8 @@ The Benchmark Integrations page lets you view the cloud security posture (CSP) b To find the Benchmark Integrations page, go to **Manage -> CSP Benchmarks**. From there, to view the benchmark rules associated with an integration, select that integration's name. -image::images/benchmark-rules.png[The Benchmark rules page] +[role="screenshot"] +image::images/benchmark-rules.png[Benchmark rules page] You can then click on a benchmark rule's name to see details, including information about how to remediate failures and related links. From c49ac6a667096688b59c214dabb2e55f23c8f9d2 Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Fri, 14 Oct 2022 10:40:57 -0400 Subject: [PATCH 24/46] Update docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc Co-authored-by: Joe Peeples --- .../cloud-nat-sec-posture-dashboard.asciidoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc b/docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc index 21588df311..5c73a85d76 100644 --- a/docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc +++ b/docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc @@ -5,7 +5,8 @@ The Cloud Posture dashboard summarizes how your Kubernetes configuration measure NOTE: To learn how to collect this data, refer to <>. -image::images/cloud-sec-dashboard.png[The Cloud Security dashboard] +[role="screenshot"] +image::images/cloud-sec-dashboard.png[Cloud Security dashboard] The first row of cards (Cloud Posture Score, Failed Findings, and Open Cases) summarizes your overall cloud security posture (CSP) by aggregating data from all monitored Kubernetes clusters. Each subsequent row summarizes the posture of an individual Kubernetes cluster. From 7a926884669ae3176f8ff0abea41c107b65e7e68 Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Fri, 14 Oct 2022 10:41:20 -0400 Subject: [PATCH 25/46] Update docs/cloud-native-security/cloud-native-security-index.asciidoc Co-authored-by: Joe Peeples --- docs/cloud-native-security/cloud-native-security-index.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/cloud-native-security-index.asciidoc b/docs/cloud-native-security/cloud-native-security-index.asciidoc index 6b601ca2c9..d06987f457 100644 --- a/docs/cloud-native-security/cloud-native-security-index.asciidoc +++ b/docs/cloud-native-security/cloud-native-security-index.asciidoc @@ -1,7 +1,7 @@ [[cloud-native-security-overview]] = Cloud native security -Elastic’s cloud security capabilities help you to improve your Kubernetes security posture by comparing your configuration to best practices, and help you monitor and investigate your Linux deployments inside and outside of Kubernetes. +Elastic’s cloud security capabilities help you to improve your Kubernetes security posture by comparing your configuration to best practices, and allow you to monitor and investigate your Linux deployments inside and outside of Kubernetes. include::kspm.asciidoc[leveloffset=+1] include::get-started-with-kspm.asciidoc[leveloffest=+1] From 4c45c1c4e34df33c344d442854a829b17ba9091f Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Fri, 14 Oct 2022 10:41:28 -0400 Subject: [PATCH 26/46] Update docs/cloud-native-security/findings.asciidoc Co-authored-by: Joe Peeples --- docs/cloud-native-security/findings.asciidoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/cloud-native-security/findings.asciidoc b/docs/cloud-native-security/findings.asciidoc index d575a435b8..b7904e6208 100644 --- a/docs/cloud-native-security/findings.asciidoc +++ b/docs/cloud-native-security/findings.asciidoc @@ -1,7 +1,8 @@ [[findings-page]] == Findings page -image::images/findings-page.png[The Findings page] +[role="screenshot"] +image::images/findings-page.png[Findings page] The Findings page shows how the configuration of your Kubernetes clusters measures up to the standards defined on the <>. From 4d4e050878f652b3ec2f0e36f63b50a3b8a9c15e Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Fri, 14 Oct 2022 10:41:54 -0400 Subject: [PATCH 27/46] Update docs/cloud-native-security/findings.asciidoc Co-authored-by: Joe Peeples --- docs/cloud-native-security/findings.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/findings.asciidoc b/docs/cloud-native-security/findings.asciidoc index b7904e6208..727b1e9de5 100644 --- a/docs/cloud-native-security/findings.asciidoc +++ b/docs/cloud-native-security/findings.asciidoc @@ -4,7 +4,7 @@ [role="screenshot"] image::images/findings-page.png[Findings page] -The Findings page shows how the configuration of your Kubernetes clusters measures up to the standards defined on the <>. +The Findings page shows how your Kubernetes clusters' configuration measures up to the standards defined on the <>. Findings are organized by the resource IDs of the associated Kubernetes infrastructure and include data about the infrastructure and benchmark rules. Each finding's result (which can be `pass` or `fail`) indicates whether a particular part of your Kubernetes infrastructure meets an active CSP benchmark rule. From b026bd407d6c78be75b07309e47b0c62f5ce58c1 Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Fri, 14 Oct 2022 10:42:36 -0400 Subject: [PATCH 28/46] Update docs/cloud-native-security/get-started-with-kspm.asciidoc Co-authored-by: Joe Peeples --- docs/cloud-native-security/get-started-with-kspm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index d7e6caa065..da5a0f5a46 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -32,7 +32,7 @@ The instructions differ depending on whether you're installing on EKS or on unma [[kspm-setup-eks-step-2]] ==== Authenticate to AWS -There are several options for how to provide AWS credentials, detailed below: +There are several options for how to provide AWS credentials: * <> * <> From 0acf76b9d2137e62d492e0b163f27f1b0d6af879 Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Fri, 14 Oct 2022 10:42:46 -0400 Subject: [PATCH 29/46] Update docs/cloud-native-security/get-started-with-kspm.asciidoc Co-authored-by: Joe Peeples --- docs/cloud-native-security/get-started-with-kspm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index da5a0f5a46..92c51f003c 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -77,7 +77,7 @@ Regardless of which option you use, you'll need to grant the following permissio [discrete] [[kspm-use-keys-directly]] -===== Option 1 - Use access keys directly: +===== Option 1 - Use access keys directly Access keys are long-term credentials for an IAM user or the AWS account root user. To use access keys as credentials, you need to provide: * `Access key ID`: The first part of the access key. From b52b8ece8518c6f4eeef7431b803e067a5618324 Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Fri, 14 Oct 2022 10:43:37 -0400 Subject: [PATCH 30/46] Update docs/cloud-native-security/get-started-with-kspm.asciidoc Co-authored-by: Joe Peeples --- docs/cloud-native-security/get-started-with-kspm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index 92c51f003c..0bed8d503d 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -89,7 +89,7 @@ IMPORTANT: You must select "Programmatic access" when creating the IAM user. [discrete] [[kspm-use-temp-credentials]] -===== Option 2 - Use temporary security credentials: +===== Option 2 - Use temporary security credentials Temporary security credentials can be configured in AWS to last for some period of time. They consist of an access key ID, a secret access key, and a security token, which is typically found using `GetSessionToken`. NOTE: IAM users with multi-factor authentication (MFA) enabled need to submit an MFA code when calling `GetSessionToken`. For more details refer to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html[AWS Temporary Security Credentials]. From b9b1a0ac6c4f931dacf4a0215e52999669ee2cdc Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Fri, 14 Oct 2022 10:43:48 -0400 Subject: [PATCH 31/46] Update docs/cloud-native-security/get-started-with-kspm.asciidoc Co-authored-by: Joe Peeples --- docs/cloud-native-security/get-started-with-kspm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index 0bed8d503d..166ebcbe8c 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -90,7 +90,7 @@ IMPORTANT: You must select "Programmatic access" when creating the IAM user. [discrete] [[kspm-use-temp-credentials]] ===== Option 2 - Use temporary security credentials -Temporary security credentials can be configured in AWS to last for some period of time. They consist of an access key ID, a secret access key, and a security token, which is typically found using `GetSessionToken`. +Temporary security credentials can be configured in AWS to last for a specified period of time. They consist of an access key ID, a secret access key, and a security token, which is typically found using `GetSessionToken`. NOTE: IAM users with multi-factor authentication (MFA) enabled need to submit an MFA code when calling `GetSessionToken`. For more details refer to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html[AWS Temporary Security Credentials]. From 7400d73729524d836343837c70fb119b451150b7 Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Fri, 14 Oct 2022 10:43:58 -0400 Subject: [PATCH 32/46] Update docs/cloud-native-security/get-started-with-kspm.asciidoc Co-authored-by: Joe Peeples --- docs/cloud-native-security/get-started-with-kspm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index 166ebcbe8c..e8ca4b7af7 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -96,7 +96,7 @@ NOTE: IAM users with multi-factor authentication (MFA) enabled need to submit an You can use the AWS CLI to generate temporary credentials. For example, you could use the following command if you have MFA enabled: `sts get-session-token --serial-number arn:aws:iam::1234:mfa/your-email@example.com --duration-seconds 129600 --token-code 123456` -The output from this command should include the following fields, which you should supply to the KSPM integration: +The output from this command includes the following fields, which you should supply to the KSPM integration: `Access key ID`: The first part of the access key. `Secret Access Key`: The second part of the access key. From 585f6514422fe51d715abfac960ff01824cc2863 Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Fri, 14 Oct 2022 10:44:15 -0400 Subject: [PATCH 33/46] Update docs/cloud-native-security/findings.asciidoc Co-authored-by: Joe Peeples --- docs/cloud-native-security/findings.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/findings.asciidoc b/docs/cloud-native-security/findings.asciidoc index 727b1e9de5..a364c3e181 100644 --- a/docs/cloud-native-security/findings.asciidoc +++ b/docs/cloud-native-security/findings.asciidoc @@ -6,6 +6,6 @@ image::images/findings-page.png[Findings page] The Findings page shows how your Kubernetes clusters' configuration measures up to the standards defined on the <>. -Findings are organized by the resource IDs of the associated Kubernetes infrastructure and include data about the infrastructure and benchmark rules. Each finding's result (which can be `pass` or `fail`) indicates whether a particular part of your Kubernetes infrastructure meets an active CSP benchmark rule. +Findings are organized by the resource IDs of the associated Kubernetes infrastructure and include data about the infrastructure and benchmark rules. Each finding's result (`pass` or `fail`) indicates whether a particular part of your Kubernetes infrastructure meets an active CSP benchmark rule. You can filter table data by entering queries into the KQL search bar. From 0e8bc8525f1c4fad92013f5fac93bcc1281ae418 Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Fri, 14 Oct 2022 10:44:38 -0400 Subject: [PATCH 34/46] Update docs/cloud-native-security/get-started-with-kspm.asciidoc Co-authored-by: Joe Peeples --- docs/cloud-native-security/get-started-with-kspm.asciidoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index e8ca4b7af7..75617cfe5b 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -98,9 +98,9 @@ You can use the AWS CLI to generate temporary credentials. For example, you coul The output from this command includes the following fields, which you should supply to the KSPM integration: -`Access key ID`: The first part of the access key. -`Secret Access Key`: The second part of the access key. -`Session Token`: A token required when using temporary security credentials. +* `Access key ID`: The first part of the access key. +* `Secret Access Key`: The second part of the access key. +* `Session Token`: A token required when using temporary security credentials. 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. From 37b6d6d8f21ff9579db8d894ca7ea2c0b93f519b Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Fri, 14 Oct 2022 10:44:45 -0400 Subject: [PATCH 35/46] Update docs/cloud-native-security/get-started-with-kspm.asciidoc Co-authored-by: Joe Peeples --- docs/cloud-native-security/get-started-with-kspm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index 75617cfe5b..9477ef6218 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -106,7 +106,7 @@ Because temporary security credentials are short term, once they expire you will [discrete] [[kspm-use-a-shared-credentials-file]] -===== Option 3 - Use a shared credentials file: +===== Option 3 - Use a 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 https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds[Create Shared Credentials File] Instead of providing the `Access key ID` and `Secret Access Key` to the integration, you will provide the information required to locate the access keys within the shared credentials file: From d48088df59acc97a724ae361ef7bda93c16d398b Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Fri, 14 Oct 2022 10:45:26 -0400 Subject: [PATCH 36/46] Update docs/cloud-native-security/get-started-with-kspm.asciidoc Co-authored-by: Joe Peeples --- docs/cloud-native-security/get-started-with-kspm.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index 9477ef6218..03b23c1597 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -111,8 +111,8 @@ If you use different AWS credentials for different tools or applications, you ca Instead of providing the `Access key ID` and `Secret Access Key` to the integration, you will provide the information required to locate the access keys within the shared credentials file: -`Credential Profile Name`: The profile name in the shared credentials file. -`Shared Credential File`: The directory of the shared credentials file. +* `Credential Profile Name`: The profile name in the shared credentials file. +* `Shared Credential File`: The directory of the shared credentials file. If you don't provide values for all configuration fields, the integration will use these defaults: From 395963c9175c7e402e4fce2981558e5ceb5839f8 Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Fri, 14 Oct 2022 10:45:54 -0400 Subject: [PATCH 37/46] Update docs/cloud-native-security/get-started-with-kspm.asciidoc Co-authored-by: Joe Peeples --- docs/cloud-native-security/get-started-with-kspm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index 03b23c1597..4f5b883f23 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -125,7 +125,7 @@ IMPORTANT: If you choose this option, make sure the associated role has the perm [discrete] [[kspm-use-iam-arn]] -===== Option 4 - Use an IAM role Amazon Resource Name (ARN): +===== Option 4 - Use an IAM role Amazon Resource Name (ARN) An IAM role 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 you with temporary security credentials for your session. From ecff51f83e621cfe055c9a5865d57bf6450a4016 Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Fri, 14 Oct 2022 10:46:12 -0400 Subject: [PATCH 38/46] Update docs/cloud-native-security/get-started-with-kspm.asciidoc Co-authored-by: Joe Peeples --- docs/cloud-native-security/get-started-with-kspm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index 4f5b883f23..51bacaf52c 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -130,7 +130,7 @@ An IAM role ARN is an IAM identity that you can create in your AWS account. You Roles do not have standard long-term credentials such as passwords or access keys. Instead, when you assume a role it provides you with temporary security credentials for your session. An IAM role's ARN can be used to specify which AWS IAM role to use to generate temporary credentials. -For more details see the https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html[AssumeRole API documentation]. +For more details refer to Amazon's https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html[AssumeRole API documentation]. Follow Amazon's instructions to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[create an IAM user], and define its permissions using the JSON permissions policy above. To use an IAM role's ARN, you need to provide either a <> or <> along with the `ARN role`. The `ARN Role` value specifies which AWS IAM role to use for generating temporary credentials. From f5e8b98cefff71f614be9953662ac900090f99c7 Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Fri, 14 Oct 2022 10:46:25 -0400 Subject: [PATCH 39/46] Update docs/cloud-native-security/get-started-with-kspm.asciidoc Co-authored-by: Joe Peeples --- docs/cloud-native-security/get-started-with-kspm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index 51bacaf52c..93f5b82068 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -146,7 +146,7 @@ If a `Credential Profile Name` is not present, the default credential profile wi Once you've provided AWS credentials, finish configuring the KSPM integration: 1. If you want to monitor Kubernetes clusters that aren’t yet enrolled in fleet, select *New Hosts* under “where to add this integration”. -2. Name the {agent} policy. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. +2. Name the {agent} policy. Use a name that matches the purpose or team of the cluster(s) you want to monitor; for example, `IT-dev-k8s-clusters`. 3. Click *Save and continue*, then *Add agent to your hosts*. The *Add agent* wizard appears and provides a DaemonSet manifest `.yaml` file with pre-populated configuration information, such as the `Fleet ID` and `Fleet URL`. [[kspm-setup-eks-step-4]] From 87789925ff1898b1db67033c98d23191c1963f0c Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Fri, 14 Oct 2022 10:48:56 -0400 Subject: [PATCH 40/46] Update docs/cloud-native-security/get-started-with-kspm.asciidoc Co-authored-by: Joe Peeples --- docs/cloud-native-security/get-started-with-kspm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index 93f5b82068..e8432cca4f 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -152,7 +152,7 @@ Once you've provided AWS credentials, finish configuring the KSPM integration: [[kspm-setup-eks-step-4]] [discrete] ==== Modify and deploy the DaemonSet to your clusters -The *Add agent* wizard helps you deploy a DaemonSet on the Kubernetes clusters you wish to monitor. To do this, for each cluster: +The *Add agent* wizard helps you deploy a DaemonSet on the Kubernetes clusters you wish to monitor. For each cluster: 1. Download the manifest and make any necessary revisions to its configuration to suit the needs of your environment. 2. Apply the manifest using the `kubectl apply -f` command. For example: `kubectl apply -f elastic-agent-managed-kubernetes.yaml` From 3e76f8c141fe1be1ba48cefeacc4b7540d8acdfd Mon Sep 17 00:00:00 2001 From: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Date: Fri, 14 Oct 2022 10:49:22 -0400 Subject: [PATCH 41/46] Update docs/cloud-native-security/get-started-with-kspm.asciidoc Co-authored-by: Joe Peeples --- docs/cloud-native-security/get-started-with-kspm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index e8432cca4f..c891b8069f 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -171,7 +171,7 @@ To install the integration: 3. Read the integration's readme to understand how it works. Then, click *Add Kubernetes Security Posture Management*. 4. Name your integration. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. 5. Select *Unmanaged Kubernetes* from the *Kubernetes Deployment* menu. -6. If you want to monitor Kubernetes clusters that aren’t yet enrolled in fleet, select *New Hosts* under “where to add this integration”. +6. If you want to monitor Kubernetes clusters that aren’t yet enrolled in {fleet}, select *New Hosts* under “where to add this integration”. 7. Select the {agent} policy where you want to add the integration. 8. Click *Save and continue*, then *Add agent to your hosts*. The *Add agent* wizard appears and provides a DaemonSet manifest `.yaml` file with pre-populated configuration information, such as the `Fleet ID` and `Fleet URL`. From 714384ef8b60303c0b6bb1a441bee59e82d5e159 Mon Sep 17 00:00:00 2001 From: benironside Date: Fri, 14 Oct 2022 11:49:04 -0400 Subject: [PATCH 42/46] Incorporates Joe's and Nastasha's feedback. --- .../cloud-nat-sec-posture-dashboard.asciidoc | 2 +- .../get-started-with-kspm.asciidoc | 63 ++++++++++--------- docs/cloud-native-security/kspm.asciidoc | 2 +- 3 files changed, 35 insertions(+), 32 deletions(-) diff --git a/docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc b/docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc index 5c73a85d76..6b2bef5bcf 100644 --- a/docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc +++ b/docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc @@ -10,6 +10,6 @@ image::images/cloud-sec-dashboard.png[Cloud Security dashboard] The first row of cards (Cloud Posture Score, Failed Findings, and Open Cases) summarizes your overall cloud security posture (CSP) by aggregating data from all monitored Kubernetes clusters. Each subsequent row summarizes the posture of an individual Kubernetes cluster. -The Cloud Posture Score card shows the percentage of your findings that passed over time. Hover over the card to display when the data was collected. +The Cloud Posture Score card shows the performance of your Kubernetes clusters on <>. Hover over the card to display when the data was collected. The Failed Findings card shows failed findings grouped by Center for Internet Security (CIS) benchmark categories. Click any section name to view its failed findings on the <>. diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index c891b8069f..89457b36d8 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -5,18 +5,18 @@ This page explains how to configure the Kubernetes Security Posture Management i The instructions differ depending on whether you're installing on EKS or on unmanaged clusters. * Install on EKS-managed clusters: - 1. <> - 2. <> - 3. <> - 4. <> + 1. <> + 2. <> + 3. <> + 4. <> * Install on unmanaged clusters: 1. <> - 2. <> + 2. <> [discrete] -[[kspm-setup-eks]] +[[kspm-setup-eks-start]] === Set up KSPM for Amazon EKS clusters [discrete] @@ -24,12 +24,12 @@ The instructions differ depending on whether you're installing on EKS or on unma 1. Go to *Dashboards -> Cloud Posture*. 2. Click *Add a KSPM integration*. -3. Read the integration's readme to understand how it works. Then, click *Add Kubernetes Security Posture Management*. +3. Read the integration's description to understand how it works. Then, click *Add Kubernetes Security Posture Management*. 4. Name your integration. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. 5. Select *EKS* from the *Kubernetes Deployment* menu. A new section for AWS credentials will appear. [discrete] -[[kspm-setup-eks-step-2]] +[[kspm-setup-eks-auth]] ==== Authenticate to AWS There are several options for how to provide AWS credentials: @@ -78,12 +78,9 @@ Regardless of which option you use, you'll need to grant the following permissio [discrete] [[kspm-use-keys-directly]] ===== Option 1 - Use access keys directly -Access keys are long-term credentials for an IAM user or the AWS account root user. To use access keys as credentials, you need to provide: +Access keys are long-term credentials for an IAM user or the AWS account root user. To use access keys as credentials, you need to provide the `Access key ID` and the `Secret Access Key`. - * `Access key ID`: The first part of the access key. - * `Secret Access Key`: The second part of the access key. - -For more details refer to https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys[AWS Access Keys and Secret Access Keys]. +For more details refer to AWS's documentation for https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html[Access Keys and Secret Access Keys]. IMPORTANT: You must select "Programmatic access" when creating the IAM user. @@ -92,7 +89,9 @@ IMPORTANT: You must select "Programmatic access" when creating the IAM user. ===== Option 2 - Use temporary security credentials Temporary security credentials can be configured in AWS to last for a specified period of time. They consist of an access key ID, a secret access key, and a security token, which is typically found using `GetSessionToken`. -NOTE: IAM users with multi-factor authentication (MFA) enabled need to submit an MFA code when calling `GetSessionToken`. For more details refer to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html[AWS Temporary Security Credentials]. +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. + +NOTE: IAM users with multi-factor authentication (MFA) enabled need to submit an MFA code when calling `GetSessionToken`. For more details refer to AWS's documentation for https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html[Temporary Security Credentials]. You can use the AWS CLI to generate temporary credentials. For example, you could use the following command if you have MFA enabled: `sts get-session-token --serial-number arn:aws:iam::1234:mfa/your-email@example.com --duration-seconds 129600 --token-code 123456` @@ -102,36 +101,34 @@ The output from this command includes the following fields, which you should sup * `Secret Access Key`: The second part of the access key. * `Session Token`: A token required when using temporary security credentials. -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. - [discrete] [[kspm-use-a-shared-credentials-file]] ===== Option 3 - Use a 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 https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds[Create 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's documentation for https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html[Shared Credentials Files] -Instead of providing the `Access key ID` and `Secret Access Key` to the integration, you will provide the information required to locate the access keys within the shared credentials file: +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: * `Credential Profile Name`: The profile name in the shared credentials file. * `Shared Credential File`: The directory of the shared credentials file. If you don't provide values for all configuration fields, the integration will use these defaults: -- If none of `Access key ID`, `Secret Access Key` and `ARN Role` are provided, then the integration will check for `Credential Profile Name`. +- If `Access key ID`, `Secret Access Key`, and `ARN Role` are not provided, then the integration will check for `Credential Profile Name`. - If there is no `Credential Profile Name`, the default profile will be used. - If `Shared Credential File` is empty, the default directory will be used. - For Linux or Unix, the shared credentials file is located at `~/.aws/credentials`. -IMPORTANT: If you choose this option, make sure the associated role has the permissions listed above. - [discrete] [[kspm-use-iam-arn]] ===== Option 4 - Use an IAM role Amazon Resource Name (ARN) -An IAM role ARN is an IAM identity that you can create in your AWS account. You define the role's permissions. +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 you with temporary security credentials for your session. An IAM role's ARN can be used to specify which AWS IAM role to use to generate temporary credentials. -For more details refer to Amazon's https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html[AssumeRole API documentation]. -Follow Amazon's instructions to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[create an IAM user], and define its permissions using the JSON permissions policy above. + +For more details refer to AWS's https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html[AssumeRole API documentation]. +Follow AWS's instructions to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[create an IAM user], and define its permissions using the JSON permissions policy above. + To use an IAM role's ARN, you need to provide either a <> or <> along with the `ARN role`. The `ARN Role` value specifies which AWS IAM role to use for generating temporary credentials. @@ -140,16 +137,16 @@ If not, the package will check for a `Credential Profile Name`. If a `Credential Profile Name` is not present, the default credential profile will be used. -[[kspm-setup-eks-step-3]] +[[kspm-setup-eks-finish]] [discrete] ==== Finish configuring the KSPM integration for EKS Once you've provided AWS credentials, finish configuring the KSPM integration: -1. If you want to monitor Kubernetes clusters that aren’t yet enrolled in fleet, select *New Hosts* under “where to add this integration”. +1. If you want to monitor Kubernetes clusters that aren’t yet enrolled in {fleet}, select *New Hosts* under “where to add this integration”. 2. Name the {agent} policy. Use a name that matches the purpose or team of the cluster(s) you want to monitor; for example, `IT-dev-k8s-clusters`. 3. Click *Save and continue*, then *Add agent to your hosts*. The *Add agent* wizard appears and provides a DaemonSet manifest `.yaml` file with pre-populated configuration information, such as the `Fleet ID` and `Fleet URL`. -[[kspm-setup-eks-step-4]] +[[kspm-setup-eks-modify-deploy]] [discrete] ==== Modify and deploy the DaemonSet to your clusters The *Add agent* wizard helps you deploy a DaemonSet on the Kubernetes clusters you wish to monitor. For each cluster: @@ -164,20 +161,26 @@ After a few minutes, a message confirming the {agent} enrollment appears, follow [[kspm-setup-unmanaged]] === Set up KSPM for unmanaged Kubernetes clusters -To install the integration: +[discrete] +==== Configure the KSPM integration +To install the integration on unmanaged clusters: 1. Go to *Dashboards -> Cloud Posture*. 2. Click *Add a KSPM integration*. -3. Read the integration's readme to understand how it works. Then, click *Add Kubernetes Security Posture Management*. +3. Read the integration's description to understand how it works. Then, click *Add Kubernetes Security Posture Management*. 4. Name your integration. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. 5. Select *Unmanaged Kubernetes* from the *Kubernetes Deployment* menu. 6. If you want to monitor Kubernetes clusters that aren’t yet enrolled in {fleet}, select *New Hosts* under “where to add this integration”. 7. Select the {agent} policy where you want to add the integration. 8. Click *Save and continue*, then *Add agent to your hosts*. The *Add agent* wizard appears and provides a DaemonSet manifest `.yaml` file with pre-populated configuration information, such as the `Fleet ID` and `Fleet URL`. +[role="screenshot"] image::images/kspm-add-agent-wizard.png[The KSPM integration's Add agent wizard] -[[kspm-setup-unmanaged-step-2]] +[[kspm-setup-unmanaged-modify-deploy]] +[discrete] +==== Modify and deploy the DaemonSet to unmanaged clusters + The *Add agent* wizard helps you deploy a DaemonSet on the Kubernetes clusters you wish to monitor. To do this, for each cluster: 1. Download the manifest and make any necessary revisions to its configuration to suit the needs of your environment. diff --git a/docs/cloud-native-security/kspm.asciidoc b/docs/cloud-native-security/kspm.asciidoc index 85a498f934..829e5a7e55 100644 --- a/docs/cloud-native-security/kspm.asciidoc +++ b/docs/cloud-native-security/kspm.asciidoc @@ -3,4 +3,4 @@ The Kubernetes Security Posture Management (KSPM) integration allows you to identify security and compliance issues in the configuration of various Kubernetes components. -This integration is currently supported for use with unmanaged Kubernetes clusters, as well as clusters managed by Amazon EKS. To set it up, you'll need to first add it to an {agent} policy, then deploy the KSPM DaemonSet to the Kubernetes clusters you want to monitor. This process differs slightly depending on whether you intend to monitor unmanaged clusters or EKS-managed clusters. +This integration is currently supported for use with unmanaged Kubernetes clusters, as well as clusters managed by Amazon EKS. To set it up, you'll need to first add it to an {fleet-guide}/agent-policy.html[{agent} policy], then deploy the KSPM DaemonSet to the Kubernetes clusters you want to monitor. This process differs slightly depending on whether you intend to monitor unmanaged clusters or EKS-managed clusters. From 4fbeeb4d7b05c291c15dc15381129084faf18dd7 Mon Sep 17 00:00:00 2001 From: benironside Date: Fri, 14 Oct 2022 12:03:15 -0400 Subject: [PATCH 43/46] maintains dashboard doc parity --- .../cloud-nat-sec-posture-dashboard.asciidoc | 2 ++ docs/dashboards/cloud-posture.asciidoc | 5 +++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc b/docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc index 6b2bef5bcf..4809e43f5a 100644 --- a/docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc +++ b/docs/cloud-native-security/cloud-nat-sec-posture-dashboard.asciidoc @@ -1,4 +1,6 @@ [[cloud-nat-sec-posture-dashboard]] +// Note: This page is intentionally duplicated by docs/dashboards/cloud-posture.asciidoc. When you update this page, update that page to match. + == Cloud Posture dashboard The Cloud Posture dashboard summarizes how your Kubernetes configuration measures up to security benchmarks. diff --git a/docs/dashboards/cloud-posture.asciidoc b/docs/dashboards/cloud-posture.asciidoc index a3b3545937..84ee6e9ab3 100644 --- a/docs/dashboards/cloud-posture.asciidoc +++ b/docs/dashboards/cloud-posture.asciidoc @@ -7,10 +7,11 @@ The Cloud Posture dashboard summarizes how your Kubernetes configuration measure NOTE: To learn how to collect this data, refer to <>. -image::images/cloud-sec-dashboard.png[The Cloud Security dashboard] +[role="screenshot"] +image::images/cloud-sec-dashboard.png[Cloud Security dashboard] The first row of cards (Cloud Posture Score, Failed Findings, and Open Cases) summarizes your overall cloud security posture (CSP) by aggregating data from all monitored Kubernetes clusters. Each subsequent row summarizes the posture of an individual Kubernetes cluster. -The Cloud Posture Score card shows the percentage of your findings that passed over time. Hover over the card to display when the data was collected. +The Cloud Posture Score card shows the performance of your Kubernetes clusters on <>. Hover over the card to display when the data was collected. The Failed Findings card shows failed findings grouped by Center for Internet Security (CIS) benchmark categories. Click any section name to view its failed findings on the <>. From 18ed5935a45a1937575846ae50ea74dd5323c059 Mon Sep 17 00:00:00 2001 From: benironside Date: Fri, 14 Oct 2022 12:22:50 -0400 Subject: [PATCH 44/46] minor change --- docs/cloud-native-security/get-started-with-kspm.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index 89457b36d8..c966b1a4e7 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -170,7 +170,7 @@ To install the integration on unmanaged clusters: 3. Read the integration's description to understand how it works. Then, click *Add Kubernetes Security Posture Management*. 4. Name your integration. Use a name that matches the purpose or team of the cluster(s) you want to monitor, for example, `IT-dev-k8s-clusters`. 5. Select *Unmanaged Kubernetes* from the *Kubernetes Deployment* menu. -6. If you want to monitor Kubernetes clusters that aren’t yet enrolled in {fleet}, select *New Hosts* under “where to add this integration”. +6. If you want to monitor Kubernetes clusters that aren’t yet enrolled in {fleet}, select *New Hosts* when choosing the {agent} policy. 7. Select the {agent} policy where you want to add the integration. 8. Click *Save and continue*, then *Add agent to your hosts*. The *Add agent* wizard appears and provides a DaemonSet manifest `.yaml` file with pre-populated configuration information, such as the `Fleet ID` and `Fleet URL`. From 96689a08583a3e9ccbec7f4aaa31ea31f2258a4e Mon Sep 17 00:00:00 2001 From: benironside Date: Mon, 17 Oct 2022 15:39:32 -0400 Subject: [PATCH 45/46] Incorporates Janeen's and Tinsae's feedback --- .../get-started-with-kspm.asciidoc | 78 ++++++++++++++----- 1 file changed, 57 insertions(+), 21 deletions(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index c966b1a4e7..b8fea179aa 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -5,22 +5,22 @@ This page explains how to configure the Kubernetes Security Posture Management i The instructions differ depending on whether you're installing on EKS or on unmanaged clusters. * Install on EKS-managed clusters: - 1. <> + 1. <> 2. <> 3. <> - 4. <> + 4. <> * Install on unmanaged clusters: 1. <> - 2. <> + 2. <> [discrete] [[kspm-setup-eks-start]] === Set up KSPM for Amazon EKS clusters [discrete] -==== Start configuring the KSPM integration +==== Name your integration and select a Kubernetes Deployment type 1. Go to *Dashboards -> Cloud Posture*. 2. Click *Add a KSPM integration*. @@ -41,7 +41,36 @@ There are several options for how to provide AWS credentials: Regardless of which option you use, you'll need to grant the following permissions: -``` + + +[source,console] +---------------------------------- +ecr:GetRegistryPolicy, +eks:ListTagsForResource +elasticloadbalancing:DescribeTags +ecr-public:DescribeRegistries +ecr:DescribeRegistry +elasticloadbalancing:DescribeLoadBalancerPolicyTypes +ecr:ListImages +ecr-public:GetRepositoryPolicy +elasticloadbalancing:DescribeLoadBalancerAttributes +elasticloadbalancing:DescribeLoadBalancers +ecr-public:DescribeRepositories +eks:DescribeNodegroup +ecr:DescribeImages +elasticloadbalancing:DescribeLoadBalancerPolicies +ecr:DescribeRepositories +eks:DescribeCluster +eks:ListClusters +elasticloadbalancing:DescribeInstanceHealth +ecr:GetRepositoryPolicy +---------------------------------- + +If you are using the AWS visual editor to create and modify your IAM Policies, you can copy and paste this IAM policy JSON object: + +.Click to view JSON object +[%collapsible] +==== { "Version": "2012-10-17", "Statement": [ @@ -73,29 +102,34 @@ Regardless of which option you use, you'll need to grant the following permissio } ] } -``` +==== [discrete] [[kspm-use-keys-directly]] ===== Option 1 - Use access keys directly Access keys are long-term credentials for an IAM user or the AWS account root user. To use access keys as credentials, you need to provide the `Access key ID` and the `Secret Access Key`. -For more details refer to AWS's documentation for https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html[Access Keys and Secret Access Keys]. +For more details, refer to AWS' https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html[Access Keys and Secret Access Keys] documentation. IMPORTANT: You must select "Programmatic access" when creating the IAM user. [discrete] [[kspm-use-temp-credentials]] ===== Option 2 - Use temporary security credentials -Temporary security credentials can be configured in AWS to last for a specified period of time. They consist of an access key ID, a secret access key, and a security token, which is typically found using `GetSessionToken`. +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. +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. -NOTE: IAM users with multi-factor authentication (MFA) enabled need to submit an MFA code when calling `GetSessionToken`. For more details refer to AWS's documentation for https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html[Temporary Security Credentials]. +NOTE: IAM users with multi-factor authentication (MFA) enabled need to submit an MFA code when calling `GetSessionToken`. For more details, refer to AWS' https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html[Temporary Security Credentials] documentation. -You can use the AWS CLI to generate temporary credentials. For example, you could use the following command if you have MFA enabled: `sts get-session-token --serial-number arn:aws:iam::1234:mfa/your-email@example.com --duration-seconds 129600 --token-code 123456` +You can use the AWS CLI to generate temporary credentials. For example, you could use the following command if you have MFA enabled: -The output from this command includes the following fields, which you should supply to the KSPM integration: +[source,console] +---------------------------------- +`sts get-session-token --serial-number arn:aws:iam::1234:mfa/your-email@example.com --duration-seconds 129600 --token-code 123456` +---------------------------------- + +The output from this command includes the following fields, which you should provide when configuring the KSPM integration: * `Access key ID`: The first part of the access key. * `Secret Access Key`: The second part of the access key. @@ -104,7 +138,7 @@ The output from this command includes the following fields, which you should sup [discrete] [[kspm-use-a-shared-credentials-file]] ===== Option 3 - Use a 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's documentation for https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html[Shared Credentials Files] +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: @@ -123,11 +157,11 @@ If you don't provide values for all configuration fields, the integration will u ===== Option 4 - Use an 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 you with temporary security credentials for your session. +Instead, when you assume a role, it provides you with temporary security credentials for your session. An IAM role's ARN can be used to specify which AWS IAM role to use to generate temporary credentials. -For more details refer to AWS's https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html[AssumeRole API documentation]. -Follow AWS's instructions to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[create an IAM user], and define its permissions using the JSON permissions policy above. +For more details, refer to AWS' https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html[AssumeRole API] documentation. +Follow AWS' instructions to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[create an IAM user], and define its permissions using the JSON permissions policy above. To use an IAM role's ARN, you need to provide either a <> or <> along with the `ARN role`. The `ARN Role` value specifies which AWS IAM role to use for generating temporary credentials. @@ -143,13 +177,13 @@ If a `Credential Profile Name` is not present, the default credential profile wi Once you've provided AWS credentials, finish configuring the KSPM integration: 1. If you want to monitor Kubernetes clusters that aren’t yet enrolled in {fleet}, select *New Hosts* under “where to add this integration”. -2. Name the {agent} policy. Use a name that matches the purpose or team of the cluster(s) you want to monitor; for example, `IT-dev-k8s-clusters`. +2. Name the {agent} policy. Use a name that matches the purpose or team of the cluster(s) you want to monitor. For example, `IT-dev-k8s-clusters`. 3. Click *Save and continue*, then *Add agent to your hosts*. The *Add agent* wizard appears and provides a DaemonSet manifest `.yaml` file with pre-populated configuration information, such as the `Fleet ID` and `Fleet URL`. [[kspm-setup-eks-modify-deploy]] [discrete] -==== Modify and deploy the DaemonSet to your clusters -The *Add agent* wizard helps you deploy a DaemonSet on the Kubernetes clusters you wish to monitor. For each cluster: +==== Deploy the KSPM integration to EKS clusters +The *Add agent* wizard helps you deploy the KSPM integration on the Kubernetes clusters you wish to monitor. For each cluster: 1. Download the manifest and make any necessary revisions to its configuration to suit the needs of your environment. 2. Apply the manifest using the `kubectl apply -f` command. For example: `kubectl apply -f elastic-agent-managed-kubernetes.yaml` @@ -161,6 +195,8 @@ After a few minutes, a message confirming the {agent} enrollment appears, follow [[kspm-setup-unmanaged]] === Set up KSPM for unmanaged Kubernetes clusters +Follow these steps to deploy the KSPM integration to unmanaged clusters. Keep in mind credentials are NOT required for unmanaged deployments. + [discrete] ==== Configure the KSPM integration To install the integration on unmanaged clusters: @@ -179,9 +215,9 @@ image::images/kspm-add-agent-wizard.png[The KSPM integration's Add agent wizard] [[kspm-setup-unmanaged-modify-deploy]] [discrete] -==== Modify and deploy the DaemonSet to unmanaged clusters +==== Deploy the KSPM integration to unmanaged clusters -The *Add agent* wizard helps you deploy a DaemonSet on the Kubernetes clusters you wish to monitor. To do this, for each cluster: +The *Add agent* wizard helps you deploy the KSPM integration on the Kubernetes clusters you wish to monitor. To do this, for each cluster: 1. Download the manifest and make any necessary revisions to its configuration to suit the needs of your environment. 2. Apply the manifest using the `kubectl apply -f` command. For example: `kubectl apply -f elastic-agent-managed-kubernetes.yaml` From 0f49d28f3a07b14af0654b34ba134a10daea1f7b Mon Sep 17 00:00:00 2001 From: benironside Date: Mon, 17 Oct 2022 16:00:58 -0400 Subject: [PATCH 46/46] minor fixes --- .../get-started-with-kspm.asciidoc | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/cloud-native-security/get-started-with-kspm.asciidoc b/docs/cloud-native-security/get-started-with-kspm.asciidoc index b8fea179aa..4d595def69 100644 --- a/docs/cloud-native-security/get-started-with-kspm.asciidoc +++ b/docs/cloud-native-security/get-started-with-kspm.asciidoc @@ -5,15 +5,15 @@ This page explains how to configure the Kubernetes Security Posture Management i The instructions differ depending on whether you're installing on EKS or on unmanaged clusters. * Install on EKS-managed clusters: - 1. <> - 2. <> - 3. <> - 4. <> + . <> + . <> + . <> + . <> * Install on unmanaged clusters: - 1. <> - 2. <> + . <> + . <> [discrete] [[kspm-setup-eks-start]] @@ -71,6 +71,7 @@ If you are using the AWS visual editor to create and modify your IAM Policies, y .Click to view JSON object [%collapsible] ==== +``` { "Version": "2012-10-17", "Statement": [ @@ -102,6 +103,7 @@ If you are using the AWS visual editor to create and modify your IAM Policies, y } ] } +``` ==== [discrete] @@ -161,7 +163,7 @@ Instead, when you assume a role, it provides you with temporary security credent An IAM role's ARN can be used to specify which AWS IAM role to use to generate temporary credentials. For more details, refer to AWS' https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html[AssumeRole API] documentation. -Follow AWS' instructions to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[create an IAM user], and define its permissions using the JSON permissions policy above. +Follow AWS' instructions to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[create an IAM user], and define the IAM role's permissions using the JSON permissions policy above. To use an IAM role's ARN, you need to provide either a <> or <> along with the `ARN role`. The `ARN Role` value specifies which AWS IAM role to use for generating temporary credentials.