🔐 Vault Inject

Secure environment variable injection from Hashicorp Vault
A powerful CLI tool that retrieves secrets from Vault KV engines and injects them as environment variables into your applications.

✨ Features

• 🔒 Secure Secret Management - Retrieve secrets from Hashicorp Vault KV v2 engines
• 🚀 Zero-Config Injection - Automatically inject secrets as environment variables
• 🎯 Flexible Command Execution - Run any command with injected secrets
• 🔍 Verbose Mode - Preview secrets before injection (with security masking)
• 🐛 Debug Support - Comprehensive debugging and error reporting
• ⚡ Fast & Lightweight - Built with TypeScript for performance and reliability
• 🛡️ Security First - Sensitive values are masked in verbose output

📦 Installation

Global Installation (Recommended)

npm install -g vault-inject

Local Installation

npm install vault-inject

Development Installation

git clone https://github.com/AmirGhiassian/vault-inject.git
cd vault-inject
npm install
npm run build

🚀 Quick Start

1. Configure Vault Access

# Set environment variables
export VAULT_ADDR="https://vault.company.com"
export VAULT_TOKEN="your-vault-token"

# Or create a .env file
echo "VAULT_ADDR=https://vault.company.com" > .env
echo "VAULT_TOKEN=your-vault-token" >> .env

2. Store Secrets in Vault

# Enable KV v2 engine (if not already enabled)
vault secrets enable -path=secret kv-v2

# Store application secrets
vault kv put secret/my-app/config \
  DATABASE_URL="postgresql://user:pass@localhost:5432/mydb" \
  API_KEY="sk-1234567890abcdef" \
  JWT_SECRET="super-secret-jwt-key"

3. Run Your Application

# Inject secrets and run your app
vault-inject -k secret -p my-app/config -- node app.js

# Or with explicit parameters
vault-inject \
  --endpoint https://vault.company.com \
  --token your-vault-token \
  --kv-engine secret \
  --path my-app/config \
  -- node app.js

📖 Usage

Basic Syntax

vault-inject [options] <command> [args...]

Command Line Options

| Option | Short | Description | Required | Default | |--------|-------|-------------|----------|---------| | --endpoint | -e | Vault server endpoint URL | No | http://127.0.0.1:8200 | | --token | -t | Vault authentication token | No* | $VAULT_TOKEN | | --kv-engine | -k | KV engine name | Yes | - | | --path | -p | Secret path within KV engine | Yes | - | | --verbose | -v | Show environment variables before injection | No | false | | --ca-cert | - | Path to CA certificate file | No | - | | --client-cert | - | Path to client certificate file | No | - | | --client-key | - | Path to client private key file | No | - | | --tls-skip-verify | - | Skip TLS certificate verification (development only) | No | false | | --debug | - | Enable debug logging | No | false | | --help | -h | Display help information | No | - | | --version | -V | Display version number | No | - |

*Required if VAULT_TOKEN environment variable is not set.

Environment Variables

| Variable | Description | Example | |----------|-------------|---------| | VAULT_ADDR | Vault server endpoint | https://vault.company.com | | VAULT_TOKEN | Vault authentication token | hvs.abc123... |

💡 Examples

Node.js Applications

# Basic Node.js app
vault-inject -k secret -p production/api -- npm start

# Express.js with custom port
vault-inject -k config -p staging/web -- node server.js --port 3000

# Next.js application
vault-inject -k secrets -p prod/nextjs -- npm run build

Python Applications

# Django application
vault-inject -k config -p production/django -- python manage.py runserver

# Flask with custom environment
vault-inject -k secrets -p staging/flask -- python app.py --env production

# FastAPI application
vault-inject -k api -p prod/fastapi -- uvicorn main:app --host 0.0.0.0

Docker & Containerization

# Docker Compose
vault-inject -k secrets -p prod/docker -- docker-compose up -d

# Docker run
vault-inject -k config -p staging/app -- docker run -p 8080:8080 myapp:latest

# Kubernetes (via kubectl)
vault-inject -k k8s -p production/cluster -- kubectl apply -f deployment.yaml

Database Operations

# PostgreSQL migrations
vault-inject -k db -p prod/postgres -- psql -h localhost -d mydb -f migrate.sql

# MySQL operations
vault-inject -k database -p staging/mysql -- mysql -u root -p mydb < backup.sql

# MongoDB operations
vault-inject -k nosql -p prod/mongodb -- mongo mydb --eval "db.users.find()"

Development & Testing

# Run tests with secrets
vault-inject -k test -p dev/secrets -- npm test

# Linting with environment
vault-inject -k config -p dev/lint -- npm run lint

