docs: self-baked example library (#50)

* docs: small renaming and explanations
* docs: clarify s3-sns-sqs use-case
* docs: self-baked user-case

Author: iru

README.md

@@ -17,6 +17,28 @@ For other Cloud providers check: [GCP](https://github.com/sysdiglabs/terraform-g
 
 <br/>
 
+[comment]: <> (## Permissions)
+
+[comment]: <> (Inspect `/module/infrastructure/permissions` subdirectories to understand the several)
+
+[comment]: <> (permissions required.)
+
+[comment]: <> (- `/iam-user` creates an IAM user + adds permissions for required modules &#40;general, cloud-connector, cloud-scanning&#41;<br/><br/>)
+
+[comment]: <> (- `/general` concerns general permissions that apply to both threat-detection and image-scanning features)
+
+[comment]: <> (- `/cloud-connector` for threat-detection features)
+
+[comment]: <> (- `/cloud-scanning` for image-scanning features)
+
+[comment]: <> (TODO review `/module/*/ permissions` vs. the ones in permissions folder)
+
+[comment]: <> (TODO review)
+
+[comment]: <> (- `/org-role-ecs`)
+
+[comment]: <> (- `/org-role-eks`)
+
 ## Usage
 
 There are several ways to deploy this in you AWS infrastructure:

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

@@ -21,9 +21,9 @@ Minimum requirements:
     ```
     sysdig_secure_api_token=<SECURE_API_TOKEN>
     ```
-4. S3 event-notification subscribed SNS topic(s).<br/>see `modules/infrastructure/cloudtrail_s3-sns-sqs` for guidance<br/><br/>
-5. **SQS topic** subscribed to the S3-SNS event notifications.<br/>The ARN of this SQS will be used as an input parameter to the module.<br/>
-   see `modules/infrastructure/sqs-sns-subscription` for guidance`<br/><br/>
+4. **SQS topic** subscribed to the Cloudtrail-S3-SNS event notifications.<br/>
+This three-actor setup (S3-SNS-SQS) can be manually provisioned, or handled through `modules/infrastructure/cloudtrail_s3-sns-sqs` module<br/><br/>
+Client is responsible for provisioning the ARN of this SQS, which will be required as an input parameter.<br/>
 
 
 ## Usage

examples-internal/self-baked/org-s3-k8s-filtered.md

@@ -0,0 +1,129 @@
+# ORG-S3-K8S-FILTERED
+
+## Use-Case explanation
+
+**Current User Setup**
+- [X] organizational setup
+  - [ ] organizational cloudtrail
+  - [X] centralized S3 bucket with cloudtrail-events
+  - [ ] member account usage - all required resources (s3/sns/sqs, sysdig workload) in same account
+  - [X] member account usage - all required resources are in scattered
+- [X] pre-existing k8s cluster we want to use to deploy Sysdig for Cloud workload
+
+**Sysdig Secure For Cloud Requirements**
+- [X] account-specific threat-detection
+- [ ] account-specific/organizational? image scanning (WIP)
+- [ ] account-specific/organizational? benchmark (WIP)
+- [X] pre-existing kubernetes management vía service account (WIP)
+<br/>this has not been tested yet, we rely on an `accessKey` created specifically for Sysdig-For-Cloud.
+<!--
+Skip step 4 and remove `aws_access_key_id` and `aws_secret_access_key` parameters from `org_k8s_threat_reuse_cloudtrail` module
+-->
+
+## Suggested building-blocks
+
+1. Define different **AWS providers**
+    1. Populate  `_REGION_` and `_S3_REGION_`
+    2. Because we are going to provision resources on multiple accounts, we're gonna need several AWS providers
+
+       2. `s3` for s3-sns-sqs resources to be deployed. IAM user-credentials, to be used for k8s must also be in S3 account
+       3. `sfc` for secure-for-cloud utilitary resources to be deployed
+
+
+```terraform
+provider "aws" {
+  alias = "s3"
+  region = "_S3_REGION_"
+  ...
+}
+
+provider "aws" {
+  alias = "sfc"
+  region = "_REGION_"
+  ...
+}
+
+```
+
+2. **Helm provider** definition
+
+Sysdig workload will be deployed through its official **Helm** [cloud-connector chart](https://charts.sysdig.com/charts/cloud-connector/).
+<br/>Note: Configure [**Helm** Provider](https://registry.terraform.io/providers/hashicorp/helm/latest/docs) for **Kubernetes** cluster
+<br/>ex:.
+```terraform
+provider "helm" {
+  kubernetes {
+    config_path = "~/.kube/config"
+  }
+}
+
+```
+
+3. **Cloudtrail-S3-SNS-SQS**
+
+   1. Populate  `_CLOUDTRAIL_S3_NAME_`
+   <br/>ex.:
+       ```text
+       cloudtrail_s3_name=cloudtrail-logging-237944556329
+       ```
+   2. Populate `_CLOUDTRAIL_S3_FILTER_PREFIX_` in order to ingest a specific-account. Otherwise just remove its assignation
+   <br/>ex.:
+       ```text
+       s3_event_notification_filter_prefix=cloudtrail/AWSLogs/237944556329
+       ```
+
+```terraform
+module "cloudtrail_s3_sns_sqs" {
+  providers = {
+    aws = aws.s3
+  }
+  source  = "sysdiglabs/secure-for-cloud/aws//modules/infrastructure/cloudtrail_s3-sns-sqs"
+  cloudtrail_s3_name = _CLOUDTRAIL_S3_NAME_
+  s3_event_notification_filter_prefix=_CLOUDTRAIL_S3_FILTER_PREFIX_
+}
+```
+
+
+4. Kubernetes Organizational **User Permissions** to be able to handle S3/SQS operations
+<br/>Because Helm Cloud-Connector chart require specific AWS credentials to be passed by parameter, a new user + access key will be created within account. See [`modules/infrastructure/permissions/iam-user`](https://github.com/sysdiglabs/terraform-aws-secure-for-cloud/blob/master/modules/infrastructure/permissions/iam-user)
+
+```terraform
+module "org_user" {
+   providers = {
+      aws = aws.s3
+   }
+   source  = "sysdiglabs/secure-for-cloud/aws//modules/infrastructure/permissions/iam-user"
+   deploy_image_scanning         = false
+   cloudtrail_s3_bucket_arn      = module.cloudtrail_s3_sns_sqs.cloudtrail_s3_arn
+   cloudtrail_subscribed_sqs_arn = module.cloudtrail_s3_sns_sqs.cloudtrail_subscribed_sqs_arn
+}
+```
+
+5. **Sysdig workload deployment on K8s**
+
+    * Populate  `_SYSDIG_SECURE_ENDPOINT_` and `_SYSDID_SECURE_API_TOKEN_`
+
+```terraform
+# force some waiting for org_user creation (eventual consistency)
+resource "time_sleep" "wait" {
+  depends_on      = [module.org_user]
+  create_duration = "5s"
+}
+
+module "org_k8s_threat_reuse_cloudtrail" {
+    providers = {
+      aws = aws.sfc
+    }
+    source  = "sysdiglabs/secure-for-cloud/aws//examples-internal/organizational-k8s-threat-reuse_cloudtrail"
+    name   = "test-orgk8s"
+
+    sysdig_secure_endpoint    = _SYSDIG_SECURE_ENDPOINT_
+    sysdig_secure_api_token   = _SYSDID_SECURE_API_TOKEN_
+    cloudtrail_s3_sns_sqs_url = module.cloudtrail_s3_sns_sqs.cloudtrail_subscribed_sqs_url
+
+    aws_access_key_id     = module.org_user.sfc_user_access_key_id
+    aws_secret_access_key = module.org_user.sfc_user_secret_access_key
+
+    depends_on = [module.org_user.sfc_user_arn, time_sleep.wait]
+}
+```

examples/organizational/README.md

@@ -97,7 +97,7 @@ Notice that:
 | <a name="module_ecs_fargate_cluster"></a> [ecs\_fargate\_cluster](#module\_ecs\_fargate\_cluster) | ../../modules/infrastructure/ecs-fargate-cluster |  |
 | <a name="module_resource_group"></a> [resource\_group](#module\_resource\_group) | ../../modules/infrastructure/resource-group |  |
 | <a name="module_resource_group_secure_for_cloud_member"></a> [resource\_group\_secure\_for\_cloud\_member](#module\_resource\_group\_secure\_for\_cloud\_member) | ../../modules/infrastructure/resource-group |  |
-| <a name="module_secure_for_cloud_role"></a> [secure\_for\_cloud\_role](#module\_secure\_for\_cloud\_role) | ../../modules/infrastructure/permissions/ecs-org-role |  |
+| <a name="module_secure_for_cloud_role"></a> [secure\_for\_cloud\_role](#module\_secure\_for\_cloud\_role) | ../../modules/infrastructure/permissions/org-role-ecs |  |
 | <a name="module_ssm"></a> [ssm](#module\_ssm) | ../../modules/infrastructure/ssm |  |
 
 ## Resources

examples/organizational/credentials.tf

@@ -8,7 +8,7 @@ module "resource_group_secure_for_cloud_member" {
 }
 
 module "secure_for_cloud_role" {
-  source = "../../modules/infrastructure/permissions/ecs-org-role"
+  source = "../../modules/infrastructure/permissions/org-role-ecs"
   providers = {
     aws.member = aws.member
   }

modules/infrastructure/cloudtrail_s3-sns-sqs/README.md

@@ -1,10 +1,28 @@
 # Cloudtrail_S3 event notification handle through SNS-SQS
 
-Provisions the SNS-SQS event-notification on a pre-existing cloudtrail, based on it S3 bucket event-notifications
+Provision a cloud-connector cloudtrail input, based on an S3-SNS-SQS event-notification.
+
+# How it works
+
+- This module's output will be visible in the `S3` console, after entering a bucket, in it's `Properties`, `Event notifications` section.
+Besides, an SQS queue will be visible, which will gather the events coming from the Cloudtrail-S3-SNS topic notifications.
+- Creates the SNS-SQS link using the underlying module `modules/infrastructure/sqs-sns-subscription`<br/><br/>
+
+## Recommended use-cases
+
+Matches one of the following points:
+
+- Accounts are organized in an AWS Organization, but there is NO [Organizational Cloudtrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/creating-trail-organization.html)
+- An existing cloudtrail is available, but it has NO
+[Cloudtrail-SNS notification configured](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/configure-sns-notifications-for-cloudtrail.html?icmpid=docs_console_unmapped)
+- An existing cloudtrail is available, but despite having Cloudtrail-SNS notification activated we want to make an
+EVENT FILTER/fine-tunning, regarding what we want to send to Sysdig Cloud-Connector for the thread-detection feature.
 
 ## Pre-requirements
+- Identify the Cloudtrail-S3 bucket name, for the `input_cloudtrail_s3_name` module input
+<!--
 - SNS must be created in the same region as Cloudtrail. Adjust `var.region` or your aws credentials region.
-
+-->
 
 
 <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
@@ -42,7 +60,7 @@ Provisions the SNS-SQS event-notification on a pre-existing cloudtrail, based on
 |------|-------------|------|---------|:--------:|
 | <a name="input_cloudtrail_s3_name"></a> [cloudtrail\_s3\_name](#input\_cloudtrail\_s3\_name) | Name of the Cloudtrail S3 bucket | `string` | n/a | yes |
 | <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_s3_event_notification_filter_prefix"></a> [s3\_event\_notification\_filter\_prefix](#input\_s3\_event\_notification\_filter\_prefix) | S3 Path filter prefix for event notification | `string` | `""` | no |
+| <a name="input_s3_event_notification_filter_prefix"></a> [s3\_event\_notification\_filter\_prefix](#input\_s3\_event\_notification\_filter\_prefix) | S3 Path filter prefix for event notification. Limit the notifications to objects with key starting with specified characters | `string` | `""` | no |
 | <a name="input_tags"></a> [tags](#input\_tags) | sysdig secure-for-cloud tags | `map(string)` | <pre>{<br>  "product": "sysdig-secure-for-cloud"<br>}</pre> | no |
 
 ## Outputs

modules/infrastructure/cloudtrail_s3-sns-sqs/variables.tf

@@ -10,7 +10,7 @@ variable "cloudtrail_s3_name" {
 variable "s3_event_notification_filter_prefix" {
   type        = string
   default     = ""
-  description = "S3 Path filter prefix for event notification"
+  description = "S3 Path filter prefix for event notification. Limit the notifications to objects with key starting with specified characters"
 }
 
 #

modules/infrastructure/permissions/general/README.md

@@ -1,6 +1,7 @@
 # Permissions :: General
 
-General permissions that apply to both threat-detection (cloud-connector) and image-scanning (cloud-scanning) features
+General permissions that apply to both cloud-connector and cloud-scanning modules
+- Currently this only applies to the capability of reading the Secure API Token from the Key Management Service
 
 <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 ## Requirements

modules/infrastructure/permissions/iam-user/README.md

@@ -1,6 +1,7 @@
 # Permissions :: Single-Account user credentials
 
-Will create an IAM user and add add permissions for required modules
+Creates an IAM user and adds permissions for required modules.
+<br/>Will use the `deploy_threat_detection` and `deploy_image_scanning` flags
 
 <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 ## Requirements

modules/infrastructure/permissions/iam-user/main.tf

@@ -10,7 +10,6 @@ resource "aws_iam_access_key" "this" {
 
 
 
-
 module "credentials_general" {
   source = "../general"
   name   = var.name

modules/infrastructure/permissions/ecs-org-role/README.md renamed to modules/infrastructure/permissions/org-role-ecs/README.md

@@ -2,14 +2,16 @@
 
 The aim of this module is to manage the organizational **managed account** required role and permissions for threat-detection and image scanning modules to work properly.
 
-1. Enables Cloudtrail SNS subscription permissions through a role specified within the Sysdig Secure workload **member account**
-2. Creates a role in the organizational **managed account** with the required permissions
+1. Enables Cloudtrail SNS subscription permissions through a role specified within the Sysdig Secure workload **member account**<br/><br/>
+2. Creates a role `sfc-SysdigSecureForCloudRole` (by default) in the organizational **managed account** with the required permissions
 
-* Threat-Detection
+
+## Permissions
+* Threat-Detection feature
   * S3 Get and List permissions in order to fetch the events
   * SNS Subscription permissions in order to subscribe a topic to it
 
-* Image scanning
+* Image scanning feature
   * Enable this role to assumeRole to member accounts through the `organizational_role_per_account` role,
     in order to be able to fetch images that may be in member-account repositories
 

modules/infrastructure/permissions/ecs-org-role/main.tf renamed to modules/infrastructure/permissions/org-role-ecs/main.tf

@@ -26,8 +26,9 @@ module "cloudtrail_s3_sns_sqs" {
   providers = {
     aws = aws.admin
   }
-  source             = "../../../modules/infrastructure/cloudtrail_s3-sns-sqs"
-  cloudtrail_s3_name = var.cloudtrail_s3_name
+  source                              = "../../../modules/infrastructure/cloudtrail_s3-sns-sqs"
+  cloudtrail_s3_name                  = var.cloudtrail_s3_name
+  s3_event_notification_filter_prefix = var.s3_event_notification_filter_prefix
 }
 
 

modules/infrastructure/permissions/ecs-org-role/outputs.tf renamed to modules/infrastructure/permissions/org-role-ecs/outputs.tf

@@ -15,6 +15,12 @@ variable "sysdig_secure_api_token" {
 # provide variables for testing
 #---------------------------------
 
+variable "s3_event_notification_filter_prefix" {
+  type        = string
+  default     = ""
+  description = "S3 Path filter prefix for event notification. Limit the notifications to objects with key starting with specified characters"
+}
+
 variable "org_profile" {
   type    = string
   default = ""