> ## Documentation Index > Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt > Use this file to discover all available pages before exploring further. # Segurança Enterprise > Arquitetura de segurança defense-in-depth do ChatCLI: autenticação JWT + RBAC, criptografia AES-256-GCM, prevenção SSRF, rate limiting, assinatura de plugins Ed25519, allowlist de comandos, audit logging estruturado e muito mais. O ChatCLI implementa uma arquitetura de **segurança em profundidade** (defense-in-depth) com mais de **30 controles de segurança** distribuídos em todas as camadas da aplicação — da autenticação e criptografia até a prevenção de injeção, hardening de infraestrutura e auditoria estruturada. Todas as proteções listadas nesta página estão **ativas por padrão**. A filosofia do ChatCLI é *secure-by-default*: você não precisa configurar nada para obter um nível elevado de segurança. *** ## Visão Geral das Proteções | # | Camada | Proteção | Status | | -- | --------------------- | ---------------------------------------------------------------- | --------------------------- | | 1 | **Autenticação** | JWT com HMAC-SHA256 (claims `iss`, `aud`, `exp`, `role`) | Ativo | | 2 | **Autorização** | RBAC com 3 roles: `admin`, `user`, `readonly` | Ativo | | 3 | **Auth Legacy** | Bearer token com comparação em tempo constante (`crypto/subtle`) | Ativo | | 4 | **Auth Rate Limit** | 5 tentativas/min por IP — bloqueio progressivo | Ativo | | 5 | **OAuth** | PKCE + Device Flow para provedores externos | Ativo | | 6 | **Criptografia** | AES-256-GCM para credenciais em repouso | Ativo | | 7 | **TLS** | TLS 1.3 obrigatório para gRPC em produção | Ativo | | 8 | **Sessões** | Criptografia de sessão em repouso com HKDF key derivation | Ativo | | 9 | **Sessões TTL** | Expiração automática de sessões inativas | Ativo | | 10 | **Keychain** | Integração com OS keychain (macOS Keychain, Linux secret-tool) | Ativo | | 11 | **Env Vars** | Redação automática de variáveis sensíveis (strict/permissive) | Ativo | | 12 | **Histórico** | Redação de secrets no histórico de conversas | Ativo | | 13 | **SSRF** | Bloqueio de IPs privados, link-local e cloud metadata | Ativo | | 14 | **Rate Limiting** | Token bucket por cliente no servidor gRPC | Ativo | | 15 | **Plugins** | Assinatura Ed25519 com verificação obrigatória | Ativo | | 16 | **Plugins** | Sistema de quarentena para plugins não verificados | Ativo | | 17 | **Comandos** | Allowlist com 150+ comandos em 8 categorias | Ativo | | 18 | **Comandos** | Modo strict vs permissive para allowlist | Ativo | | 19 | **Leitura** | Bloqueio de caminhos sensíveis (`.env`, `.ssh`, etc.) | Ativo | | 20 | **Prompt Injection** | Delimitadores `` para isolar dados de instruções | Ativo | | 21 | **Log Scrubbing** | 18 padrões de sanitização antes de enviar ao LLM | Ativo | | 22 | **Audit Log** | Logging estruturado em JSON Lines para auditoria | Ativo | | 23 | **CORS** | Deny-all por padrão no operator Kubernetes | Ativo | | 24 | **Resource Types** | Allowlist de 17 tipos seguros, 18 tipos perigosos bloqueados | Ativo | | 25 | **Operator Auth** | Fail-closed — requisições sem auth são recusadas | Ativo | | 26 | **RBAC K8s** | Least-privilege, namespace-scoped por padrão | Ativo | | 27 | **gRPC Limits** | Limites de tamanho de mensagem e conexões concorrentes | Ativo | | 28 | **Bind Address** | Bind em `localhost` por padrão (não expõe na rede) | Ativo | | 29 | **JWT Clock Skew** | Tolerância configurável para diferença de relógio | Ativo | | 30 | **NetworkPolicy** | Política de rede para o operator Kubernetes | Ativo | | 31 | **Cosign** | Assinatura de imagens de container com Cosign | Ativo | | 32 | **govulncheck** | Verificação de vulnerabilidades em dependências Go no CI | Ativo | | 33 | **gosec** | Análise estática de segurança no CI | Ativo | | 34 | **Dependabot** | Atualização automática de dependências | Ativo | | 35 | **Admission Webhook** | Validação de recursos antes da criação no K8s | Ativo | *** ## Autenticação e Autorização O ChatCLI suporta dois modelos de autenticação: **JWT** (recomendado para produção) e **Bearer Token legado** (para desenvolvimento e compatibilidade). ### Autenticação JWT O JWT (JSON Web Token) fornece autenticação stateless com claims estruturados. O ChatCLI valida `iss` (issuer), `aud` (audience), `exp` (expiração) e o claim customizado `role` para autorização. ```bash theme={"system"} # Variáveis obrigatórias para habilitar JWT export CHATCLI_JWT_SECRET="sua-chave-secreta-com-pelo-menos-32-caracteres" export CHATCLI_JWT_ISSUER="chatcli-auth" export CHATCLI_JWT_AUDIENCE="chatcli-server" # Opcional: tolerância de clock skew (padrão: 30s) export CHATCLI_JWT_CLOCK_SKEW=60s chatcli server ``` ```bash theme={"system"} # Exemplo: gerar token JWT com role admin (usando Go) # O token deve incluir os claims: iss, aud, exp, sub, role # Exemplo com curl para um auth service externo: curl -X POST https://auth.example.com/token \ -H "Content-Type: application/json" \ -d '{ "username": "admin", "password": "...", "audience": "chatcli-server" }' # Usar o token com o cliente: export CHATCLI_SERVER_TOKEN="eyJhbGciOiJIUzI1NiIs..." chatcli remote connect server.example.com:50051 ``` ```bash theme={"system"} # Autenticação simples com Bearer token # Usa crypto/subtle.ConstantTimeCompare (previne timing attacks) export CHATCLI_SERVER_TOKEN=$(openssl rand -hex 32) chatcli server --token $CHATCLI_SERVER_TOKEN # No cliente: chatcli remote connect localhost:50051 --token $CHATCLI_SERVER_TOKEN ``` ### RBAC — Controle de Acesso Baseado em Roles O claim `role` no JWT determina as permissões do usuário. O sistema segue o princípio do **menor privilégio**. | Permissão | `admin` | `user` | `readonly` | | -------------------------- | :-------------------: | :-------------------: | :-------------------: | | Enviar mensagens | | | | | Executar comandos (agente) | | | | | Listar sessões | | | | | Ler sessões | | | | | Deletar sessões | | | | | Gerenciar plugins | | | | | Configurar servidor | | | | | Alterar roles de usuários | | | | | Visualizar audit logs | | | | | Health check | | | | O role `readonly` **não pode** enviar mensagens nem executar comandos. Ideal para dashboards de monitoramento e integrações que apenas consomem dados. ### Rate Limiting de Autenticação Tentativas de autenticação falhadas são limitadas a **5 por minuto por IP**. Após exceder o limite, o IP recebe `429 Too Many Requests` com backoff progressivo. ``` Tentativa 1-5: Resposta normal (401 Unauthorized) Tentativa 6: 429 Too Many Requests (espere 30s) Tentativa 7+: 429 Too Many Requests (espere 60s, 120s, 240s...) ``` ### OAuth PKCE + Device Flow Para autenticação com provedores externos (Anthropic, GitHub, Google), o ChatCLI implementa: * **PKCE** (Proof Key for Code Exchange): Previne interceptação do authorization code * **Device Flow**: Para ambientes sem browser (SSH, containers, CI/CD) Veja a documentação completa de OAuth em [Autenticação OAuth](/pt/features/oauth-authentication). *** ## Criptografia e Proteção de Dados ### AES-256-GCM para Credenciais Todas as credenciais OAuth e tokens são armazenados com criptografia **AES-256-GCM** (Galois/Counter Mode), que fornece tanto confidencialidade quanto autenticidade dos dados. ``` ~/.chatcli/ auth-profiles.json (0600) — credenciais criptografadas AES-256-GCM .auth-key (0600) — chave mestre de 256 bits ``` ```go theme={"system"} // Fluxo de criptografia simplificado: // 1. Gera chave aleatória de 256 bits (crypto/rand) // 2. Cria cipher AES-256 // 3. Gera nonce aleatório de 12 bytes // 4. Encripta com GCM (nonce || ciphertext || tag) // 5. Codifica em base64 para armazenamento nonce := make([]byte, gcm.NonceSize()) // 12 bytes io.ReadFull(crypto.Reader, nonce) ciphertext := gcm.Seal(nonce, nonce, plaintext, nil) ``` ### Criptografia de Sessão em Repouso Os dados de sessão são criptografados antes de gravar em disco usando uma chave derivada via **HKDF** (HMAC-based Key Derivation Function) a partir da chave mestre. ``` Chave mestre (.auth-key) │ ▼ HKDF (SHA-256, salt=session-id, info="chatcli-session") │ ▼ Chave de sessão (256 bits, única por sessão) │ ▼ AES-256-GCM (criptografia dos dados de sessão) ``` ### TLS 1.3 para gRPC Em produção, o servidor gRPC exige TLS 1.3 com cipher suites fortes. ```bash theme={"system"} # Gerar certificado autoassinado para testes: openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 \ -keyout key.pem -out cert.pem -days 365 -nodes \ -subj "/CN=chatcli-server" # Iniciar servidor com TLS: chatcli server --tls-cert cert.pem --tls-key key.pem ``` Se o carregamento do certificado TLS falhar, o erro é escrito em **stderr** e no log estruturado, incluindo os caminhos do certificado e da chave. Em containers, isso garante que o erro seja visível via `kubectl logs` mesmo que o logger estruturado não consiga fazer flush antes do crash. Quando TLS não está configurado, o servidor emite um log de warning a cada startup. O comportamento funcional não muda, mas a comunicação trafega em texto plano. ### Redação de Variáveis de Ambiente O ChatCLI detecta e redacta automaticamente variáveis de ambiente sensíveis antes de exibir ou enviar ao LLM. ```bash theme={"system"} export CHATCLI_ENV_REDACTION=strict # Redacta QUALQUER variável que contenha: # KEY, SECRET, TOKEN, PASSWORD, CREDENTIAL, AUTH, # API_KEY, PRIVATE, CERTIFICATE, e mais ``` Exemplo de saída: ``` AWS_ACCESS_KEY_ID=****REDACTED**** DATABASE_URL=****REDACTED**** OPENAI_API_KEY=****REDACTED**** ``` ```bash theme={"system"} export CHATCLI_ENV_REDACTION=permissive # Redacta apenas variáveis em uma lista fixa: # *_KEY, *_SECRET, *_TOKEN, *_PASSWORD # Variáveis como PATH, HOME, SHELL são preservadas ``` ### Redação do Histórico de Conversas O histórico de conversas passa por redação automática antes de ser persistido. Padrões detectados incluem: * API keys (formato `sk-...`, `pk_...`, `ghp_...`) * Tokens JWT (formato `eyJ...`) * Connection strings com credenciais * IPs privados em contextos sensíveis * Números de cartão de crédito (Luhn validation) ### Integração com OS Keychain Quando disponível, o ChatCLI armazena a chave mestre no keychain do sistema operacional em vez do arquivo `.auth-key`. | Sistema | Backend | Comando | | ------- | ---------------------------------------------- | ------------------------------- | | macOS | Keychain Services | `security add-generic-password` | | Linux | Secret Service API (GNOME Keyring, KDE Wallet) | `secret-tool store` | | Windows | Windows Credential Manager | `cmdkey /add` | A integração com keychain é automática quando o backend está disponível. Use `CHATCLI_DISABLE_KEYCHAIN=true` para forçar o armazenamento em arquivo. *** ## Segurança do Modo Agente O modo agente permite que a IA execute comandos no seu sistema. O ChatCLI implementa **múltiplas camadas de proteção** para garantir que apenas operações seguras sejam executadas. ### Allowlist de Comandos O sistema mantém uma allowlist com **150+ comandos** organizados em **8 categorias**. Apenas comandos nesta lista são permitidos sem confirmação do usuário. ``` ls, ll, la, tree, pwd, cd, find, locate, which, whereis, file, stat, df, du, wc, dirname, basename, realpath, readlink, test, mkdir, touch, head, tail, less ``` Comandos de escrita (`cp`, `mv`, `rm`) **não** estão na allowlist — requerem confirmação. ``` cat, bat, less, more, head, tail, grep, rg, ag, ack, sed (somente leitura), awk (somente leitura), cut, sort, uniq, diff, comm, join, paste, tr, expand, unexpand ``` ``` git status, git log, git diff, git show, git branch, git tag, git stash list, git remote -v, git describe, git rev-parse, git ls-files, git ls-tree, git blame, git shortlog, git reflog, git config --get, git cherry, git merge-base, git name-rev, git whatchanged ``` Operações destrutivas como `git push --force`, `git reset --hard` e `git clean -f` **nunca** estão na allowlist. ``` go build, go test, go vet, go fmt, go mod tidy, go run, go generate, go doc, go env, go version, npm run, npm test, npm list, npx, yarn, pnpm, make, cmake, cargo build, cargo test, cargo clippy, python -m pytest, pip list, rustc --version ``` ``` uname, hostname, uptime, whoami, id, groups, env (com redação), printenv (com redação), date, cal, free, top (modo batch), ps, lsb_release, sw_vers, sysctl (somente leitura) ``` ``` ping, traceroute, dig, nslookup, host, whois, curl (somente GET), wget (somente download), ss, netstat, ip addr, ifconfig, nmap (somente scan), openssl s_client (verificação TLS) ``` Comandos de rede que podem modificar configurações (`iptables`, `route add`, `ip link set`) são **bloqueados**. ``` docker ps, docker images, docker logs, docker inspect, docker stats, docker top, docker port, kubectl get, kubectl describe, kubectl logs, kubectl top, kubectl api-resources, kubectl explain, kubectl config view, kubectl cluster-info, helm list, helm status, helm get values, crictl ps, podman ps ``` ``` jq, yq, xq, xmllint, python -m json.tool, base64 (decodificação), md5sum, sha256sum, tar (somente listar: tf/tvf), zip (somente listar: -l), echo, printf, tee (somente leitura), column, fmt ``` ### Modo Strict vs Permissive ```bash theme={"system"} export CHATCLI_AGENT_ALLOWLIST_MODE=strict ``` * Apenas comandos da allowlist executam sem confirmação * Qualquer comando fora da lista requer aprovação explícita do usuário * **Recomendado para produção e ambientes compartilhados** ```bash theme={"system"} export CHATCLI_AGENT_ALLOWLIST_MODE=permissive ``` * Comandos da allowlist executam sem confirmação * Comandos desconhecidos exibem um aviso, mas permitem execução após confirmação simplificada * Comandos na **denylist** continuam bloqueados * **Use apenas em ambientes de desenvolvimento isolados** ### Bloqueio de Caminhos Sensíveis O agente **não pode ler** arquivos em caminhos considerados sensíveis, independentemente da allowlist: | Caminho | Motivo | | ------------------------------- | ------------------------------ | | `~/.ssh/*` | Chaves SSH privadas | | `~/.gnupg/*` | Chaves GPG | | `~/.aws/credentials` | Credenciais AWS | | `~/.azure/credentials` | Credenciais Azure | | `~/.gcp/*.json` | Service accounts GCP | | `~/.kube/config` | Kubeconfig com tokens | | `~/.env`, `.env`, `.env.*` | Variáveis de ambiente | | `~/.chatcli/.auth-key` | Chave mestre de criptografia | | `~/.chatcli/auth-profiles.json` | Credenciais criptografadas | | `/etc/shadow` | Hashes de senhas do sistema | | `/etc/sudoers` | Configuração de sudo | | `**/id_rsa`, `**/id_ed25519` | Chaves privadas SSH | | `**/*.pem`, `**/*.key` | Certificados e chaves privadas | Tentativas de leitura desses caminhos são **silenciosamente bloqueadas** e registradas no audit log. A IA recebe uma mensagem genérica informando que o arquivo não está acessível. ### Shell Config Sourcing Por padrão, o agente **não** carrega arquivos de configuração do shell (`.bashrc`, `.zshrc`). Isso previne execução de código arbitrário que possa existir nesses arquivos. ```bash theme={"system"} # Habilitar source de shell config (opt-in) export CHATCLI_AGENT_SOURCE_SHELL_CONFIG=true ``` ### Input guard — proteção contra typeahead em prompts de segurança Quando uma security box aparece (modo coder/agent), três camadas defendem contra digitação acidental ser consumida como resposta y/n: 1. **Flush kernel TTY** — `TCIFLUSH` (Linux) / `TIOCFLUSH` (BSD/Darwin) / `FlushConsoleInputBuffer` (Windows) descarta bytes na fila do kernel **antes** de renderizar a box. 2. **Drain channel** — esvazia o canal centralizado de stdin não-bloqueante (buffer de 10 linhas que o reader goroutine usa). 3. **Intent debounce** — descarta qualquer input que chegue nos primeiros **250ms** após a box ser desenhada (a janela de reação humana mínima). Sem essas camadas, digitar acidentalmente durante o stream do LLM faria a security box consumir os bytes prontos como aprovação. A primeira vez que isso aconteceu motivou o input guard. Adicionalmente, no início de cada turn do agente, o ChatCLI faz `stty sane` no `/dev/tty` controlador para recuperar de um teardown anterior do go-prompt que possa ter deixado o terminal em raw mode (echo off). Sem esse reset, você digita e não vê os caracteres na tela — embora o kernel esteja capturando. ### Sanitização de Saída de Comandos A saída de todos os comandos executados passa por um sanitizador que detecta tentativas de **prompt injection**: ``` Padrões detectados e removidos: - "Ignore previous instructions..." - "You are now a..." - "System: new instructions..." - Sequências de escape ANSI maliciosas - Caracteres Unicode de controle (RTL override, etc.) ``` *** ## Segurança de Plugins O sistema de plugins do ChatCLI usa **assinatura criptográfica Ed25519** para garantir integridade e autenticidade. ### Verificação Ed25519 Cada plugin deve ser assinado com uma chave Ed25519. Na instalação, o ChatCLI verifica: 1. A assinatura é válida contra a chave pública do autor 2. O hash SHA-256 do binário confere com o manifesto 3. O manifesto não foi alterado (assinatura cobre o manifesto inteiro) ### Sistema de Quarentena Plugins não verificados são colocados em **quarentena** — um diretório isolado onde não podem ser executados: ``` ~/.chatcli/plugins/ verified/ — plugins com assinatura válida (executáveis) quarantine/ — plugins sem assinatura ou com assinatura inválida ``` ### Permissões de Arquivo | Arquivo | Permissão | Descrição | | ------------------- | --------- | --------------------------------------------- | | Diretório do plugin | `0700` | Acesso apenas do dono | | Binário do plugin | `0600` | Leitura apenas do dono (executado via loader) | | Manifesto | `0600` | Leitura apenas do dono | | Assinatura | `0600` | Leitura apenas do dono | ### Permitir Plugins Não Assinados Essa opção desabilita a verificação de assinatura. Use **apenas** em desenvolvimento local. ```bash theme={"system"} export CHATCLI_ALLOW_UNSIGNED_PLUGINS=true ``` ### Como Assinar um Plugin ```bash theme={"system"} chatcli plugin keygen --output ~/.chatcli/plugin-keys/ # Gera: # plugin-signing.key (chave privada — NUNCA compartilhe) # plugin-signing.pub (chave pública — distribua com o plugin) ``` ```json theme={"system"} { "name": "meu-plugin", "version": "1.0.0", "description": "Descrição do plugin", "author": "seu-nome", "binary": "meu-plugin", "checksum": "" } ``` ```bash theme={"system"} sha256sum meu-plugin | awk '{print $1}' # Copie o hash para o campo "checksum" do manifesto ``` ```bash theme={"system"} chatcli plugin sign \ --manifest manifest.json \ --key ~/.chatcli/plugin-keys/plugin-signing.key \ --output manifest.json.sig ``` Inclua na distribuição: * O binário do plugin * `manifest.json` * `manifest.json.sig` * `plugin-signing.pub` (chave pública) ```bash theme={"system"} chatcli plugin install ./meu-plugin/ # A verificação de assinatura é automática # Se falhar, o plugin vai para quarentena ``` *** ## Segurança do Servidor gRPC ### Prevenção de SSRF O servidor gRPC inclui proteção contra **Server-Side Request Forgery** (SSRF). Todas as URLs processadas passam por validação antes de serem acessadas. **CIDRs bloqueados:** ``` 10.0.0.0/8 — Rede privada Classe A 172.16.0.0/12 — Rede privada Classe B 192.168.0.0/16 — Rede privada Classe C 127.0.0.0/8 — Loopback 169.254.169.254/32 — AWS/GCP metadata endpoint 100.100.100.200/32 — Alibaba Cloud metadata fd00::/8 — IPv6 Unique Local ::1/128 — IPv6 loopback fe80::/10 — IPv6 link-local ``` A validação também resolve DNS para prevenir bypass via domínios que apontam para IPs privados (DNS rebinding). ### Rate Limiting por Cliente O servidor implementa rate limiting com **token bucket** por cliente, identificado pelo IP de origem. | Parâmetro | Padrão | Variável | | ------------------ | ------ | ---------------------------- | | Tokens por segundo | 10 | `CHATCLI_RATE_LIMIT_RPS` | | Burst máximo | 20 | `CHATCLI_RATE_LIMIT_BURST` | | Cleanup interval | 5min | `CHATCLI_RATE_LIMIT_CLEANUP` | ```bash theme={"system"} # Configurar rate limiting customizado export CHATCLI_RATE_LIMIT_RPS=5 export CHATCLI_RATE_LIMIT_BURST=10 chatcli server ``` ### Limites de Mensagem gRPC | Parâmetro | Padrão | Variável | | ----------------------------------- | ------ | ---------------------------- | | Tamanho máximo de mensagem recebida | 4 MB | `CHATCLI_GRPC_MAX_RECV_SIZE` | | Tamanho máximo de mensagem enviada | 4 MB | `CHATCLI_GRPC_MAX_SEND_SIZE` | | MaxConcurrentStreams | 100 | `CHATCLI_GRPC_MAX_STREAMS` | ### Interceptor de Validação de Campos Todas as requisições gRPC passam por um interceptor que valida: * Tamanho máximo de strings (previne DoS por payload) * Caracteres permitidos em identificadores * Formato de UUIDs de sessão * Ranges de valores numéricos ### Bind Address ```bash theme={"system"} # Padrão local: bind apenas em localhost (seguro) chatcli server # Escuta em 127.0.0.1:50051 # Em Kubernetes: auto-detecta via KUBERNETES_SERVICE_HOST e usa 0.0.0.0 # Nenhuma configuração necessária! # Expor na rede manualmente (use apenas com TLS + auth) chatcli server --bind 0.0.0.0:50051 --tls-cert cert.pem --tls-key key.pem ``` Em Kubernetes, o bind address é automaticamente configurado para `0.0.0.0` — nenhuma configuração manual é necessária. O servidor detecta o ambiente via a variável `KUBERNETES_SERVICE_HOST`. Nunca exponha o servidor na rede (`0.0.0.0`) sem TLS e autenticação habilitados. ### gRPC Reflection O gRPC reflection está **desabilitado por padrão**. Quando habilitado, expõe o schema completo do serviço, facilitando reconhecimento por atacantes. ```bash theme={"system"} # Habilitar apenas para debugging local export CHATCLI_GRPC_REFLECTION=true ``` ### Audit Logging Estruturado Todas as operações do servidor são registradas em formato **JSON Lines** para integração com sistemas de SIEM. ```json theme={"system"} { "timestamp": "2026-04-06T10:30:00Z", "level": "info", "event": "grpc.request", "method": "/chatcli.v1.ChatService/SendMessage", "client_ip": "192.168.1.100", "user": "admin@example.com", "role": "admin", "duration_ms": 245, "status": "OK", "request_size": 1024, "response_size": 4096 } ``` ```bash theme={"system"} # Configurar output do audit log export CHATCLI_AUDIT_LOG=/var/log/chatcli/audit.jsonl export CHATCLI_AUDIT_LOG_MAX_SIZE=100M export CHATCLI_AUDIT_LOG_MAX_AGE=90d ``` *** ## Segurança do Operator Kubernetes O operator Kubernetes do ChatCLI implementa proteções específicas para o ambiente cloud-native. ### Autenticação Fail-Closed A API REST do operator usa autenticação **fail-closed**: se o middleware de autenticação falhar por qualquer motivo (erro interno, timeout, configuração inválida), a requisição é **recusada**. Nenhuma requisição passa sem validação explícita. ``` Requisição → Auth Middleware → Erro? ├── Sim → 403 Forbidden (fail-closed) └── Não → Validar token → Processar ``` As API keys são carregadas com hot-reload a cada 30 segundos, na seguinte ordem de prioridade: 1. **Secret** `chatcli-operator-secrets` (prioridade) — campo `api-keys` com lista YAML de entradas `{key, role, description}` 2. **ConfigMap** `chatcli-operator-config` (fallback) — mesmo campo `api-keys` 3. Rejeita a requisição (ou aceita em dev-mode se `CHATCLI_OPERATOR_DEV_MODE=true`) **Não confunda os dois Secrets de Auth do projeto** — ambos costumam aparecer juntos no namespace do operator: | Secret | Para quê | Quem consome | Campo | | -------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------- | | `chatcli-operator-secrets` | **REST API auth** do operator (dashboard, `/api/v1/*`) | operator pod (este capítulo) | `api-keys` (YAML) | | `chatcli-api-keys` | **LLM provider keys** (OPENAI\_API\_KEY, ANTHROPIC\_API\_KEY, etc.) usadas pelo gateway chatcli | chatcli **server** pod via `Instance.spec.apiKeys.name` | uma chave por provedor (`OPENAI_API_KEY`, etc.) | O Secret `chatcli-operator-secrets` precisa estar **no mesmo namespace que o pod do operator** (o controller chama `Secrets(resolveNamespace()).Get(...)` — `resolveNamespace()` lê `POD_NAMESPACE` env var, o arquivo de namespace do ServiceAccount, ou cai pro default `chatcli-system`). Se você fez `helm install --namespace `, crie o Secret em ``. API keys armazenadas no Secret são recarregadas automaticamente a cada 30s -- nenhum restart do operator é necessário. ### Allowlist de Tipos de Recursos O operator só pode remediar um conjunto restrito de recursos Kubernetes. Isso previne que a IA modifique recursos críticos do cluster. ``` Deployment, StatefulSet, DaemonSet, ReplicaSet, Pod, Service, ConfigMap, Ingress, Job, CronJob, HorizontalPodAutoscaler, PodDisruptionBudget, NetworkPolicy, ServiceAccount, Role, RoleBinding, Endpoints ``` ``` Node, Namespace, PersistentVolume, ClusterRole, ClusterRoleBinding, CustomResourceDefinition, MutatingWebhookConfiguration, ValidatingWebhookConfiguration, APIService, StorageClass, PriorityClass, RuntimeClass, PodSecurityPolicy, ResourceQuota, LimitRange, Secret, PersistentVolumeClaim, CSIDriver ``` Tentativas de remediar tipos bloqueados são registradas no audit log e geram alertas. ### Log Scrubbing (18 Padrões) Antes de enviar logs ao LLM para análise, o operator remove informações sensíveis usando **18 padrões de sanitização**: | # | Padrão | Exemplo | | -- | --------------------- | --------------------------------------------------------- | | 1 | API Keys | `Bearer sk-abc123...` → `Bearer ****` | | 2 | JWT Tokens | `eyJhbGciOi...` → `[JWT_REDACTED]` | | 3 | Connection Strings | `postgres://user:pass@host` → `postgres://****:****@host` | | 4 | Certificados Base64 | `LS0tLS1CRUdJTi...` → `[CERT_REDACTED]` | | 5 | Chaves Privadas | `-----BEGIN RSA PRIVATE KEY-----` → `[KEY_REDACTED]` | | 6 | AWS Access Keys | `AKIA...` → `[AWS_KEY_REDACTED]` | | 7 | AWS Secret Keys | `wJalrXUtnFEMI...` → `[AWS_SECRET_REDACTED]` | | 8 | GCP Service Account | `"private_key": "..."` → `[GCP_KEY_REDACTED]` | | 9 | Passwords em URLs | `://user:password@` → `://****:****@` | | 10 | Tokens OAuth | `access_token=...` → `access_token=****` | | 11 | GitHub Tokens | `ghp_...`, `gho_...` → `[GH_TOKEN_REDACTED]` | | 12 | Slack Tokens | `xoxb-...`, `xoxp-...` → `[SLACK_TOKEN_REDACTED]` | | 13 | Stripe Keys | `sk_live_...`, `pk_live_...` → `[STRIPE_REDACTED]` | | 14 | Números de Cartão | `4111 1111 1111 1111` → `[CARD_REDACTED]` | | 15 | SSN (US) | `123-45-6789` → `[SSN_REDACTED]` | | 16 | IPs em contextos auth | `auth from 10.0.0.1` → `auth from [IP_REDACTED]` | | 17 | Email em logs | `user@domain.com` → `[EMAIL_REDACTED]` | | 18 | Kubernetes Secrets | `data: {key: base64...}` → `data: {key: [REDACTED]}` | ### CORS Deny-All O operator responde com headers CORS que **negam todas as origens** por padrão: ``` Access-Control-Allow-Origin: (não definido) Access-Control-Allow-Methods: (não definido) Access-Control-Allow-Headers: (não definido) ``` Para integrar com dashboards web, configure origens permitidas explicitamente via `CHATCLI_OPERATOR_CORS_ORIGINS`. ### RBAC Least-Privilege O Helm chart cria **Role** e **RoleBinding** (namespace-scoped) por padrão: ```yaml theme={"system"} # values.yaml rbac: create: true clusterWide: false # Role (padrão) vs ClusterRole ``` ### NetworkPolicy O chart inclui uma NetworkPolicy restritiva: ```yaml theme={"system"} apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: chatcli-operator spec: podSelector: matchLabels: app: chatcli-operator policyTypes: - Ingress - Egress ingress: - from: - namespaceSelector: matchLabels: chatcli-access: "true" ports: - port: 8443 # API REST (TLS) - port: 50051 # gRPC (TLS) egress: - to: - namespaceSelector: {} ports: - port: 443 # Kubernetes API - port: 6443 # Kubernetes API (alternativo) ``` ### Admission Webhook O operator inclui um **ValidatingWebhookConfiguration** que intercepta criação e atualização de recursos ChatCLI customizados, validando: * Schema dos CRDs * Limites de recursos * Referências a secrets existentes * Nomes de namespace válidos ### Structured Audit Logging Todas as ações de remediação são logadas em formato estruturado: ```json theme={"system"} { "timestamp": "2026-04-06T10:30:00Z", "event": "remediation.applied", "resource_type": "Deployment", "resource_name": "nginx", "namespace": "production", "action": "scale_up", "replicas_before": 1, "replicas_after": 3, "reason": "Pod CrashLoopBackOff detectado", "approved_by": "auto-policy", "audit_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ``` *** ## Segurança de CI/CD O pipeline de CI/CD do ChatCLI inclui verificações automáticas de segurança em cada pull request e release. Verifica todas as dependências Go contra o banco de dados de vulnerabilidades do Go. Falha o build se encontrar CVEs conhecidos em dependências usadas. ```bash theme={"system"} govulncheck ./... ``` Análise estática de segurança que detecta padrões inseguros no código-fonte: SQL injection, uso de `crypto/md5`, hardcoded credentials, e mais. ```bash theme={"system"} gosec -fmt json ./... ``` Monitora dependências e cria PRs automáticos quando atualizações de segurança estão disponíveis. Configurado para Go modules e GitHub Actions. Todas as imagens de container publicadas são assinadas com **Sigstore Cosign**. Verifique a autenticidade antes de usar: ```bash theme={"system"} cosign verify ghcr.io/diillson/chatcli:latest \ --certificate-oidc-issuer https://token.actions.githubusercontent.com \ --certificate-identity-regexp "github.com/diillson/chatcli" ``` ### API Key Masking em Workflows Todos os secrets usados nos workflows do GitHub Actions são mascarados automaticamente nos logs. Além disso, o ChatCLI implementa masking adicional para prevenir vazamento acidental de chaves em outputs de testes. *** ## Referência de Variáveis de Segurança Tabela completa de todas as variáveis de ambiente relacionadas à segurança do ChatCLI: ### Autenticação e Autorização | Variável | Descrição | Padrão | | ------------------------------- | ---------------------------------------------- | ----------------------- | | `CHATCLI_JWT_SECRET` | Chave secreta para validação JWT (HMAC-SHA256) | `""` (JWT desabilitado) | | `CHATCLI_JWT_ISSUER` | Valor esperado do claim `iss` | `""` | | `CHATCLI_JWT_AUDIENCE` | Valor esperado do claim `aud` | `""` | | `CHATCLI_JWT_CLOCK_SKEW` | Tolerância de clock skew para validação `exp` | `30s` | | `CHATCLI_SERVER_TOKEN` | Token Bearer para autenticação legada | `""` (sem auth) | | `CHATCLI_AUTH_RATE_LIMIT` | Tentativas de auth por minuto por IP | `5` | | `CHATCLI_AUTH_LOCKOUT_DURATION` | Duração do bloqueio após exceder rate limit | `5m` | ### Criptografia e TLS | Variável | Descrição | Padrão | | ---------------------------- | ------------------------------------------------------ | ------- | | `CHATCLI_SERVER_TLS_CERT` | Caminho do certificado TLS do servidor | `""` | | `CHATCLI_SERVER_TLS_KEY` | Caminho da chave TLS do servidor | `""` | | `CHATCLI_TLS_MIN_VERSION` | Versão mínima de TLS aceita | `1.3` | | `CHATCLI_ENCRYPTION_KEY` | Chave de criptografia customizada (override .auth-key) | `""` | | `CHATCLI_DISABLE_KEYCHAIN` | Desabilita integração com OS keychain | `false` | | `CHATCLI_SESSION_ENCRYPTION` | Habilita/desabilita criptografia de sessão | `true` | | `CHATCLI_SESSION_TTL` | Tempo de vida máximo de sessão inativa | `24h` | ### Redação e Proteção de Dados | Variável | Descrição | Padrão | | ---------------------------- | ----------------------------------------------------------- | ------------- | | `CHATCLI_ENV_REDACTION` | Modo de redação de env vars (`strict`/`permissive`/`off`) | `strict` | | `CHATCLI_HISTORY_REDACTION` | Habilita redação do histórico de conversas | `true` | | `CHATCLI_LOG_SCRUB_PATTERNS` | Padrões regex adicionais para log scrubbing (`;` separados) | `""` | | `CHATCLI_AUDIT_LOG` | Caminho do arquivo de audit log | `""` (stdout) | | `CHATCLI_AUDIT_LOG_MAX_SIZE` | Tamanho máximo do arquivo de audit log | `100M` | | `CHATCLI_AUDIT_LOG_MAX_AGE` | Idade máxima dos logs de auditoria | `90d` | ### Modo Agente | Variável | Descrição | Padrão | | ----------------------------------- | --------------------------------------------------------- | -------- | | `CHATCLI_AGENT_ALLOWLIST_MODE` | Modo da allowlist (`strict`/`permissive`) | `strict` | | `CHATCLI_AGENT_DENYLIST` | Padrões regex adicionais para bloquear (`;` separados) | `""` | | `CHATCLI_AGENT_ALLOW_SUDO` | Permite execução de sudo no modo agente | `false` | | `CHATCLI_AGENT_CMD_TIMEOUT` | Timeout de execução por comando | `10m` | | `CHATCLI_AGENT_SOURCE_SHELL_CONFIG` | Permite source de `.bashrc`/`.zshrc` | `false` | | `CHATCLI_AGENT_MAX_OUTPUT_SIZE` | Tamanho máximo da saída de comandos | `1M` | | `CHATCLI_AGENT_BLOCKED_PATHS` | Caminhos adicionais para bloquear leitura (`;` separados) | `""` | ### Plugins | Variável | Descrição | Padrão | | -------------------------------- | -------------------------------------------------- | ------------------------------- | | `CHATCLI_ALLOW_UNSIGNED_PLUGINS` | Permite plugins sem assinatura Ed25519 | `false` | | `CHATCLI_PLUGIN_TRUSTED_KEYS` | Chaves públicas Ed25519 confiáveis (`,` separadas) | `""` | | `CHATCLI_PLUGIN_QUARANTINE_DIR` | Diretório de quarentena customizado | `~/.chatcli/plugins/quarantine` | ### Servidor gRPC | Variável | Descrição | Padrão | | ---------------------------- | ------------------------------------------------------------------- | ----------------------------------------- | | `CHATCLI_GRPC_REFLECTION` | Habilita gRPC reflection | `false` | | `CHATCLI_GRPC_MAX_RECV_SIZE` | Tamanho máximo de mensagem recebida | `4MB` | | `CHATCLI_GRPC_MAX_SEND_SIZE` | Tamanho máximo de mensagem enviada | `4MB` | | `CHATCLI_GRPC_MAX_STREAMS` | Máximo de streams concorrentes por conexão | `100` | | `CHATCLI_GRPC_BIND` | Endereço de bind do servidor. Auto-detecta `0.0.0.0` em Kubernetes. | `127.0.0.1:50051` / `0.0.0.0:50051` (K8s) | | `CHATCLI_RATE_LIMIT_RPS` | Requests por segundo por cliente | `10` | | `CHATCLI_RATE_LIMIT_BURST` | Burst máximo por cliente | `20` | | `CHATCLI_RATE_LIMIT_CLEANUP` | Intervalo de limpeza de buckets expirados | `5m` | ### SSRF e Rede | Variável | Descrição | Padrão | | ----------------------------- | -------------------------------------------------------- | ------ | | `CHATCLI_SSRF_BLOCK_PRIVATE` | Bloqueia acesso a redes privadas | `true` | | `CHATCLI_SSRF_BLOCK_METADATA` | Bloqueia acesso a endpoints de metadata cloud | `true` | | `CHATCLI_SSRF_ALLOWED_HOSTS` | Hosts permitidos mesmo em redes privadas (`,` separados) | `""` | | `CHATCLI_SSRF_DNS_CHECK` | Valida DNS resolution contra IPs privados | `true` | ### Operator Kubernetes | Variável | Descrição | Padrão | | ------------------------------------ | ------------------------------------------------ | ------------------ | | `CHATCLI_OPERATOR_CORS_ORIGINS` | Origens CORS permitidas (`,` separadas) | `""` (deny-all) | | `CHATCLI_OPERATOR_AUTH_MODE` | Modo de autenticação (`fail-closed`/`fail-open`) | `fail-closed` | | `CHATCLI_OPERATOR_ALLOWED_RESOURCES` | Override da allowlist de tipos de recursos | (17 tipos seguros) | | `CHATCLI_OPERATOR_LOG_SCRUB` | Habilita log scrubbing antes de enviar ao LLM | `true` | ### CI/CD e Verificação | Variável | Descrição | Padrão | | ------------------------------- | ------------------------------------------------ | ------- | | `CHATCLI_DISABLE_VERSION_CHECK` | Desabilita verificação automática de versão | `false` | | `CHATCLI_COSIGN_KEY` | Chave pública Cosign para verificação de imagens | `""` | *** ## Boas Práticas para Produção ```bash theme={"system"} export CHATCLI_JWT_SECRET=$(openssl rand -hex 32) export CHATCLI_JWT_ISSUER="sua-org-auth" export CHATCLI_JWT_AUDIENCE="chatcli-production" chatcli server ``` ```bash theme={"system"} # Use certificados de uma CA confiável (Let's Encrypt, etc.) chatcli server \ --tls-cert /etc/chatcli/tls/cert.pem \ --tls-key /etc/chatcli/tls/key.pem ``` ```bash theme={"system"} export CHATCLI_AGENT_ALLOWLIST_MODE=strict export CHATCLI_AGENT_ALLOW_SUDO=false export CHATCLI_AGENT_CMD_TIMEOUT=5m ``` ```bash theme={"system"} export CHATCLI_AUDIT_LOG=/var/log/chatcli/audit.jsonl export CHATCLI_AUDIT_LOG_MAX_SIZE=100M export CHATCLI_AUDIT_LOG_MAX_AGE=90d ``` ```bash theme={"system"} export CHATCLI_ENV_REDACTION=strict export CHATCLI_HISTORY_REDACTION=true export CHATCLI_OPERATOR_LOG_SCRUB=true ``` Não defina `CHATCLI_GRPC_REFLECTION=true` nem `CHATCLI_OPERATOR_CORS_ORIGINS` em produção, a menos que estritamente necessário. ```bash theme={"system"} # Padrão — mas verifique que não foi sobrescrito: export CHATCLI_ALLOW_UNSIGNED_PLUGINS=false ``` ```bash theme={"system"} helm install chatcli oci://ghcr.io/diillson/charts/chatcli \ --set rbac.clusterWide=false \ --set securityContext.readOnlyRootFilesystem=true \ --set podSecurityContext.runAsNonRoot=true ``` ```yaml theme={"system"} resources: requests: memory: "128Mi" cpu: "100m" limits: memory: "512Mi" cpu: "500m" ``` ```bash theme={"system"} cosign verify ghcr.io/diillson/chatcli:latest \ --certificate-oidc-issuer https://token.actions.githubusercontent.com \ --certificate-identity-regexp "github.com/diillson/chatcli" ``` ```bash theme={"system"} # Verifique vulnerabilidades localmente: govulncheck ./... # Atualize dependências: go get -u ./... go mod tidy ``` ```bash theme={"system"} # Verificar tentativas de auth falhadas: jq 'select(.event == "auth.failed")' /var/log/chatcli/audit.jsonl # Verificar remediações do operator: jq 'select(.event == "remediation.applied")' /var/log/chatcli/audit.jsonl # Alertar em tentativas de acesso a caminhos bloqueados: jq 'select(.event == "blocked_path.access")' /var/log/chatcli/audit.jsonl ``` *** ## Próximos Passos Configuração detalhada de PKCE, Device Flow e integração com provedores. Regras de policy, denylist customizada e controle granular de permissões. Desenvolvimento, distribuição e gerenciamento de plugins. Deploy, configuração avançada e monitoramento do servidor. Deploy do operator, CRDs e configuração de remediação automática. Guia completo de deploy containerizado com hardening. Todas as variáveis de ambiente e opções de configuração. Automação de tarefas com hooks de ciclo de vida.