git-secret-protector

git-secret-protector is a Python-based CLI tool designed to securely manage and protect sensitive files in your Git repositories. It integrates with Cloud Secret Storage Services to encrypt and decrypt secrets, ensuring that your sensitive data remains secure throughout your development process.

Features

• AES Key Management: Securely create, manage, and rotate AES data keys using Cloud Secret Storage Services such as AWS Parameter Store, Google Cloud Secret Manager.
• File Encryption/Decryption: Automatically encrypt and decrypt files in your repository based on patterns defined in the .gitattributes file.
• Cache Management: Cache AES data keys locally to improve performance and reduce redundant calls to Cloud Services.

Install Guide

Requirements

• pipx (Download)

• You can install the git-secret-protector module via pipx:

  pipx install git-secret-protector
  

Usage

1. Initial Setup for Repositories Owners

1.1. Create .gitattributes file

• Create a .gitattributes file in the root of your repository to define which files should be encrypted.

  Sample .gitattributes file:

  dev/secrets* filter=sample-app-dev diff=sample-app-dev
  
  prod/secrets* filter=sample-app-prod diff=sample-app-prod
  
  .gitattributes !filter !diff
  

1.2. Configure Git Filters

• Set up the Git clean and smudge filters base on the filters defined in the .gitattributes file.

  git-secret-protector setup-filters
  

This command will configure the Git clean and smudge filters based on the patterns defined in the .gitattributes file. The filters will automatically encrypt and decrypt files based on the specified patterns.

• You can verify the configured filters in the .git/config file, for example:

  [filter "sample-app-dev"]
      clean = git-secret-protector encrypt sample-app-dev
      smudge = git-secret-protector decrypt sample-app-dev
      required = true
  

1.3. Configuration

The config.ini file contains settings that customize the behavior of the git-secret-protector module. The file should be located in the module's directory (by default: .git_secret_protector/config.ini) and can be used to override the default values set in the code.

• Sample config.ini

  [DEFAULT]
  module_name = git-secret-protector
  log_file = /path/to/log/git_secret_protector.log
  log_level = INFO
  log_max_size = 1048576
  log_backup_count = 3
  magic_header = ENCRYPTED
  storage_type = AWS_SSM
  

• Configuration Parameters

  • module_name: Name of the module.
  • log_file: Path to the log file.
  • log_level: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
  • log_max_size: Maximum size of the log file in bytes.
  • log_backup_count: Number of log files to keep.
  • magic_header: Magic header to identify encrypted files.
  • storage_type: Cloud Secret Storage Service to use (AWS_SSM, GCP_SECRET_MANAGER).
    • AWS_SSM (default): AWS Parameter Store
    • GCP_SECRET: Google Cloud Secret Manager

1.4. Set up AES key

Notes: Before executing this command, ensure you have the necessary permissions to manage resources in the using Cloud Secret Storage Services.

• Command to set up AES key

  git-secret-protector setup-aes-key <filter_name>
  

• Sample command to set up an AES key for the sample-app-dev filter:

  git-secret-protector setup-aes-key sample-app-dev
  

1.5. Verify filter functionality

• Ensure that files are properly encrypted or decrypted by running:

  git-secret-protector status
  

The status will display the files managed by the filter and their encryption status.

2. Installation Steps for Team Members

2.1. Pull AES Key and IV

Notes Before encrypting or decrypting files, it's necessary to retrieve the relevant AES keys from the Cloud Secret Storage Service for filters:

• Command to pull AES key

  git-secret-protector pull-aes-key <filter_name>
  

This command fetches the latest AES data key and IV from the Cloud Secret Storage Service for the designated filter and caches them locally for subsequent operations. This step ensures that you have the correct keys for encryption or decryption tasks related to the specified filter.

2.2. Configure Git Filters

• Set up the Git clean and smudge filters base on the filters defined in the .gitattributes file.

  git-secret-protector setup-filters
  

  Refer to 1.2. Configure Git Filters for instructions to verify if filters have been configured properly.

2.2. Decrypt secret files

• Command to decrypt secret files:

  git-secret-protector decrypt-files <filter_name>
  

3. Common Usages

3.1. Add a File to a filter's managed list

• Add the file

  Update the .gitattributes file to include the file under a path that matches a filter pattern. For example, to add live/dev/secret.auto.tfvars, update the .gitattributes file as follows:

  live/dev/secret*.auto.tfvars filter=sample-app-dev diff=sample-app-dev
  

• Encrypt the file

  Use the following command to encrypt the file under the specified filter:

  git-secret-protector encrypt-files <filter>
  

  Replace <filter> with the name of the filter (e.g., sample-app-dev).

• Verify encryption

  Confirm that the file has been encrypted by running:

  git-secret-protector status
  

  Sample output

  Filter: sample-app-dev
    ./live/dev/secrets.auto.tfvars: Encrypted
    ./config/slack/secrets.tf: Encrypted
  Filter: sample-app-prod
    ...
  

• Review before creating pull requests

  Inspect the pull request to ensure encrypted files are included. Verify everything is correct before clicking the Create pull request button.

3.2. Key Rotation

In case you need to rotate the AES key due to security reasons or a team member leaving the project, you can rotate the keys using the following command:

• Command to Rotate Keys

  git-secret-protector rotate-key <filter_name>
  

