From 723ce99786701f39f5ceaf0ef593afe3d803b54c Mon Sep 17 00:00:00 2001 From: Drew DeVault Date: Fri, 19 Feb 2021 09:20:41 -0500 Subject: Add docs about keeping build secrets secret --- builds.sr.ht/index.md | 35 ++++++++++++++++++++++++++++++++--- 1 file changed, 32 insertions(+), 3 deletions(-) (limited to 'builds.sr.ht') diff --git a/builds.sr.ht/index.md b/builds.sr.ht/index.md index d43fe60..8378c0a 100644 --- a/builds.sr.ht/index.md +++ b/builds.sr.ht/index.md @@ -86,9 +86,38 @@ View the full list of [supported build images](compatibility.md). builds.sr.ht can keep track of secrets for you, like SSH keys or PGP keys, and include them in builds for the purpose of deployment. You can manage your -secrets at the [secrets dashboard](https://builds.sr.ht/secrets). Each secret -will only be included in the runtime image if the job was submitted using an -OAuth key which has access to the secrets specified in the build manifest. +secrets at the [secrets dashboard](https://builds.sr.ht/secrets). + +## Keeping your secrets a secret + +If you need to reference a secret in a command line argument or shell variable, +make sure to run `set +x` first to temporarily disable detailed command logging +in the build shell. Run `set -x` again once you're done handling secret +information to re-enable command logging. You also need to be careful that +secrets are not printed to stdout or stderr by the commands which use them +— add ` 2>&1 >/dev/null` to the affected commands if you need to hide this +output. + +Whenever you submit a build via the API, you can pass the `secrets` parameter (a +boolean) to explicitly disable secrets. In this case, they will be discarded and +the build run without including them (it's up to you to deal with this +gracefully in your shell scripts, by the way). It is important that you use this +parameter whenever submitting a build which runs code anyone you don't trust +could have tampered with. This includes not only the build manifests themselves, +but any code run as a side-effect, like your Makefile. + +This is done for you automatically whenever you submit builds using sr.ht +features. When building patches from your mailing list, sr.ht will automatically +disable secrets. The same is true of pull requests from GitHub submitted via +dispatch.sr.ht. + +In any case, if your secret is leaked, you **must** consider it permanently +compromised, revoke it from any services it provides authentication for, and +generate new secrets from scratch. All build logs are public, and to encourage +users to roll over secrets which are compromised, our policy is to refuse to +redact secrets leaked in this manner. If you require some time to fully address +the consequences of a secret leak, we may redact them for up to one week — +[email support](mailto:sir@cmpwn.com) if you require this. ## Build environment -- cgit