diff --git a/README.md b/README.md index dfb7603..6726377 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,25 @@ pip install envcloak[dev] ## ๐Ÿš€ Example Workflow +> โ„น๏ธ More examples are present in [examples](./examples) section. + +### Generating key: + +```bash +# With password and salt +envcloak generate-key-from-password --password "YourTopSecretPassword" \ +--salt "e3a1c8b0d4f6e2c7a5b9d6f0cr2ad1a2" --output secretkey.key + +# With password without salt (we will add random salt then) +envcloak generate-key-from-password --password "YourTopSecretPassword" --output secretkey.key + +# From random password and salt +envcloak generate-key --output secretkey.key +``` +> **What it does:** generates your private key used to encrypt and decrypt files. **Appends (or creates if needed) .gitignore as well** as super-hero should! ๐ŸŽ‰ + +> โš  **If someone knows your password and salt (option 1) can recreate same key.** โš  + ### Encrypting Variables: ```bash @@ -41,7 +60,6 @@ envcloak decrypt --input .env.enc --output .env --key-file mykey.key ``` > **What it does:** Decrypts the `.env.enc` file back to `.env` using the same key. Voilร ! - or you may want to use it ... ### ๐Ÿ In Your Python Code diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..21377ce --- /dev/null +++ b/examples/README.md @@ -0,0 +1,20 @@ +# EnvCloak Examples ๐Ÿ“˜ + +Explore practical examples for using EnvCloak in different scenarios: + +## ๐Ÿ“‚ CLI Examples +Navigate to [CLI Examples](./cli/README.md) for usage instructions and examples of using EnvCloak via the command-line interface (CLI). Perfect for quick manual operations and scripts. + +--- + +## ๐Ÿ“‚ In-Code Examples +Visit [In-Code Examples](./in_code/README.md) to learn how to use EnvCloak in Python code. Includes examples for securely loading and managing encrypted environment variables programmatically. + +--- + +## ๐Ÿ“‚ Workflow Examples +Check out [Workflow Examples](./workflow/README.md) for guidance on integrating EnvCloak into CI/CD pipelines. Covers popular platforms like GitHub Actions, GitLab CI/CD, Jenkins, and Azure Pipelines. + +--- + +**Need more help?** Visit the main [README](../README.md) for an overview of EnvCloak features. diff --git a/examples/cli/README.md b/examples/cli/README.md new file mode 100644 index 0000000..2927d4c --- /dev/null +++ b/examples/cli/README.md @@ -0,0 +1,118 @@ +# EnvCloak: CLI examples + +EnvCloak simplifies managing sensitive environment variables by encrypting and decrypting .env files securely. It supports generating encryption keys, encrypting/decrypting files, and rotating keys efficiently. Designed for developers and CI/CD pipelines, EnvCloak is the security superhero your project needs! ๐Ÿ›ก๏ธ + +## Usage + +### Key Generation + +#### 1. Generate a Key from a Password and Salt + +```bash +envcloak generate-key-from-password --password "YourTopSecretPassword" \ +--salt "e3a1c8b0d4f6e2c7a5b9d6f0cr2ad1a2" --output secretkey.key +``` + +**Description:** Derives a key from a password and a salt. The salt ensures uniqueness, preventing duplicate keys from identical passwords. +**By default:** +* If a `.gitignore` exists, it appends the key file name to it. +* If `.gitignore` doesn't exist, it creates one and includes the key file name. + +> **Not recommended:** you may bypass this by additional flag `--no-gitignore`. โš  + +#### 2. Generate a Key from a Password Without a Salt + +```bash +envcloak generate-key-from-password --password "YourTopSecretPassword" --output secretkey.key +``` + +**Description:** Derives a key from a password and a randomly generated salt. The salt is stored for future use. +**By default:** +* If a `.gitignore` exists, it appends the key file name to it. +* If `.gitignore` doesn't exist, it creates one and includes the key file name. + +> **Not recommended:** you may bypass this by additional flag `--no-gitignore`. โš  + +#### 3. Generate a Random Key + +```bash +envcloak generate-key --output secretkey.key +``` + +**Description:** Creates a random encryption key. +**By default:** +* If a `.gitignore` exists, it appends the key file name to it. +* If `.gitignore` doesn't exist, it creates one and includes the key file name. + +> **Not recommended:** you may bypass this by additional flag `--no-gitignore`. โš  + +### Encrypting Variables + +```bash +envcloak encrypt --input .env --output .env.enc --key-file mykey.key +``` + +**Description:** Encrypts your `.env` file into `.env.enc`. The original file remains unchanged. + +### Decrypting Variables + +```bash +envcloak decrypt --input .env.enc --output .env --key-file mykey.key +``` + +**Description:** Decrypts `.env.enc` back to `.env`. Ensure the `key-file` used matches the one from the encryption step. + +### Rotating Keys + +```bash +envcloak rotate-keys --input .env.enc --old-key-file oldkey.key \ +--new-key-file newkey.key --output .env.enc.new +``` + +**Description:** Re-encrypts an encrypted file with a new key, ensuring minimal disruption when rotating encryption keys. + +## Use Cases + +### 1. Secure Environment Variables in CI/CD Pipelines + +Problem: Sharing sensitive data like API keys or database credentials in a CI/CD pipeline. +Solution: Use EnvCloak to encrypt .env files during deployment: + +1. Before commit +```bash +# Generate key +envcloak generate-key --output secretkey.key +# Encrypt sensitive data +envcloak encrypt --input .env --output .env.enc --key-file secretkey.key +git add .env.enc +git commit -m "Secure .env file" +``` +2. During build/deploy +```bash +# Decrypt for normal use +envcloak decrypt --input .env.enc --output .env --key-file secretkey.key +``` +> You must provide `secretkey.key` in CI/CD workflow in secure way. + +The decrypted `.env` file is ready for use in your application. + +### 2. Setting Up a New Project + +Problem: Sharing initial credentials and configurations with your team securely. +Solution: Encrypt the `.env` file before distributing: + +1. Generate key +```bash +envcloak generate-key --output myproject.key +``` +2. Encrypt sensitive data +```bash +envcloak encrypt --input .env --output .env.enc --key-file myproject.key +``` +Distribute the `.env.enc` file and keep the `myproject.key` secure. + +## Best Practices + +* Never commit keys: Always use `.gitignore` to exclude `key` files. +* Secure `password`s and `salt`s: Treat them as sensitive as the `key`s themselves. +* Automate `encryption`/`decryption`: Include EnvCloak commands in CI/CD pipelines or scripts for consistency. \ No newline at end of file diff --git a/examples/in_code/README.md b/examples/in_code/README.md new file mode 100644 index 0000000..cf112ea --- /dev/null +++ b/examples/in_code/README.md @@ -0,0 +1,49 @@ +# EnvCloak: In code examples + +EnvCloak can be easily integrated into your Python application to securely load encrypted environment variables directly into your os.environ. Here's how you can do it: + +## Installation + +Ensure you have EnvCloak installed: +```bash +pip install envcloak +``` + +## Loading Encrypted Variables in Code + +```python +import os +from envcloak import load_encrypted_env + +# Load encrypted environment variables from a file +load_encrypted_env('path/to/your/env.enc', key_file='path/to/your/key.key').to_os_env() + +# Now os.environ contains the decrypted variables +print("DB_USERNAME:", os.getenv("DB_USERNAME")) +print("DB_PASSWORD:", os.getenv("DB_PASSWORD")) + +``` + +you may test it on our `mock` data: + +```python +# test.py file in this dir +import os +from envcloak import load_encrypted_env + +load_encrypted_env('tests/mock/variables.env.enc', key_file='tests/mock/mykey.key').to_os_env() +# Now os.environ contains the decrypted variables + +# Check if specific variables are in os.environ +print("DB_USERNAME:", os.getenv("DB_USERNAME")) +print("DB_PASSWORD:", os.getenv("DB_PASSWORD")) +``` + +## Use Cases + +* **Secure Application Configurations:** Load sensitive variables (e.g., API keys, database credentials) without exposing them in plaintext files. +* **Seamless CI/CD Integration:** Securely handle environment variables in automated pipelines. + +--- + +`EnvCloak` makes managing sensitive configurations both simple and secure! ๐ŸŒŸ \ No newline at end of file diff --git a/examples/in_code/test.py b/examples/in_code/test.py new file mode 100644 index 0000000..939e4e7 --- /dev/null +++ b/examples/in_code/test.py @@ -0,0 +1,9 @@ +import os +from envcloak import load_encrypted_env + +load_encrypted_env('tests/mock/variables.env.enc', key_file='tests/mock/mykey.key').to_os_env() +# Now os.environ contains the decrypted variables + +# Check if specific variables are in os.environ +print("DB_USERNAME:", os.getenv("DB_USERNAME")) +print("DB_PASSWORD:", os.getenv("DB_PASSWORD")) \ No newline at end of file diff --git a/examples/workflow/README.md b/examples/workflow/README.md new file mode 100644 index 0000000..02d8ba5 --- /dev/null +++ b/examples/workflow/README.md @@ -0,0 +1,208 @@ +# Using EnvCloak in CI/CD Workflows for Decryption + +EnvCloak simplifies the secure management of sensitive environment variables. In CI/CD workflows, the encrypted `.env.enc` file is typically created and committed manually, while the decryption happens automatically during deployment or application startup. This guide focuses on **decrypting variables** in workflows using both the `envcloak` CLI and Python code. + +--- + +## Key Handling: Securely Storing `ENVCLOAK_KEY_B64` + +The variable `ENVCLOAK_KEY_B64` is a **Base64-encoded string of the encryption key**. This encoding ensures the key's binary content can be safely stored in plaintext-compatible fields, such as CI/CD secrets. It should be stored securely using your CI/CD platformโ€™s secrets management (e.g., GitHub Secrets, Jenkins Credentials, GitLab Vault). + +### **How to Generate `ENVCLOAK_KEY_B64`** + +1. Encode the key file to Base64: + ``` + base64 mykey.key > mykey.key.b64 + ``` + +2. Copy the Base64 string from `mykey.key.b64` and store it as `ENVCLOAK_KEY_B64` in your CI/CD secrets. + +--- + +## Workflow Examples: Decrypting Variables + +### **GitHub Actions: Decrypt Variables with CLI Commands** + +```yaml +name: Deploy Application + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + - name: Checkout Code + uses: actions/checkout@v3 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: 3.9 + + - name: Install EnvCloak + run: pip install envcloak + + - name: Decrypt Environment Variables + env: + ENVCLOAK_KEY_B64: ${{ secrets.ENVCLOAK_KEY_B64 }} + run: | + echo "$ENVCLOAK_KEY_B64" | base64 --decode > mykey.key + envcloak decrypt --input .env.enc --output .env --key-file mykey.key + + - name: Run Application + run: | + export $(cat .env | xargs) + python app.py +``` + +--- + +### **GitLab CI/CD: Decrypt Variables** + +```yaml +stages: + - deploy + +deploy_app: + stage: deploy + image: python:3.9 + before_script: + - pip install envcloak + script: + - echo "$ENVCLOAK_KEY_B64" | base64 --decode > mykey.key + - envcloak decrypt --input .env.enc --output .env --key-file mykey.key + - export $(cat .env | xargs) + - python app.py +``` + +--- + +### **Jenkins Pipeline: Decrypt Variables with CLI** + +```groovy +pipeline { + agent any + + environment { + ENVCLOAK_KEY_B64 = credentials('jenkins-envcloak-key-b64') // Store Base64 key in Jenkins credentials + } + + stages { + stage('Setup') { + steps { + script { + sh 'pip install envcloak' + sh 'echo ${ENVCLOAK_KEY_B64} | base64 --decode > mykey.key' + } + } + } + stage('Decrypt Variables') { + steps { + script { + sh 'envcloak decrypt --input path/to/.env.enc --output .env --key-file mykey.key' + } + } + } + stage('Run Application') { + steps { + script { + sh 'export $(cat .env | xargs)' + sh 'python app.py' + } + } + } + } +} +``` + +--- + +### **Azure Pipelines: Decrypt Variables** + +```yaml +trigger: + branches: + include: + - main + +jobs: +- job: Deploy + displayName: Deploy Application + pool: + vmImage: 'ubuntu-latest' + steps: + - task: UsePythonVersion@0 + inputs: + versionSpec: '3.x' + - script: | + pip install envcloak + echo "$ENVCLOAK_KEY_B64" | base64 --decode > mykey.key + envcloak decrypt --input .env.enc --output .env --key-file mykey.key + export $(cat .env | xargs) + python app.py + displayName: Decrypt and Run Application +``` + +--- + +## Using EnvCloak in Python Code + +### **GitHub Actions: Using Python Code for Decryption** + +```yaml +name: Deploy Application with Python + +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + - name: Checkout Code + uses: actions/checkout@v3 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: 3.9 + + - name: Install Dependencies + run: pip install envcloak + + - name: Run Application with Decrypted Variables + env: + ENVCLOAK_KEY_B64: ${{ secrets.ENVCLOAK_KEY_B64 }} + run: | + echo "$ENVCLOAK_KEY_B64" | base64 --decode > mykey.key + python -c " + from envcloak import load_encrypted_env; + load_encrypted_env('.env.enc', key_file='mykey.key').to_os_env() + " + python app.py +``` + +--- + +## Best Practices + +1. **Base64-Encode Keys**: + - Binary keys may contain non-printable characters. Always encode them to Base64 before storing them in secrets. + +2. **Secure Secrets Storage**: + - Store `ENVCLOAK_KEY_B64` in your CI/CD platformโ€™s secrets management (e.g., GitHub Secrets, Jenkins Credentials, GitLab Vault). + +3. **Automate Decryption**: + - Automate the decryption process in your pipeline to securely load sensitive variables. + +--- + +`EnvCloak` provides a secure and flexible approach to managing encrypted environment variables in workflows using both CLI commands and Python code. ๐ŸŒŸ