Update documentation to include pre-commit hooks

bridgecrewio · Oct 16, 2023 · 2a37ec6 · 2a37ec6
1 parent 81d470f
commit 2a37ec6
Showing 1 changed file with 94 additions and 42 deletions.
diff --git a/README.md b/README.md
@@ -1,25 +1,25 @@
 [![checkov](https://raw.githubusercontent.com/bridgecrewio/checkov/main/docs/web/images/checkov_by_bridgecrew.png)](#)
-       
+
 [![Maintained by Bridgecrew.io](https://img.shields.io/badge/maintained%20by-bridgecrew.io-blueviolet)](https://bridgecrew.io/?utm_source=github&utm_medium=organic_oss&utm_campaign=checkov)
 [![build status](https://github.com/bridgecrewio/checkov/workflows/build/badge.svg)](https://github.com/bridgecrewio/checkov/actions?query=workflow%3Abuild)
-[![security status](https://github.com/bridgecrewio/checkov/workflows/security/badge.svg)](https://github.com/bridgecrewio/checkov/actions?query=event%3Apush+branch%3Amaster+workflow%3Asecurity) 
-[![code_coverage](https://raw.githubusercontent.com/bridgecrewio/checkov/main/coverage.svg?sanitize=true)](https://github.com/bridgecrewio/checkov/actions?query=workflow%3Acoverage) 
+[![security status](https://github.com/bridgecrewio/checkov/workflows/security/badge.svg)](https://github.com/bridgecrewio/checkov/actions?query=event%3Apush+branch%3Amaster+workflow%3Asecurity)
+[![code_coverage](https://raw.githubusercontent.com/bridgecrewio/checkov/main/coverage.svg?sanitize=true)](https://github.com/bridgecrewio/checkov/actions?query=workflow%3Acoverage)
 [![docs](https://img.shields.io/badge/docs-passing-brightgreen)](https://www.checkov.io/1.Welcome/What%20is%20Checkov.html?utm_source=github&utm_medium=organic_oss&utm_campaign=checkov)
 [![PyPI](https://img.shields.io/pypi/v/checkov)](https://pypi.org/project/checkov/)
 [![Python Version](https://img.shields.io/pypi/pyversions/checkov)](#)
 [![Terraform Version](https://img.shields.io/badge/tf-%3E%3D0.12.0-blue.svg)](#)
 [![Downloads](https://static.pepy.tech/badge/checkov)](https://pepy.tech/project/checkov)
 [![Docker Pulls](https://img.shields.io/docker/pulls/bridgecrew/checkov.svg)](https://hub.docker.com/r/bridgecrew/checkov)
 [![slack-community](https://img.shields.io/badge/Slack-4A154B?style=plastic&logo=slack&logoColor=white)](https://slack.bridgecrew.io/)
- 
+
 
 **Checkov** is a static code analysis tool for infrastructure as code (IaC) and also a software composition analysis (SCA) tool for images and open source packages.
 
 It scans cloud infrastructure provisioned using [Terraform](https://terraform.io/), [Terraform plan](docs/7.Scan%20Examples/Terraform%20Plan%20Scanning.md), [Cloudformation](docs/7.Scan%20Examples/Cloudformation.md), [AWS SAM](docs/7.Scan%20Examples/AWS%20SAM.md), [Kubernetes](docs/7.Scan%20Examples/Kubernetes.md), [Helm charts](docs/7.Scan%20Examples/Helm.md), [Kustomize](docs/7.Scan%20Examples/Kustomize.md), [Dockerfile](docs/7.Scan%20Examples/Dockerfile.md),  [Serverless](docs/7.Scan%20Examples/Serverless%20Framework.md), [Bicep](docs/7.Scan%20Examples/Bicep.md), [OpenAPI](docs/7.Scan%20Examples/OpenAPI.md) or [ARM Templates](docs/7.Scan%20Examples/Azure%20ARM%20templates.md) and detects security and compliance misconfigurations using graph-based scanning.
 
 It performs [Software Composition Analysis (SCA) scanning](docs/7.Scan%20Examples/Sca.md) which is a scan of open source packages and images for Common Vulnerabilities and Exposures (CVEs).
- 
-Checkov also powers [**Bridgecrew**](https://bridgecrew.io/?utm_source=github&utm_medium=organic_oss&utm_campaign=checkov), the developer-first platform that codifies and streamlines cloud security throughout the development lifecycle. Bridgecrew identifies, fixes, and prevents misconfigurations in cloud resources and infrastructure-as-code files. 
+
+Checkov also powers [**Bridgecrew**](https://bridgecrew.io/?utm_source=github&utm_medium=organic_oss&utm_campaign=checkov), the developer-first platform that codifies and streamlines cloud security throughout the development lifecycle. Bridgecrew identifies, fixes, and prevents misconfigurations in cloud resources and infrastructure-as-code files.
 
 <a href="https://www.bridgecrew.cloud/login/signUp/?utm_campaign=checkov-github-repo&utm_source=github.com&utm_medium=get-started-button" title="Try_Bridgecrew">
     <img src="https://dabuttonfactory.com/button.png?t=Try+Bridgecrew&f=Open+Sans-Bold&ts=26&tc=fff&hp=45&vp=20&c=round&bgt=unicolored&bgc=662eff" align="right" width="120">
@@ -51,7 +51,7 @@ Checkov also powers [**Bridgecrew**](https://bridgecrew.io/?utm_source=github&ut
  * Policies support evaluation of [variables](docs/2.Basics/Handling%20Variables.md) to their optional default value.
  * Supports in-line [suppression](docs/2.Basics/Suppressing%20and%20Skipping%20Policies.md) of accepted risks or false-positives to reduce recurring scan failures. Also supports global skip from using CLI.
  * [Output](docs/2.Basics/Reviewing%20Scan%20Results.md) currently available as CLI, [CycloneDX](https://cyclonedx.org), JSON, JUnit XML, CSV, SARIF and github markdown and link to remediation [guides](https://docs.bridgecrew.io/docs/aws-policy-index).
- 
+
 ## Screenshots
 
 Scan results in CLI
@@ -119,10 +119,10 @@ Or a terraform plan file in json format
 ```sh
 terraform init
 terraform plan -out tf.plan
-terraform show -json tf.plan  > tf.json 
+terraform show -json tf.plan  > tf.json
 checkov -f tf.json
 ```
-Note: `terraform show` output file `tf.json` will be a single line. 
+Note: `terraform show` output file `tf.json` will be a single line.
 For that reason all findings will be reported line number 0 by checkov
 ```sh
 check: CKV_AWS_21: "Ensure all data stored in the S3 bucket have versioning enabled"
@@ -133,7 +133,7 @@ check: CKV_AWS_21: "Ensure all data stored in the S3 bucket have versioning enab
 
 If you have installed `jq` you can convert json file into multiple lines with the following command:
 ```sh
-terraform show -json tf.plan | jq '.' > tf.json 
+terraform show -json tf.plan | jq '.' > tf.json
 ```
 Scan result would be much user friendly.
 ```sh
@@ -162,10 +162,10 @@ checkov -f tf.json --repo-root-for-plan-enrichment /user/path/to/iac/code
 Passed Checks: 1, Failed Checks: 1, Suppressed Checks: 0
 Check: "Ensure all data stored in the S3 bucket is securely encrypted at rest"
 /main.tf:
-	 Passed for resource: aws_s3_bucket.template_bucket 
+	 Passed for resource: aws_s3_bucket.template_bucket
 Check: "Ensure all data stored in the S3 bucket is securely encrypted at rest"
 /../regionStack/main.tf:
-	 Failed for resource: aws_s3_bucket.sls_deployment_bucket_name       
+	 Failed for resource: aws_s3_bucket.sls_deployment_bucket_name
 ```
 
 Start using Checkov by reading the [Getting Started](docs/1.Welcome/Quick%20Start.md) page.
@@ -183,18 +183,18 @@ Note that there are certain cases where redirecting `docker run --tty` output to
 
 The `--workdir /tf` flag is optional to change the working directory to the mounted volume. If you are using the SARIF output `-o sarif` this will output the results.sarif file to the mounted volume (`/user/tf` in the example above). If you do not include that flag, the working directory will be "/".
 
-### Running or skipping checks 
+### Running or skipping checks
 
-By using command line flags, you can specify to run only named checks (allow list) or run all checks except 
+By using command line flags, you can specify to run only named checks (allow list) or run all checks except
 those listed (deny list). If you are using the platform integration via API key, you can also specify a severity threshold to skip and / or include.
 Moreover, as json files can't contain comments, one can pass regex pattern to skip json file secret scan.
 
 See the docs for more detailed information about how these flags work together.
-   
+
 
 ## Examples
 
-Allow only the two specified checks to run: 
+Allow only the two specified checks to run:
 ```sh
 checkov --directory . --check CKV_AWS_20,CKV_AWS_57
 ```
@@ -239,7 +239,7 @@ Run check CKV_789, but skip it if it is a medium severity (the --check logic is
 checkov -d . --skip-check MEDIUM --check CKV_789 --bc-api-key ...
 ```
 
-For Kubernetes workloads, you can also use allow/deny namespaces.  For example, do not report any results for the 
+For Kubernetes workloads, you can also use allow/deny namespaces.  For example, do not report any results for the
 kube-system namespace:
 ```sh
 checkov -d . --skip-check kube-system
@@ -283,7 +283,7 @@ checkov -d /MyDirectory --framework secrets --bc-api-key ... --skip-check CKV_SE
 ```
 
 One can mask values from scanning results by supplying a configuration file (using --config-file flag) with mask entry.
-The masking can apply on resource & value (or multiple values, seperated with a comma). 
+The masking can apply on resource & value (or multiple values, seperated with a comma).
 Examples:
 ```sh
 mask:
@@ -297,8 +297,8 @@ In the example above, the following values will be masked:
 
 ### Suppressing/Ignoring a check
 
-Like any static-analysis tool it is limited by its analysis scope. 
-For example, if a resource is managed manually, or using subsequent configuration management tooling, 
+Like any static-analysis tool it is limited by its analysis scope.
+For example, if a resource is managed manually, or using subsequent configuration management tooling,
 suppression can be inserted as a simple code annotation.
 
 #### Suppression comment format
@@ -334,7 +334,7 @@ Check: "S3 Bucket has an ACL defined which allows public access."
 	SKIPPED for resource: aws_s3_bucket.foo-bucket
 	Suppress comment: The bucket is a public static content host
 	File: /example_skip_acl.tf:1-25
-	
+
 ...
 ```
 To skip multiple checks, add each as a new line.
@@ -343,11 +343,11 @@ To skip multiple checks, add each as a new line.
   #checkov:skip=CKV2_AWS_6
   #checkov:skip=CKV_AWS_20:The bucket is a public static content host
 ```
-  
+
 To suppress checks in Kubernetes manifests, annotations are used with the following format:
 `checkov.io/skip#: <check_id>=<suppression_comment>`
 
-For example: 
+For example:
 
 ```bash
 apiVersion: v1
@@ -365,7 +365,7 @@ spec:
 
 #### Logging
 
-For detailed logging to stdout set up the environment variable `LOG_LEVEL` to `DEBUG`. 
+For detailed logging to stdout set up the environment variable `LOG_LEVEL` to `DEBUG`.
 
 Default is `LOG_LEVEL=WARNING`.
 
@@ -414,25 +414,25 @@ directory:
   - test-dir
 docker-image: sample-image
 dockerfile-path: Dockerfile
-download-external-modules: true 
-evaluate-variables: true 
-external-checks-dir: 
-  - sample-dir 
-external-modules-download-path: .external_modules 
+download-external-modules: true
+evaluate-variables: true
+external-checks-dir:
+  - sample-dir
+external-modules-download-path: .external_modules
 framework:
-  - all 
-no-guide: true 
-output: cli 
-quiet: true 
-repo-id: bridgecrew/sample-repo 
-skip-check: 
-  - CKV_DOCKER_3 
-  - CKV_DOCKER_2 
-skip-fixes: true 
+  - all
+no-guide: true
+output: cli
+quiet: true
+repo-id: bridgecrew/sample-repo
+skip-check:
+  - CKV_DOCKER_3
+  - CKV_DOCKER_2
+skip-fixes: true
 skip-framework:
   - dockerfile
   - secrets
-skip-suppressions: true 
+skip-suppressions: true
 soft-fail: true
 ```
 
@@ -456,9 +456,61 @@ Defaults:
   --external-modules-download-path:.external_modules
   --evaluate-variables:True
 ```
+
+### Pre-commit hook
+
+If you want to automatically run `checkov` tasks when files in your git repo change, [install the pre-commit binary](https://pre-commit.com/#install), and add a [.pre-commit-config.yaml file](./.pre-commit-config.yaml) to your project with content similar to the example below.
+
+Note that depending on the hook id you select for pre-commit hooks, you may need to provide the following:
+
+* For the `python` hooks, pre-commit 3.x is able to provide [python](https://pre-commit.com/#python) without additional dependencies.
+* For the `container` hooks, the [Docker](https://docs.docker.com/get-docker/) CLI and a container runtime must be available.
+
+```yaml
+  - repo: https://github.com/bridgecrewio/checkov.git
+    rev: '2.4.2'
+    hooks:
+      - id: checkov
+      # - id: checkov_container
+      # - id: checkov_diff
+      # - id: checkov_diff_container
+      # - id: checkov_secrets
+      # - id: checkov_secrets_container
+```
+
+To pass arguments to `checkov` use the following examples as a guide:
+
+```yaml
+      - id: checkov
+        args:
+          - '--quiet'
+```
+
+When using the `diff` or `secrets` hooks, the last argument _must_ be `-f` due to how `checkov` and `pre-commit` interact:
+
+```yaml
+      - id: checkov_secrets_container
+        args:
+          - '--quiet'
+          - '-f' # required and must come last
+```
+
+After adding the hooks to `.pre-commit-config.yaml` run the following command(s):
+
+```bash
+pre-commit install --install-hooks
+```
+
+or
+
+```bash
+pre-commit install
+pre-commit install-hooks
+```
+
 ## Contributing
 
-Contribution is welcomed! 
+Contribution is welcomed!
 
 Start by reviewing the [contribution guidelines](CONTRIBUTING.md). After that, take a look at a [good first issue](https://github.com/bridgecrewio/checkov/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
 
@@ -469,14 +521,14 @@ You can even start this with one-click dev in your browser through Gitpod at the
 Looking to contribute new checks? Learn how to write a new check (AKA policy) [here](docs/6.Contribution/Contribution%20Overview.md).
 
 ## Disclaimer
-`checkov` does not save, publish or share with anyone any identifiable customer information.  
+`checkov` does not save, publish or share with anyone any identifiable customer information.
 No identifiable customer information is used to query Bridgecrew's publicly accessible guides.
 `checkov` uses Bridgecrew's API to enrich the results with links to remediation guides.
 To skip this API call use the flag `--no-guide`.
 
 ## Support
 
-[Bridgecrew](https://bridgecrew.io/?utm_source=github&utm_medium=organic_oss&utm_campaign=checkov) builds and maintains Checkov to make policy-as-code simple and accessible. 
+[Bridgecrew](https://bridgecrew.io/?utm_source=github&utm_medium=organic_oss&utm_campaign=checkov) builds and maintains Checkov to make policy-as-code simple and accessible.
 
 Start with our [Documentation](https://bridgecrewio.github.io/checkov/) for quick tutorials and examples.