docs: updates Manual CSPM Install for AWS (#171)

Co-authored-by: Radhika Puthiyetath <[email protected]>

Author: nkraemer-sysdig

use-cases/manual-compliance.md

@@ -1,120 +1,157 @@
-# Compliance
+# Manually Onboard an AWS Account for CSPM
 
+To enable [CSPM (Compliance)](https://docs.sysdig.com/en/docs/sysdig-secure/posture/compliance/) in your AWS account, you create the following resources on the Sysdig Secure SaaS backend:
 
-## AWS
-On each account where compliance wants to be checked (`AWS_ACCOUNT_ID`), we need to provide a role for Sysdig to be able to impersonate and perform `SecurityAudit` tasks.
+- An `account` representing the AWS account for which you want to enable CSPM
+- A trust-relationship `component` that represents the IAM Role in your AWS account
+- A CSPM `feature` that indicates CSPM scans should be run against this account
+ 
 
-In addition, we must make Sysdig aware of these accounts and role.
-We will guide you to provide, on the Sysdig Secure SaaS backend, the following resources:
-- a cloud-account for each account of your organization where compliance is wanted to be checked
-- a task that will run `aws_foundations_bench-1.3.0` schema on previously defined accounts
+## Guidelines
 
-### Sysdig Side
+- This method of installation will only support CSPM (Compliance).
 
-1. **Register cloud accounts** on Sysdig
+- The following features will not work:
+    - Threat Detection
+    - Identity and Access
+    - Image Scanning
 
-For each account you want to provision for the Compliance feature, we need to register it on Sysdig Secure, so
-it can impersonate and perform `SecurityAudit` tasks.
+  To install other features, see the [Installation Guide](https://docs.sysdig.com/en/docs/installation/sysdig-secure/connect-cloud-accounts/aws/).
+
+- In each AWS account you want to run CSPM, you must create an IAM Role with `SecurityAudit` permissions that Sysdig is able to assume.
+
+- Ensure that you make Sysdig aware of these accounts and roles.
+
+
+## Preparation
+
+To learn more about using the Sysdig Secure APIs, see [Development Tools](https://docs.sysdig.com/en/docs/developer-tools/).
+
+### Retrieve the **Sysdig Trusted Identity** and **ExternalID**
+
+Run the following to retrieve the `TrustRelationshipPolicy`:
 
-For Sysdig Secure backend API communication [How to use development tools](https://docs.sysdig.com/en/docs/developer-tools/). Also, we have this [AWS provisioning script](./utils/sysdig_cloud_compliance_provisioning.sh) as reference, but we will explain it here too.
 ```shell
-$ curl "https://<SYSDIG_SECURE_ENDPOINT>/api/cloud/v2/accounts?upsert=true" \
---header "Authorization: Bearer <SYSDIG_SECURE_API_TOKEN>" \
--X POST \
--H 'Accept: application/json' \
--H 'Content-Type: application/json' \
--d '{
- "accountId": "<AWS_ACCOUNT_ID>",
- "alias": "<AWS_ACCOUNT_ALIAS>",
- "provider": "aws",
- "roleAvailable": true,
- "roleName": "SysdigComplianceRole"
-}'
+$ curl -s 'https://<SYSDIG_SECURE_ENDPOINT>/api/cloud/v2/aws/trustedRoleDoc' \
+--header 'Authorization: Bearer <SYSDIG_SECURE_API_TOKEN>'
 ```
-<br/>
+This policy will be used when you create an IAM role as given below.
+
+An example response to this call:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Principal": {
+        "AWS": "arn:aws:iam::123456789012:role/us-east-1-some-sysdig-role"
+      },
+      "Action": "sts:AssumeRole",
+      "Condition": {
+        "StringEquals": {
+          "sts:ExternalId": "0123abc456defg7890hijk123lmn0774"
+        }
+      }
+    }
+  ]
+}
+```
+
+## Provision Your AWS Account
+
+### Create an IAM Role
+
+Sysdig secures your cloud environment by assuming an IAM Role you create within your AWS Account.
+
+1. Create a new IAM Role with a Custom trust policy.
+2. Set the value of the trust polity to the `TrustRelationshipPolicy` policy retrieved above.
+3. Attach the AWS-managed `arn:aws:iam::aws:policy/SecurityAudit` policy.
+4. Give the role a unique name, and save the name for later use.
+5. Add **Tags** and a **Description** as desired.
 
-2. Register **Benchmark Task**
+For more information, see [IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html)
 
-Create a single task to scope the organization account ids (or just a single account) to be assessed with the
-`aws_foundations_bench-1.3.0` compliance framework.
+## Provision Sysdig
+
+### Create an AWS Account Representation
 
-This script does not cover it, but specific regions can be scoped too. Check `Benchmarks-V2` REST-API for more detail
 ```shell
-$ curl -s "https://<SYSDIG_SECURE_ENDPOINT>/api/benchmarks/v2/tasks" \
+$ curl "https://<SYSDIG_SECURE_ENDPOINT>/api/cloudauth/v1/accounts" \
 --header "Authorization: Bearer <SYSDIG_SECURE_API_TOKEN>" \
 -X POST \
 -H 'Accept: application/json' \
 -H 'Content-Type: application/json' \
 -d '{
-  "name": "Sysdig Secure for Cloud (AWS) - Organization",
-  "schedule": "0 3 * * *",
-  "schema": "aws_foundations_bench-1.2.0",
-  "scope": "aws.accountId in ('<AWS_ACCOUNT_ID_1>',...,'<AWS_ACCOUNT_ID_N>')'",
+  "providerId": "<AWS_ACCOUNT_ID>",
+  "provider": "PROVIDER_AWS",
   "enabled": true
 }'
 ```
 
-<br/>
-
-3. Get **Sysdig Federation Trusted Identity**
-
-For later usage, fetch the Trusted Identity `SYSDIG_AWS_TRUSTED_IDENTITY_ARN`
-
-```shell
-$ curl -s 'https://<SYSDIG_SECURE_ENDPOINT>/api/cloud/v2/aws/trustedIdentity' \
---header 'Authorization: Bearer <SYSDIG_SECURE_API_TOKEN>'
-```
-
-   Response pattern:
-```shell
-arn:aws:iam::SYSDIG_AWS_ACCOUNT_ID:role/SYSDIG_AWS_ROLE_NAME
+An example response to this call:
+
+```json
+{
+  "id": "2fb94253-3a93-4d43-a739-2cb8c1c6f886",
+  "customerId": "123",
+  "enabled": true,
+  "providerId": "123456789012",
+  "provider": "PROVIDER_AWS",
+  "feature": {},
+  "createdAt": "2023-05-22T21:26:03.288075Z",
+  "updatedAt": "2023-05-22T21:26:03.288358Z"
+}
 ```
 
