diff --git a/README.md b/README.md index 8019828..ce04d34 100644 --- a/README.md +++ b/README.md @@ -7,27 +7,22 @@ [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md) [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md) -`envguard` é uma ferramenta open source de linha de comando (CLI) desenvolvida em **Go**, projetada para atuar como uma -camada leve de proteção entre o desenvolvedor e o Git. O foco principal é detectar, alertar e prevenir a exposição -indevida de arquivos de variáveis de ambiente (`.env`, `.env.production`, `.env.local`, etc.) em repositórios. +`envguard` é uma ferramenta open source de linha de comando (CLI) desenvolvida em **Go**, projetada para atuar como uma camada leve de proteção entre o desenvolvedor e o Git. O foco principal é detectar, alertar, remediar e prevenir a exposição indevida de arquivos de variáveis de ambiente (`.env`, `.env.production`, `.env.local`, etc.) em repositórios. --- ## Por que o `envguard`? -Arquivos `.env` costumam armazenar dados sensíveis: credenciais de banco de dados, chaves de API, tokens e certificados. -Um descuido na configuração do `.gitignore` ou um simples `git add .` desavisado pode comitar esses segredos no -histórico de versão. +Arquivos `.env` costumam armazenar dados sensíveis: credenciais de banco de dados, chaves de API, tokens e certificados. Um descuido na configuração do `.gitignore` ou um simples `git add .` desavisado pode comitar esses segredos no histórico de versão. O `envguard` resolve isso com foco específico em arquivos de ambiente: -- **Git-Aware:** Entende o estado do repositório — diferencia se um `.env` está rastreado (_tracked_), preparado - (_staged_), ignorado ou desprotegido. -- **Rápido & Local:** Funciona 100% offline, sem envio de dados para servidores externos. Ideal para execução local, - _precommit hooks_ e pipelines de CI/CD. -- **Seguro por Design:** Nunca imprime ou expõe valores de variáveis, ou segredos em logs, ou saídas do terminal. -- **Pronto para CI/CD:** Suporta formato JSON estruturado (`--format json`) e códigos de saída determinísticos para - automação. +- **Git-Aware:** Entende o estado do repositório — diferencia se um `.env` está rastreado (_tracked_), preparado (_staged_), ignorado ou desprotegido. +- **Rápido & Local:** Funciona 100% offline, sem envio de dados para servidores externos. Ideal para execução local, _pre-commit hooks_ e pipelines de CI/CD. +- **Remediação Automática:** Adiciona padrões ausentes ao `.gitignore` automaticamente (`envguard fix`). +- **Hooks Nativos & Framework Pre-commit:** Instalação direta em `.git/hooks/pre-commit` e suporte ao framework Python `pre-commit`. +- **Seguro por Design:** Nunca imprime ou expõe valores de variáveis ou segredos em logs e saídas do terminal. +- **Pronto para CI/CD:** Suporta formato JSON estruturado (`--format json`) e códigos de saída determinísticos para automação. --- @@ -67,17 +62,27 @@ envguard scan Exemplo de saída no terminal: ```text -envguard v0.1.0 - -Repository: ./my-project -Scanning... - - ✗ .env CRITICAL tracked by Git - ⚠ .env.local WARNING not covered by .gitignore - ✓ .env.example INFO allowed template file - -Found 2 finding(s) (1 CRITICAL, 1 WARNING) -Exit code: 1 +🛡️ envguard v0.2.0 +Target: ./meu-projeto +────────────────────────────────────────────────── + +Findings: + ✗ [CRITICAL] .env + Message: Environment file is tracked by Git (committed in repository history). + Suggestions: + • Remove file from git tracking: git rm --cached .env + • Add to .gitignore + • Rotate any leaked credentials + + ⚠ [WARNING] .env.local + Message: Environment file exists locally and is not ignored by .gitignore. + Suggestions: + • Add to .gitignore + +────────────────────────────────────────────────── +Summary: + Total Findings: 2 (Critical: 1, High: 0, Warning: 1, Info: 0) + Status: ✗ FAILED ``` ### 2. Validação para CI/CD (`check`) @@ -88,7 +93,34 @@ Ideal para pipelines e automações. Retorna código de erro (`exit code 1`) cas envguard check ``` -### 3. Remediação Automática (`fix`) +### 3. Git Pre-Commit Hooks (`hook`) + +Instala ou executa inspeções ultrarrápidas (<10ms) focadas exclusivamente em arquivos preparados para commit (`staged`): + +```bash +# Instalar o hook nativo em .git/hooks/pre-commit +envguard hook install + +# Executar checagem de stage (bloqueia commits com .env não permitidos) +envguard hook run + +# Desinstalar o hook nativo +envguard hook uninstall +``` + +#### Integração com Python `pre-commit`: + +Adicione ao seu `.pre-commit-config.yaml`: + +```yaml +repos: + - repo: https://github.com/joaooncode/envguard + rev: v0.2.0 + hooks: + - id: envguard +``` + +### 4. Remediação Automática (`fix`) Adiciona automaticamente padrões correspondentes para arquivos desprotegidos (`WARNING`) no `.gitignore` da raiz, preservando comentários e formatação existente: @@ -103,7 +135,7 @@ envguard fix --dry-run envguard fix --path ./meu-projeto ``` -### 4. Inicialização de Configuração e Templates (`init`) +### 5. Inicialização de Configuração e Templates (`init`) Gera o arquivo de configuração `.envguard.yaml` documentado e, opcionalmente, cria templates `.env.example` sanitizados a partir de variáveis locais: @@ -114,17 +146,17 @@ envguard init # Inicializar configuração e gerar template .env.example sanitizado envguard init --template -# Inicializar em diretório específico sobrescrevendo arquivos existentes -envguard init --path ./meu-projeto --force +# Inicializar a partir de arquivo de origem específico +envguard init --template-from .env.production ``` -### 5. Saída Estruturada em JSON +### 6. Saída Estruturada em JSON ```bash envguard scan --format json ``` -### 6. Verificar Versão +### 7. Verificar Versão ```bash envguard version @@ -132,14 +164,41 @@ envguard version --- +## Arquivo de Configuração (`.envguard.yaml`) + +O `envguard` pode ser personalizado criando um arquivo `.envguard.yaml` na raiz do repositório: + +```yaml +version: '1' + +scanner: + ignore_dirs: + - 'node_modules' + - '.git' + - 'vendor' + +detector: + custom_patterns: + - '*.env.vault' + allowlist: + - '.env.example' + - '.env.sample' + - '.env.template' + severity_overrides: + - pattern: '.env.test' + severity: 'warning' +``` + +--- + ## Níveis de Severidade -| Nível | Situação | Ação Recomendada | -| :------------------ | :---------------------------------------------------------------------- | :--------------------------------------------------------------------- | -| **`CRITICAL`** | Arquivo de ambiente rastreado (_tracked_) no histórico Git | Remover do rastreamento (`git rm --cached`) e rotacionar credenciais | -| **`HIGH`** | Arquivo de ambiente adicionado para commit (_staged_) | Retirar da stage (`git reset HEAD `) e adicionar ao `.gitignore` | -| **`WARNING`** | Arquivo existe localmente mas **não está** no `.gitignore` | Executar `envguard fix` ou adicionar padrão ao `.gitignore` | -| **`INFO` / `SAFE`** | Arquivo protegido ou template permitido (`.env.example`, `.env.sample`) | Nenhuma ação necessária | +| Nível | Situação | Ação Recomendada | +| :------------------ | :---------------------------------------------------------------------- | :--------------------------------------------------------------------------- | +| **`CRITICAL`** | Arquivo de ambiente rastreado (_tracked_) no histórico Git | Remover do rastreamento (`git rm --cached`) e rotacionar credenciais | +| **`HIGH`** | Arquivo de ambiente adicionado para commit (_staged_) | Retirar da stage (`git restore --staged `) e adicionar ao `.gitignore` | +| **`WARNING`** | Arquivo existe localmente mas **não está** no `.gitignore` | Executar `envguard fix` ou adicionar padrão ao `.gitignore` | +| **`INFO` / `SAFE`** | Arquivo protegido ou template permitido (`.env.example`, `.env.sample`) | Nenhuma ação necessária | --- @@ -157,14 +216,16 @@ envguard version - [x] Integração Git (_tracked_, _staged_, _gitignore_) - [x] Relatórios em Terminal e JSON - [x] Códigos de saída para CI/CD -- [ ] **v0.2.0:** +- [x] **v0.2.0:** - [x] `envguard init` (criação automática de `.envguard.yaml` e templates) - [x] `envguard fix` (auxílio na adição automática ao `.gitignore`) - - [ ] Instalação de _Git Precommit Hooks_ + - [x] Suporte a arquivo de configuração `.envguard.yaml` e flag `--config` + - [x] Instalação de _Git Pre-commit Hooks_ nativos e suporte a Python `pre-commit` - [ ] **v0.3.0:** - [ ] Secret scanning básico por conteúdo & cálculo de entropia + - [ ] Deteção de padrões comuns de chaves (AWS, Stripe, GitHub, etc.) - [ ] **v1.0.0:** - - [ ] GitHub Action oficial + - [ ] GitHub Action oficial do envguard - [ ] Pacotes para Homebrew, Scoop, WinGet e AUR --- diff --git a/internal/cli/cli_test.go b/internal/cli/cli_test.go index 2e9e146..115ce67 100644 --- a/internal/cli/cli_test.go +++ b/internal/cli/cli_test.go @@ -33,8 +33,8 @@ func TestCLIVersion(t *testing.T) { } out := stdout.String() - if !strings.Contains(out, "envguard v0.1.0") { - t.Fatalf("expected stdout to contain 'envguard v0.1.0', got: %s", out) + if !strings.Contains(out, "envguard v0.2.0") { + t.Fatalf("expected stdout to contain 'envguard v0.2.0', got: %s", out) } }) } @@ -168,8 +168,8 @@ func TestCLIScanCleanDirectory(t *testing.T) { if !report.Summary.Passed { t.Fatalf("expected report summary passed to be true, got false") } - if report.Version != "0.1.0" { - t.Fatalf("expected report version 0.1.0, got %s", report.Version) + if report.Version != "0.2.0" { + t.Fatalf("expected report version 0.2.0, got %s", report.Version) } }) } diff --git a/internal/cli/version.go b/internal/cli/version.go index daea8e5..a3ba5ac 100644 --- a/internal/cli/version.go +++ b/internal/cli/version.go @@ -3,7 +3,7 @@ package cli import "fmt" // Version is the current semantic version of envguard. -const Version = "0.1.0" +const Version = "0.2.0" // VersionString returns the formatted version string. func VersionString() string { diff --git a/package.json b/package.json index 11c8fe4..aba5f76 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "envguard", - "version": "0.1.0", + "version": "0.2.0", "private": true, "description": "Prevent .env files and environment secrets from accidentally reaching Git.", "scripts": { diff --git a/website/blog/2026-09-02-lancamento-envguard-v020.md b/website/blog/2026-09-02-lancamento-envguard-v020.md new file mode 100644 index 0000000..10167a8 --- /dev/null +++ b/website/blog/2026-09-02-lancamento-envguard-v020.md @@ -0,0 +1,51 @@ +--- +slug: lancamento-envguard-v020 +title: Lançamento do envguard v0.2.0 - Hooks, Configuração, Init e Fix +authors: [joaooncode] +tags: [release, security, cli, golang, git-hooks, automation] +--- + +É com muito orgulho que anunciamos o lançamento do **`envguard` v0.2.0**! 🎉 + +Esta versão consolida a automação e remediação do ecossistema do `envguard`, trazendo recursos nativos para proteger o fluxo de desenvolvimento antes mesmo da execução de commits. + + + +## Principais Novidades da v0.2.0 + +### 1. Suporte a Git Pre-commit Hooks (`envguard hook`) + +- **Instalação Nativa (`envguard hook install`):** Cria o script executável em `.git/hooks/pre-commit` com detecção de assinatura e proteção contra sobrescrita acidental. +- **Inspeção Instantânea (`envguard hook run`):** Avalia exclusivamente os arquivos preparados para commit (`staged`) em menos de 10ms, bloqueando o commit se houver variáveis de ambiente desprotegidas. +- **Integração Oficial com Python `pre-commit`:** Arquivo `.pre-commit-hooks.yaml` incluído na raiz do repositório para adoção imediata. + +### 2. Remediação Automática com `envguard fix` + +- Analisa o repositório e insere automaticamente os arquivos de ambiente desprotegidos no `.gitignore` da raiz. +- Suporte a simulação não-destrutiva com `--dry-run` para pré-visualizar as alterações antes de aplicar no disco. + +### 3. Inicialização e Sanitização de Templates (`envguard init`) + +- Gera o arquivo `.envguard.yaml` completo e comentado. +- Suporte à geração de templates `.env.example` através da higienização automática (`--template` e `--template-from`), removendo valores sensíveis e preservando chaves e comentários. + +### 4. Arquivo de Configuração `.envguard.yaml` + +- Controle total de `ignore_dirs`, `custom_patterns`, `allowlist` e `severity_overrides` por projeto ou via flag `--config`. + +--- + +## Como Atualizar + +```bash +go install github.com/joaooncode/envguard/cmd/envguard@latest +``` + +Verifique a versão instalada: + +```bash +envguard version +# envguard v0.2.0 +``` + +Confira a [documentação oficial](/docs/intro) para explorar todos os novos comandos e guias de integração! diff --git a/website/blog/tags.yml b/website/blog/tags.yml index 1edf024..7fd2013 100644 --- a/website/blog/tags.yml +++ b/website/blog/tags.yml @@ -17,3 +17,13 @@ golang: label: Go permalink: /golang description: Tópicos sobre o ecossistema Go + +git-hooks: + label: Git Hooks + permalink: /git-hooks + description: Gerenciamento e boas práticas com Git Hooks + +automation: + label: Automação + permalink: /automacao + description: Automação e pipelines de segurança diff --git a/website/docs/commands/fix.md b/website/docs/commands/fix.md new file mode 100644 index 0000000..0d15d85 --- /dev/null +++ b/website/docs/commands/fix.md @@ -0,0 +1,75 @@ +--- +sidebar_position: 4 +title: envguard fix +--- + +# envguard fix + +O comando **`envguard fix`** realiza a remediação automática de arquivos de ambiente desprotegidos (`WARNING`), inserindo os padrões correspondentes no `.gitignore` da raiz do repositório de forma não destrutiva. + +--- + +## Uso + +```bash +envguard fix [flags] +``` + +--- + +## Flags Disponíveis + +| Flag | Tipo | Padrão | Descrição | +| :---------------- | :------- | :------ | :--------------------------------------------------------------------------- | +| `-p`, `--path` | `string` | `"."` | Diretório alvo para varredura e remediação. | +| `-d`, `--dry-run` | `bool` | `false` | Pré-visualiza as alterações propostas no `.gitignore` sem modificar o disco. | +| `-c`, `--config` | `string` | `""` | Caminho para um arquivo de configuração customizado. | +| `--no-color` | `bool` | `false` | Desativa cores ANSI na saída do terminal. | + +--- + +## Exemplos de Uso + +### 1. Aplicar correções automáticas no `.gitignore` + +```bash +envguard fix +``` + +Saída de exemplo: + +```text +✓ Successfully updated .gitignore with 2 rule(s): + + .env + + /services/api/.env.local +``` + +### 2. Modo Dry-Run (Simulação) + +Permite inspecionar quais regras seriam adicionadas antes de alterar qualquer arquivo: + +```bash +envguard fix --dry-run +``` + +Saída de exemplo: + +```text +🔍 Dry run mode: changes will not be written to disk + +Proposed .gitignore additions: + + .env + + .env.local +``` + +### 3. Alertas para Arquivos Rastreados (`CRITICAL`) + +Se um arquivo já foi commitado no Git, o `.gitignore` não é suficiente para remover o histórico. O `envguard fix` detecta a situação, exibe instruções práticas de remoção do cache (`git rm --cached `) e retorna `exit code 1` alertando sobre a pendência. + +--- + +## Características de Segurança + +- **Formatação Não Destrutiva:** Novas regras são adicionadas sob o cabeçalho `# Added by envguard`, preservando comentários existentes, indentação e quebras de linha. +- **Prevenção de Duplicatas:** Verifica regras já presentes no `.gitignore` e não insere padrões repetidos. +- **Resolução de Caminhos Relativos:** Arquivos localizados em subpastas (ex: `packages/backend/.env`) são mapeados corretamente em relação à raiz do repositório. diff --git a/website/docs/commands/hook.md b/website/docs/commands/hook.md new file mode 100644 index 0000000..1ff9c25 --- /dev/null +++ b/website/docs/commands/hook.md @@ -0,0 +1,101 @@ +--- +sidebar_position: 5 +title: envguard hook +--- + +# envguard hook + +O comando **`envguard hook`** gerencia hooks de pré-commit locais no Git e realiza inspeções ultrarrápidas (`<10ms`) direcionadas exclusivamente aos arquivos que estão em stage (`git add`). + +--- + +## Subcomandos + +```bash +envguard hook [flags] +``` + +| Subcomando | Descrição | +| :---------- | :------------------------------------------------------------------------------------- | +| `install` | Instala o script executável de pré-commit em `.git/hooks/pre-commit`. | +| `run` | Executa a inspeção dos arquivos em stage e bloqueia commits com variáveis de ambiente. | +| `uninstall` | Remove com segurança o script instalado pelo envguard de `.git/hooks/pre-commit`. | +| `help` | Exibe a ajuda dos comandos de hook. | + +--- + +## Flags Disponíveis + +| Flag | Subcomandos | Tipo | Padrão | Descrição | +| :--------------- | :--------------------- | :------- | :------ | :-------------------------------------------------------- | +| `-p`, `--path` | Todos | `string` | `"."` | Diretório raiz do repositório Git. | +| `-f`, `--force` | `install`, `uninstall` | `bool` | `false` | Força a instalação ou remoção sobre hooks pré-existentes. | +| `-c`, `--config` | `run` | `string` | `""` | Caminho para um arquivo de configuração customizado. | +| `--no-color` | `run` | `bool` | `false` | Desativa cores ANSI na saída do terminal. | + +--- + +## Exemplos de Uso + +### 1. Instalar o Hook Nativo + +Instala o script de hook no repositório local: + +```bash +envguard hook install +``` + +Caso já exista um hook customizado ou de terceiros, o envguard evita sobrescrever acidentalmente. Utilize `--force` caso deseje substituir: + +```bash +envguard hook install --force +``` + +### 2. Executar Inspeção em Stage (`hook run`) + +Chamado automaticamente pelo Git antes de cada commit: + +```bash +envguard hook run +``` + +Se nenhum arquivo sensível estiver em stage: + +```text +✓ No unprotected environment files staged for commit. +``` + +Se um arquivo `.env` não permitido for adicionado para commit: + +```text +🚨 Git Pre-Commit Check Failed! +Found 1 unprotected environment file(s) staged for commit: + + ✗ [STAGED] .env.production + Message: Environment file is staged for commit in Git index. + Suggestions: + • Unstage file: git restore --staged .env.production + • Add to .gitignore + +Commit blocked to prevent sensitive credentials from reaching Git. +``` + +### 3. Desinstalar o Hook Nativo + +```bash +envguard hook uninstall +``` + +--- + +## Integração com o Framework Python `pre-commit` + +O `envguard` possui suporte nativo ao framework popular [pre-commit](https://pre-commit.com/). Basta adicionar o arquivo `.pre-commit-config.yaml` no seu projeto: + +```yaml +repos: + - repo: https://github.com/joaooncode/envguard + rev: v0.2.0 + hooks: + - id: envguard +``` diff --git a/website/docs/commands/init.md b/website/docs/commands/init.md new file mode 100644 index 0000000..3a81ac7 --- /dev/null +++ b/website/docs/commands/init.md @@ -0,0 +1,71 @@ +--- +sidebar_position: 3 +title: envguard init +--- + +# envguard init + +O comando **`envguard init`** inicializa o arquivo de configuração do projeto (`.envguard.yaml`) e permite gerar templates seguros de variáveis de ambiente (`.env.example`) através de higienização automatizada. + +--- + +## Uso + +```bash +envguard init [flags] +``` + +--- + +## Flags Disponíveis + +| Flag | Tipo | Padrão | Descrição | +| :----------------- | :------- | :------ | :-------------------------------------------------------------------------- | +| `-p`, `--path` | `string` | `"."` | Diretório alvo para criar os arquivos de configuração e template. | +| `-f`, `--force` | `bool` | `false` | Sobrescreve arquivos existentes (`.envguard.yaml` ou `.env.example`). | +| `-t`, `--template` | `bool` | `false` | Gera automaticamente um template seguro `.env.example`. | +| `--template-from` | `string` | `""` | Caminho do arquivo `.env` de origem a ser sanitizado para criar o template. | + +--- + +## Exemplos de Uso + +### 1. Inicializar configuração padrão + +Cria o arquivo `.envguard.yaml` com comentários explicativos e padrões de segurança: + +```bash +envguard init +``` + +### 2. Inicializar configuração e gerar `.env.example` + +Se já existir um arquivo `.env` local, ele é automaticamente lido e higienizado (valores removidos, mantendo chaves e comentários): + +```bash +envguard init --template +``` + +### 3. Sanitizar um arquivo `.env` específico + +Gera o `.env.example` a partir de um arquivo com outro nome (ex.: `.env.production` ou `.env.local`): + +```bash +envguard init --template-from .env.production +``` + +### 4. Forçar sobrescrita em caso de arquivos existentes + +```bash +envguard init --path ./meu-projeto --template --force +``` + +--- + +## Como Funciona a Sanitização + +A sanitização do `envguard init` garante que nenhum segredo seja exposto: + +1. Preserva comentários (`# ...`), quebras de linha e estrutura do arquivo. +2. Mantém os nomes das variáveis (ex.: `DATABASE_URL=`, `JWT_SECRET=`). +3. Limpa com segurança todos os valores atribuídos. diff --git a/website/docs/commands/scan.md b/website/docs/commands/scan.md index a253d7c..f072cda 100644 --- a/website/docs/commands/scan.md +++ b/website/docs/commands/scan.md @@ -19,10 +19,14 @@ envguard scan [flags] ## Flags Disponíveis -| Flag | Tipo | Descrição | Padrão | -| :------------- | :------- | :---------------------------------- | :------ | -| `--format` | `string` | Formato da saída (`text` ou `json`) | `text` | -| `--help`, `-h` | `bool` | Exibe a ajuda do comando | `false` | +| Flag | Tipo | Descrição | Padrão | +| :----------------- | :------- | :------------------------------------------------------------------------ | :------ | +| `-p`, `--path` | `string` | Diretório alvo para a varredura | `"."` | +| `-f`, `--format` | `string` | Formato da saída (`text`, `terminal` ou `json`) | `text` | +| `-s`, `--severity` | `string` | Nível mínimo de severidade (`all`, `info`, `warning`, `high`, `critical`) | `all` | +| `-c`, `--config` | `string` | Caminho para arquivo de configuração customizado | `""` | +| `--no-color` | `bool` | Desativa cores ANSI na saída do terminal | `false` | +| `--help`, `-h` | `bool` | Exibe a ajuda do comando | `false` | --- @@ -37,16 +41,27 @@ envguard scan #### Exemplo de Saída: ```text -envguard v0.1.0 - -Repository: ./meu-projeto -Scanning... - - ✗ .env CRITICAL tracked by Git - ⚠ .env.local WARNING not covered by .gitignore - ✓ .env.example INFO allowed template file - -Found 2 finding(s) (1 CRITICAL, 1 WARNING) +🛡️ envguard v0.2.0 +Target: ./meu-projeto +────────────────────────────────────────────────── + +Findings: + ✗ [CRITICAL] .env + Message: Environment file is tracked by Git (committed in repository history). + Suggestions: + • Remove file from git tracking: git rm --cached .env + • Add to .gitignore + • Rotate any leaked credentials + + ⚠ [WARNING] .env.local + Message: Environment file exists locally and is not ignored by .gitignore. + Suggestions: + • Add to .gitignore + +────────────────────────────────────────────────── +Summary: + Total Findings: 2 (Critical: 1, High: 0, Warning: 1, Info: 0) + Status: ✗ FAILED ``` --- diff --git a/website/docs/commands/version.md b/website/docs/commands/version.md index f55158c..2dde7ee 100644 --- a/website/docs/commands/version.md +++ b/website/docs/commands/version.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 6 title: envguard version --- @@ -20,5 +20,5 @@ envguard version ## Exemplo de Saída ```text -envguard v0.1.0 +envguard v0.2.0 ``` diff --git a/website/docs/configuration.md b/website/docs/configuration.md new file mode 100644 index 0000000..8c1c014 --- /dev/null +++ b/website/docs/configuration.md @@ -0,0 +1,68 @@ +--- +sidebar_position: 4 +title: Arquivo de Configuração +--- + +# Arquivo de Configuração + +O `envguard` suporta personalização profunda por meio de um arquivo de configuração `.envguard.yaml` (ou `.envguard.yml`) localizado na raiz do projeto ou indicado via flag `--config`. + +--- + +## Ordem de Descoberta + +Quando um comando é executado, a configuração é carregada seguindo esta prioridade: + +1. Caminho explícito passado pela flag `--config `. +2. Arquivo `.envguard.yaml` no diretório alvo. +3. Arquivo `.envguard.yml` no diretório alvo. +4. Padrões embutidos padrão do `envguard`. + +--- + +## Estrutura do Arquivo `.envguard.yaml` + +```yaml +version: '1' + +scanner: + # Diretórios ignorados durante a varredura recursiva + ignore_dirs: + - 'node_modules' + - '.git' + - 'vendor' + - 'dist' + - 'build' + - '.idea' + - '.vscode' + +detector: + # Padrões adicionais de arquivos a serem reconhecidos como variáveis de ambiente + custom_patterns: + - '*.env.vault' + - '.env.release' + + # Padrões considerados seguros (não geram alerta) + allowlist: + - '.env.example' + - '.env.sample' + - '.env.template' + - '.env.ci' + + # Sobrescrita explícita de níveis de severidade + severity_overrides: + - pattern: '.env.test' + severity: 'warning' # info, warning, high, critical + - pattern: '.env.sandbox' + severity: 'info' +``` + +--- + +## Gerando a Configuração Automaticamente + +Para criar o arquivo inicial no seu projeto com todos os comentários explicativos: + +```bash +envguard init +``` diff --git a/website/docs/installation.md b/website/docs/installation.md index d92aa66..dcfb725 100644 --- a/website/docs/installation.md +++ b/website/docs/installation.md @@ -61,7 +61,7 @@ envguard version Saída esperada: ```text -envguard v0.1.0 +envguard v0.2.0 ``` --- diff --git a/website/docs/intro.md b/website/docs/intro.md index 17dd15b..b6dd889 100644 --- a/website/docs/intro.md +++ b/website/docs/intro.md @@ -49,6 +49,7 @@ O `envguard` resolve isso com foco específico em arquivos de ambiente: ## Próximos Passos - [Instalação](./installation.md): Saiba como instalar o binário localmente. -- [Comandos](./commands/scan.md): Conheça os comandos `scan`, `check` e `version`. +- [Comandos](./commands/scan.md): Conheça os comandos `scan`, `check`, `init`, `fix`, `hook` e `version`. +- [Arquivo de Configuração](./configuration.md): Personalize regras, exceções e severidades via `.envguard.yaml`. - [Níveis de Severidade](./severity-levels.md): Entenda os alertas e as ações recomendadas. -- [Integração CI/CD](./cicd-integration.md): Automatize a proteção no GitHub Actions. +- [Integração CI/CD](./cicd-integration.md): Automatize a proteção no GitHub Actions e pre-commit hooks.