Skip to content

Commit ca6d4c0

Browse files
vannicktrinquieragold-rh
vannicktrinquier
and
agold-rh
authored
feat: add library of custom module for scc security health analytics (#1481)
Co-authored-by: Andrew Gold <[email protected]>
1 parent e578786 commit ca6d4c0

File tree

129 files changed

+2664
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

129 files changed

+2664
-0
lines changed

Diff for: ‎README.md

+4
Original file line numberDiff line numberDiff line change
@@ -417,6 +417,10 @@ Platform usage.
417417
prioritize a specific scope (e.g. project or folder) to attribute CUDs first
418418
before letting any unconsumed discount float to other parts of an
419419
organization.
420+
* [Custom Module for Security Health Analytics Library](tools/custom-module-security-health-analytics-library) -
421+
A library of custom modules for SCC Security Health Analytics. It includes
422+
tools to easily generate custom modules and provisioning them on your organization.
423+
This library helps organization to detect configuration and compliance drifts.
420424
* [Custom Organization Policy Library](tools/custom-organization-policy-library) - A library
421425
of custom organization policy constraints and samples. It includes tools to easily generate policies for provisioning across your organization using either Google Cloud (gcloud) or Terraform.
422426
* [Custom Role Analyzer](tools/custom-roles-analyzer) - This tool will provide

Diff for: ‎tools/custom-module-security-health-analytics-library/.gitignore

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.terraform.lock.hcl
2+
.terraform
3+
.terraform.tfstate*
4+
5+
*.out
6+
*.bak
7+
8+
*/**/terraform.tfstate*
9+
terraform/

Diff for: ‎tools/custom-module-security-health-analytics-library/Makefile

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Make will use bash instead of sh
2+
SHELL := /usr/bin/env bash
3+
CONFIG := -f build/config/schema.yaml -f build/config/services/ -f values.yaml -f build/ytt_lib/
4+
OUTPUT_GCLOUD := samples/gcloud
5+
6+
YQ := $(shell command -v yq 2> /dev/null)
7+
ifndef YQ
8+
$(error "yq is not installed or not in PATH. Please install yq: https://github.com/mikefarah/yq/#install")
9+
endif
10+
11+
ORGANIZATION_ID := $(shell $(YQ) '.organization' values.yaml)
12+
13+
.PHONY: sha
14+
sha:
15+
rm -rf $(OUTPUT_GCLOUD)/sha
16+
ytt $(CONFIG) -f build/custom-sha/ --output-files $(OUTPUT_GCLOUD)/custom-sha
17+
18+
.PHONY: build
19+
build: clean sha
20+
21+
.PHONY: deploy-sha
22+
deploy-sha:
23+
sh scripts/deploy.sh sha $(OUTPUT_GCLOUD)/custom-sha/ --organization $(ORGANIZATION_ID)
24+
25+
.PHONY: deploy
26+
deploy: build deploy-sha
27+
28+
.PHONY: clean
29+
clean:
30+
rm -rf $(OUTPUT_GCLOUD)
31+
rm -rf $(OUTPUT_TF)
32+
33+

Diff for: ‎tools/custom-module-security-health-analytics-library/README.md

+193
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# Custom Module for Security Health Analytics Library
2+
## Overview
3+
4+
This repository provides a library of custom module for security health analytics (SHA) and samples. It includes tools to easily provision custom modules on your organization using gcloud.
5+
For more information on how Custom Module for Security Health Analytics (Custom Module for SHA) can help secure your environment, please refer to the [Google Cloud documentation](https://cloud.google.com/security-command-center/docs/custom-modules-sha-overview).
6+
7+
**Custom Module for Security Health Analytics is available only with the Security Command Center Premium tier.**
8+
9+
## Setting up environment
10+
You can quickly set up your environment to manage the Custom Module for SHA library using [ytt](https://carvel.dev/ytt/).
11+
12+
### Install via script (macOS or Linux)
13+
Install ytt into specific directory. Note that install.sh script installs other Carvel tools as well. For more detail instruction, you can check [here](https://carvel.dev/ytt/docs/latest/install/)
14+
```bash
15+
mkdir local-bin/
16+
curl -L https://carvel.dev/install.sh | K14SIO_INSTALL_BIN_DIR=local-bin bash
17+
export PATH=$PWD/local-bin/:$PATH
18+
ytt version
19+
```
20+
21+
Install yq following [those instructions](https://github.com/mikefarah/yq/#install)
22+
23+
### Install binaries via Homebrew (macOS or Linux)
24+
Require Homebrew to be installed
25+
```bash
26+
brew tap carvel-dev/carvel
27+
brew install ytt
28+
ytt version
29+
30+
brew install yq
31+
```
32+
For more details about other type of installation, please refer to official documentation [here](https://carvel.dev/ytt/docs/latest/install/)
33+
34+
## Organization of the repository
35+
The repository is organized as follows:
36+
- `build`: Contains configuration files and the ytt library used to generate final custom modules.
37+
- `docs`: Contains documentation related to this tool.
38+
- `samples`: Contains the generated custom modules.
39+
- `scripts`: Contains scripts used for deployment of custom modules.
40+
41+
Here's a visual representation:
42+
```
43+
$ tree -d -L 4
44+
.
45+
├── build
46+
│ ├── config
47+
│ │ └── services
48+
│ ├── custom-sha
49+
│ │ ├── artifactregistry
50+
│ │ ├── bigquery
51+
│ │ ├── cloudfunctions
52+
│ │ ├── cloudkms
53+
│ │ ├── cloudresourcemanager
54+
│ │ ├── cloudrun
55+
│ │ ├── cloudsql
56+
│ │ ├── compute
57+
│ │ ├── gke
58+
│ │ ├── logging
59+
│ │ ├── secretmanager
60+
│ │ └── serviceUsage
61+
│ └── ytt_lib
62+
├── docs
63+
├── samples
64+
│ └── gcloud
65+
│ └── custom-sha
66+
│ ├── artifactregistry
67+
│ ├── bigquery
68+
│ ├── cloudfunctions
69+
│ ├── cloudkms
70+
│ ├── cloudresourcemanager
71+
│ ├── cloudrun
72+
│ ├── cloudsql
73+
│ ├── compute
74+
│ ├── gke
75+
│ ├── logging
76+
│ ├── secretmanager
77+
│ └── serviceUsage
78+
└── scripts
79+
```
80+
81+
## Generating Custom Modules for SHA
82+
`ytt` is a command-line tool for templating and patching YAML files. It simplifies the creation of YAML files for custom modules.
83+
The scripts in this repository further streamline the process for various organization structures.
84+
85+
Steps to Generate:
86+
87+
**1. Configure Generation Settings**
88+
- Define organization-specific settings (organization ID, bundles to enable, custom module parameters) in the values.yaml file.
89+
90+
**2. Generate Custom Modules**
91+
- Use `make build` for gcloud format.
92+
93+
**3. Provision Custom Modules**
94+
- Use `make deploy` to apply the generated files to your organization.
95+
96+
### 1. Configure Generation Settings
97+
To generate custom modules, it is expected to provide the good configuration values.
98+
Those configuration settings are specific to an organization such as organization id, bundles to be enabled, custom modules parameters (when needed) to use.
99+
Those settings needs to be defined in the `values.yaml` file.
100+
101+
#### General settings
102+
103+
| Settings | Defaut value | Description |
104+
|-------------------------------|--------------|------------------------------------------------------------------------------------------|
105+
| organization | 111111 | Organization ID used for the generation of custom module |
106+
| bundles | | Represents whether custom module of a specific bundles have to be generated |
107+
| bundles.pci_dss | false | Generate only custom modules that are part of PCI-DSS 4.0 recommendations for GKE |
108+
| bundles.cis | false | Generate only custom modules that are part of CIS Benchmark v1.5 for GKE recommendations |
109+
110+
Example of values.yaml
111+
```
112+
organization: '11111111'
113+
bundles:
114+
pci-dss: false
115+
cis: true
116+
```
117+
118+
#### Custom Module parameters settings
119+
It might happens that some custom modules requires some parameters (e.g. allowed locations, allowed VPN projects). For those specific modules, it is expected to provide the settings in the `values.yaml` file.
120+
121+
Example of values.yaml with parameters provided for generation
122+
```
123+
organization: '11111111'
124+
bundles:
125+
pci-dss: false
126+
cis: false
127+
cloudresourcemanager:
128+
cloudresourcemanagerRequiredProjectLabels:
129+
params:
130+
labels:
131+
- "bu"
132+
- "app"
133+
- "env"
134+
cloudrun:
135+
cloudrunAllowedDomainMapping:
136+
params:
137+
domains:
138+
- "mydomain.com"
139+
- "mysite.com"
140+
cloudsql:
141+
cloudsqlAllowedDatabaseEngineVersions:
142+
params:
143+
database_versions:
144+
- "MYSQL_8_0"
145+
- "POSTGRES_17"
146+
- "SQLSERVER_2022_WEB"
147+
```
148+
149+
150+
### 2. Generate the custom modules
151+
By default, generation of custom modules require to be executed with gcloud command.
152+
Integration with Terraform is not possible for now.
153+
154+
#### Gcloud format
155+
```
156+
make build
157+
```
158+
The different configurations files are generated in the `samples/gcloud` folder.
159+
160+
161+
#### Available Commands
162+
For more precise controls on what to be generated, you can use of the following commands defined in the Makefile.
163+
164+
```
165+
make sha Build custom module for SHA using gcloud format
166+
make build Build custom module for SHA using gcloud format
167+
make deploy-sha Deploy custom module to organization level using gcloud format
168+
make deploy Build and deploy custom module based using gcloud format
169+
```
170+
171+
### 3. Provision the custom modules
172+
Once the custom module generation is done, this is possible to deploy those custom modules to the organization infrastructure.
173+
Provisionning with `gcloud` command can be done by using following commands.
174+
175+
**Provisionning the custom modules**
176+
```
177+
$ make deploy
178+
...
179+
---------------
180+
Processing file: samples/gcloud/custom-sha//artifactregistry/artifactregistryRequireCMEK.yaml (Action: sha)
181+
Checking for existing SHA Custom Module with display name 'artifactregistryRequireCMEK' under --organization=1111111111...
182+
SHA Custom Module 'organizations/1111111111/securityHealthAnalyticsSettings/customModules/1234' updated successfully from 'samples/gcloud/custom-sha//artifactregistry/artifactregistryRequireCMEK.yaml'.
183+
---------------
184+
Processing file: samples/gcloud/custom-sha//bigquery/bigqueryAllowedTableExpiration.yaml (Action: sha)
185+
Checking for existing SHA Custom Module with display name 'bigqueryAllowedTableExpiration' under --organization=741724935092...
186+
SHA Custom Module 'organizations/1111111111/securityHealthAnalyticsSettings/customModules/12345' updated successfully from 'samples/gcloud/custom-sha//bigquery/bigqueryAllowedTableExpiration.yaml'.
187+
---------------
188+
...
189+
```
190+
191+
## Developing a custom module for SHA
192+
193+
If this library doesn't contain a custom module that matches your use case, you can develop a new one using the [Adding Custom Module for Security Health Analytics Guide](./docs/adding_custom_module_sha.md).

Diff for: ‎tools/custom-module-security-health-analytics-library/build/config/config.yaml

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
#! Copyright 2024 Google LLC
2+
#!
3+
#! Licensed under the Apache License, Version 2.0 (the "License");
4+
#! you may not use this file except in compliance with the License.
5+
#! You may obtain a copy of the License at
6+
#!
7+
#! http://www.apache.org/licenses/LICENSE-2.0
8+
#!
9+
#! Unless required by applicable law or agreed to in writing, software
10+
#! distributed under the License is distributed on an "AS IS" BASIS,
11+
#! WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
#! See the License for the specific language governing permissions and
13+
#! limitations under the License.
14+
15+
#@ load("@ytt:data", "data")
16+
#@ load("@ytt:template", "template")
17+
#@ load("/config.lib.star", "generate_config")
18+
19+
organization: #@ data.values.organization
20+
bundles: #@ data.values.bundles
21+
dryrun: #@ data.values.dryrun
22+
policies:
23+
#@ template.replace(generate_config())
24+
values: #@ data.values

Diff for: ‎tools/custom-module-security-health-analytics-library/build/config/schema.yaml

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
#! Copyright 2024 Google LLC
2+
#!
3+
#! Licensed under the Apache License, Version 2.0 (the "License");
4+
#! you may not use this file except in compliance with the License.
5+
#! You may obtain a copy of the License at
6+
#!
7+
#! http://www.apache.org/licenses/LICENSE-2.0
8+
#!
9+
#! Unless required by applicable law or agreed to in writing, software
10+
#! distributed under the License is distributed on an "AS IS" BASIS,
11+
#! WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
#! See the License for the specific language governing permissions and
13+
#! limitations under the License.
14+
15+
#@data/values-schema
16+
---
17+
organization: "111111"
18+
bundles:
19+
pci-dss: false
20+
cis: false
21+
dryrun: false

Diff for: ‎tools/custom-module-security-health-analytics-library/build/config/services/schema.artifactregistry.yaml

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
#! Copyright 2024 Google LLC
2+
#!
3+
#! Licensed under the Apache License, Version 2.0 (the "License");
4+
#! you may not use this file except in compliance with the License.
5+
#! You may obtain a copy of the License at
6+
#!
7+
#! http://www.apache.org/licenses/LICENSE-2.0
8+
#!
9+
#! Unless required by applicable law or agreed to in writing, software
10+
#! distributed under the License is distributed on an "AS IS" BASIS,
11+
#! WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
#! See the License for the specific language governing permissions and
13+
#! limitations under the License.
14+
15+
#@ load("@ytt:overlay", "overlay")
16+
#@data/values-schema
17+
---
18+
#@overlay/match missing_ok=True
19+
artifactregistry:
20+
artifactregistryRequireCMEK:
21+
#@schema/validation one_of=["default", "skip", "include"]
22+
generation: "default"
23+
bundles:
24+
pci-dss: false
25+
cis: false

Diff for: ‎tools/custom-module-security-health-analytics-library/build/config/services/schema.bigquery.yaml

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
#! Copyright 2024 Google LLC
2+
#!
3+
#! Licensed under the Apache License, Version 2.0 (the "License");
4+
#! you may not use this file except in compliance with the License.
5+
#! You may obtain a copy of the License at
6+
#!
7+
#! http://www.apache.org/licenses/LICENSE-2.0
8+
#!
9+
#! Unless required by applicable law or agreed to in writing, software
10+
#! distributed under the License is distributed on an "AS IS" BASIS,
11+
#! WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
#! See the License for the specific language governing permissions and
13+
#! limitations under the License.
14+
15+
#@ load("@ytt:overlay", "overlay")
16+
#@data/values-schema
17+
---
18+
#@overlay/match missing_ok=True
19+
bigquery:
20+
bigqueryAllowedTableExpiration:
21+
#@schema/validation one_of=["default", "skip", "include"]
22+
generation: "default"
23+
bundles:
24+
pci-dss: false
25+
cis: false
26+
params:
27+
#@schema/validation min=1
28+
max_table_expiration_ms: 0

0 commit comments

Comments
 (0)