Add documentation for SecretsUsedInArgOrEnv rule

Signed-off-by: Talon Bowler <[email protected]>

Author: daghack

frontend/dockerfile/dockerfile2llb/convert.go

@@ -55,6 +55,11 @@ const (
 	sbomScanStage   = "BUILDKIT_SBOM_SCAN_STAGE"
 )
 
+var (
+	secretsRegexpOnce sync.Once
+	secretsRegexp     *regexp.Regexp
+)
+
 var nonEnvArgs = map[string]struct{}{
 	sbomScanContext: {},
 	sbomScanStage:   {},
@@ -2347,24 +2352,32 @@ func validateBaseImagePlatform(name string, expected, actual ocispecs.Platform,
 	}
 }
 
-func validateNoSecretKey(key string, location []parser.Range, lint *linter.Linter) {
+func getSecretsRegex() *regexp.Regexp {
 	// Check for either full value or first/last word.
 	// Examples: api_key, DATABASE_PASSWORD, GITHUB_TOKEN, secret_MESSAGE, AUTH
 	// Case insensitive.
-	secretTokens := []string{
-		"apikey",
-		"auth",
-		"credential",
-		"credentials",
-		"key",
-		"password",
-		"pword",
-		"passwd",
-		"secret",
-		"token",
-	}
-	pattern := `(?i)(?:_|^)(?:`+strings.Join(secretTokens, "|")+`)(?:_|$)`
-	if matched, _ := regexp.MatchString(pattern, key); matched {
+	secretsRegexpOnce.Do(func() {
+		secretTokens := []string{
+			"apikey",
+			"auth",
+			"credential",
+			"credentials",
+			"key",
+			"password",
+			"pword",
+			"passwd",
+			"secret",
+			"token",
+		}
+		pattern := `(?i)(?:_|^)(?:` + strings.Join(secretTokens, "|") + `)(?:_|$)`
+		secretsRegexp = regexp.MustCompile(pattern)
+	})
+	return secretsRegexp
+}
+
+func validateNoSecretKey(key string, location []parser.Range, lint *linter.Linter) {
+	pattern := getSecretsRegex()
+	if pattern.MatchString(key) {
 		msg := linter.RuleSecretsUsedInArgOrEnv.Format(key)
 		lint.Run(&linter.RuleSecretsUsedInArgOrEnv, location, msg)
 	}

frontend/dockerfile/dockerfile_lint_test.go

@@ -61,55 +61,63 @@ ENV git_key=
 				RuleName:    "SecretsUsedInArgOrEnv",
 				Description: "Potentially sensitive data should not be used in the ARG or ENV commands",
 				Detail:      `Secrets should not be used in the ARG or ENV commands (key named "SECRET_PASSPHRASE")`,
+				URL:         "https://docs.docker.com/go/dockerfile/rule/secrets-used-in-arg-or-env/",
 				Level:       1,
 				Line:        3,
 			},
 			{
 				RuleName:    "SecretsUsedInArgOrEnv",
 				Description: "Potentially sensitive data should not be used in the ARG or ENV commands",
 				Detail:      `Secrets should not be used in the ARG or ENV commands (key named "SUPER_Secret")`,
+				URL:         "https://docs.docker.com/go/dockerfile/rule/secrets-used-in-arg-or-env/",
 				Level:       1,
 				Line:        4,
 			},
 			{
 				RuleName:    "SecretsUsedInArgOrEnv",
 				Description: "Potentially sensitive data should not be used in the ARG or ENV commands",
 				Detail:      `Secrets should not be used in the ARG or ENV commands (key named "password")`,
+				URL:         "https://docs.docker.com/go/dockerfile/rule/secrets-used-in-arg-or-env/",
 				Level:       1,
 				Line:        5,
 			},
 			{
 				RuleName:    "SecretsUsedInArgOrEnv",
 				Description: "Potentially sensitive data should not be used in the ARG or ENV commands",
 				Detail:      `Secrets should not be used in the ARG or ENV commands (key named "secret")`,
+				URL:         "https://docs.docker.com/go/dockerfile/rule/secrets-used-in-arg-or-env/",
 				Level:       1,
 				Line:        5,
 			},
 			{
 				RuleName:    "SecretsUsedInArgOrEnv",
 				Description: "Potentially sensitive data should not be used in the ARG or ENV commands",
 				Detail:      `Secrets should not be used in the ARG or ENV commands (key named "super_duper_secret_token")`,
+				URL:         "https://docs.docker.com/go/dockerfile/rule/secrets-used-in-arg-or-env/",
 				Level:       1,
 				Line:        6,
 			},
 			{
 				RuleName:    "SecretsUsedInArgOrEnv",
 				Description: "Potentially sensitive data should not be used in the ARG or ENV commands",
 				Detail:      `Secrets should not be used in the ARG or ENV commands (key named "auth")`,
+				URL:         "https://docs.docker.com/go/dockerfile/rule/secrets-used-in-arg-or-env/",
 				Level:       1,
 				Line:        6,
 			},
 			{
 				RuleName:    "SecretsUsedInArgOrEnv",
 				Description: "Potentially sensitive data should not be used in the ARG or ENV commands",
 				Detail:      `Secrets should not be used in the ARG or ENV commands (key named "apikey")`,
+				URL:         "https://docs.docker.com/go/dockerfile/rule/secrets-used-in-arg-or-env/",
 				Level:       1,
 				Line:        7,
 			},
 			{
 				RuleName:    "SecretsUsedInArgOrEnv",
 				Description: "Potentially sensitive data should not be used in the ARG or ENV commands",
 				Detail:      `Secrets should not be used in the ARG or ENV commands (key named "git_key")`,
+				URL:         "https://docs.docker.com/go/dockerfile/rule/secrets-used-in-arg-or-env/",
 				Level:       1,
 				Line:        8,
 			},

frontend/dockerfile/docs/rules/_index.md

@@ -84,5 +84,9 @@ $ docker build --check .
       <td><a href="./redundant-target-platform/">RedundantTargetPlatform</a></td>
       <td>Setting platform to predefined $TARGETPLATFORM in FROM is redundant as this is the default behavior</td>
     </tr>
+    <tr>
+      <td><a href="./secrets-used-in-arg-or-env/">SecretsUsedInArgOrEnv</a></td>
+      <td>Potentially sensitive data should not be used in the ARG or ENV commands</td>
+    </tr>
   </tbody>
 </table>

frontend/dockerfile/docs/rules/secrets-used-in-arg-or-env.md

@@ -0,0 +1,32 @@
+---
+title: SecretsUsedInArgOrEnv
+description: Potentially sensitive data should not be used in the ARG or ENV commands
+aliases:
+  - /go/dockerfile/rule/secrets-used-in-arg-or-env/
+---
+
+## Output
+
+```text
+Potentially sensitive data should not be used in the ARG or ENV commands
+```
+
+## Description
+
+While it is common in many local development setups to pass secrets to running
+processes through environment variables, setting these within a Dockerfile via
+the `ENV` command means that these secrets will be committed to the build
+history of the resulting image, exposing the secret. For the same reasons,
+passing secrets in as build arguments, via the `ARG` command, will similarly
+expose the secret. This rule reports violations where `ENV` and `ARG` key names
+appear to be secret-related.
+
+## Examples
+
+❌ Bad: `AWS_SECRET_ACCESS_KEY` is a secret value.
+
+```dockerfile
+FROM scratch
+ARG AWS_SECRET_ACCESS_KEY
+```
+

frontend/dockerfile/linter/docs/SecretsUsedInArgOrEnv.md

@@ -0,0 +1,24 @@
+## Output
+
+```text
+Potentially sensitive data should not be used in the ARG or ENV commands
+```
+
+## Description
+
+While it is common in many local development setups to pass secrets to running
+processes through environment variables, setting these within a Dockerfile via
+the `ENV` command means that these secrets will be committed to the build
+history of the resulting image, exposing the secret. For the same reasons,
+passing secrets in as build arguments, via the `ARG` command, will similarly
+expose the secret. This rule reports violations where `ENV` and `ARG` key names
+appear to be secret-related.
+
+## Examples
+
+❌ Bad: `AWS_SECRET_ACCESS_KEY` is a secret value.
+
+```dockerfile
+FROM scratch
+ARG AWS_SECRET_ACCESS_KEY
+```

frontend/dockerfile/linter/ruleset.go

@@ -135,6 +135,7 @@ var (
 	RuleSecretsUsedInArgOrEnv = LinterRule[func(string) string]{
 		Name:        "SecretsUsedInArgOrEnv",
 		Description: "Potentially sensitive data should not be used in the ARG or ENV commands",
+		URL:         "https://docs.docker.com/go/dockerfile/rule/secrets-used-in-arg-or-env/",
 		Format: func(secretKey string) string {
 			return fmt.Sprintf("Secrets should not be used in the ARG or ENV commands (key named %q)", secretKey)
 		},