Sigaba

Sigaba is a command-line tool for encrypting selected values in configuration files. It is designed for sensitive data such as passwords, API keys, and connection strings.

Once encrypted, the file remains human-readable, but matching values are replaced with encrypted values.

So, before encryption you would have a file with the following content:

{
    "private_field_secret": "some secret data",
    "public_field": "public value"
}

and/or

KEY_SECRET=some secret data
KEY=value

and after the encryption:

{
    "private_field_secret": "ENC(XAKfHKC...)",
    "public_field": "public value"
}

and/or

KEY_SECRET=ENC(AJFFKTRS...)
KEY=value

Important: Sigaba currently supports only JSON and .env files.

TL;DR

Initialize:

Run:

dotnet tool install --global Sigaba
sigaba init
> Enter a password to encrypt the private key: ********
> Enter the password again to confirm: ********

Edit sigaba.json to select which files and fields will be encrypted or decrypted.

Move the private key from <user profile folder>\.sigaba\private.key to a secure location.

Encrypt:

sigaba encrypt

Decrypt:

Put the private key file (private.key) in:

• the current working directory, or
• in a folder defined in the environment variable SIGABA_PRIVATE_KEY_DIR, or
• in the .sigaba folder in the user profile, in a subfolder matching the projectId in the sigaba.json file.
• anywhere, since you can specify its path with the --private-key-file option.

Then run:

sigaba decrypt -p <password>

or

sigaba decrypt -p <password> -k <path-to-private-key>

Edit and encrypt

sigaba edit <path-to-file>

Features

1. Encrypts any kind of JSON values — strings, numbers, booleans, arrays, and even nulls — except entire objects (see limitations below).
2. Encrypts .env files.
3. Preserves comments and formatting after decryption and encryption.
4. Allows users to update the secret values and re-encrypt them, but not decrypt them without the private key and password.
5. Searches through nested folders, allowing one configuration file to process multiple projects or subfolders.

Installation

Install as a dotnet tool:

dotnet tool install --global Sigaba

or with tool manifests:

dotnet new tool-manifest # if you don't have a manifest file yet
dotnet tool install Sigaba

Usage

Initialization

Initialize Sigaba from your project or solution directory:

sigaba init

or

sigaba init --non-interactive --password <password>

During initialization, you set the password required to decrypt the files.

The tool creates sigaba.json in the current directory and stores the encrypted private key in the user profile:

• sigaba.json:
  • placed in the current working directory, i.e. the folder where you run the command.
  • contains the tool configuration (see more below).
  • required to perform encryption/decryption, so the tool won't work without it.
  • sets the topmost folder where the tool will search for files to encrypt/decrypt.
  • this file can be kept in the source control, so that all team members will have the same configuration.
• private.key:
  • stored in the user profile for safety, such as %USERPROFILE%\.sigaba\private.key on Windows or ~/.sigaba/private.key on Linux and macOS.
  • it is needed to decrypt files.
  • the private key content is encrypted with the provided password, so it is useless without it.
  • once created, move it to a secure location.
  • do not check it into source control!
  • it is generally good practice to allow only an automated system to access the private key through a secure mechanism. For example, in Azure DevOps, you can upload the private key as a secure file and use it during a deployment pipeline.

Encryption

To encrypt your files, use the following command:

sigaba encrypt

The tool looks for files and fields according to the configuration file and encrypts matching values.

Values that are already in the ENC(...) format are left unchanged. To change an encrypted value, use sigaba edit, update the value, save the file, and close the editor. Sigaba will encrypt the new value automatically.

Edit and encrypt

The following command will open the file, allowing you to edit it:

sigaba edit <path-to-file>

Once you save the changes and close the editor, the tool will encrypt the file automatically.

Decryption

To decrypt your files, use:

sigaba decrypt -p <password>

To decrypt files, Sigaba requires:

• the password you defined during initialization. You pass it to the command line as shown above. This password is used to decrypt the private key file.
• the private key file private.key that was created during initialization. The tool will search for it in the following locations, in order:
  • A directory path defined in the environment variable SIGABA_PRIVATE_KEY_DIR
  • The current working directory, i.e. the folder where you run the command.
  • The .sigaba folder in the user profile, in a subfolder matching the projectId in sigaba.json.

Keep in mind those locations above when you are planning to use the tool in a CI/CD pipeline, so that the private key is available for decryption.

Or you can use:

sigaba decrypt --password <password> --private-key-file <path-to-private-key>

With the --private-key-file option, you can specify the path to the private key file, so the tool will not search for it in the default locations.

Configuration

To configure the tool, open sigaba.json and edit the fields in the configuration section.

Do not modify the fields outside the configuration section.

The section will contain the following fields:

Name	Type
fieldRegex	string	The regex pattern used to select the fields to be encrypted/decrypted. The pattern is matched against the field name, not its value.
include	string array	A glob pattern to filter which file will be encrypted/decrypted.
exclude	string array	A glob pattern to filter which file will NOT be encrypted/decrypted.

Example

With the following configuration:

{
  "configuration": {
    "fieldRegex": "^.*_secret$",
    "include": [ "**/*.secrets.json", "**/*.env" ],
    "exclude": [ "**node_modules/**", "**/bin/**", "**/obj/**", "**/dist/**" ]
  },

  "meta": {
    "version": 1,
    "projectId": "b5f2a6d1b4124bc38012c2a70c575646",
    "publicKey": "ATBZMBMGByqGSM49Ag=="
  }
  
}

the tool will work according to these rules:

• the tool will process all files that end with .secrets.json, such as appsettings.secrets.json and myconfig.secrets.json.
• the tool will process all files that end with .env.
• the tool will skip any file inside a node_modules, bin, obj or dist folder.
• in each matching file, the tool will look for field names that end with _secret and encrypt or decrypt their values.

NOTE: Mind that the regex pattern to match field names is case-insensitive.

Limitations

Single configuration per project or solution

Currently, the tool cannot handle nested sigaba.json files in the same folder hierarchy. It means that:

• or you have only one configuration in the project root folder,
• or multiple configurations, each one in a different project subfolder.

Json files

Although the tool can reach any field in the document hierarchy, it cannot encrypt entire JSON objects. So if you have:

{
    "parent_secret": { 
        "child_secret": "sensitive data" 
    }
}

will become:

{
    "parent_secret": { 
        "child_secret": "ENC(AAAA...)" 
    }
}

That's to avoid confusion on which level of the document would be encrypted first and the hassle to handle nested encrypted values.

Changelog

0.5

• For decryption, you can place the private key anywhere, as long as you specify its path with the --private-key-file option.

0.4

• support for .env files
• updated exclude patterns to include /dist/

0.3

• Improved cli experience with better messages
  • can run commands with -q or --quiet to suppress messages
  • can run commands with --verbosity detailed to show more details