feat(config): Implementar suporte a arquivo de configuracao .envguard.yaml #15

Activity

1. joaooncode

   added this to the v0.2.0 milestone on Aug 30, 2026
2. joaooncode

   added

   enhancementNew feature or requestNew feature or request

   coreCore engine, scanning, and detectorsCore engine, scanning, and detectors

   on Aug 30, 2026
3. joaooncode

   self-assigned this

   on Aug 30, 2026
4. joaooncode commented on Sep 2, 2026

   

   joaooncode

   on Sep 2, 2026

   Last edited by joaooncode

   OwnerAuthor

   More actions

   Declaração do Problema

   Atualmente, o envguard depende exclusivamente de padrões e regras fixas (hardcoded) para detectar arquivos de ambiente, templates permitidos (allowlist), diretórios ignorados e níveis de severidade. Projetos com estruturas de diretórios específicas (ex: pastas customizadas de build ou vendor), convenções próprias de nomes de arquivos de ambiente (ex: *.env.vault, .env.secret) ou políticas internas de risco não conseguiam personalizar o comportamento do envguard sem alterar o código-fonte.

   Solução

   Implementação do suporte completo a arquivo de configuração (.envguard.yaml / .envguard.yml) e à flag de linha de comando --config (-c). A configuração permite declarar:

   1. scanner.ignore_dirs: diretórios adicionais a serem ignorados durante a varredura.
   2. detector.custom_patterns: padrões adicionais de arquivos a serem identificados como arquivos de ambiente.
   3. detector.allowlist: padrões adicionais de arquivos seguros (templates/exemplos).
   4. detector.severity_overrides: mapeamentos explícitos para sobrescrever o nível de severidade de arquivos correspondentes a padrões específicos.

   O parsing é estrito (fail-fast) contra erros de sintaxe ou campos desconhecidos para evitar brechas acidentais de segurança. As listas customizadas do usuário estendem (append) os padrões seguros embutidos por padrão.

   Histórias de Usuário (User Stories)

   1. Como desenvolvedor utilizando o envguard em um repositório, quero que o envguard detecte e carregue automaticamente o .envguard.yaml ou .envguard.yml na raiz do projeto para que as regras da minha equipe sejam aplicadas automaticamente.
   2. Como engenheiro de DevOps em pipelines de CI/CD, quero fornecer a flag --config <path> (ou -c) aos comandos para aplicar um arquivo de configuração centralizado ou específico de ambiente.
   3. Como desenvolvedor com padrões customizados de nomenclatura (como backend.env.vault), quero especificar detector.custom_patterns para que o envguard identifique esses arquivos como arquivos de ambiente.
   4. Como desenvolvedor com templates específicos (como .env.local.sample), quero especificar regras em detector.allowlist para que esses arquivos sejam classificados como informativos (info) e não causem falha na verificação.
   5. Como desenvolvedor trabalhando com ferramentas proprietárias ou pastas de build em monorepo (como .tmp_build), quero especificar scanner.ignore_dirs para que o envguard não varra nem aponte arquivos dentro desses diretórios.
   6. Como engenheiro de segurança, quero definir detector.severity_overrides para que arquivos críticos específicos (como .env.production) sempre disparem severidade critical, independentemente do status de rastreamento no Git.
   7. Como desenvolvedor que comete um erro de digitação no .envguard.yaml, quero que o envguard falhe rapidamente com uma mensagem de erro clara indicando o problema de sintaxe ou validação, evitando executar varreduras com configuração corrompida.
   8. Como usuário executando o envguard em um repositório sem .envguard.yaml, quero que o envguard execute silenciosamente usando as configurações padrão embutidas sem emitir erros.

   Decisões de Implementação

   • Criação do pacote dedicado internal/config responsável por:
     • Definição das structs Config, ScannerConfig, DetectorConfig e SeverityOverride com tags YAML.
     • Descoberta de arquivos de configuração: flag --config -> .envguard.yaml no diretório alvo -> .envguard.yml no diretório alvo -> padrões embutidos.
     • Decodificação estrita via gopkg.in/yaml.v3 (KnownFields(true)) e validação semântica.
   • Atualização de internal/detector.Detector para suportar padrões customizados de ambiente e allowlist estendida.
   • Atualização de internal/scanner.Scanner para aceitar config.Config, combinando diretórios ignorados customizados com os padrões, repassando padrões ao detector e aplicando severity_overrides na classificação de cada finding.
   • Atualização de internal/cli (comandos scan e check) para aceitar as flags --config e -c e carregar a configuração antes de iniciar o scanner.

   Decisões de Testes

   • Testes com TDD nas seguintes camadas/costuras (seams):
     1. Camada CLI (internal/cli): Execução ponta a ponta dos comandos scan e check com flag --config, arquivos YAML válidos, inválidos (validando código de saída 2) e ausentes.
     2. Camada de Configuração (internal/config): Testes unitários validando defaults, ordem de descoberta, erros estritos de sintaxe YAML e lógica de validação.
     3. Camada de Integração Scanner & Detector (internal/scanner e internal/detector): Testes de varredura com diretórios ignorados customizados, padrões extras de .env, allowlist customizada e overrides de severidade.

   Fora de Escopo (Out of Scope)

   • Carregamento de configurações remotas via URL (ex: http://...).
   • Sobrescrita de chaves YAML via variáveis de ambiente (ex: ENVGUARD_IGNORE_DIRS).
   • Formatos de configuração JSON ou TOML (YAML é o padrão exclusivo).

   Notas Adicionais

   • O campo version: "1" na raiz do YAML é opcional, mas recomendado para compatibilidade futura.
5. joaooncode

   added

   ready-for-agentFully specified, ready for an AFK agentFully specified, ready for an AFK agent

   on Sep 2, 2026
6. joaooncode

   closed this as completedin #24on Sep 2, 2026