-<br/>
+Take note of the `id` field, which is referenced in subsequent calls. Note this is **not the AWS AccountID**, which is stored in the `providerId` field.
 
-4. Get **Sysdig ExternalId**
 
-For later usage, fetch `SYSDIG_AWS_EXTERNAL_ID` from one of the previously registered GCP accounts. All accounts will have same id (you only need to run it once).
-```shell
-$ curl -s "https://<SYSDIG_SECURE_ENDPOINT>/api/cloud/v2/accounts/<AWS_ACCOUNT_ID>?includeExternalId=true" \
---header "Authorization: Bearer <SYSDIG_SECURE_API_TOKEN>"
-```
-From the resulting payload get the `externalId` attribute value, it should be a 32character string mixed with letters and numbers with no dashes, ex.:`0ab697b38dec8fb0932903jasfh38309`
+### Create a Trust Relationship Component
 
-<br/>
+1. Collect the following:
 
-### Customer's Side
+  - `<CLOUD_ACCOUNT_ID>`: The `id` field retrieved from the response in the previous step.
+  - `<ROLE_NAME>`: The name of the IAM role created above. Note this is not the ARN, but the role name.
 
-Now create `SysdigCompliance` role on each account using the values gathered in previous step.
-  - Add `arn:aws:iam::aws:policy/SecurityAudit` AWS managed policy
-  - Allow following Trusted-Identity
-    ```json
-    {
-      "Effect": "Allow",
-      "Action": "sts:AssumeRole",
-      "Principal": {
-        "AWS": [ "<SYSDIG_AWS_TRUSTED_IDENTITY_ARN>" ]
-      },
-      "Condition": {
-        "StringEquals": {"sts:ExternalId": "<SYSDIG_AWS_EXTERNAL_ID>"}
-      }
-    }
-    ```
+2. Replace `<CLOUD_ACCOUNT_ID>` and `<ROLE_NAME>` with the `id` and the role name respectively, and run the following:
 
-### End-To-End Validation
+      ```shell
+      $ curl -s "https://<SYSDIG_SECURE_ENDPOINT>/api/cloudauth/v1/accounts/<CLOUD_ACCOUNT_ID>/components" \
+      --header "Authorization: Bearer <SYSDIG_SECURE_API_TOKEN>" \
+      -X POST \
+      -H 'Accept: application/json' \
+      -H 'Content-Type: application/json' \
+      -d '{
+        "type": "COMPONENT_TRUSTED_ROLE",
+        "instance": "manual",
+        "trustedRoleMetadata": {
+          "aws": {
+            "roleName": "<ROLE_NAME>"
+          }
+        }
+      }'
+      ```
 
-Validate if Sysdig <-> Customer infra connection is properly made using [`/cloud/accounts/{accountId}/validateRole`](https://secure.sysdig.com/swagger.html#tag/Cloud/paths/~1api~1cloud~1v2~1accounts~1{accountId}~1validateRole/get)
 
-```bash
-$ https://<SYSDIG_SECURE_ENDPOINT>/api/cloud/v2/accounts/<AWS_ACCOUNT_ID>/validateRole \
---header 'Authorization: Bearer <SYSDIG_SECURE_API_TOKEN>'
-```
+### Create a CSPM Feature Representation
 
-You should get success or the reason of failure.
+Replace `<CLOUD_ACCOUNT_ID>` with the `id` field you have retrieved before and run the following:
 
+```shell
+$ curl -s "https://<SYSDIG_SECURE_ENDPOINT>/api/cloudauth/v1/accounts/<CLOUD_ACCOUNT_ID>/feature/FEATURE_SECURE_CONFIG_POSTURE" \
+--header "Authorization: Bearer <SYSDIG_SECURE_API_TOKEN>" \
+-X PUT \
+-H 'Accept: application/json' \
+-H 'Content-Type: application/json' \
+-d '{
+  "type": "FEATURE_SECURE_CONFIG_POSTURE",
+  "enabled": true,
+  "components": ["COMPONENT_TRUSTED_ROLE/manual"]
+}'
+```
 
-### Testing
+## Verify the Installation
 
-Check within Sysdig Secure
-- Posture > Compliance  for the compliance task schedule
-- [Official Docs Check Guide](https://docs.sysdig.com/en/docs/installation/sysdig-secure-for-cloud/deploy-sysdig-secure-for-cloud-on-aws/#confirm-the-services-are-working)
+Verify that your installation is successful by following the [CSPM Validation instructions](https://docs.sysdig.com/en/docs/installation/sysdig-secure/connect-cloud-accounts/aws/#check-cspm).