enveloper

Background

[ KrebsOnSecurity, DockerHub/GitGuardian, Toyota/GitGuardian]

---

When developing software, there are often secrets that every developer or team need to deal with. These include:

• API keys
• API secrets
• Web passwords
• User-Ids
• User and Administrative Passwords
• Tokens
• Private endpoints
• File paths
• Universal Identifiers
• Authorization keys
• etc.

In some cases, these are inadvertently hard-coded into code, which is then pushed out to shared repositories. There are services to scan for these, but a recommended practice has been to place these in .env files.

[GitGuardian]

---

.env files are often excluded in .gitignore files so they don't get pushed out. But at build time, they can be loaded into the current environment (terminal, Docker, Lambdas, CI/CD instances). The problem is, if you move to a new machine, or want others to work on the code, they need to get a copy of the .env file so they can use these shared secrets.

Over time, these .env files themselves end up proliferating all over someone's computer, end up in logs, backups, or lost.

Lately, there's also the matter of AI-based agents with access to the local filesystem. Unless specifically excluded agents can access and read .env files, or send them to remote LLMs. Security company Wiz noticed that "AI-related secret instances constitute a disproportional majority of the findings (4 out of top 5 secrets found were AI-related)".

---

Enter enveloper

enveloper allows you to avoid .env files or hard-coded credentials by storing secrets in your own protected system keychain. These can be injected into a build session at runtime, without any risk of inadvertent release.

Local keychains work well for individuals. But what about sharing secrets? Fortunately, cloud-based services have already solved this problem, by offering Secret Managers or Vaults stored in cryptographically secure locations.

enveloper lets you store all your secrets in your local keychain or cloud-based secret managers, and easily move them back and forth or share them without having to leave any data in the open.

Manage environment secrets via your system keychain or cloud secret stores. Don't leave exposed .env files laying about your filesystem.

---

Installation

pip install enveloper            # CLI only
pip install enveloper[sdk]       # CLI + SDK (load_dotenv / dotenv_values)
pip install enveloper[all]       # CLI + SDK + all cloud backends

Quick Start

# Sample .env file

# Import an existing .env file into the keychain
enveloper import sample.env --domain dev --project Enveloper

# List what's stored

enveloper list key --domain dev --project Enveloper

# Load local environment settings from keychain

eval "$(enveloper --domain dev --project Enveloper export --format unix)"

# Values are loaded into local environment variables. 
# Use in Makefile, shell scripts, etc. 
# 'unix' format works for Linux, Mac, and Windows WSL. 
# For Windows Powershell, use 'win' as format.

# When done, you can use 'unexport' command to remove the set of env variables

eval "$(enveloper --domain dev --project Enveloper unexport --format unix)"

# Push to cloud service

enveloper --domain dev --project Enveloper push --service aws

In the console, we can verify that the values are stored (in the case of AWS, in the SSM Parameter Store)

# Verify that they got pushed in AWS console for System Store > Parameters

enveloper list key --domain dev --project Enveloper --service aws

# Pull from AWS SSM into local keychain

enveloper pull --domain dev --project Enveloper --service aws

# Clear environment settings
enveloper clear --domain dev --project Enveloper --service aws

Multiple cloud services

Amazon Web Services (aws)

Google Cloud (gcp)

Microsoft Azure Cloud (azure)

Hashicorp Vault (vault)

Features

• Backward compatible with .env files.
• Store values in local keychains (Mac, Linux, Windows), or cloud service secret stores (see below).
• Work with individual environment variables or sets.
• Versioning of environment values using Semantic Versioning.
• Use in build chains (Make, Gradle, etc.) or CI/CD, including Github Actions.
• Support for hierarchical settings via domain and project sets.

Supported Backends

Backend	Description
Local Keychain	MacOS Keychain, Linux Secret Service, Windows Credential Locker
File	Plain .env files
AWS SSM	AWS Systems Manager Parameter Store
Vault	HashiCorp Vault KV v2
GCP	Google Cloud Secret Manager
Azure	Azure Key Vault
Alibaba	Alibaba Cloud KMS Secrets Manager (untested)
GitHub	GitHub Actions secrets (coming soon)

Documentation

• Step-by-Step Tutorial - From sample.env to keychain, builds, and cloud
• CLI Reference - All commands and options
• Technical Details - Architecture and internals
• Local Keychain - OS keychain setup and usage
• Cloud Storage - Cloud service configuration
• Cloud Setup Guide - Azure, GCP, and AWS setup (credentials, IAM/RBAC, testing)
• Versioning - Semantic versioning for secrets
• JSON/YAML - Import/export in JSON and YAML formats
• SDK - Python SDK for load_dotenv / dotenv_values
• Project Config - .enveloper.toml configuration
• Config/Env Overrides - Priority order for settings
• Service Backend - Backend selection and configuration
• CI/CD Integration - GitHub Actions, CodeBuild, GitLab CI
• Makefile Integration - Build system integration
• Other Projects - Comparison with similar tools
• Development - Contributing and development
• Adding Stores - Creating custom store plugins
• Publishing - Publishing to PyPI
• Security - Secure data storage and access control
• Disclosures - Disclosures and confessions
• License - AGPL-3.0-or-later

License

GNU AGPL v3.0 or later