Creds Vault 🔐

A secure command-line utility for sharing .env files across development teams using GitHub Gists with client-side AES-256 encryption.

🚀 Features

• 🔒 Client-side Encryption: AES-256 encryption with PBKDF2 key derivation
• 🆓 Free Storage: Uses GitHub Gists (no additional service costs)
• 👥 Team-friendly: Simple sharing via gist IDs
• 🛡️ Zero-knowledge: GitHub never sees your plaintext secrets
• 📁 Project-aware: Remembers vault configuration per project
• 🔐 Secure by Default: Restricted file permissions (600)

🛡️ Security Architecture

┌─────────────────┐    AES-256     ┌──────────────────┐    HTTPS    ┌─────────────┐
│   Local .env    │ ──────────────▶│  Encrypted Blob  │ ───────────▶│ GitHub Gist │
│   (plaintext)   │   Client-side  │   (ciphertext)   │             │  (private)  │
└─────────────────┘                └──────────────────┘             └─────────────┘

• Your secrets never leave your machine in plaintext
• Password-based encryption with 100,000 PBKDF2 iterations
• Salt-based security prevents rainbow table attacks
• Private GitHub Gists for encrypted storage

📦 Installation

Option 1: Install from PyPI (Recommended)

pip install creds-vault

Option 2: Install from Source

git clone https://github.com/mirzamudassir/creds-vault.git
cd creds-vault
make install

Option 3: Development Installation

git clone https://github.com/mirzamudassir/creds-vault.git
cd creds-vault
make install-dev

⚙️ Setup

1. GitHub Token Setup

Create a GitHub personal access token with gist scope:

1. Go to GitHub Settings → Tokens
2. Click "Generate new token (classic)"
3. Select only the gist scope
4. Copy the token

# Set environment variable
export GITHUB_TOKEN="ghp_your_token_here"

# Make it permanent
echo 'export GITHUB_TOKEN="ghp_your_token_here"' >> ~/.bashrc
source ~/.bashrc

2. Verify Installation

secrets --version
secrets --help

🔄 Usage

First-time Setup (Project Owner)

# Navigate to your project
cd my-awesome-project

# Create or edit your .env file
cat > .env << EOF
DATABASE_URL=postgresql://localhost:5432/myapp
API_KEY=sk-1234567890abcdef
STRIPE_SECRET=sk_test_xyz123
JWT_SECRET=super-secret-jwt-key
EOF

# Initialize encrypted vault
secrets init

# Output:
# ✅ Successfully initialized encrypted secrets vault
# 🔒 Content encrypted with AES-256
# 📝 Gist ID: xxxxxx
# 
# 📤 Share this command with your team:
#    secrets pull --gist-id xxxxxx
# 
# ⚠️  Important: Share the vault password securely!

Team Member Setup

# Navigate to project directory
cd my-awesome-project

# Pull secrets (replace with actual gist ID)
secrets pull --gist-id xxxxxx
# Enter vault password: ••••••••••

# ✅ Successfully pulled and decrypted .env
# 📝 Saved project configuration

Daily Workflow

# Check project status
secrets status

# Pull latest changes
secrets pull

# Make local changes to .env
echo "NEW_FEATURE_FLAG=true" >> .env

# Push changes to vault
secrets push

# Check what's configured
secrets status

📋 Command Reference

secrets init

Initialize encrypted vault with current .env file.

secrets init [--filename .env.local]

Options:

• --filename: Specify custom env file name (default: .env)

secrets push

Push local env file to vault.

secrets push [--filename .env.local]

Options:

• --filename: Specify custom env file name (default: .env)

secrets pull

Pull env file from vault.

secrets pull [--gist-id ID] [--filename .env] [--force]

Options:

• --gist-id: Gist ID (required for first-time setup)
• --filename: Custom filename (default: auto-detect)
• --force: Overwrite without confirmation

secrets status

Show project status and configuration.

secrets status

🏗️ Project Structure

After installation, your project will have:

your-project/
├── .env                     # Your secrets file
├── .gitignore              # Should include .env
└── (other project files)

~/.creds-vault/
└── config.json             # Project → gist mappings

🔒 Security Best Practices

Password Security

• Use strong passwords: Minimum 12 characters with mixed case, numbers, symbols
• Unique passwords: Don't reuse passwords from other services
• Secure sharing: Use password managers or secure channels to share vault passwords
• Regular rotation: Consider rotating vault passwords periodically

GitHub Token Security

• Minimal permissions: Only grant gist scope
• Regular rotation: Rotate tokens every 3-6 months
• Secure storage: Never commit tokens to code repositories
• Team vs individual: Consider using team-specific tokens for organizations

File Security

• Gitignore: Always add .env* to your .gitignore
• Permissions: Tool automatically sets secure permissions (600)
• Cleanup: Remove .env files when no longer needed

🚨 Security Considerations

✅ What's Protected

• Plaintext secrets: Never transmitted or stored in the cloud
• Man-in-the-middle: HTTPS protects data in transit
• GitHub breaches: Encrypted data remains secure
• Token compromise: Attackers only see encrypted blobs

⚠️ Limitations

• Password security: Vault security depends on password strength
• Local compromise: If your machine is compromised, local files are at risk
• Social engineering: Sharing passwords insecurely can compromise vaults
• GitHub availability: Service depends on GitHub being accessible

🏢 Compliance

• Development environments: Suitable for dev/staging secrets
• Production secrets: Consider dedicated secret management for production
• Audit requirements: Tool doesn't provide audit logs (GitHub does)
• Regulatory compliance: Evaluate against your specific requirements

🛠️ Development

Setup Development Environment

git clone https://github.com/mirzamudassir/creds-vault.git
cd creds-vault
make install-dev

Run Tests

make test

Code Quality

make lint          # Run linting
make format        # Format code
make check         # Lint + test

Build and Release

make build         # Build distribution
make publish       # Publish to PyPI

🔧 Advanced Usage

Custom Filenames

# Initialize with custom filename
secrets init --filename .env.production

# Push/pull custom files
secrets push --filename .env.local
secrets pull --filename .env.staging

Multiple Projects

The tool automatically manages different vaults per project:

cd project-a
secrets init        # Creates vault A

cd ../project-b  
secrets init        # Creates vault B

secrets status      # Shows project B config
cd ../project-a
secrets status      # Shows project A config

CI/CD Integration

# In CI/CD pipeline
export GITHUB_TOKEN="${{ secrets.GITHUB_TOKEN }}"
secrets pull --gist-id $VAULT_ID --force

🐛 Troubleshooting

Common Issues

"Invalid GitHub token"

# Check token is set
echo $GITHUB_TOKEN

# Verify token has gist scope
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user

"Project not initialized"

# Initialize new vault
secrets init

# Or link to existing vault
secrets pull --gist-id your-gist-id

"Decryption failed"

# Wrong password - try again
secrets pull

# Vault corrupted - contact vault creator

"File permission denied"

# Fix file permissions
chmod 600 .env

Debug Mode

# Enable verbose logging
export DEBUG=1
secrets status

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Start

git clone https://github.com/mirzamudassir/creds-vault.git
cd creds-vault
make install-dev
make test

Reporting Issues

• Bug Reports
• Feature Requests
• Security Issues

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• cryptography: For robust encryption primitives
• requests: For HTTP client functionality
• GitHub: For providing free Gist storage
• Python community: For excellent tooling and libraries

📚 Resources

• GitHub Gists Documentation
• OWASP Cryptographic Storage Cheat Sheet
• NIST Password Guidelines

---