generated from mintlify/starter
-
Notifications
You must be signed in to change notification settings - Fork 45
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: add encrypting secrets spec #113
Open
dwisiswant0
wants to merge
1
commit into
main
Choose a base branch
from
dwisiswant0/docs/add-encrypting-secrets-spec
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -31,7 +31,7 @@ Since authentication can be done in multiple ways, for example, using 3rd party | |
### Dealing with Dynamic Authentication | ||
|
||
Implementing and managing Static Authentication is easy, but dealing with Dynamic Authentication is a bit complex due to multiple entities and secrets and the flow of authentication being involved. Some might require a browser guided authentication while some might be achievable with auth flow. | ||
A common solution for this is to capture and generate a login flow/sequence using a browser and then feed that script to app handling the authentication._createMdxContent | ||
A common solution for this is to capture and generate a login flow/sequence using a browser and then feed that script to app handling the authentication. | ||
|
||
To focus on making this process easy, familiar, and scalable (users should be able to scan thousands of targets with authentication without much hassle), we leverage the existing rich ecosystem of `nuclei-templates`. These are written in YAML, are scalable, and comes with a powerful engine. | ||
|
||
|
@@ -53,15 +53,76 @@ Since authentication can be done in multiple ways, for example, using 3rd party | |
We have not imposed the need to hardcode secrets in the `Secret File` configuration, and support the use of third-party secret management systems to templatize and manage secrets. | ||
|
||
|
||
### Integrations with Secret Management Systems | ||
### Encrypting Secrets | ||
|
||
We are currently exploring integrations with popular secret management systems for easy and secure management of secrets | ||
To make it easy to manage and encrypt your secrets, Nuclei integrates with [SOPS](https://github.com/getsops/sops). It's a tool designed specifically for encrypting and decrypting files, allowing you to store sensitive information like API keys or passwords in a secure format. By integrating SOPS into your workflow, you can ensure your sensitive data is encrypted at rest while still being accessible to Nuclei during runtime. | ||
|
||
We are prioritizng support for: | ||
<Note> | ||
This feature is available in Nuclei **vX.Y.Z**. | ||
</Note> | ||
|
||
- **1Password** | ||
- **Hashicorp Vault** | ||
- **AWS Secrets Manager** | ||
#### Recommended SOPS Configuration | ||
|
||
To simplify the encryption process, you can set up a [`.sops.yaml`](https://github.com/projectdiscovery/nuclei/blob/dev/.sops.yaml) file with rules that automatically encrypt specific [fields](/tools/nuclei/authenticated-scans#secret-file-fields) in your files. Here's a recommended configuration: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Note: update There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We don't have to wait tho |
||
|
||
```yaml | ||
creation_rules: | ||
- encrypted_regex: ^(password|username|token|value|key|raw)$ | ||
``` | ||
|
||
With this setup, SOPS will automatically encrypt [fields](/tools/nuclei/authenticated-scans#secret-file-fields) that match common sensitive patterns such as password, username, token, and similar keys whenever you create or update your files. This reduces the chances of accidentally exposing sensitive information in plaintext. | ||
|
||
Here's a simple guide to help you create and use encrypted secret files with Nuclei: | ||
|
||
1. [Define your secret file](/tools/nuclei/authenticated-scans#secret-file-formats) | ||
2. Encrypt the Secret File with SOPS | ||
|
||
Use SOPS to encrypt the plaintext file. Run the following command in your terminal: | ||
|
||
```bash | ||
sops encrypt --output secret-file.enc.yaml secret-file.yaml | ||
``` | ||
|
||
This command generates an encrypted version of your file called `secret-file.enc.yaml`. The original plaintext file (`secret-file.yaml`) should be deleted afterward to avoid accidentally exposing your sensitive data. | ||
|
||
<Note> | ||
Please refer to the [SOPS documentation](https://getsops.io/docs/) for encrypting with AWS KMS, GCP KMS, Azure Key Vault, age, or PGP. | ||
</Note> | ||
|
||
3. Verify the Encrypted Secret File | ||
|
||
Open the encrypted file (`secret-file.enc.yaml`) to confirm that all sensitive fields have been encrypted. You should see unreadable ciphertext that looks something like this: | ||
|
||
```yaml | ||
username: ENC[AES256_GCM,data:...,iv:...,tag:...] | ||
password: ENC[AES256_GCM,data:...,iv:...,tag:...] | ||
api_key: ENC[AES256_GCM,data:...,iv:...,tag:...] | ||
``` | ||
|
||
This means your secrets are now securely encrypted. | ||
|
||
4. Use the Encrypted Secret File with Nuclei | ||
|
||
Configure Nuclei to use the encrypted secret file (`secret-file.enc.yaml`) with `-secret-file`/`-sf` flag during execution. Nuclei will automatically decrypt the file at runtime, ensuring the secrets are accessible only when needed without ever exposing them in plaintext. This keeps your sensitive data secure both at rest and in use. | ||
|
||
#### Why Use Encrypted Secret Files? | ||
|
||
Using encrypted secret files ensures that your sensitive information is always stored securely, whether it's in your local environment or being shared across systems. It prevents accidental leaks of confidential data and aligns with best practices for secure application development. Plus, since Nuclei handles decryption on the fly, you don't need to worry about manually decrypting files or exposing plaintext values in your configuration. | ||
|
||
#### `.gitignore` Configuration | ||
|
||
To prevent sensitive files from being accidentally committed to your Git repository, it's important to update your `.gitignore` file. Here's a recommended configuration: | ||
|
||
```yaml | ||
# Ignore all YAML files except encrypted files and SOPS config | ||
*.yaml | ||
!*.enc.yaml | ||
!.sops.yaml | ||
``` | ||
|
||
This setup ignores all YAML files by default, ensuring that plaintext secret files like `secret-file.yaml` are never tracked in your repo. However, it makes an exception for encrypted files (`*.enc.yaml`) and the SOPS configuration file (`.sops.yaml`), allowing you to safely store and share these files. | ||
|
||
By following these steps and best practices, you can effectively secure your secrets while keeping them accessible for use with Nuclei. This approach ensures your sensitive information stays safe and your workflow remains smooth and efficient. | ||
|
||
### Skipping Secret File | ||
|
||
|
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
TBD. @ehsandeep