297 lines
7.7 KiB
Markdown
297 lines
7.7 KiB
Markdown
# Env Guard
|
|
|
|
A powerful Rust CLI tool that automatically detects, validates, and secures environment variables across different environments.
|
|
|
|
[](https://7000pct.gitea.bloupla.net/7000pctAUTO/env-guard/actions)
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://www.rust-lang.org)
|
|
|
|
## Features
|
|
|
|
- **Auto-detect missing env vars**: Scan .env files and compare against expected variables defined in schema files
|
|
- **Format validation**: Validate URLs, emails, UUIDs, API keys, database connections, JWTs, and more
|
|
- **Generate .env.example**: Create template files with descriptive placeholder values
|
|
- **Secret detection**: Scan source code for accidentally committed secrets (AWS keys, tokens, passwords)
|
|
- **Framework integration**: Auto-detect frameworks (Next.js, Rails, Django, Express, etc.)
|
|
- **CI/CD ready**: Perfect for pre-commit hooks and deployment pipelines
|
|
|
|
## Installation
|
|
|
|
### From Source
|
|
|
|
```bash
|
|
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/env-guard.git
|
|
cd env-guard
|
|
cargo build --release
|
|
./target/release/env-guard --help
|
|
```
|
|
|
|
### Using Cargo
|
|
|
|
```bash
|
|
cargo install env-guard
|
|
env-guard --help
|
|
```
|
|
|
|
### Pre-built Binaries
|
|
|
|
Download pre-built binaries from the [Releases](https://7000pct.gitea.bloupla.net/7000pctAUTO/env-guard/releases) page.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Check your .env file for issues
|
|
env-guard check --path .env
|
|
|
|
# Validate all environment variables
|
|
env-guard validate --path .env
|
|
|
|
# Generate a .env.example template
|
|
env-guard generate --path .env --output .env.example
|
|
|
|
# Scan for accidentally committed secrets
|
|
env-guard secrets --path .
|
|
|
|
# Initialize for a specific framework
|
|
env-guard init --framework nextjs
|
|
```
|
|
|
|
## Commands
|
|
|
|
### scan
|
|
|
|
Scan .env files and compare against expected variables.
|
|
|
|
```bash
|
|
env-guard scan --path . --schema .env.schema.json
|
|
```
|
|
|
|
Options:
|
|
- `-p, --path PATH`: Path to scan for .env files (default: ".")
|
|
- `-s, --schema FILE`: Path to schema file
|
|
|
|
### validate
|
|
|
|
Validate format of environment variable values.
|
|
|
|
```bash
|
|
env-guard validate --path .env --strict
|
|
```
|
|
|
|
Options:
|
|
- `-p, --path FILE`: Path to .env file (default: ".env")
|
|
- `-S, --strict`: Enable strict validation (fail on any error)
|
|
|
|
### generate
|
|
|
|
Generate .env.example file from .env.
|
|
|
|
```bash
|
|
env-guard generate --path .env --output .env.example
|
|
```
|
|
|
|
Options:
|
|
- `-p, --path FILE`: Path to .env file (default: ".env")
|
|
- `-o, --output FILE`: Output file path (default: ".env.example")
|
|
|
|
### secrets
|
|
|
|
Scan source code for accidentally committed secrets.
|
|
|
|
```bash
|
|
env-guard secrets --path . --strict
|
|
```
|
|
|
|
Options:
|
|
- `-p, --path PATH`: Path to scan for secrets (default: ".")
|
|
- `-S, --strict`: Enable strict secret detection (fail if any secrets found)
|
|
|
|
### init
|
|
|
|
Initialize env-guard with framework detection.
|
|
|
|
```bash
|
|
env-guard init --framework nextjs --path .
|
|
```
|
|
|
|
Options:
|
|
- `-f, --framework FRAMEWORK`: Framework to use (nextjs, rails, django, node)
|
|
- `-p, --path PATH`: Path to project directory (default: ".")
|
|
|
|
### check
|
|
|
|
Check .env file for common issues.
|
|
|
|
```bash
|
|
env-guard check --path .env
|
|
```
|
|
|
|
Options:
|
|
- `-p, --path FILE`: Path to .env file (default: ".env")
|
|
|
|
## Framework Support
|
|
|
|
Env Guard auto-detects the following frameworks by scanning for configuration files:
|
|
|
|
| Framework | Detected By | Key Variables |
|
|
|-----------|-------------|---------------|
|
|
| Next.js | `next.config.js`, `package.json` | `NEXT_PUBLIC_*`, `NEXTAUTH_*` |
|
|
| Ruby on Rails | `Gemfile`, `config.ru` | `DATABASE_URL`, `SECRET_KEY_BASE` |
|
|
| Django | `manage.py`, `requirements.txt` | `SECRET_KEY`, `DEBUG`, `ALLOWED_HOSTS` |
|
|
| Express.js | `package.json` with "express" | `PORT`, `MONGODB_URI`, `JWT_SECRET` |
|
|
| Spring Boot | `pom.xml`, `build.gradle` | `SPRING_DATASOURCE_*`, `SERVER_PORT` |
|
|
| Laravel | `composer.json`, `artisan` | `APP_*`, `DB_*` |
|
|
| Flask | `app.py`, `requirements.txt` | `FLASK_*`, `SECRET_KEY` |
|
|
| NestJS | `package.json` with "@nestjs/core" | `PORT`, `DATABASE_URL`, `JWT_SECRET` |
|
|
| Go Fiber | `go.mod` with "gofiber" | `PORT`, `DATABASE_URL` |
|
|
| Phoenix | `mix.exs` | `DATABASE_URL`, `SECRET_KEY` |
|
|
|
|
## Configuration
|
|
|
|
### Schema File (.env.schema.json)
|
|
|
|
Define expected environment variables with types and validation:
|
|
|
|
```json
|
|
{
|
|
"$schema": "https://json.env-guard/schema/v1",
|
|
"framework": "nextjs",
|
|
"variables": [
|
|
{
|
|
"key": "DATABASE_URL",
|
|
"required": true,
|
|
"type": "database_url",
|
|
"description": "PostgreSQL connection string",
|
|
"default": "postgresql://localhost:5432/dbname"
|
|
},
|
|
{
|
|
"key": "API_KEY",
|
|
"required": true,
|
|
"type": "api_key",
|
|
"description": "External API key"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Validation Types
|
|
|
|
| Type | Description | Example |
|
|
|------|-------------|---------|
|
|
| `url` | Valid HTTP/HTTPS URL | `https://api.example.com` |
|
|
| `email` | Valid email format | `user@example.com` |
|
|
| `uuid` | UUID v4 format | `550e8400-e29b-41d4-a716-446655440000` |
|
|
| `api_key` | Generic API key (min 16 chars) | `sk_live_abc123...` |
|
|
| `boolean` | true/false, yes/no, 1/0 | `true` |
|
|
| `integer` | Whole numbers | `3000` |
|
|
| `database_url` | Database connection strings | `postgresql://user:pass@localhost:5432/db` |
|
|
| `jwt` | JWT token format | `eyJhbG...` |
|
|
| `aws_key` | AWS access key ID | `AKIAIOSFODNN7EXAMPLE` |
|
|
| `github_token` | GitHub PAT format | `ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx` |
|
|
| `slack_webhook` | Slack webhook URL | `https://hooks.slack.com/services/T...` |
|
|
|
|
## Secret Detection
|
|
|
|
Env Guard scans for the following secret patterns:
|
|
|
|
- **Critical**: AWS Access Keys, GitHub Tokens, OpenAI Keys, Stripe Keys, Private Keys, JWTs
|
|
- **High**: Slack Bot Tokens, Google API Keys
|
|
- **Medium**: Slack Webhook URLs
|
|
|
|
Example output:
|
|
```
|
|
Scanning for secrets in: .
|
|
|
|
CRITICAL - 2 found:
|
|
[CRITICAL] AWS Access Key ID (line 42): AKIAIOSFODNN7EXAMPLE
|
|
-> Rotate this AWS access key immediately and remove from code
|
|
[CRITICAL] GitHub Personal Access Token (line 15): ghp_xxxxxxxxxxxxxxxx...
|
|
-> Revoke this GitHub token and use a new one
|
|
|
|
Total secrets found: 2
|
|
```
|
|
|
|
## CI/CD Integration
|
|
|
|
### GitHub Actions
|
|
|
|
```yaml
|
|
name: Env Validation
|
|
|
|
on: [push, pull_request]
|
|
|
|
jobs:
|
|
env-guard:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
- name: Install env-guard
|
|
run: cargo install env-guard
|
|
- name: Check for secrets
|
|
run: env-guard secrets --path . --strict
|
|
- name: Validate env vars
|
|
run: env-guard validate --path .env --strict
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Basic Usage
|
|
|
|
```bash
|
|
# Generate a .env.example from existing .env
|
|
env-guard generate --path .env --output .env.example
|
|
|
|
# Validate your .env file
|
|
env-guard validate --path .env
|
|
|
|
# Check for secrets in your codebase
|
|
env-guard secrets --path . --strict
|
|
|
|
# Initialize for a new project
|
|
env-guard init --framework nextjs
|
|
|
|
# Scan for missing required variables
|
|
env-guard scan --path . --schema .env.schema.json
|
|
```
|
|
|
|
### Strict Mode for CI
|
|
|
|
```bash
|
|
# Fail CI if secrets are found
|
|
env-guard secrets --path . --strict
|
|
|
|
# Validate env vars and fail on any error
|
|
env-guard validate --path .env --strict
|
|
```
|
|
|
|
## Development
|
|
|
|
### Building
|
|
|
|
```bash
|
|
cargo build --release
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
cargo test
|
|
cargo clippy
|
|
```
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
3. Commit your changes (`git commit -m 'Add amazing feature'`)
|
|
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
5. Open a Pull Request
|
|
|
|
## License
|
|
|
|
MIT License - see [LICENSE](LICENSE) file for details.
|
|
|
|
## Security
|
|
|
|
If you discover a security vulnerability, please open an issue or contact the maintainers directly. We take security seriously and will respond promptly.
|