docs: non-normative organizational review (#143)

<!--
Thank you for your contribution!

## Testing your PR

You can pinpoint the pr changes as terraform module source with
following format

```
source                    = "github.com/sysdiglabs/terraform-aws-secure-for-cloud//examples/organizational?ref=<BRANCH_NAME>"
```


## General recommendations
Check contribution guidelines at
https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/blob/master/CONTRIBUTE.md#contribution-checklist

For a cleaner PR make sure you follow these recommendations:
- Review modified files and delete small changes that were not intended
and maybe slip the commit.
- Use Pull Request Drafts for visibility on Work-In-Progress branches
and use them on daily mob/pairing for team review
- Unless an external revision is desired, in order to validate or gather
some feedback, you are free to merge as long as **validation checks are
green-lighted**

## Checklist

- [ ] If `test/fixtures/*/main.tf` files are modified, update:
    - [ ] the snippets in the README.md file under root folder.
- [ ] the snippets in the README.md file for the corresponding example.
- [ ] If `examples` folder are modified, update:
    - [ ] README.md file with pertinent changes.
- [ ] `test/fixtures/*/main.tf` in case the snippet needs modifications.
- [ ] If any architectural change has been made, update the diagrams.

-->

Author: iru

examples/organizational/README.md

@@ -1,5 +1,8 @@
 # Sysdig Secure for Cloud in AWS<br/>[ Example :: Shared Organizational Trail ]
 
+> :warning: If you want to re-use your resources such as cloudtrail or  cloudtrail-s3, through [#input_existing_cloudtrail_config](#input_existing_cloudtrail_config), this example will not work out of the box for **ControlTower** landings, since the S3 bucket is in an account different to the management account, and this is a requirement for the default setup. Please check alternative [use-cases](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/docs-organizational-review/use-cases#use-case-summary)
+
+
 Assess the security of your organization.
 
 Deploy Sysdig Secure for Cloud using an [AWS Organizational Cloudtrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/creating-trail-organization.html) that will fetch events from all organization member accounts (and the managed one too).
@@ -197,7 +200,7 @@ $ terraform apply
 | <a name="input_ecs_vpc_id"></a> [ecs\_vpc\_id](#input\_ecs\_vpc\_id) | ID of the VPC where the workload is to be deployed. If defaulted a new VPC will be created. If specified all three parameters `ecs_cluster_name`, `ecs_vpc_id` and `ecs_vpc_subnets_private_ids` are required | `string` | `"create"` | no |
 | <a name="input_ecs_vpc_region_azs"></a> [ecs\_vpc\_region\_azs](#input\_ecs\_vpc\_region\_azs) | List of Availability Zones for ECS VPC creation. e.g.: ["apne1-az1", "apne1-az2"]. If defaulted, two of the default 'aws\_availability\_zones' datasource will be taken | `list(string)` | `[]` | no |
 | <a name="input_ecs_vpc_subnets_private_ids"></a> [ecs\_vpc\_subnets\_private\_ids](#input\_ecs\_vpc\_subnets\_private\_ids) | List of VPC subnets where workload is to be deployed. If defaulted new subnets will be created within the VPC. A minimum of two subnets is suggested. If specified all three parameters `ecs_cluster_name`, `ecs_vpc_id` and `ecs_vpc_subnets_private_ids` are required. | `list(string)` | `[]` | no |
-| <a name="input_existing_cloudtrail_config"></a> [existing\_cloudtrail\_config](#input\_existing\_cloudtrail\_config) | Optional block. If not set, a new cloudtrail, sns and sqs resources will be created in the management account.<br>If provided, all resources (cloudtrail,s3,sqs) must exist in the management account.<br>Otherwise, check [use-cases](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/use-cases) for proper permission setup.<br>If there's an existing cloudtrail, input one of the Optional 1/2/3 blocks.<br><ul><br>  <li>cloudtrail\_s3\_arn: Optional 1. ARN of a pre-existing cloudtrail\_sns s3 bucket. Used together with `cloudtrail_sns_arn`, `cloudtrail_s3_arn`. If it does not exist, it will be inferred from create cloudtrail"</li><br>  <li>cloudtrail\_sns\_arn: Optional 1. ARN of a pre-existing cloudtrail\_sns. Used together with `cloudtrail_sns_arn`, `cloudtrail_s3_arn`. If it does not exist, it will be inferred from created cloudtrail. Providing an ARN requires permission to SNS:Subscribe, check ./modules/infrastructure/cloudtrail/sns\_permissions.tf block</li><br>  <li>cloudtrail\_s3\_role\_arn: Optional 2. ARN of the role to be assumed for S3 access. This role must be in the same account of the S3 bucket. Currently this setup is not compatible with organizational scanning feature</li><br>  <li>cloudtrail\_s3\_sns\_sqs\_arn: Optional 3. ARN of the queue that will ingest events forwarded from an existing cloudtrail\_s3\_sns</li><br>  <li>cloudtrail\_s3\_sns\_sqs\_url: Optional 3. URL of the queue that will ingest events forwarded from an existing cloudtrail\_s3\_sns<</li><br></ul> | <pre>object({<br>    cloudtrail_s3_arn         = optional(string)<br>    cloudtrail_sns_arn        = optional(string)<br>    cloudtrail_s3_role_arn    = optional(string)<br>    cloudtrail_s3_sns_sqs_arn = optional(string)<br>    cloudtrail_s3_sns_sqs_url = optional(string)<br>  })</pre> | <pre>{<br>  "cloudtrail_s3_arn": "create",<br>  "cloudtrail_s3_role_arn": null,<br>  "cloudtrail_s3_sns_sqs_arn": null,<br>  "cloudtrail_s3_sns_sqs_url": null,<br>  "cloudtrail_sns_arn": "create"<br>}</pre> | no |
+| <a name="input_existing_cloudtrail_config"></a> [existing\_cloudtrail\_config](#input\_existing\_cloudtrail\_config) | Optional block. If not set, a new cloudtrail, sns and sqs resources will be created in the **management account**.<br>If provided through Option 1,  resources (cloudtrail,cloudtrail-s3) must exist in the management account.<br>Option 2, is mandatory to be used when the cloudtrail-s3 is in a different account than where SFC worklaod is installed.<br>Option 3, is an alterntive to Option1, to be able to ingest events through cloudtrail-s3-sns subscribed SQS, instead of just cloudtrail-sns<br>Check [use-cases](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/use-cases) for proper permission setup.<br><ul><br>  <li>cloudtrail\_s3\_arn: Optional 1. ARN of a pre-existing cloudtrail\_sns s3 bucket. Used together with `cloudtrail_sns_arn`, `cloudtrail_s3_arn`. If it does not exist, it will be inferred from create cloudtrail"</li><br>  <li>cloudtrail\_sns\_arn: Optional 1. ARN of a pre-existing cloudtrail\_sns. Used together with `cloudtrail_sns_arn`, `cloudtrail_s3_arn`. If it does not exist, it will be inferred from created cloudtrail. Providing an ARN requires permission to SNS:Subscribe, check ./modules/infrastructure/cloudtrail/sns\_permissions.tf block</li><br>  <li>cloudtrail\_s3\_role\_arn: Optional 2. ARN of the role to be assumed for S3 access. This role must be in the same account of the S3 bucket. Currently this setup is not compatible with organizational scanning feature</li><br>  <li>cloudtrail\_s3\_sns\_sqs\_arn: Optional 3. ARN of the queue that will ingest events forwarded from an existing cloudtrail\_s3\_sns</li><br>  <li>cloudtrail\_s3\_sns\_sqs\_url: Optional 3. URL of the queue that will ingest events forwarded from an existing cloudtrail\_s3\_sns<</li><br></ul> | <pre>object({<br>    cloudtrail_s3_arn         = optional(string)<br>    cloudtrail_sns_arn        = optional(string)<br>    cloudtrail_s3_role_arn    = optional(string)<br>    cloudtrail_s3_sns_sqs_arn = optional(string)<br>    cloudtrail_s3_sns_sqs_url = optional(string)<br>  })</pre> | <pre>{<br>  "cloudtrail_s3_arn": "create",<br>  "cloudtrail_s3_role_arn": null,<br>  "cloudtrail_s3_sns_sqs_arn": null,<br>  "cloudtrail_s3_sns_sqs_url": null,<br>  "cloudtrail_sns_arn": "create"<br>}</pre> | 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"` | no |
 | <a name="input_organizational_member_default_admin_role"></a> [organizational\_member\_default\_admin\_role](#input\_organizational\_member\_default\_admin\_role) | Default role created by AWS for management-account users to be able to admin member accounts.<br/>https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts_access.html | `string` | `"OrganizationAccountAccessRole"` | no |
 | <a name="input_tags"></a> [tags](#input\_tags) | customization of tags to be assigned to all resources. <br/>always include 'product' default tag for resource-group proper functioning.<br/>can also make use of the [provider-level `default-tags`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#default_tags) | `map(string)` | <pre>{<br>  "product": "sysdig-secure-for-cloud"<br>}</pre> | no |

examples/organizational/variables.tf

@@ -65,10 +65,11 @@ variable "existing_cloudtrail_config" {
   }
 
   description = <<-EOT
-    Optional block. If not set, a new cloudtrail, sns and sqs resources will be created in the management account.
-    If provided, all resources (cloudtrail,s3,sqs) must exist in the management account.
-    Otherwise, check [use-cases](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/use-cases) for proper permission setup.
-    If there's an existing cloudtrail, input one of the Optional 1/2/3 blocks.
+    Optional block. If not set, a new cloudtrail, sns and sqs resources will be created in the **management account**.
+    If provided through Option 1,  resources (cloudtrail,cloudtrail-s3) must exist in the management account.
+    Option 2, is mandatory to be used when the cloudtrail-s3 is in a different account than where SFC worklaod is installed.
+    Option 3, is an alterntive to Option1, to be able to ingest events through cloudtrail-s3-sns subscribed SQS, instead of just cloudtrail-sns
+    Check [use-cases](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/use-cases) for proper permission setup.
     <ul>
       <li>cloudtrail_s3_arn: Optional 1. ARN of a pre-existing cloudtrail_sns s3 bucket. Used together with `cloudtrail_sns_arn`, `cloudtrail_s3_arn`. If it does not exist, it will be inferred from create cloudtrail"</li>
       <li>cloudtrail_sns_arn: Optional 1. ARN of a pre-existing cloudtrail_sns. Used together with `cloudtrail_sns_arn`, `cloudtrail_s3_arn`. If it does not exist, it will be inferred from created cloudtrail. Providing an ARN requires permission to SNS:Subscribe, check ./modules/infrastructure/cloudtrail/sns_permissions.tf block</li>

use-cases/README.md

@@ -1,36 +1,8 @@
 # Secure for Cloud for AWS Use-Cases
 
-
-
-Current examples were developed for simple use-case scenarios. 
-
-New use-cases are appearing and once we consolidate a standard scenario, we will create new examples to accommodate new requirements.
-
-Check current use-case list or use the [questionnaire](./_questionnaire.md) to let us know your needs.
-
-Secure for cloud is served through Terraform for [AWS](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud) 
-[GCP](https://github.com/sysdiglabs/terraform-google-secure-for-cloud) and [Azure](https://github.com/sysdiglabs/terraform-azurerm-secure-for-cloud) clouds, 
+Secure for cloud is served through Terraform for [AWS](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud)
+[GCP](https://github.com/sysdiglabs/terraform-google-secure-for-cloud) and [Azure](https://github.com/sysdiglabs/terraform-azurerm-secure-for-cloud) clouds,
 and for AWS in [Cloudformation](https://github.com/sysdiglabs/aws-templates-secure-for-cloud) too.
-<br/>If not Terraform nor Cloudformation suits, take a look at the `manual-*` prefixed use-cases.
- 
-
-## Use-Case summary
-
-### Examples
-
-|                   | `/examples/single-*`                                               | `/examples/organizational-*` |
-| --| -- | -- |
-| Deployment Type   | all Sysdig resources will be deployed within the selected account | Most Sysdig resources will be deployed within the selected account (just one), but some features, require resources to be deployed on all of the member-accounts (for Compliance and Image Scanning) . <br />One role is needed on the management account for cloudtrail-s3 event access |
-| Target          | will only analyse current account                                 |  handles all accounts (managed and member)|
-| Drawbacks         | cannot re-use another account Cloudtrail data (unless its deployed on the same account where the sns/s3 bucket is) | for scanning, a per-member-account access role is required |
-| Optional usage limitations | - |  For organizational example, optional resources must exist in the management account. For other setups check
-other alternative use-cases | 
-| More Info | [single-ecs](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/examples/single-account-ecs), [single-apprunner](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/examples/single-account-apprunner), [single-k8s](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/examples/single-account-k8s) | [organizational](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/examples/organizational) |
-
-With both examples `single` and `org`, you can customize the desired features to de deployed with the `deploy_*` input vars to avoid deploying more than wanted.
-
-
-<br/>
 
 ### Compute Workload Type
 
@@ -55,3 +27,26 @@ Make use of optionals to allow the re-use of pre-existing resources, and avoid i
 | Azure | ResourceGroup | `resource_group_name` | - |
 | | ACR | `registry_name`, `registry_resource_group_name` | - |
 | * | Compute Workload | - | All clouds allow Sysdig Secure for cloud to be deployed on a pre-existing K8S cluster|
+
+
+<br/><br/>
+
+## Use-Case summary
+
+
+Current examples were developed for simple use-case scenarios.
+<br/>New use-cases are appearing and once we consolidate a standard scenario, we will create new examples to accommodate new requirements.
+<br/>Check current use-case list or use the [questionnaire](./_questionnaire.md) to let us know your needs.
+
+If not Terraform nor Cloudformation suits, take a look at the `manual-*` prefixed use-cases.
+
+
+|                   | `/examples/single-*`                                               | `/examples/organizational-*` |
+| --| -- | -- |
+| Deployment Type   | all Sysdig resources will be deployed within the selected account | Most Sysdig resources will be deployed within the selected account (just one), but some features, require resources to be deployed on all of the member-accounts (for Compliance and Image Scanning) . <br />One role is needed on the management account for cloudtrail-s3 event access |
+| Target          | will only analyse current account                                 |  handles all accounts (managed and member)|
+| Drawbacks         | cannot re-use another account Cloudtrail data (unless its deployed on the same account where the sns/s3 bucket is) | for scanning, a per-member-account access role is required |
+| Optional resources usage limitations | - |  For organizational example, Cloudtrail optional resources must exist in the management account. For other setups check other alternative use-cases</br><ul><li>[manual deployment; cloudtrail-s3 bucket in another member account](./manual-org-three-way.md)</li><li>[terraform-based deployment; cloudtrail with cloudtrail-s3 bucket in another member account. k8s flavor](./org-s3-k8s-filtered-account.md)</li><li>[terraform-based deployment; cloudtrail with cloudtrail-s3 bucket in another member account. ecs flavor](./org-three-cross-account-s3-event-forward.md)</li></ul>|
+| More Info | [single-ecs](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/examples/single-account-ecs), [single-apprunner](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/examples/single-account-apprunner), [single-k8s](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/examples/single-account-k8s) | [organizational](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/tree/master/examples/organizational) |
+
+With both examples `single` and `org`, you can customize the desired features to de deployed with the `deploy_*` input vars to avoid deploying more than wanted.

use-cases/manual-compliance.md

@@ -33,7 +33,7 @@ $ curl "https://<SYSDIG_SECURE_ENDPOINT>/api/cloud/v2/accounts?upsert=true" \
 
 2. Register **Benchmark Task**
 
-Create a single task to scope the organization account ids (or just a single account) to be assessed with the 
+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.
 
 This script does not cover it, but specific regions can be scoped too. Check `Benchmarks-V2` REST-API for more detail
@@ -62,7 +62,7 @@ For later usage, fetch the Trusted Identity `SYSDIG_AWS_TRUSTED_IDENTITY_ARN`
 $ 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