Added directions for Heimdall Lite (#59)

* 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 <lippold@gmail.com>

Author: aaronlippold

README.md

@@ -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)
 
@@ -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
@@ -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

inspec.yml

@@ -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: copyright@google.com
-license: Apache-2.0
+title: "InSpec GCP CIS 1.1 Benchmark"
+maintainer: "Google Cloud Platform"
+copyright: "(c) 2020, Google, Inc."
+copyright_email: "copyright@google.com"
+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:
+      - ""

walkthrough.md

@@ -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:
 
@@ -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.
 
@@ -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
 ```
@@ -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.