doc: use case org-k8s-threat-compliance (#116)

iru · web-flow · commit ca444889a0a1 · 2022-07-28T12:56:03.000+02:00
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -7,7 +7,12 @@ repos:
         pass_filenames: false
         language: system
         entry: bash -c "find . \( -iname ".terraform*" ! -iname ".terraform-docs*" ! -path "*/test/*" \)  -print0 | xargs -0 rm -r; true"
-
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.0.1
+    hooks:
+      - id: check-merge-conflict
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
   - repo: local
     # https://github.com/antonbabenko/pre-commit-terraform/#terraform_validate
     # Adding this patch to fix organizational multi-provider terraform validate error
@@ -45,9 +50,3 @@ repos:
           - '--args=--only=terraform_required_providers'
           - '--args=--only=terraform_standard_module_structure'
           - '--args=--only=terraform_workspace_remote'
-  - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.0.1
-    hooks:
-      - id: check-merge-conflict
-      - id: end-of-file-fixer
-      - id: trailing-whitespace
diff --git a/README.md b/README.md
@@ -31,12 +31,12 @@ Your user **must** have following **roles** in your GCP credentials
 ### Use a Service Account
 
 Instead of using a user, you can also deploy the module using a Service Account (SA). In order to create a SA for the organization, you need to go
-to one of your organization projects and create a SA. 
+to one of your organization projects and create a SA.
 This SA must have been granted with _Organization Admin_ role. Additionally, you should allow your user to be able to use this SA.
 
-| SA role         | SA user permissions     | 
+| SA role         | SA user permissions     |
 |--------------|-----------|
-| ![Service Account Role](https://raw.githubusercontent.com/sysdiglabs/terraform-google-secure-for-cloud/master/resources/sa-role.jpeg) | ![Service Accouynt User](https://raw.githubusercontent.com/sysdiglabs/terraform-google-secure-for-cloud/master/resources/sa-user.jpeg)    | 
+| ![Service Account Role](https://raw.githubusercontent.com/sysdiglabs/terraform-google-secure-for-cloud/master/resources/sa-role.jpeg) | ![Service Account User](https://raw.githubusercontent.com/sysdiglabs/terraform-google-secure-for-cloud/master/resources/sa-user.jpeg)    |
 
 ### APIs
 Besides, the following GCP **APIs must be enabled** to deploy resources correctly for:
diff --git a/examples/organization/.generate-providers.sh b/examples/organization/.generate-providers.sh
@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+go install github.com/hashicorp/terraform-config-inspect@latest
 terraform-config-inspect --json ./examples/organization | jq -r '
   [.required_providers[].aliases]
   | flatten
diff --git a/examples/organization/README.md b/examples/organization/README.md
@@ -48,7 +48,7 @@ For quick testing, use this snippet on your terraform files and provide followin
 - `ORG_DOMAIN` GCP organization identification
 - `PROJECT_ID` GCP project where workload will be deployed
 - `REGION_ID` for the workload to be deployed
- 
+
 
 ```terraform
 terraform {
@@ -87,7 +87,7 @@ module "secure-for-cloud_example_organization" {
     google-beta.multiproject = google-beta.multiproject
   }
 
-  source = "sysdiglabs/secure-for-cloud/google//examples/organization"  
+  source = "sysdiglabs/secure-for-cloud/google//examples/organization"
   organization_domain       = "<ORG_DOMAIN>"
 }
 ```
@@ -106,8 +106,8 @@ module "secure-for-cloud_example_organization" {
 
 | Name | Version |
 |------|---------|
-| <a name="provider_google"></a> [google](#provider\_google) | 4.24.0 |
-| <a name="provider_sysdig"></a> [sysdig](#provider\_sysdig) | 0.5.37 |
+| <a name="provider_google"></a> [google](#provider\_google) | 4.30.0 |
+| <a name="provider_sysdig"></a> [sysdig](#provider\_sysdig) | 0.5.39 |
 
 ## Modules
 
diff --git a/examples/single-project-k8s/README.md b/examples/single-project-k8s/README.md
@@ -81,9 +81,9 @@ See [inputs summary](#inputs) or module module [`variables.tf`](./variables.tf)
 
 | Name | Version |
 |------|---------|
-| <a name="provider_google"></a> [google](#provider\_google) | 4.24.0 |
-| <a name="provider_helm"></a> [helm](#provider\_helm) | 2.5.1 |
-| <a name="provider_sysdig"></a> [sysdig](#provider\_sysdig) | 0.5.37 |
+| <a name="provider_google"></a> [google](#provider\_google) | 4.30.0 |
+| <a name="provider_helm"></a> [helm](#provider\_helm) | 2.6.0 |
+| <a name="provider_sysdig"></a> [sysdig](#provider\_sysdig) | 0.5.39 |
 
 ## Modules
 
diff --git a/examples/single-project/README.md b/examples/single-project/README.md
@@ -82,8 +82,8 @@ module "secure-for-cloud_example_single-project" {
 
 | Name | Version |
 |------|---------|
-| <a name="provider_google"></a> [google](#provider\_google) | 4.24.0 |
-| <a name="provider_sysdig"></a> [sysdig](#provider\_sysdig) | 0.5.37 |
+| <a name="provider_google"></a> [google](#provider\_google) | 4.30.0 |
+| <a name="provider_sysdig"></a> [sysdig](#provider\_sysdig) | 0.5.39 |
 
 ## Modules
 
diff --git a/examples/trigger-events/README.md b/examples/trigger-events/README.md
@@ -38,7 +38,7 @@ module "secure-for-cloud_trigger_events" {
 
 | Name | Version |
 |------|---------|
-| <a name="provider_google"></a> [google](#provider\_google) | 4.24.0 |
+| <a name="provider_google"></a> [google](#provider\_google) | 4.30.0 |
 
 ## Modules
 
diff --git a/modules/infrastructure/organization_sink/README.md b/modules/infrastructure/organization_sink/README.md
@@ -12,7 +12,7 @@
 
 | Name | Version |
 |------|---------|
-| <a name="provider_google"></a> [google](#provider\_google) | 4.24.0 |
+| <a name="provider_google"></a> [google](#provider\_google) | 4.30.0 |
 
 ## Modules
 
diff --git a/modules/infrastructure/project_sink/README.md b/modules/infrastructure/project_sink/README.md
@@ -12,7 +12,7 @@
 
 | Name | Version |
 |------|---------|
-| <a name="provider_google"></a> [google](#provider\_google) | 4.24.0 |
+| <a name="provider_google"></a> [google](#provider\_google) | 4.30.0 |
 
 ## Modules
 
diff --git a/modules/infrastructure/pubsub_subscription/README.md b/modules/infrastructure/pubsub_subscription/README.md
@@ -15,7 +15,7 @@ already exists in the project. It will create the topic if it doesn't exist.
 
 | Name | Version |
 |------|---------|
-| <a name="provider_google"></a> [google](#provider\_google) | 4.24.0 |
+| <a name="provider_google"></a> [google](#provider\_google) | 4.30.0 |
 
 ## Modules
 
diff --git a/modules/infrastructure/secrets/README.md b/modules/infrastructure/secrets/README.md
@@ -12,7 +12,7 @@
 
 | Name | Version |
 |------|---------|
-| <a name="provider_google"></a> [google](#provider\_google) | 4.24.0 |
+| <a name="provider_google"></a> [google](#provider\_google) | 4.30.0 |
 
 ## Modules
 
diff --git a/modules/services/cloud-connector/README.md b/modules/services/cloud-connector/README.md
@@ -32,7 +32,7 @@ module "cloud_connector_gcp" {
 
 | Name | Version |
 |------|---------|
-| <a name="provider_google"></a> [google](#provider\_google) | 4.24.0 |
+| <a name="provider_google"></a> [google](#provider\_google) | 4.30.0 |
 
 ## Modules
 
diff --git a/use-cases/org-k8s-threat-compliance.md b/use-cases/org-k8s-threat-compliance.md
@@ -0,0 +1,207 @@
+# Organizational - Kubernetes only (no TF) - Threat Detection and Compliance
+
+## Use-Case explanation
+
+- Organizational setup
+  - Dynamic environments with projects created and destroyed on-demand
+- Sysdig features: Threat-detection, Compliance (no image scanning)
+- Due to dynamic nature of customer's environment, a heavy programmatically ops tooling are used (not including Terraform) .
+- A summary of the required resources/permissions will be done, so they're provisioned for the Secure for Cloud feature sto work.
+
+## Infrastructure Solution
+
+As a quick summary we'll need
+
+- Organization
+  - Log Router Sink
+  - CloudBench Role for compliance
+- Member project (Sysdig resources, existing project or new one)
+  - PubSub to wire events from the log router into cloud-connector compute module
+  - CloudBench Role for compliance
+  - K8s cluster for cloud-connector (Sysdig compute workload for threat detection)
+- Rest of member projects
+  - CloudBench Role for compliance
+
+![overall infrastructure](resources/diagram-org-k8s-threat-compliance.png)
+
+
+We suggest to
+- start with secure for cloud, cloud-connector module required infrastructure wiring and deployment (this will cover threat-detection side)
+- then move on to Compliance role setup
+<br/><br/>
+
+### Cloud-Connector wiring: Log Router Sink + PubSub Topic
+
+0. From your organization, **choose a member project** as `SYSDIG_PROJECT_ID`
+1. In `SYSDIG_PROJECT_ID`, create a **Pub/Sub** topic (with default configuration is enough)
+   - Save `SYSDIG_PUBSUB_SUBSCRIPTION_NAME` for later
+2. In the organizational domain level, create **Logging Logs Router** Sink
+   - Add as destination the Pub/Sub from previous point.
+   - Choose to ingest organization and child resources
+   - Set the following filter
+    ```text
+    logName=~"/logs/cloudaudit.googleapis.com%2Factivity$" AND -resource.type="k8s_cluster"
+    ```
+3. Give Sink **Permissions** to write on PubSub
+   - Grab the `Writer Identity` user from the just created Sink
+   - In the PubSub resource, grant `Pub/Sub Publisher` role to the Sink `Writer Identity`
+
+<br/><br/>
+### Secure for Cloud Compute Deployment
+
+<!--
+-- TODO. authentication howto.
+- 1/first approach would be to create a SA
+
+small explanation here https://github.com/sysdiglabs/terraform-google-secure-for-cloud/tree/master/examples/single-project-k8s
+and code reference here https://github.com/sysdiglabs/terraform-google-secure-for-cloud/blob/master/examples/single-project-k8s/cloud-connector-config.tf#L21
+
+- 2/more elegant approach to use the serviceAccount from the chart. talk with @javi
+-->
+
+- Create Service Account with the `pubsub/subscriber` role.
+- Get the JSON credentials file for the created Service Account `<JSON_CONTENT_FROM_THE_CREDENTIALS_FILE>` (this would be an example of the content).
+    ```
+      {
+        "type": "service_account",
+        "project_id": ...
+        "private_key_id": ...
+        ...
+      }
+    ```
+<br/>
+
+- Sysdig **Helm** [cloud-connector chart](https://charts.sysdig.com/charts/cloud-connector/) will be used with following parametrization
+
+  - Locate your `<SYSDIG_SECURE_ENDPOINT>` and `<SYSDIG_SECURE_API_TOKEN>`. [Howto fetch ApiToken](https://docs.sysdig.com/en/docs/administration/administration-settings/user-profile-and-password/retrieve-the-sysdig-api-token/)
+
+
+```yaml
+rules: []
+scanners: []
+sysdig:
+  url: <SYSDIG_SECURE_ENDPOINT>
+  secureAPIToken: <SYSDIG_SECURE_API_TOKEN>
+
+# not required but would help product
+telemetryDeploymentMethod: "helm_gcp_k8s_org"
+
+ingestors:
+  # receives GCP auditlog from a PubSub topic
+  - gcp-auditlog-pubsub:
+      project: <SYSDIG_PROJECT_ID>
+      subscription: <SYSDIG_PUBSUB_SUBSCRIPTION_NAME>
+
+gcpCredentials: |
+  <JSON_CONTENT_FROM_THE_CREDENTIALS_FILE> (beware of the tabulation)
+```
+
+Check that deployment logs throw no errors and can go to [confirm services are working](#confirm-services-are-working) for threat detection functionality checkup.
+<br/>
+<br/>
+
+### Compliance - Sysdig Side
+
+1. **Register Customer Organization Projects** on Sysdig
+    - For each project you want to provision for the Compliance feature, we need to register them on Sysdig Secure
+    - 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](https://github.com/sysdiglabs/aws-templates-secure-for-cloud/blob/main/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": "<GCP_PROJECT_NUMBER>",
+       "alias": "<GCP_PROJECT_ID>",
+       "provider": "gcp",
+       "roleAvailable": true,
+       "roleName": "sysdigcloudbench"
+    }'
+    ```
+
+<br/>
+<br/>
+
+2. Register **Benchmark Task**
+    - Create a single task to scope the organization group ids to be assessed.
+    - 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" \
+    --header "Authorization: Bearer <SYSDIG_SECURE_API_TOKEN>" \
+    -X POST \
+    -H 'Accept: application/json' \
+    -H 'Content-Type: application/json' \
+    -d '{
+    "name": "Sysdig Secure for Cloud (GCP) - Organization",
+    "schedule": "0 3 * * *",
+    "schema": "gcp_foundations_bench-1.2.0",
+    "scope": "gcp.projectId in ('<GCP_PROJECT_ID1>',...,'<GCP_PROJECT_IDN>')'",
+    "enabled": true
+    }'
+    ```
+
+<br/>
+<br/>
+
+3. Get **Sysdig Federation Trusted Identity**
+   - For later usage, fetch the Trusted Identity, which is composed by the parts `SYSDIG_AWS_ACCOUNT_ID` and `SYSDIG_AWS_ROLE_NAME`
+    ```shell
+    $ curl -s 'https://<SYSDIG_SECURE_ENDPOINT>/api/cloud/v2/gcp/trustedIdentity' \
+    --header 'Authorization: Bearer <SYSDIG_SECURE_API_TOKEN>'
+    ```
+    Response pattern:
+    ```shell
+    arn:aws:iam::SYSDIG_AWS_ACCOUNT_ID:role/SYSDIG_AWS_ROLE_NAME
+    ```
+   <br/><br/>
+4. Get **Sysdig ExternalId**
+    - For later usage, fetch `SYSDIG_AWS_EXTERNAL_ID` from one of the previously registered GCP projects. All accounts will have same id (you only need to run it once).
+    ```shell
+    $ curl -s "https://<SYSDIG_SECURE_ENDPOINT>/api/cloud/v2/accounts/<GCP_PROJECT_ID>?includeExternalId=true" \
+    --header "Authorization: Bearer $SYSDIG_API_TOKEN"
+    ```
+    From the resulting payload get the `externalId` attribute value.
+
+   <br/><br/>
+
+### Compliance - Customer's Side
+
+We'll need, **for each project** (`GCP_PROJECT_NUMBER`)
+
+- A **Service Account** (SA) with `IAM Workload Identity Federation` that provides access to Sysdig's AWS Cloud infrastructure, to be able to assess your infrastructure Compliance
+    - currently, federation is only available through AWS, but we will enable other clouds in the near-future
+- **Permissions** set to the SA to be able to read customer's infrastructure
+
+![compliance role](resources/diagram-org-k8s-threat-compliance-roles.png)
+
+
+1. Create a **Custom Role** (ex.: 'Sysdig Cloud Benchmark Role') and assign to it following permissions
+   - `storage.buckets.getIamPolicy`
+   - `bigquery.tables.list`
+   - this is required to add some more permissions that are not available in GCP builtin viewer role
+2. Create a **Service Account** with the name 'sysdigcloudbench'
+   - This role must match the `roleName` set when the project was registered with Sydig in step 1 of Compliance - Sysdig Side
+   - Give it GCP builtin `roles/viewer` **Viewer Role**
+   - And previously created Custom Role <!-- tip: in UI: IAM & Admin -> IAM (Edit)-->
+
+3. Create a **Workload Identity Federation Provider and Pool**
+   - Provider must be created for `aws` provider, using the `SYSDIG_AWS_ACCOUNT_ID`
+   - Create a pool as with name 'sysdigcloud' `<IDENTITY_POOL_ID>`
+   - Provider must be AWS:
+     - Provider name: "Sysdig Secure for Cloud"
+     - Attribute mapping, set both
+     ```text
+     google.subject: assertion.arn
+     attribute.aws_role: assertion.arn
+     ```
+
+4. In the previously created 'sysdigcloudbench' SA, we need to create a **Service Account Pool Binding**
+   - Set Pool Binding the role `roles/iam.workloadIdentityUser`
+   - For the members value, we will add the following
+     > principalSet://iam.googleapis.com/projects/<GCP_PROJECT_NUMBER>/locations/global/workloadIdentityPools/<IDENTITY_POOL_ID>/attribute.aws_role/arn:aws:sts::<SYSDIG_AWS_ACCOUNT_ID>:assumed-role/<SYSDIG_AWS_ROLE_NAME>/<SYSDIG_AWS_EXTERNAL_ID>
+
+## Confirm services are working
+
+- [Official Docs Check Guide](https://docs.sysdig.com/en/docs/installation/sysdig-secure-for-cloud/deploy-sysdig-secure-for-cloud-on-gcp/#confirm-the-services-are-working)
+- [Forcing events](https://github.com/sysdiglabs/terraform-google-secure-for-cloud#forcing-events)
diff --git a/use-cases/resources/diagram-org-k8s-threat-compliance-roles.png b/use-cases/resources/diagram-org-k8s-threat-compliance-roles.png
diff --git a/use-cases/resources/diagram-org-k8s-threat-compliance-roles.py b/use-cases/resources/diagram-org-k8s-threat-compliance-roles.py
@@ -0,0 +1,24 @@
+# diagrams as code vía https://diagrams.mingrammer.com
+from diagrams import Diagram, Cluster
+from diagrams.gcp.security import Iam
+from diagrams.custom import Custom
+
+diagram_attr = {
+    "pad": "0.25",
+}
+
+color_event = "firebrick"
+color_scanning = "dark-green"
+color_permission = "red"
+color_non_important = "gray"
+color_sysdig = "lightblue"
+
+with Diagram("Role", graph_attr=diagram_attr, filename="diagram-org-k8s-threat-compliance-roles", show=True, direction="TB"):
+
+    with Cluster("", graph_attr={"bgcolor": "lightblue"}):
+        serviceAccount = Iam("Service Account")
+        sysdigCloudBenchmarkRole = Iam("Sysdig Cloud \n Benchmark Role \n [storage.buckets.getIamPolicy, \n bigquery.tables.list]")
+        roleViewer = Iam("roles/viewer")
+
+        serviceAccount << sysdigCloudBenchmarkRole
+        serviceAccount << roleViewer
diff --git a/use-cases/resources/diagram-org-k8s-threat-compliance.png b/use-cases/resources/diagram-org-k8s-threat-compliance.png
diff --git a/use-cases/resources/diagram-org-k8s-threat-compliance.py b/use-cases/resources/diagram-org-k8s-threat-compliance.py

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`#!/usr/bin/env bash`
	`2`	`+go install github.com/hashicorp/terraform-config-inspect@latest`
`2`	`3`	`terraform-config-inspect --json ./examples/organization \| jq -r '`
`3`	`4`	`[.required_providers[].aliases]`
`4`	`5`	`\| flatten`