Skip to content

Commit

Permalink
Added directions for Heimdall Lite (#59)
Browse files Browse the repository at this point in the history
* added directions to README and Walkthough to create a json result and looad into Heimdall Lite
* added default dummy value for the project_id
* fixed indent issues in inspec.yml
* fixed markdown syntax in README
Signed-off-by: Aaron Lippold <[email protected]>
  • Loading branch information
aaronlippold authored Oct 14, 2020
1 parent 059e1ff commit a9134fc
Show file tree
Hide file tree
Showing 3 changed files with 170 additions and 118 deletions.
151 changes: 85 additions & 66 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,27 +10,41 @@ This is not an officially supported Google product. This code is intended to hel

The following GCP CIS v1.1.0 Benchmark Controls are not covered:

* Identity and Access Management 1.2 - "Ensure that multi-factor authentication is enabled for all non-service accounts"
* Identity and Access Management 1.3 - "Ensure that Security Key Enforcement is enabled for all admin accounts"
* Identity and Access Management 1.12 - "Ensure API keys are not created for a project"
* Identity and Access Management 1.13 - "Ensure API keys are restricted to use by only specified Hosts and Apps"
* Identity and Access Management 1.14 - "Ensure API keys are restricted to only APIs that application needs access"
* Identity and Access Management 1.15 - "Ensure API keys are rotated every 90 days"
* Cloud SQL Database Services 6.3 - "Ensure that MySql database instance does not allow anyone to connect with administrative privileges"
* Cloud SQL Database Services 6.4 - "Ensure that MySQL Database Instance does not allows root login from any Host"
- Identity and Access Management 1.2 - "Ensure that multi-factor authentication is enabled for all non-service accounts"
- Identity and Access Management 1.3 - "Ensure that Security Key Enforcement is enabled for all admin accounts"
- Identity and Access Management 1.12 - "Ensure API keys are not created for a project"
- Identity and Access Management 1.13 - "Ensure API keys are restricted to use by only specified Hosts and Apps"
- Identity and Access Management 1.14 - "Ensure API keys are restricted to only APIs that application needs access"
- Identity and Access Management 1.15 - "Ensure API keys are rotated every 90 days"
- Cloud SQL Database Services 6.3 - "Ensure that MySql database instance does not allow anyone to connect with administrative privileges"
- Cloud SQL Database Services 6.4 - "Ensure that MySQL Database Instance does not allows root login from any Host"

## Usage

### Profile Attributes
### Profile Inputs (see `inspec.yml` file)

* **gcp_project_id** - (Default: "", type: string) - The target GCP Project that must be specified.
* **sa_key_older_than_seconds** - (Default: 7776000, type: int, CIS IAM 1.15) - The maximum allowed age of GCP User-managed Service Account Keys (90 days in seconds).
* **kms_rotation_period_seconds** - (Default: 7776000, type: int, CIS IAM 1.10) - The maximum allowed age of KMS keys (90 days in seconds).
This profile uses InSpec Inputs to make the tests more flexible. You are able to provide inputs at runtime either via the `cli` or via `YAML files` to help the profile work best in your deployment.

**pro tip**: Do not change the inputs in the `inspec.yml` file directly, either:

- update them via the cli - via the `--input` flag
- pass them in via a YAML file as shown in the `Example` - via the `--input-file` flag

Further details can be found here: <https://docs.chef.io/inspec/inputs/>

### (Required) User Provided Inputs - via the CLI or Input Files

- **gcp_project_id** - (Default: null, type: String) - The target GCP Project you are scanning.

### (Optional) User Provided Inputs

- **bucket_logging_ignore_regex** - (type: String) - Ignore this bucket by regex from requiring logging to be enabled. Example: `-logging`
- **sa_key_older_than_seconds** - (Default: 7776000, type: int, CIS IAM 1.15) - The maximum allowed age of GCP User-managed Service Account Keys (90 days in seconds).
- **kms_rotation_period_seconds** - (Default: 7776000, type: int, CIS IAM 1.10) - The maximum allowed age of KMS keys (90 days in seconds).

### Cloud Shell Walkthrough

Use this Cloud Shell walkthrough for a hands-on example.
Use this Cloud Shell Walkthrough for a hands-on example.

[![Open this project in Cloud Shell](http://gstatic.com/cloudssh/images/open-btn.png)](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/inspec-gcp-cis-benchmark&page=editor&tutorial=walkthrough.md)

Expand All @@ -51,8 +65,8 @@ $ gcloud auth application-default login
```

```
# scan a project with this profile, replace <YOUR_PROJECT_ID> with your project ID
$ inspec exec https://github.com/GoogleCloudPlatform/inspec-gcp-cis-benchmark.git -t gcp:// --input gcp_project_id=<YOUR_PROJECT_ID>
# scan a project with this profile, replace {{project-id}} with your project ID
$ inspec exec https://github.com/GoogleCloudPlatform/inspec-gcp-cis-benchmark.git -t gcp:// --input gcp_project_id={{project-id}} --reporter cli json:{{project-id}}_scan.json
...snip...
Profile Summary: 48 successful controls, 5 control failures, 7 controls skipped
Test Summary: 166 successful, 7 failures, 7 skipped
Expand All @@ -61,62 +75,67 @@ Test Summary: 166 successful, 7 failures, 7 skipped
### Required APIs

Consider these GCP projects, which may all be the same or different:
* the project of the Service Account that's used to authenticate the scan
* the project from which the benchmark is called
* the project to be scanned

- the project of the Service Account that's used to authenticate the scan
- the project from which the benchmark is called
- the project to be scanned

The following GCP APIs should be enabled in **all** of these projects:
* cloudkms.googleapis.com
* cloudresourcemanager.googleapis.com
* compute.googleapis.com
* dns.googleapis.com
* iam.googleapis.com
* logging.googleapis.com
* monitoring.googleapis.com
* sqladmin.googleapis.com
* storage-api.googleapis.com


- cloudkms.googleapis.com
- cloudresourcemanager.googleapis.com
- compute.googleapis.com
- dns.googleapis.com
- iam.googleapis.com
- logging.googleapis.com
- monitoring.googleapis.com
- sqladmin.googleapis.com
- storage-api.googleapis.com

### Required Permissions

The following permissions are required to run the CIS benchmark profile:

On organization level:
* resourcemanager.organizations.get
* resourcemanager.projects.get
* resourcemanager.projects.getIamPolicy
* resourcemanager.folders.get

- resourcemanager.organizations.get
- resourcemanager.projects.get
- resourcemanager.projects.getIamPolicy
- resourcemanager.folders.get

On project level:
* cloudkms.cryptoKeys.get
* cloudkms.cryptoKeys.getIamPolicy
* cloudkms.cryptoKeys.list
* cloudkms.keyRings.list
* cloudsql.instances.get
* cloudsql.instances.list
* compute.firewalls.get
* compute.firewalls.list
* compute.instances.get
* compute.instances.list
* compute.networks.get
* compute.networks.list
* compute.projects.get
* compute.regions.list
* compute.sslPolicies.get
* compute.sslPolicies.list
* compute.subnetworks.get
* compute.subnetworks.list
* compute.targetHttpsProxies.get
* compute.targetHttpsProxies.list
* compute.zones.list
* dns.managedZones.get
* dns.managedZones.list
* iam.serviceAccountKeys.list
* iam.serviceAccounts.list
* logging.logMetrics.list
* logging.sinks.get
* logging.sinks.list
* monitoring.alertPolicies.list
* resourcemanager.projects.get
* resourcemanager.projects.getIamPolicy
* storage.buckets.get
* storage.buckets.getIamPolicy
* storage.buckets.list

- cloudkms.cryptoKeys.get
- cloudkms.cryptoKeys.getIamPolicy
- cloudkms.cryptoKeys.list
- cloudkms.keyRings.list
- cloudsql.instances.get
- cloudsql.instances.list
- compute.firewalls.get
- compute.firewalls.list
- compute.instances.get
- compute.instances.list
- compute.networks.get
- compute.networks.list
- compute.projects.get
- compute.regions.list
- compute.sslPolicies.get
- compute.sslPolicies.list
- compute.subnetworks.get
- compute.subnetworks.list
- compute.targetHttpsProxies.get
- compute.targetHttpsProxies.list
- compute.zones.list
- dns.managedZones.get
- dns.managedZones.list
- iam.serviceAccountKeys.list
- iam.serviceAccounts.list
- logging.logMetrics.list
- logging.sinks.get
- logging.sinks.list
- monitoring.alertPolicies.list
- resourcemanager.projects.get
- resourcemanager.projects.getIamPolicy
- storage.buckets.get
- storage.buckets.getIamPolicy
- storage.buckets.list
97 changes: 55 additions & 42 deletions inspec.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,51 +13,64 @@
# limitations under the License.

name: inspec-gcp-cis-benchmark
title: "Inspec GCP CIS 1.1 Benchmark"
maintainer:
copyright: Google
copyright_email: [email protected]
license: Apache-2.0
title: "InSpec GCP CIS 1.1 Benchmark"
maintainer: "Google Cloud Platform"
copyright: "(c) 2020, Google, Inc."
copyright_email: "[email protected]"
license: "Apache-2.0"
summary: "Inspec Google Cloud Platform Center for Internet Security Benchmark v1.1 Profile"
version: "1.1.0-19"
version: 1.1.0-19

supports:
- platform: gcp

depends:
- name: inspec-gcp-helpers
url: https://github.com/GoogleCloudPlatform/inspec-gcp-helpers/archive/v1.0.7.tar.gz
- name: inspec-gcp-helpers
url: https://github.com/GoogleCloudPlatform/inspec-gcp-helpers/archive/v1.0.7.tar.gz

inputs:
- name: gcp_project_id
description: 'The GCP project identifier.'
type: string
value: "replace_with_your_gcp_project_id"
- name: cis_version
description: 'The short version of the GCP CIS Benchmark'
value: '1.0'
type: string
- name: cis_url
description: 'The URL to the GCP CIS Benchmark'
value: 'https://www.cisecurity.org/benchmark/google_cloud_computing_platform/'
type: string
- name: sa_key_older_than_seconds
description: 'How many seconds SA keys should not be older than'
value: 7776000
type: numeric
- name: kms_rotation_period_seconds
description: 'How many seconds KMS Keys should be last rotated (90 days)'
value: 7776000
type: numeric
- name: bucket_logging_ignore_regex
description: 'Ignore this bucket by regex from requiring logging to be enabled'
# {{gcp_project_id}} and {{bucket_logging_ignore_regex}}
# must be defined at runtime by the user
- name: gcp_project_id
description: "The GCP project identifier."
type: String
required: true
value: 'aaa-bbb-ccc-ddd'

# example = "-logging"
value: "replace-with-bucket-name-or-partial-match"
type: string
- name: gcp_gke_locations
description: 'The list of regions and/or zone names where GKE clusters are running. An empty array searches all locations'
type: array
value:
- ""
- name: gce_zones
description: 'The list of zone names where GCE instances are running. An empty array searches all locations'
type: array
value:
- ""
# "replace-with-bucket-name-or-partial-match"
- name: bucket_logging_ignore_regex
description: "Ignore this bucket by regex from requiring logging to be enabled"
type: String
required: false

- name: cis_version
description: "The short version of the GCP CIS Benchmark"
value: "1.0"
type: String

- name: cis_url
description: "The URL to the GCP CIS Benchmark"
value: "https://www.cisecurity.org/benchmark/google_cloud_computing_platform/"
type: String

- name: sa_key_older_than_seconds
description: "How many seconds SA keys should not be older than"
value: 7776000
type: Numeric

- name: kms_rotation_period_seconds
description: "How many seconds KMS Keys should be last rotated (90 days)"
value: 7776000
type: Numeric

- name: gcp_gke_locations
description: "The list of regions and/or zone names where GKE clusters are running. An empty array searches all locations"
type: Array
value:
- ""
- name: gce_zones
description: "The list of zone names where GCE instances are running. An empty array searches all locations"
type: Array
value:
- ""
40 changes: 30 additions & 10 deletions walkthrough.md
Original file line number Diff line number Diff line change
@@ -1,29 +1,27 @@
# Introduction to Running InSpec in Cloud Shell


## Let's get started!
## Getting Started

This guide will show you how to install InSpec on your Cloud Shell instance and how to use InSpec to check the infrastructure in your Google Cloud Project against the CIS GCP Benchmark.

**Time to complete**: About 5 minutes

Click the **Start** button to move to the next step.


## What is InSpec?

Before we jump in, let's briefly go over what InSpec can do.

[InSpec](https://github.com/inspec/inspec), a popular framework in the DevSecOps community, checks the configuration state of resources within virtual machines, containers, and cloud providers such as GCP, AWS, and Azure. InSpec's lightweight nature, approachable domain specific Language (DSL) and extensibility, make it a valuable tool for:

- Expressing compliance policies as code
- Enabling development teams to add application-specific tests and assess the compliance of their applications to security policies before pushing changes to the production environment.
- Automating compliance verification in CI/CD pipelines and as part of the release process
- Unifying compliance assessments across multiple cloud providers and on premises environments

Continue on to the next step to start setting up your tutorial.


## Install InSpec
## Installing InSpec

InSpec is distributed as a Ruby gem and your Cloud Shell instance has a Ruby environment already configured. All you need to do is install the InSpec gem:

Expand All @@ -35,7 +33,7 @@ gem install inspec-bin --no-document --quiet

Next, you’ll select a Google Cloud Project to scan with InSpec.

## Select a Google Cloud Project to scan
## Select the Google Cloud Project to scan

Pick a project where you have sufficient permissions. We'll use your user credentials in Cloud Shell to scan the project.

Expand All @@ -45,20 +43,19 @@ The project you selected is **{{project-id}}**. If this is blank, make sure you

Hit Next after you successfully selected your project.


## Scan Your Project

To scan your project against the CIS GCP Benchmark with InSpec, run:

```bash
CHEF_LICENSE=accept-no-persist inspec exec https://github.com/GoogleCloudPlatform/inspec-gcp-cis-benchmark.git -t gcp:// --input gcp_project_id={{project-id}}
CHEF_LICENSE=accept-no-persist inspec exec https://github.com/GoogleCloudPlatform/inspec-gcp-cis-benchmark.git -t gcp:// --input gcp_project_id={{project-id}} --reporter cli json:{{project-id}}_scan.json
```

This should take about two minutes to complete.

Once complete, your terminal output should look something like this:

```
```bash
Profile Summary: 14 successful controls, 34 control failures, 7 controls skipped
Test Summary: 107 successful, 88 failures, 7 skipped
```
Expand All @@ -69,10 +66,33 @@ To scan another project, press the Previous button and select a different projec

Press Next if you're done scanning projects.

## Review your scan results with [Heimdall-Lite](https://heimdall-lite.mitre.org)

### What is Heimdall-Lite?

Heimdall-Lite is a great open-source Security Results Viewer by the [MITRE Corporation](https://www.mitre.org) for reviewing your GCP CIS Benchmark scan results.

Heimdall-Lite is one of many MITRE [Security Automation Framework](https://saf.mitre.org) (SAF) Supporting Tools working to enhance the Security Automation and DevSecOps communities.

The [MITRE SAF](https://saf.mitre.org) is an open-source community partnership including Government, Industry and the Open Community working together to make truly automated security a reality. It also hosts many InSpec profiles created by the SAF and references to many partner developed profiles - **_including this one_**.

**Tip**: MITRE hosts Heimdall-Lite on GitHub pages, but you can easily run it in your environment via Docker or NPM or whatever suites your need. See the projects GitHub more information.

### Download your JSON formatted results

1. Right click on your `myscan.json` file
2. Then select `Download` to save the `{{project-id}}_scan.json` file locally

### Go to Heimdall Lite and Load your JSON formatted Results

1. Navigate to [Heimdall Lite](https://heimdall-lite.mitre.org)
2. Click `Local Files` on the left side of the loader
3. Drag and Drop or select and load your `{{project-id}}_scan.json` file to review your results.

## Congratulations

<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>

You’re all set!

You can now scan your Google Cloud Projects with InSpec directly from Cloud Shell.
You can now scan your Google Cloud Projects with InSpec directly from Cloud Shell.

0 comments on commit a9134fc

Please sign in to comment.