Initial commit: env-guard CLI tool with CI/CD
This commit is contained in:
CI Bot
296
README.md
Normal file
296
README.md
Normal file
@@ -0,0 +1,296 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user