• This command will execute the following steps:

  • Generate a new AES data key in AWS Parameter Store
  • Re-encrypt your files associated with the specified filter with the new key
  • Update the local cache.

• Post-Rotation Code Reset

  After rotating the keys, it is necessary to clear the Git cache and re-checkout all files. This step ensures that the smudge filters are triggered, allowing the files to be decrypted with the new key.

  # Remove all files from the index to clear the Git cache
  git rm --cached -r .
  
  # Force Git to re-checkout all files, triggering smudge filters
  git reset --hard
  

4. Output Control

Three global flags control how the CLI produces output. They can be placed before or after the subcommand:

• --quiet - suppress success and info messages; errors are still printed to stderr and exit codes are unchanged.
• --verbose - emit internal log output to stderr for debugging.
• --json - output machine-readable JSON. Supported for status, doctor, version, and the action commands (setup-aes-key, pull-aes-key, rotate-key, encrypt-files, decrypt-files). Action commands emit an {ok, command, ...} envelope; bulk operations (encrypt-files, decrypt-files) include a counts object with totals. Note: --json is ignored for the git-invoked encrypt and decrypt filter commands because their stdout is the raw file payload.

git-secret-protector status --json
git-secret-protector doctor --json
git-secret-protector --quiet encrypt-files my-secrets
git-secret-protector --json status   # flag position before or after subcommand is equivalent

5. Logging

Logs are stored in the .git_secret_protector/logs/ directory by default, and you can configure the log level and file rotation in the config.ini file.

6. Encryption Scheme Versioning

git-secret-protector supports two encryption schemes:

• v1 (default) - unauthenticated AES-CBC. Readable by every client version, so new filters do not break teammates on installs older than 1.4.0.
• v2 - authenticated AES-256-CTR + HMAC-SHA256. Prefer this once all clients are on 1.4.0 or later.

The scheme a new key gets is resolved by precedence: --scheme flag > encryption_scheme in config.ini (v1|v2) > built-in default (v1). Decryption automatically handles both formats, so a v2 key still reads existing v1 files - migration is safe to perform at any time.

Setting the scheme when creating a key

By default, setup-aes-key creates a v1 key (widest cross-version compatibility):

git-secret-protector setup-aes-key <filter_name>

To create an authenticated v2 key (recommended once every client is on 1.4.0+):

git-secret-protector setup-aes-key <filter_name> --scheme v2

Or set the default for the whole repo in .git_secret_protector/config.ini:

[DEFAULT]
encryption_scheme = v2

SECURITY NOTE: the default v1 scheme is unauthenticated - an attacker with write access to the ciphertext can tamper with it without detection. v1 maximizes cross-version compatibility at the cost of tamper detection; switch to v2 (via --scheme v2 or encryption_scheme = v2) as soon as every client is on 1.4.0 or later, and migrate existing filters with upgrade-scheme (below).

Migrating a filter from v1 to v2

Once all clients on a repository are on 1.4.0 or later, run:

git-secret-protector upgrade-scheme <filter_name>

This command:

• Re-encrypts all files matched by the filter using v2.
• Updates the stored key blob so future encryptions also use v2.
• Is confirm-gated (use -y / --yes to skip the prompt in automation).
• Is idempotent - running it on an already-v2 filter is a no-op.
• Is one-way - there is no downgrade command.

Checking the active scheme

status shows the active scheme for each filter:

git-secret-protector status

doctor also shows the scheme and flags any v1 filter as a [WARN]:

git-secret-protector doctor

A filter using v1 is reported as [WARN] to prompt migration; a v2 filter reports [ OK ].

Development

Running Tests

• Unit Tests: Located in the tests/unit directory, run them using pytest.

  poetry run pytest tests/unit
  

• Integration Tests: Located in the tests/integration directory, these tests interact with Secret Store in cloud and should be run manually.

  poetry run pytest tests/integration
  

Changelog

See CHANGELOG.md for a history of changes and updates.

Troubleshooting

If you encounter any issues while using the git-secret-protector tool, try the following tips and solutions:

Common Issues

1. Filter Configuration Issues

If the filters are not configured correctly, you might encounter errors when encrypting or decrypting files.

• Solution: Re-setup the filters based on your .gitattributes file.

  git-secret-protector setup-filters
  

2. Missing or Incorrect AES Key

If you fail to encrypt or decrypt files due to a missing or incorrect AES key, you will need to ensure that the keys are correctly fetched from the Cloud Secret Storage Service.

• Solution: Pull the latest AES keys from the Cloud Secret Storage Service for the relevant filters.

  git-secret-protector pull-aes-key <filter_name>
  

3. Permissions Issues

Lack of necessary permissions can result in errors while accessing Cloud Secret Storage Services.

• Solution: Ensure that you have the required permissions to manage resources in your Cloud Secret Storage Service.

Example Issue: File Decryption Failure

Issue: You receive an error when trying to decrypt files using the decrypt-files command.

Solution:

• Ensure that you have pulled the latest AES keys:

  git-secret-protector pull-aes-key <filter_name>
  

• Check if the filters are correctly set up:

  git-secret-protector setup-filters
  

• Attempt to decrypt the files again:

  git-secret-protector decrypt-files <filter_name>
  

If the issue persists, verify your configurations in the config.ini file, and consult the logs located in the logs/ directory for more detailed error information.