From 9435de1f9330ddb955782da8258ec623a22d33e4 Mon Sep 17 00:00:00 2001 From: Clemens Wolff Date: Mon, 28 Oct 2019 13:29:07 -0400 Subject: [PATCH 1/2] Add section about credential scanning --- TECH-LEADS-CHECKLIST.md | 2 +- continuous-integration/credential-scanning/README.md | 7 +++++++ 2 files changed, 8 insertions(+), 1 deletion(-) create mode 100644 continuous-integration/credential-scanning/README.md diff --git a/TECH-LEADS-CHECKLIST.md b/TECH-LEADS-CHECKLIST.md index 43f5cfb7e5..19b17b0b60 100644 --- a/TECH-LEADS-CHECKLIST.md +++ b/TECH-LEADS-CHECKLIST.md @@ -7,7 +7,7 @@ This checklist helps to ensure that our projects meet our Engineering Fundamenta - [ ] Merges are done through PRs. - [ ] PRs reference related work items. - [ ] Commit history is consistent and commit messages are informative (what, why). -- [ ] Secrets are not part of the commit history or made public. +- [ ] Secrets are not part of the commit history or made public. (see [Credential scanning](./continuous-integration/credential-scanning/README.md)) - [ ] Public repositories follow the [OSS guidelines](source-control/git.md#Required files in default branch for public repositories ). diff --git a/continuous-integration/credential-scanning/README.md b/continuous-integration/credential-scanning/README.md new file mode 100644 index 0000000000..69d7f81601 --- /dev/null +++ b/continuous-integration/credential-scanning/README.md @@ -0,0 +1,7 @@ +## Credential scanning + +Credential scanning is the engineering practice of automatically inspecting a project to ensure that no secrets are included in the project's source code. Secrets include database passwords, storage connection strings, admin logins, service principals, etc. See also [Secrets management](../../continuous-deployment/secrets-management/readme.md). + +Having credentials included in a project's source code not only exposes the project to information security risks resulting from theft and impersonation of the credentials, but also exposes the project to architectural risks such as strongly coupling the project's source code to its infrastructure and deployment specifics. As such, there should be a clear boundary between code and secrets: should be managed outside of the source code, in a system such as [Azure Key Vault](https://azure.microsoft.com/en-us/services/key-vault/) or [HashiCorp Vault](https://www.vaultproject.io) and credential scanning should be employed to ensure that this boundary is never violated. + +Ideally, credential scanning should be run as part of a developer's workflow (e.g. via a [git pre-commit hook](https://githooks.com)), however, to protect against developer error, credential scanning must also be enforced as part of the continuous integration process to ensure that no credentials ever get merged to a project's master branch. From c9cd27e1010d211c2f620fce874c7ad1c8b255aa Mon Sep 17 00:00:00 2001 From: Clemens Wolff Date: Mon, 28 Oct 2019 13:29:20 -0400 Subject: [PATCH 2/2] Add recipe for detect-secrets --- .../credential-scanning/README.md | 3 ++ .../recipes/detect-secrets.md | 39 +++++++++++++++++++ 2 files changed, 42 insertions(+) create mode 100644 continuous-integration/credential-scanning/recipes/detect-secrets.md diff --git a/continuous-integration/credential-scanning/README.md b/continuous-integration/credential-scanning/README.md index 69d7f81601..9f26811a0b 100644 --- a/continuous-integration/credential-scanning/README.md +++ b/continuous-integration/credential-scanning/README.md @@ -5,3 +5,6 @@ Credential scanning is the engineering practice of automatically inspecting a pr Having credentials included in a project's source code not only exposes the project to information security risks resulting from theft and impersonation of the credentials, but also exposes the project to architectural risks such as strongly coupling the project's source code to its infrastructure and deployment specifics. As such, there should be a clear boundary between code and secrets: should be managed outside of the source code, in a system such as [Azure Key Vault](https://azure.microsoft.com/en-us/services/key-vault/) or [HashiCorp Vault](https://www.vaultproject.io) and credential scanning should be employed to ensure that this boundary is never violated. Ideally, credential scanning should be run as part of a developer's workflow (e.g. via a [git pre-commit hook](https://githooks.com)), however, to protect against developer error, credential scanning must also be enforced as part of the continuous integration process to ensure that no credentials ever get merged to a project's master branch. + +To implement credential scanning for a project, consider building on-top of one of the following recipes: +- [detect-secrets](./recipes/detect-secrets.md) diff --git a/continuous-integration/credential-scanning/recipes/detect-secrets.md b/continuous-integration/credential-scanning/recipes/detect-secrets.md new file mode 100644 index 0000000000..58476c149e --- /dev/null +++ b/continuous-integration/credential-scanning/recipes/detect-secrets.md @@ -0,0 +1,39 @@ +## Credential scanning tool suggestion: detect-secrets + +### Background + +The [detect-secrets](https://github.com/Yelp/detect-secrets) tool is an open source project that uses heuristics and rules to scan for [a wide range](https://github.com/Yelp/detect-secrets#currently-supported-plugins) of secrets. The tool can be extended with custom rules and heuristics via a simple [Python plugin API](https://github.com/Yelp/detect-secrets/blob/a9dff60/detect_secrets/plugins/base.py#L27-L49). + +Unlike many credential scanning tools, detect-secrets does not attempt to check a project's entire git history when invoked, but instead only scans the project's current state. This means that the tool runs very quickly which makes it ideal for use in continuous integration pipelines. Additionally, detect-secrets employs the concept of a "baseline file", i.e. a list of known secrets already present in the repository, and can be configured to ignore any of these pre-existing secrets when running. This makes it easy to gradually introduce the tool into a pre-existing project. The baseline file also provides a simple and convenient way of handling false positives: white-list the false positive in the baseline file and it will be ignored on future invocations of the tool. + +### Setup + +```sh +# install system dependencies: diff, jq, python3 +apt-get install -y diffutils jq python3 python3-pip + +# install the detect-secrets tool +python3 -m pip install detect-secrets + +# run the tool to establish a list of known secrets +# this file should be reviewed carefully and checked into the repository +detect-secrets scan > .secrets.baseline +``` + +### Usage + +```sh +# backup the list of known secrets +cp .secrets.baseline .secrets.new + +# find all the secrets currently in the repository +detect-secrets scan --update .secrets.new $(find . -type f ! -name '.secrets.*' ! -path '*/.git*') + +# if there is any difference between the known and newly detected secrets, break the build +list_secrets() { jq -r '.results | keys[] as $key | "\($key),\(.[$key] | .[] | .hashed_secret)"' "$1" | sort; } + +if ! diff <(list_secrets .secrets.baseline) <(list_secrets .secrets.new) >&2; then + echo "Detected new secrets in the repo" >&2 + exit 1 +fi +```