dotnet-sops
0.1.0-alpha.2
See the version list below for details.
dotnet tool install --global dotnet-sops --version 0.1.0-alpha.2
dotnet new tool-manifest # if you are setting up this repo dotnet tool install --local dotnet-sops --version 0.1.0-alpha.2
#tool dotnet:?package=dotnet-sops&version=0.1.0-alpha.2&prerelease
nuke :add-package dotnet-sops --version 0.1.0-alpha.2
dotnet-sops: A .NET tool for encrypting .NET user-secrets using SOPS
dotnet-sops
is a .NET tool for securely storing and sharing user-secrets with all your team members.
It utilizes SOPS under the hood to encrypt and decrypt secrets, thereby supporting all key types supported by SOPS: Azure Key Vault, AWS KMS, GCP KMS, HashiCorp Vault, age, and PGP.
When secrets are decrypted using
dotnet sops decrypt
they are stored in plain, unencrypted text that can be loaded by the user-secrets tool.Remove plaintext by running
dotnet user-secrets clear
and usedotnet sops run
to load secrets into the environment.
Table of Contents
Background
dotnet-sops
was developed to address the security risks posed by plain-text secrets in Git repositories. It offers a streamlined solution, integrating with SOPS encryption, to enable secure management and sharing of development secrets within the .NET ecosystem.
Installation
Local (Recommended)
Run the following commands to install the tool:
dotnet new tool-manifest
dotnet tool install dotnet-sops
This will write the .config/dotnet-tools.json
file with version of the tool used. Add this file to source control. Your team members can then run the follwing command to install the same version of the tool:
dotnet tool restore
Global
Run the following commands to install the tool globally:
dotnet tool install dotnet-sops --global
Get started
Basic usage
# Follow the text wizard to create .sops.yaml configuration file. (Only the first time)
dotnet sops init
# Download SOPS executable. (Only the first time)
dotnet sops download-sops
# Generate UserSecretId for dotnet project. Skip if already have it setup. (Only the first time)
dotnet user-secrets init
# Add an example secret to user-secrets. (Only for new secrets)
dotnet user-secrets set "MyApi:ApiKey" "MySuperSecretApiKeyValue"
# Encrypt user-secrets to the secrets.json file.
dotnet sops encrypt
# Clear secrets from user-secrets.
dotnet user-secrets clear
# Run 'dotnet run' with decrypted secrets injected into the environment.
dotnet sops run
# Decrypt secrets.json to user-secrets.
dotnet sops decrypt
For more information on how to use user-secrets to add secrets, refer to Safe storage of app secrets in development in ASP.NET Core
Usage
init
Initiate the prompt to create a valid .sops.yaml
configuration file:
dotnet sops init
download-sops
If you don't have SOPS in your PATH, you can download SOPS from https://github.com/getsops/sops using the follwing command:
dotnet sops download-sops
The downloaded SOPS executable has its SHA-512 checksum verified. This version of SOPS will be used by the encrypt
and decrypt
commands.
encrypt
Encrypt existing .NET user secrets.
dotnet sops encrypt
This will create a secrets.json
file that can be shared with other team members working on your project.
decrypt
Decrypt a secrets.json
file into .NET user secrets.
dotnet sops decrypt
run
Run dotnet run
with secrets from secrets.json
injected into the environment.
dotnet sops run
dotnet sops run
accepts the same arguments and options as dotnet run
.
--help
All commands support the --help
option:
# List all commands
dotnet sops --help
# List all options for encryption
dotnet sops encrypt --help
Configure SOPS
The .sops.yaml
configuration file is used to inform SOPS how to handle encryption and decryption. The content should define a creation_rules
for the secrets.json
path.
The following command can be used to help create a vaild .sops.yaml
:
dotnet sops init
You can also create and edit the .sops.yaml
file yourself. Refer to the SOPS documentation for more information.
Using age
Usage with age key:
creation_rules:
- path_regex: secrets.json
age: age1
Only decryption is possible for user with the private key.
Refer to the SOPS documentation to learn how SOPS accesses age private keys.
If more people should have access, then mulitple public age keys can be specified:
creation_rules:
- path_regex: secrets.json
age: age1,age2
This requires user access to the age1 or age2 private key.
Using Azure Key Vault
Usage with Azure Key Vault key:
creation_rules:
- path_regex: secrets.json
azure_keyvault: https://my-key-vault-name.vault.azure.net/keys/my-key-name/my-key-version
Users should be assigned the encrypt
and decrypt
rights for the key vault.
Configure SOPS with key groups
SOPS can also be configured to require access to more than one key. This can be achieved by using key groups in the configuration. Refer to the SOPS key group dokumentation for more information.
Example using three key groups:
creation_rules:
- path_regex: secrets.json
key_groups:
- pgp: # Key group 1
- fingerprint1
age:
- age1
- pgp: # Key group 2
- fingerprint2
- age: # Key group 3
- age2
This requires that the user has access to all three key groups. For key group 1, it requires the user to have access to either fingerprint1 or age1.
Contributing
Refer to the contributing guide for detailed instructions on how to contribute to dotnet-sops.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
This package has no dependencies.
Version | Downloads | Last updated |
---|---|---|
1.1.1 | 189 | 3/29/2024 |
1.1.0 | 281 | 12/8/2023 |
1.0.0 | 310 | 10/15/2023 |
0.1.0-alpha.2 | 79 | 8/31/2023 |
0.1.0-alpha.1 | 213 | 8/20/2023 |