docs: 2022.09 maintenance; troubleshooting, sysdig_secure_url and org permissions (#71)

* doc: explicit SYSDIG_SECURE_URL on sydig provider
* doc: troubleshoot invalid credentials
* doc: notes for further testing
* doc: permissions review

Author: iru

README.md

@@ -72,7 +72,7 @@ More info in [`./examples/organizational`](https://github.com/sysdiglabs/terrafo
 
 If no [examples](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/examples) fit your use-case, be free to call desired modules directly.
 
-In this use-case we will ONLY deploy cloud-bench, into the target account, calling modules directly
+In this use-case we will ONLY deploy cloud-bench, into the target account, calling modules directly.
 
 ```terraform
 terraform {
@@ -89,7 +89,8 @@ provider "aws" {
 }
 
 provider "sysdig" {
-  sysdig_secure_api_token  = "00000000-1111-2222-3333-444444444444"
+  sysdig_secure_url         = "<SYSDIG_SECURE_URL>"
+  sysdig_secure_api_token   = "<SYSDIG_SECURE_API_TOKEN>"
 }
 
 module "cloud_bench" {
@@ -145,11 +146,20 @@ It may take some time, but you should see logs detecting the new image in the EC
 
 ## Troubleshooting
 
-### Q: Getting error "Error: failed creating ECS Task Definition: ClientException: No Fargate configuration exists for given values.
+### Q-General: Getting error "Error: cannot verify credentials" on "sysdig_secure_trusted_cloud_identity" data
+A: This happens when Sysdig credentials are not working correctly.
+S: Check sysdig provider block is correctly configured with the `sysdig_secure_url` and `sysdig_secure_api_token` variables
+with the correct values. Check [Sysdig SaaS per-region URLs if required](https://docs.sysdig.com/en/docs/administration/saas-regions-and-ip-ranges)
+
+### Q-General: I'm not able to see Cloud Infrastructure Entitlements Management (CIEM) results
+A: Make sure you installed both [cloud-bench](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/modules/services/cloud-bench) and [cloud-connector](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/modules/services/cloud-connector) modules
+
+
+### Q-AWS: Getting error "Error: failed creating ECS Task Definition: ClientException: No Fargate configuration exists for given values.
 A: Your ECS task_size values aren't valid for Fargate. Specifically, your mem_limit value is too big for the cpu_limit you specified
 S: Check [supported task cpu and memory values](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-cpu-memory-error.html)
 
-### Q: Getting error "404 Invalid parameter: TopicArn" when trying to reuse an existing cloudtrail-sns
+### Q-AWS: Getting error "404 Invalid parameter: TopicArn" when trying to reuse an existing cloudtrail-sns
 
 ```text
 │ Error: error creating SNS Topic Subscription: InvalidParameter: Invalid parameter: TopicArn
@@ -164,7 +174,7 @@ S: Check [supported task cpu and memory values](https://docs.aws.amazon.com/Amaz
 A: In order to subscribe to a SNS Topic, SQS queue must be in the same region
 <br/>S: Change `aws provider` `region` variable to match same region for all resources
 
-### Q: Getting error "400 availabilityZoneId is invalid" when creating the ECS subnet
+### Q-AWS: Getting error "400 availabilityZoneId is invalid" when creating the ECS subnet
 ```text
 │ Error: error creating subnet: InvalidParameterValue: Value (apne1-az3) for parameter availabilityZoneId is invalid. Subnets can currently only be created in the following availability zones: apne1-az1, apne1-az2, apne1-az4.
 │ 	status code: 400, request id: 6e32d757-2e61-4220-8106-22ccf814e1fe
@@ -178,11 +188,7 @@ A: For the ECS workload deployment a VPC is being created under the hood. Some A
 <br/>S: Specify the desired VPC region availability zones for the vpc module, using the `ecs_vpc_region_azs` variable to explicit its desired value and workaround the error until AWS gives support for your region.
 
 
-### Q: I'm not able to see Cloud Infrastructure Entitlements Management (CIEM) results
-A: Make sure you installed both [cloud-bench](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/modules/services/cloud-bench) and [cloud-connector](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/modules/services/cloud-connector) modules
-
-
-### Q: I get 400 api error AuthorizationHeaderMalformed on the Sysdig workload ECS Task
+### Q-AWS: I get 400 api error AuthorizationHeaderMalformed on the Sysdig workload ECS Task
 
 ```text
 error while receiving the messages: error retrieving from S3 bucket=crit-start-trail: operation error S3: GetObject,
@@ -195,12 +201,12 @@ This error happens when the ECS `TaskRole` has no permissions to assume this rol
 <br/>S: Give permissions to `sts:AssumeRole` to the role used.
 
 
-### Q: How to iterate cloud-connector modification testing
+### Q-Dev-Contrib: How to iterate cloud-connector modification testing
 
 A: Build a custom docker image of cloud-connector `docker build . -t <DOCKER_IMAGE> -f ./build/cloud-connector/Dockerfile` and upload it to any registry (like dockerhub).
 Modify the [var.image](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/modules/services/cloud-connector/variables.tf) variable to point to your image and deploy
 
-### Q: How can I iterate ECS modification testing
+### Q-Dev-Contrib: How can I iterate ECS modification testing
 
 A: After applying your modifications (vía terraform for example) restart the service
   ```

examples-internal/organizational-k8s-threat-reuse_cloudtrail_s3/README.md

@@ -47,7 +47,8 @@ terraform {
 }
 
 provider "sysdig" {
-  sysdig_secure_api_token    = "00000000-1111-2222-3333-444444444444"
+  sysdig_secure_url         = "<SYSDIG_SECURE_URL>"
+  sysdig_secure_api_token   = "<SYSDIG_SECURE_API_TOKEN>"
 }
 
 provider "aws" {

examples-internal/use-cases-reuse-resources/org-existing-cloudtrail-ecs-vpc-subnet.md

@@ -117,7 +117,8 @@ terraform {
 }
 
 provider "sysdig" {
-  sysdig_secure_api_token = "<SYSDIG_SECURE_API_TOKEN>"
+  sysdig_secure_url         = "<SYSDIG_SECURE_URL>"
+  sysdig_secure_api_token   = "<SYSDIG_SECURE_API_TOKEN>"
 }
 
 provider "aws" {

examples-internal/use-cases-reuse-resources/single-existing-cloudtrail.md

@@ -77,7 +77,8 @@ terraform {
 }
 
 provider "sysdig" {
-  sysdig_secure_api_token = "<SYSDIG_API_TOKEN>"
+  sysdig_secure_url         = "<SYSDIG_SECURE_URL>"
+  sysdig_secure_api_token   = "<SYSDIG_SECURE_API_TOKEN>"
 }
 
 provider "aws" {

examples-internal/use-cases-self-baked/single-benchmark.md

@@ -25,7 +25,8 @@ terraform {
 }
 
 provider "sysdig" {
-  sysdig_secure_api_token = "<SYSDIG_API_TOKEN>"
+  sysdig_secure_url        = "<SYSDIG_SECURE_URL>"
+  sysdig_secure_api_token  = "<SYSDIG_SECURE_API_TOKEN>"
 }
 
 provider "aws" {

examples/organizational/README.md

@@ -38,6 +38,27 @@ Minimum requirements:
     sysdig_secure_api_token=<SECURE_API_TOKEN>
     ```
 
+
+## Permission Summary
+
+Permission requirement for this example comes as follows
+
+- **management account**
+    - terraform aws provider: default
+    - `SysdigSecureForCloudRole` will be created
+      - used by Sysdig to subscribe to cloudtrail-sns
+      - used by Sysdig to be able to jump to several member accounts to pull ECR hosted images through the `OrganizationAccountAccessRole` role
+    - `SysdigCloudBench` role will be created for SecurityAudit read-only purpose, used by Sysdig to benchmark
+- **member accounts**
+    - terraform aws provider: 'member' aliased
+      - this provider can be configured as desired, we just provide a default option
+    - requires [`OrganizationAccountAccessRole`](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts_access.html) default role created by AWS for managed-account users to be able to admin member accounts
+      - if this role does not exist provide input var `organizational_member_default_admin_role` with the role
+    - `SysdigCloudBench` role will be created for SecurityAudit read-only purpose, used by Sysdig to benchmark
+    - **sysdig member account workload**
+      - if ECS workload is deployed, `ECSTaskRole` will be used to define its permissions
+        - used by Sysdig to assumeRole on management account `SysdigSecureForCloudRole` and other organizations `OrganizationAccountAccessRole`
+
 ## Notice
 
 * **Resource creation inventory** Find all the resources created by Sysdig examples in the resource-group `sysdig-secure-for-cloud` (AWS Resource Group & Tag Editor) <br/><br/>
@@ -58,7 +79,8 @@ terraform {
 }
 
 provider "sysdig" {
-  sysdig_secure_api_token    = "00000000-1111-2222-3333-444444444444"
+  sysdig_secure_url         = "<SYSDIG_SECURE_URL>"
+  sysdig_secure_api_token   = "<SYSDIG_SECURE_API_TOKEN>"
 }
 
 provider "aws" {

examples/organizational/diagram-permissions.py

@@ -0,0 +1,39 @@
+# diagrams as code vía https://diagrams.mingrammer.com
+from diagrams import Cluster, Diagram, Edge, Node
+from diagrams.aws.security import IAM, IAMRole
+from diagrams.aws.management import Cloudtrail
+from diagrams.aws.storage import S3
+from diagrams.aws.compute import ECR
+
+
+with Diagram("Sysdig Secure for Cloud\n(organizational permissions)", filename="diagram-permissions", show=True):
+
+
+    with Cluster("member account (sysdig workload)"):
+#        bench_role = IAMRole(label="Benchmark role")
+        member_sysdig_role = IAMRole(label="OrganizationAccountAccessRole")
+        member_sysdig_ecr = ECR("container registry")
+        member_sysdig_role >> member_sysdig_ecr
+
+        ecs_role = IAMRole(label="ECSTaskRole")
+        # bench_role - Edge(style="invis") - member_sysdig_ecr
+
+
+    with Cluster("member accounts"):
+#        IAMRole(label="Benchmark role")
+
+        member_role = IAMRole(label="OrganizationAccountAccessRole")
+        member_ecr = ECR("container registry")
+        member_role >> member_ecr
+
+
+    with Cluster("management account"):
+#        IAMRole(label="Benchmark role")
+        sf4c_role = IAMRole(label="SysdigSecureForCloud")
+        sf4c_role >> Cloudtrail()
+        sf4c_role >> S3()
+
+
+    ecs_role >> sf4c_role
+    sf4c_role >> member_role
+    sf4c_role >> member_sysdig_role

examples/single-account-k8s/README.md

@@ -41,7 +41,8 @@ terraform {
 }
 
 provider "sysdig" {
-  sysdig_secure_api_token    = "00000000-1111-2222-3333-444444444444"
+  sysdig_secure_url         = "<SYSDIG_SECURE_URL>"
+  sysdig_secure_api_token   = "<SYSDIG_SECURE_API_TOKEN>"
 }
 
 provider "aws" {

examples/single-account/README.md

@@ -35,7 +35,8 @@ terraform {
 }
 
 provider "sysdig" {
-   sysdig_secure_api_token    = "00000000-1111-2222-3333-444444444444"
+   sysdig_secure_url        = "<SYSDIG_SECURE_URL>"
+   sysdig_secure_api_token  = "<SYSDIG_SECURE_API_TOKEN>"
 }
 
 provider "aws" {

modules/infrastructure/cloudtrail/sns_permissions.tf

@@ -27,6 +27,9 @@ data "aws_iam_policy_document" "cloudtrail_sns" {
       principals {
         identifiers = ["arn:aws:iam::${var.organizational_config.sysdig_secure_for_cloud_member_account_id}:role/${var.organizational_config.organizational_role_per_account}"]
         type        = "AWS"
+        #        more open policy but without requiring aws provider role
+        #        identifiers = ["sqs.amazonaws.com"]
+        #        type        = "Service"
       }
       actions   = ["sns:Subscribe"]
       resources = [aws_sns_topic.cloudtrail.arn]