You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
## Summary
Going forward, the easiest path to updating secrets is to run the task
`detect-secrets - update and audit baseline`.
- add .vscode tasks for running `detect-secrets`
- update README on `detect-secrets` guidance
- internal wiki will also be updated
// print guidance on how to manage the possible secrets
201
202
console.error(
202
-
'\nUh oh! If you have secrets in your code, please remove them before committing.\n'
203
+
// allow-any-unicode-next-line
204
+
'\n👆 Uh oh! detect-secrets has a complaint.\n'
203
205
.magenta+
204
-
`If you are certain that these are false positives, see ${'build/secrets/README.md'.underline
205
-
} for instructions on how to mark them as such.\n`.magenta
206
+
`If you have secrets in your code, please remove them before committing.\nFor further guidance, see ${'build/secrets/README.md'.underline} for instructions on how to update and audit the secrets baseline.\n`.magenta
Copy file name to clipboardExpand all lines: build/secrets/README.md
+64-30Lines changed: 64 additions & 30 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,20 +6,76 @@ For more information on how to use detect-secrets, see the [detect-secrets docum
6
6
7
7
A wrapper script [detect-secrets.js](../detect-secrets.js) is used to run detect-secrets with the appropriate configuration and baseline secrets file.
8
8
9
-
## Installation
9
+
## 🛠️ Install `detect-secrets`
10
10
11
11
Install detect-secrets via `pip install detect-secrets` (Python and pip installed already) or `brew install detect-secrets` (MacOS).
12
12
13
-
## Pre-commit hook
14
-
The pre-commit hook associated with the `hygiene` command will run `detect-secrets-hook` on staged files and fail if any secrets are found (if the secrets are not already in the baseline secrets file).
13
+
## 🏃 Run detect-secrets
14
+
15
+
### When to run `detect-secrets`?
16
+
17
+
`detect-secrets` automatically runs on staged files via the [pre-commit hook](#pre-commit-hook) when you run `git commit`.
18
+
19
+
However, `detect-secrets` must be run manually when reviewing automated PRs, such as the [Workbench extension bump PRs](https://github.com/posit-dev/positron/pulls?q=is:pr+author:app/posit-jenkins-enterprise).
20
+
21
+
### How to run `detect-secrets` manually?
22
+
23
+
> [!IMPORTANT]
24
+
> ⚠️ Windows users: please use a Mac or Linux machine to run the following commands, as the `detect-secrets` tool will rewrite all file paths to use Windows-style paths, which will cause all of the baseline file entries to be marked as new secrets that need to be audited again.
25
+
26
+
> [!TIP]
27
+
> While auditing the secrets, if you see the error `ERROR: Secret not found on line <LINE_NUMBER>! Try recreating your baseline to fix this issue.`, **_do not_** recreate the baseline file (i.e., **don't** run `node ./build/detect-secrets.js init-baseline`, as the marked false and true positives metadata may be lost). Please reach out to the team for help with this error.
28
+
29
+
The core steps are:
30
+
1. Update the baseline secrets file to include new secret-like strings
31
+
2. Audit the baseline secrets file to mark each "secret" as okay to commit or not
32
+
3. Commit the updated baseline secrets file
33
+
34
+
Use one of the following methods to update the contents of the `.secrets.baseline` file.
35
+
36
+
#### Method 1: tasks.json
37
+
38
+
The `tasks.json` file in the `.vscode` directory contains tasks to run detect-secrets commands.
39
+
40
+
In general, you'll run the `detect-secrets - update and audit baseline` task, which will run the `update-baseline` and `audit-baseline` commands in sequence.
41
+
42
+
1. Run `Tasks: Run Task` in Command Palette and select the task `detect-secrets - update and audit baseline`
43
+
2. Wait for the baseline secrets file to be updated and prepared for auditing
44
+
3. Follow the instructions in the terminal to audit the baseline secrets file, generally this involves marking false positives as "yes, should be committed"
45
+
- If there are new secrets in the baseline file that are unrelated to your changes, notify the team. You can skip them in the audit as you assess the other detected secrets, but they should be addressed before committing the updated baseline file.
46
+
4. Commit the updated baseline secrets file
47
+
48
+
#### Method 2: `detect-secrets.js` wrapper script
49
+
50
+
We have a wrapper script [detect-secrets.js](../detect-secrets.js) that runs `detect-secrets` with the appropriate configuration, arguments, baseline secrets file, and additional logging.
51
+
52
+
1. Run the commands from the root of the project:
53
+
```bash
54
+
node ./build/detect-secrets.js update-baseline
55
+
node ./build/detect-secrets.js audit-baseline
56
+
```
57
+
2. Wait for the baseline secrets file to be updated and prepared for auditing
58
+
3. Follow the instructions in the terminal to audit the baseline secrets file, generally this involves marking false positives as "yes, should be committed"
59
+
- If there are new secrets in the baseline file that are unrelated to your changes, notify the team. You can skip them in the audit as you assess the other detected secrets, but they should be addressed before committing the updated baseline file.
60
+
4. Commit the updated baseline secrets file
61
+
62
+
## 📚 Additional reading
63
+
64
+
Here are some additional notes on how to use `detect-secrets`, if you're having issues with the pre-commit hook or want to further customize the secrets scanning process.
65
+
66
+
### Pre-commit hook
67
+
68
+
The pre-commit hook associated with the `hygiene` command will run `detect-secrets-hook` on staged files and fail if any secret-like strings are found (if the secret-like strings are not already in the baseline secrets file or have changed).
69
+
70
+
If secret-like strings are found and your commit fails, update the baseline secrets file and mark any false positive "secrets" as okay to commit, then commit the updated baseline secrets file. See [Updating the baseline secrets file](#updating-the-baseline-secrets-file) and [Auditing the baseline secrets file](#auditing-the-baseline-secrets-file) for more details.
15
71
16
72
If you feel like something is going wrong with the pre-commit hook, you can run `node ./build/detect-secrets.js run-hook --debug` to run the hook manually with additional debug output. You can copy the generated `detect-secrets-hook` command and run it in your terminal with an additional option `--verbose` to debug further.
17
73
18
74
If you're committing changes that modify the line number of a previously detected secret (false positive or otherwise) in the baseline file, `detect-secrets` will automatically update the baseline file with the new line number and fail the commit so you can add the updated baseline file to your commit.
19
75
20
76
If the baseline file _doesn't_ get updated automatically, follow the instructions on [updating the baseline secrets file](#updating-the-baseline-secrets-file) to manually update the baseline file.
21
77
22
-
### Example
78
+
####Example
23
79
`my_secret` on line 2 is already captured in the baseline secrets file.
If you are receiving false positives from the pre-commit hook, you can update the baseline secrets file to mark the detected "secrets" as okay to commit.
38
-
39
-
First, update the baseline secrets file to include the new strings. Then, run the audit command to mark the new strings as false positives. Once complete, commit the updated baseline secrets file.
92
+
### Report of secrets found
40
93
41
-
### Updating the baseline secrets file
94
+
A JSON report of the detected secret-like strings can be generated. It is similar to the output of the audit command, but in JSON format instead.
42
95
43
-
> [!IMPORTANT]
44
-
> ⚠️ Windows users: please use a Mac or Linux machine to run the following commands, as the `detect-secrets` tool will rewrite all file paths to use Windows-style paths, which will cause all of the baseline file entries to be marked as new secrets that need to be audited again.
96
+
To generate the report, run `node ./build/detect-secrets.js generate-report` from the root of the project. The generated file `secrets_report[_pro].json` will not be committed as it is listed in our `.gitignore`.
45
97
46
-
From the root of the project:
47
-
1. Run `node ./build/detect-secrets.js update-baseline` to scan for new secrets and update the baseline secrets file
48
-
2. See [Auditing the baseline secrets file](#auditing-the-baseline-secrets-file) below to audit the baseline secrets file
49
-
3. Commit the updated baseline secrets file
50
-
51
-
See [detect-secrets documentation](https://github.com/Yelp/detect-secrets/tree/master?tab=readme-ov-file#adding-new-secrets-to-baseline) for more details.
52
-
53
-
### Auditing the baseline secrets file
54
-
From the root of the project:
55
-
1. Run `node ./build/detect-secrets.js audit-baseline` to audit the baseline secrets file (flag each secret as either true or false positive).
56
-
- If there are new secrets in the baseline file that are unrelated to your changes, notify the team. You can skip them in the audit as you assess the other detected secrets, but they should be addressed before committing the updated baseline file.
57
-
- If you see the error `ERROR: Secret not found on line <LINE_NUMBER>! Try recreating your baseline to fix this issue.`, **_do not_** recreate the baseline file (i.e., **don't** run `node ./build/detect-secrets.js init-baseline`, as the marked false and true positives metadata may be lost). Instead, follow the instructions on [updating the baseline secrets file](#updating-the-baseline-secrets-file), which should automatically remove outdated secrets (i.e., if the secret no longer exists or the line number has changed).
58
-
59
-
## Report of secrets found
60
-
From the root of the project:
61
-
1. Run `node ./build/detect-secrets.js generate-report`.
62
-
- The output is similar to the output of `node ./build/detect-secrets.js audit-baseline` but in JSON format.
63
-
-`secrets_report[_pro].json` will not be committed as it is `.gitignore`-d
98
+
### Filtering secrets
64
99
65
-
## Filtering secrets
66
100
We currently only use the built-in filtering mechanism `--exclude-files` to filter out secrets in specific files, file name patterns and directories. These directories contain third-party code that we do not want to scan for secrets.
67
101
68
102
See the `excludeFiles` array in the [detect-secrets.js script](../detect-secrets.js) for the list of files, file name patterns and directories that are excluded.
0 commit comments