# Build with production secrets
vault-inject -k secrets -p prod/build -- npm run build:prod

Verbose Mode Examples

# Preview secrets before injection
vault-inject -v -k secret -p my-app/config -- echo "Secrets loaded"

# Debug mode with verbose output
vault-inject --debug -v -k config -p staging/api -- node app.js

🔧 Advanced Usage

Multiple Secret Paths

# Load from different paths sequentially
vault-inject -k secret -p app/database -- \
  vault-inject -k secret -p app/redis -- \
  node app.js

Custom Vault Endpoints

# Different Vault instances
vault-inject -e https://vault-dev.company.com -k dev -p config -- node app.js
vault-inject -e https://vault-prod.company.com -k prod -p config -- node app.js

Environment-Specific Configurations

# Development
vault-inject -k config -p dev/app -- npm run dev

# Staging
vault-inject -k config -p staging/app -- npm run start:staging

# Production
vault-inject -k config -p prod/app -- npm run start:prod

TLS Certificate Configuration

# Using custom CA certificate
vault-inject --ca-cert /path/to/ca.pem -k secret -p config -- node app.js

# Using client certificates for mutual TLS
vault-inject \
  --ca-cert /path/to/ca.pem \
  --client-cert /path/to/client.pem \
  --client-key /path/to/client.key \
  -k secret -p config -- node app.js

# Skip TLS verification (development only)
vault-inject --tls-skip-verify -k secret -p config -- node app.js

# Combine with custom endpoint
vault-inject \
  -e https://vault.company.com \
  --ca-cert /etc/ssl/certs/company-ca.pem \
  -k secret -p prod/config -- node app.js

🛠️ Development

Prerequisites

• Node.js 16+
• npm 7+
• TypeScript 5.9+
• Hashicorp Vault (for testing)

Setup Development Environment

# Clone repository
git clone https://github.com/AmirGhiassian/vault-inject.git
cd vault-inject

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

# Test the CLI
node index.ts --help

Available Scripts

npm run build      # Compile TypeScript to JavaScript
npm run start      # Run the application with ts-node
npm run dev        # Run with file watching for development
npm test           # Run tests (when implemented)

Project Structure

vault-inject/
├── index.ts           # Main CLI application
├── tsconfig.json      # TypeScript configuration
├── package.json       # Package configuration
├── README.md          # This documentation
├── example.env        # Example environment file
└── dist/              # Compiled JavaScript output

🔒 Security Considerations

Token Management

• Never commit tokens to version control
• Use environment variables or secure secret management
• Rotate tokens regularly
• Use least-privilege access policies

Secret Masking

• Verbose mode automatically masks sensitive values
• Only first 4 and last 4 characters are shown
• Use --debug for troubleshooting (shows full configuration)

Network Security

• Use HTTPS endpoints in production
• Consider Vault's TLS certificate validation
• Use proper firewall rules for Vault access

Best Practices

# ✅ Good: Use environment variables
export VAULT_TOKEN=$(vault write -field=token auth/approle/login role_id=my-role)

# ✅ Good: Use .env files (not committed)
echo "VAULT_TOKEN=your-token" > .env

# ❌ Bad: Hardcode tokens
vault-inject -t "hardcoded-token" -k secret -p config -- node app.js

🐛 Troubleshooting

Common Issues

Connection Refused

# Check Vault server status
curl -s $VAULT_ADDR/v1/sys/health

# Verify endpoint URL
vault-inject --debug -e http://localhost:8200 -k secret -p config -- echo "test"

Authentication Failed

# Verify token validity
vault token lookup

# Check token permissions
vault token capabilities secret/data/my-app/config

Secret Not Found

# List available secrets
vault kv list secret/

# Check specific path
vault kv get secret/my-app/config

Permission Denied

# Check policy permissions
vault policy read my-policy

# Verify token has correct policy
vault token capabilities secret/data/my-app/config

Debug Mode

# Enable debug logging
vault-inject --debug -k secret -p config -- node app.js

# Verbose output with debug
vault-inject -v --debug -k secret -p config -- node app.js

Error Codes

| Code | Description | Solution | |------|-------------|----------| | 1 | General error | Check logs for specific error message | | 2 | Invalid arguments | Verify command line options | | 3 | Vault connection failed | Check Vault server and network | | 4 | Authentication failed | Verify token and permissions | | 5 | Secret not found | Check KV engine and path |

🤝 Contributing

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

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests (if applicable)
5. Submit a pull request

📄 License

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

🙏 Acknowledgments

• Hashicorp Vault for secure secret management
• Commander.js for CLI framework
• node-vault for Vault client library

📞 Support

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📧 Contact: GitHub Profile

Made with ❤️ by Amir Ghiassian