doc: enhance permissions and role usage (#89)

* doc: enhance permissions

Author: iru

README.md

@@ -128,6 +128,70 @@ $ terraform plan
 $ terraform apply
 ```
 
+## Required Permissions
+
+### Required Permissions
+
+#### Provisioning Permissions
+
+Terraform provider credentials/token, requires `Administrative` permissions in order to be able to create the
+resources specified in the per-example diagram.
+
+Some components may vary, and you can check full resources on each module "Resources" section in their README's, but this would be an overall schema of the **created resources**:
+
+- SSM Parameter for Sysdig API Token Storage
+- Cloudtrail / SNS / S3 / SQS
+
+- Sysdig Workload: ECS / AppRunner creation (EKS is pre-required, not created)
+  - each compute solution require a role to assume for execution
+
+- CodeBuild for on-demand image scanning
+- Role for Sysdig [Benchmarks](./modules/services/cloud-bench)
+
+#### Runtime Permissions
+
+Modules create several roles to be able to manage the following permissions.
+
+**General  Permissions**
+
+```shell
+ssm: GetParameters
+
+sqs: ReceiveMessage
+sqs: DeleteMessage
+
+s3: ListBucket
+s3: GetObject
+```
+
+**Image-Scanning specific**
+
+```shell
+codebuild: StartBuild
+
+ecr: GetAuthorizationToken
+ecr: BatchCheckLayerAvailability
+ecr: GetDownloadUrlForLayer
+ecr: GetRepositoryPolicy
+ecr: DescribeRepositories
+ecr: ListImages
+ecr: DescribeImages
+ecr: BatchGetImage
+ecr: GetLifecyclePolicy
+ecr: GetLifecyclePolicyPreview
+ecr: ListTagsForResource
+ecr: DescribeImageScanFindings
+
+ecs:DescribeTaskDefinition
+
+```
+
+Notes:
+- only Sysdig workload related permissions are specified above; infrastructure internal resource permissions (such as Cloudtrail permissions to publish on SNS, or SNS-SQS Subscription)
+are not detailed.
+- For a better security, permissions are resource pinned, instead of `*`
+- Check [Organizational Use Case - Role Summary](./examples/organizational/README.md#role-summary) for more details
+
 
 ## Forcing Events
 

examples/organizational/README.md

@@ -5,8 +5,10 @@ Deploy Sysdig Secure for Cloud using an [AWS Organizational Cloudtrail](https://
 * In the **management account**
     * An Organizational Cloutrail will be deployed  (with required S3,SNS)
     * An additional role `SysdigSecureForCloudRole` will be created
-        * to be able to read cloudtrail-s3 bucket events from sysdig workload member account.
-        * will also be used to asummeRole over other roles, and enable the process of scanning on ECR's that may be present in other member accounts.
+        * to be able to read cloudtrail-s3 bucket events (and query cloudtrail-sqs) from sysdig workload member account.
+        * scanning-only, to assumeRole over member-account role
+          * to scan images pushed to ECR's that may be present in other member accounts.
+          * to describe ECS task definitions and get images to be scanned, on clusters in other member accounts
 * In the **user-provided member account**
     * All the Sysdig Secure for Cloud service-related resources/workload will be created
 
@@ -18,22 +20,22 @@ Minimum requirements:
 
 1. Have an existing AWS account as the organization management account
     *  Within the Organization, following services must be enabled (Organization > Services)
-       * Organizational CloudTrail
-       * [Organizational CloudFormation StackSets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-orgs-enable-trusted-access.html)
+        * Organizational CloudTrail
+        * [Organizational CloudFormation StackSets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-orgs-enable-trusted-access.html)
 2. Configure [Terraform **AWS** Provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) for the `management` account of the organization
     * This provider credentials must be [able to manage cloudtrail creation](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/creating-trail-organization.html)
       > You must be logged in with the management account for the organization to create an organization trail. You must also have sufficient permissions for the IAM user or role in the management account to successfully create an organization trail.
 
 3. Organizational Multi-Account Setup
     * An specific role is required, to enable Sysdig to impersonate and be able to provide
-      * For scanning feature, the ability to pull ECR hosted images when they're allocated in a different account
-      * For scanning too, the ability to query the ECS tasks that are allocated in different account, in order to fetch the image to be scanned
-      * A solution to resolve current limitation when accessing an S3 bucket in a different region than where it's being called from
+        * For scanning feature, the ability to pull ECR hosted images when they're allocated in a different account
+        * For scanning too, the ability to query the ECS tasks that are allocated in different account, in order to fetch the image to be scanned
+        * A solution to resolve current limitation when accessing an S3 bucket in a different region than where it's being called from
     * By default, it uses [AWS created default role `OrganizationAccountAccessRole`](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts_access.html)
-      * When an account is created within an organization, AWS will create an `OrganizationAccountAccessRole` [for account management](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts_access.html), which Sysdig Secure for Cloud will use for member-account provisioning and role assuming.
-      * However, when the account is invited into the organization, it's required to [create the role manually](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts_access.html#orgs_manage_accounts_create-cross-account-role)
-        > You have to do this manually, as shown in the following procedure. This essentially duplicates the role automatically set up for created accounts. We recommend that you use the same name, OrganizationAccountAccessRole, for your manually created roles for consistency and ease of remembering.
-      * If role name, `OrganizationAccountAccessRole` wants to be modified, it must be done both on the `aws` member-account provider AND input value `organizational_member_default_admin_role`
+        * When an account is created within an organization, AWS will create an `OrganizationAccountAccessRole` [for account management](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts_access.html), which Sysdig Secure for Cloud will use for member-account provisioning and role assuming.
+        * However, when the account is invited into the organization, it's required to [create the role manually](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts_access.html#orgs_manage_accounts_create-cross-account-role)
+          > You have to do this manually, as shown in the following procedure. This essentially duplicates the role automatically set up for created accounts. We recommend that you use the same name, OrganizationAccountAccessRole, for your manually created roles for consistency and ease of remembering.
+        * If role name, `OrganizationAccountAccessRole` wants to be modified, it must be done both on the `aws` member-account provider AND input value `organizational_member_default_admin_role`
 
 3. Provide a member **account ID for Sysdig Secure for Cloud workload** to be deployed.
    Our recommendation is for this account to be empty, so that deployed resources are not mixed up with your workload.
@@ -49,27 +51,26 @@ Minimum requirements:
 
 ## Role Summary
 
-Permission requirement for this example comes as follows
+Role usage for this example comes as follows. Check [permissions](../../README.md#required-permissions) too
 
 - **management account**
     - terraform aws provider: default
     - `SysdigSecureForCloudRole` will be created
-      - used by Sysdig to subscribe to cloudtrail events
-      - used by Sysdig to be able to jump to several member accounts to pull ECR hosted images through the `OrganizationAccountAccessRole` role
-      - assumming previous role will also enable the access of cloudtrail s3 buckets when they are in a different region than were the terraform module is deployed
-
+        - used by Sysdig to subscribe to cloudtrail events
+        - used by Sysdig, for image scanning feature, to `assumeRole` on `OrganizationAccountAccessRole` to be able to fetch image data from ECS Tasks and scan ECR hosted images
+        <!--  - assuming previous role will also enable the access of cloudtrail s3 buckets when they are in a different region than were the terraform module is deployed -->
     - `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
+        - this provider can be configured as desired, we just provide a default option
     - by default, we suggest using an assumeRole to the [AWS created default role `OrganizationAccountAccessRole`](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts_access.html)
-      - if this role does not exist provide input var `organizational_member_default_admin_role` with the role
+        - 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 workload member account**
-  - 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`
+    - 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
 

modules/services/cloud-connector-ecs/README.md

@@ -81,7 +81,7 @@ A task deployed on an **ECS deployment** will detect events in your infrastructu
 | <a name="input_image"></a> [image](#input\_image) | Image of the cloud connector to deploy | `string` | `"quay.io/sysdig/cloud-connector:latest"` | no |
 | <a name="input_is_organizational"></a> [is\_organizational](#input\_is\_organizational) | whether secure-for-cloud should be deployed in an organizational setup | `bool` | `false` | no |
 | <a name="input_name"></a> [name](#input\_name) | Name to be assigned to all child resources. A suffix may be added internally when required. Use default value unless you need to install multiple instances | `string` | `"sfc-cloudconnector"` | no |
-| <a name="input_organizational_config"></a> [organizational\_config](#input\_organizational\_config) | organizational\_config. following attributes must be given<br><ul><br>  <li>`sysdig_secure_for_cloud_role_arn` for cloud-connector assumeRole in order to read cloudtrail s3 events</li><br>  <li>`connector_ecs_task_role_name` which has been granted trusted-relationship over the secure\_for\_cloud\_role</li><br>  <li>`organizational_role_per_account` is the name of the organizational role deployed by AWS in each account of the organization</li><br></ul> | <pre>object({<br>    sysdig_secure_for_cloud_role_arn = string<br>    organizational_role_per_account  = string<br>    connector_ecs_task_role_name     = string<br>  })</pre> | <pre>{<br>  "connector_ecs_task_role_name": null,<br>  "organizational_role_per_account": null,<br>  "sysdig_secure_for_cloud_role_arn": null<br>}</pre> | no |
+| <a name="input_organizational_config"></a> [organizational\_config](#input\_organizational\_config) | organizational\_config. following attributes must be given<br><ul><br>  <li>`sysdig_secure_for_cloud_role_arn` for cloud-connector assumeRole in order to read cloudtrail s3 events</li><br>  <li>`connector_ecs_task_role_name` which has been granted trusted-relationship over the secure\_for\_cloud\_role</li><br>  <li>`organizational_role_per_account` is the name of the organizational role deployed by AWS in each account of the organization. used for image-scanning only</li><br></ul> | <pre>object({<br>    sysdig_secure_for_cloud_role_arn = string<br>    organizational_role_per_account  = string<br>    connector_ecs_task_role_name     = string<br>  })</pre> | <pre>{<br>  "connector_ecs_task_role_name": null,<br>  "organizational_role_per_account": null,<br>  "sysdig_secure_for_cloud_role_arn": null<br>}</pre> | no |
 | <a name="input_tags"></a> [tags](#input\_tags) | sysdig secure-for-cloud tags. always include 'product' default tag for resource-group proper functioning | `map(string)` | <pre>{<br>  "product": "sysdig-secure-for-cloud"<br>}</pre> | no |
 | <a name="input_verify_ssl"></a> [verify\_ssl](#input\_verify\_ssl) | true/false to determine ssl verification for sysdig\_secure\_url | `bool` | `true` | no |
 

modules/services/cloud-connector-ecs/variables.tf

@@ -75,7 +75,7 @@ variable "organizational_config" {
     <ul>
       <li>`sysdig_secure_for_cloud_role_arn` for cloud-connector assumeRole in order to read cloudtrail s3 events</li>
       <li>`connector_ecs_task_role_name` which has been granted trusted-relationship over the secure_for_cloud_role</li>
-      <li>`organizational_role_per_account` is the name of the organizational role deployed by AWS in each account of the organization</li>
+      <li>`organizational_role_per_account` is the name of the organizational role deployed by AWS in each account of the organization. used for image-scanning only</li>
     </ul>
   EOT
 }