Guardian

O Guardian é o motor de governança do Vectora, compilado diretamente no binário Go. Ele atua como um firewall de aplicação, inspecionando cada comando e caminho antes da execução. Trust Folder (path isolation), pattern matching (regex rules), e audit logging.

Guardian não é um firewall - é um gatekeeper. Uma violação Guardian é BLOQUEADA antes de chegar ao filesystem, sem exceções.

Arquitetura

Request para ler arquivo
    ↓
┌─────────────────┐
│ Trust Folder │ Está dentro do perímetro?
│ Check │
└────────┬────────┘
         │ SIM
         ↓
┌─────────────────────┐
│ Guardian Rules │ Matches allow/deny pattern?
│ Pattern Matching │
└────────┬────────────┘
         │ ALLOW (ou SEM MATCH)
         ↓
┌──────────────────┐
│ RBAC Check │ Usuário tem permissão?
│ │
└────────┬─────────┘
         │ SIM
         ↓
┌──────────────────────┐
│ File Access │ Arquivo pode ser lido
│ Permitido │
└──────────────────────┘

Se qualquer check FALHA → Request é BLOQUEADO + Audit Log

Configuração

A configuração do Guardian é dividida em camadas lógicas, permitindo um equilíbrio entre restrição rígida e flexibilidade operacional.

Trust Folder (Camada 1)

Define o perímetro de segurança:

# vectora.config.yaml
project:
  trust_folder: "./src"
  # Apenas arquivos em ./src/* podem ser acessados

Qualquer tentativa de ler fora deste diretório é bloqueada:

Request: ../../../.env
Trust Folder: ./src
Resultado: BLOQUEADO (fora do périmetro)

Guardian Rules (Camada 2)

Padrões de regex para allow/deny:

# vectora.config.yaml
guardian:
  rules:
    # DENY tem prioridade
    - name: "block_env"
      pattern: "\.env.*" # .env, .env.local, .env.production
      action: "deny"

    - name: "block_secrets"
      pattern: "secrets/.*"
      action: "deny"

    - name: "block_credentials"
      pattern: ".*credentials.*" # Any file with "credentials"
      action: "deny"

    # ALLOW (opcional, mais específico)
    - name: "allow_src_docs"
      pattern: "^(src|docs)/.*"
      action: "allow"

Ordem importa: regras são avaliadas top→bottom, primeira match vence.

RBAC (Camada 3)

Além disso, Vectora respeita permissões de user:

# Definido em RBAC config
roles:
  owner:
    permissions:
      - search
      - index
      - configure
      - manage_users
  editor:
    permissions:
      - search
      - index
  viewer:
    permissions:
      - search

Padrões Pré-Configurados

Guardian vem com padrões de segurança pré-set:

# Defaults (sempre ativa)
defaults:
  block_patterns:
    - "\.env.*"
    - ".*\.key$"
    - ".*\.pem$"
    - ".*secret.*"
    - "\.git/.*"
    - "\.ssh/.*"
    - "bin/.*"
    - "vendor/.*"
    - "\.git/.*"

Para customizar, sobrescreva em config:

guardian:
  override_defaults: true
  rules:
    - name: "my_rule"
      pattern: "custom.*"
      action: "deny"

Audit Logging

Toda tentativa de acesso (bloqueada ou permitida) é logged:

VECTORA_AUDIT_LOG=true vectora search "query"

Log output:

{
  "timestamp": "2026-04-19T10:30:00Z",
  "event": "guardian_check",
  "action": "file_access",
  "requested_file": ".env",
  "trust_folder": "/home/user/project/src",
  "status": "BLOCKED",
  "reason": "matches_deny_pattern",
  "pattern": ".env.*",
  "user": "dev@company.com",
  "user_role": "editor",
  "ip": "192.168.1.100"
}

Inspecionar logs:

# Últimas 24h
vectora audit --action file_access --since 24h

# Apenas bloqueados
vectora audit --filter "BLOCKED"

# Por padrão
vectora audit --filter "pattern:\.env"

Casos de Uso

Abaixo estão exemplos práticos de como configurar o Guardian para cenários comuns de segurança em desenvolvimento e produção.

Case 1: Proteger .env

guardian:
  rules:
    - name: "block_dotenv"
      pattern: "\.env.*"
      action: "deny"

Resultado: .env, .env.local, .env.production são todos bloqueados.

Case 2: Proteger dados privados

guardian:
  rules:
    - name: "block_private"
      pattern: "private/.*"
      action: "deny"

    - name: "block_test_data"
      pattern: "test_data/.*\.csv"
      action: "deny"

Case 3: Allow-list específico

project:
  trust_folder: "." # Confio em tudo

guardian:
  rules:
    # Explicitamente permitir apenas src/ e docs/
    - name: "allow_src_docs"
      pattern: "^(src|docs)/"
      action: "allow"

    # Tudo mais é bloqueado
    - name: "deny_everything_else"
      pattern: ".*"
      action: "deny"

Violações Conhecidas

O Guardian é treinado para identificar e mitigar vetores de ataque comuns baseados em manipulação de caminhos e referências.

Directory Traversal Attempts

Tentativa: ../../.env
Resolução: Normalizado para /absolute/path/.env
Trust Folder: /absolute/path/src
Resultado: BLOQUEADO (fora do perímetro)

