diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml index 114cfd054ac..ee2cffd158d 100644 --- a/.pre-commit-hooks.yaml +++ b/.pre-commit-hooks.yaml @@ -14,17 +14,48 @@ exclude: \.+.terraform\/.*$ require_serial: true +- id: checkov_container + name: Checkov + description: This hook runs checkov. + entry: --tty bridgecrew/checkov:latest -d . + args: [] + language: docker_image + pass_filenames: false + always_run: false + files: \.tf$ + exclude: \.+.terraform\/.*$ + require_serial: true + - id: checkov_diff name: Checkov Diff description: This hook runs checkov against all changed files. - entry: checkov --enable-secret-scan-all-files -f + entry: checkov --enable-secret-scan-all-files + args: ["-f"] # required and must come last language: python require_serial: true +- id: checkov_diff_container + name: Checkov Diff + description: This hook runs checkov against all changed files. + entry: --tty bridgecrew/checkov:latest --enable-secret-scan-all-files + args: ["-f"] # required and must come last + language: docker_image + require_serial: true + - id: checkov_secrets name: Checkov Secrets description: This hook looks for secrets with checkov. - entry: checkov --framework secrets --enable-secret-scan-all-files -f + entry: checkov --framework secrets --enable-secret-scan-all-files + args: ["-f"] # required and must come last language: python always_run: true require_serial: true + +- id: checkov_secrets_container + name: Checkov Secrets + description: This hook looks for secrets with checkov. + entry: --tty bridgecrew/checkov:latest --framework secrets --enable-secret-scan-all-files + args: ["-f"] # required and must come last + language: docker_image + always_run: true + require_serial: true diff --git a/README.md b/README.md index 688acef8351..f1433a1446e 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,8 @@ [![Maintained by Prisma Cloud](https://img.shields.io/badge/maintained_by-Prisma_Cloud-blue)](https://prismacloud.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)](#) @@ -11,7 +11,7 @@ [![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://codifiedsecurity.slack.com/) - + **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. @@ -120,11 +120,14 @@ 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. 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" FAILED for resource: aws_s3_bucket.customer @@ -134,7 +137,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 @@ -163,10 +166,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. @@ -184,18 +187,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 ``` @@ -240,7 +243,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 @@ -284,7 +287,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: @@ -298,8 +301,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 @@ -335,7 +338,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. @@ -344,11 +347,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#: =` -For example: +For example: ```bash apiVersion: v1 @@ -366,7 +369,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`. @@ -415,11 +418,11 @@ 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 output: cli @@ -454,9 +457,10 @@ Defaults: --external-modules-download-path:.external_modules --evaluate-variables:True ``` + ## 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). diff --git a/docs/4.Integrations/pre-commit.md b/docs/4.Integrations/pre-commit.md index d0e074c4178..69a22c9f374 100644 --- a/docs/4.Integrations/pre-commit.md +++ b/docs/4.Integrations/pre-commit.md @@ -7,17 +7,41 @@ nav_order: 6 # Pre-Commit -To use Checkov with [pre-commit](https://pre-commit.com), just add the following to your local repo's `.pre-commit-config.yaml` file: +If you want to automatically run `checkov` 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: '' # change to tag or sha hooks: - id: checkov + # - id: checkov_container + # - id: checkov_diff + # - id: checkov_diff_container + # - id: checkov_secrets + # - id: checkov_secrets_container ``` Make sure to change `rev:` to be either a git commit sha or tag of checkov containing `.pre-commit-hooks.yaml`. Note that local environment variables will apply when using pre-commit hooks. In urgent situations, pre-commit hooks can be skipped with the `--no-verify` flag. +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 +``` + ## Adding Custom Parameters By default, the Checkov pre-commit hook runs when there are changes to `.tf` files. This can be modified by overriding the file parameter: @@ -70,6 +94,21 @@ repos: entry: checkov -d . --skip-check CKV_AWS_123 ``` +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 +``` + +By default, the container based pre-commit hooks use the `latest` tag. This can be overridden by declaring the version number in the entry field in the pre-commit config. + +```yaml + hooks: + - id: checkov_container + entry: bridgecrew/checkov:2.4.2 -d . ## Diff scanning pre-commit hook To let `checkov` only scan the changed files choose the `checkov_diff` hook, which scans against all frameworks: @@ -80,6 +119,7 @@ repos: rev: '' # change to tag or sha hooks: - id: checkov_diff + # - id: checkov_diff_container ``` if you want to customize this hook, you need to override the `entry` field, because the file flag `-f` has to be at the end: @@ -103,4 +143,5 @@ repos: rev: '' # change to tag or sha hooks: - id: checkov_secrets + # - id: checkov_secrets_container ```