Symlink Attacks

File: ./src/link-to-secret → ../../secret.key
Resolução: Resolvido para /absolute/path/secret.key
Trust Folder: /absolute/path/src
Resultado: BLOQUEADO (symlink fora do perímetro)

Para permitir symlinks específicos:

guardian:
  symlink_handling: "follow" # ou "deny"
  symlink_whitelist:
    - "./src/allowed-link"

Case Sensitivity (Windows)

Windows é case-insensitive, padrões são case-sensitive por padrão:

guardian:
  case_sensitive: false # Match .ENV, .Env, .env

Testing & Validation

Antes de aplicar regras em produção, é fundamental validar o comportamento do Guardian usando ferramentas de simulação e teste de padrões.

Dry-Run Mode

Testar regras sem bloquear:

vectora guardian validate --dry-run

Output:

Guardian Validation Report
├─ Trust Folder: ./src
├─ Default Deny Patterns: 9
├─ Custom Rules: 3
└─ Test Cases:
   ├─ .env → BLOCKED (pattern: \.env.*)
   ├─ src/main.ts → ALLOWED
   └─ secrets/key.pem → BLOCKED (pattern: secrets/.*)

Rule Testing

# Testar padrão específico
vectora guardian test-pattern "\.env.*" ".env.local"
# Output: MATCH

vectora guardian test-pattern "\.env.*" "src/index.ts"
# Output: NO MATCH

Monitoring & Alerts

Mantenha a visibilidade sobre o estado de segurança do seu servidor através de métricas detalhadas e alertas em tempo real.

Métricas

Guardian captura métricas de segurança:

vectora metrics --filter guardian

Output:

guardian_metrics:
  period: "24h"
  total_checks: 12543
  allowed: 12500
  blocked: 43

  blocked_by_reason:
    deny_pattern: 35
    outside_trust_folder: 8
    rbac_violation: 0

  top_blocked_patterns:
    - "\.env.*": 15
    - "\.key$": 12
    - "secret": 8

Alertas

Configure alertas para violações:

guardian:
  alerts:
    enabled: true
    notify_on_violations: true
    threshold_per_hour: 10 # Alerta se > 10 bloqueios/h
    webhook: "https://your-slack.com/webhook"

Best Practices

Siga estas recomendações para garantir que o Guardian atue com a máxima eficiência sem prejudicar a produtividade dos desenvolvedores.

1. Trust Folder Mínimo

Não confie em ./ - seja específico:

# Inseguro
project:
  trust_folder: "."

# Seguro
project:
  trust_folder: "./src"

2. Deny-by-Default

Quando possível, use padrão “deny all, allow specific”:

guardian:
  rules:
    - name: "allow_src_docs"
      pattern: "^(src|docs)/"
      action: "allow"

    - name: "deny_everything"
      pattern: ".*"
      action: "deny"

3. Audit Regularmente

# Weekly review
vectora audit --since 7d --filter "BLOCKED" | wc -l

4. Avoid Exceptions

Não crie “exception rules” para .env - use valores default:

# Ruim - exceção
guardian:
  rules:
    - name: "allow_local_env"
      pattern: "\.env\.local" # Exceção!
      action: "allow"

# Melhor - usar variáveis
guardian:
  rules:
    - name: "block_env"
      pattern: "\.env"
      action: "deny"

# Use .env via environment variables ao invés
export GEMINI_API_KEY="..."

Troubleshooting

Se encontrar problemas de acesso ou mensagens inesperadas, utilize estes procedimentos para diagnosticar e resolver conflitos com o Guardian.

Arquivo legítimo bloqueado

Error: ./src/config.secrets.ts is blocked by pattern

Diagnóstico:

vectora guardian explain "./src/config.secrets.ts"
# Output: Matches deny_pattern ".*secret.*"

Solução 1: Renomear arquivo

mv src/config.secrets.ts src/config.secure.ts

Solução 2: Ajustar padrão (menos recomendado)

guardian:
  rules:
    - name: "block_secrets"
      pattern: "secret_keys/.*" # Mais específico
      action: "deny"

“Guardian disabled” messages

Se Guardian está desabilitado (dev mode):

# Verificar status
vectora config get guardian.enabled

# Reabilitar
vectora config set guardian.enabled true

Compliance & Regulations

Guardian ajuda a cumprir:

GDPR: Dados pessoais protegidos
HIPAA: Medical records não indexados
PCI-DSS: Números de cartão bloqueados
SOC 2: Audit trail completo

Configure regras específicas:

# HIPAA
guardian:
  rules:
    - pattern: "patient_data/.*"
      action: "deny"
    - pattern: ".*\.phi\..*" # Protected Health Info
      action: "deny"

Próximo: RBAC System

External Linking

Concept	Resource	Link
RBAC	NIST Role-Based Access Control Standard	csrc.nist.gov/projects/rbac
MCP	Model Context Protocol Specification	modelcontextprotocol.io/specification
MCP Go SDK	Go SDK for MCP (mark3labs)	github.com/mark3labs/mcp-go

Parte do ecossistema Vectora · Open Source (MIT) · Contribuidores

BYOK & Privacy RBAC