Este guia mostra como deployar o ChatCLI em produção com todas as medidas de segurança habilitadas . Siga cada etapa na ordem para garantir uma configuração completa.
Pré-requisitos
Cluster Kubernetes com Helm 3.8+
kubectl e helm configuradosopenssl disponível para geração de chavesAcesso para criar Secrets no namespace de destino
Passo 1: Gerar Segredo JWT e Criar Secret K8s O JWT é usado para autenticar conexões entre clientes e o servidor ChatCLI.
# Gerar um segredo JWT de 256 bits JWT_SECRET = $( openssl rand -hex 32 ) # Criar o Secret no Kubernetes kubectl create namespace chatcli kubectl -n chatcli create secret generic chatcli-jwt \ --from-literal=secret= " $JWT_SECRET "
Guarde o valor de $JWT_SECRET em um cofre de segredos (Vault, AWS Secrets Manager, etc.). Você precisará dele para configurar clientes remotos.
Verifique o Secret:
kubectl -n chatcli get secret chatcli-jwt -o jsonpath='{.data.secret}' | base64 -d
Passo 2: Configurar Certificados TLS # chatcli-certificate.yaml apiVersion : cert-manager.io/v1 kind : Certificate metadata : name : chatcli-tls namespace : chatcli spec : secretName : chatcli-tls-certs issuerRef : name : letsencrypt-prod kind : ClusterIssuer dnsNames : - chatcli.meudominio.com
kubectl apply -f chatcli-certificate.yaml
# Gerar certificado auto-assinado (apenas para testes) openssl req -x509 -newkey rsa:4096 -keyout tls.key -out tls.crt \ -days 365 -nodes -subj "/CN=chatcli.meudominio.com" kubectl -n chatcli create secret tls chatcli-tls-certs \ --cert=tls.crt --key=tls.key
Passo 3: Configurar Rate Limiting Defina limites de requisições para prevenir abuso e DoS:
# values-security.yaml (parcial) security : rateLimitRps : 20 # 20 requisições por segundo # bindAddress: "0.0.0.0" # Opcional — auto-detectado em Kubernetes
Em Kubernetes, o bindAddress é automaticamente configurado para 0.0.0.0 via detecção de KUBERNETES_SERVICE_HOST. Defina explicitamente apenas em servidores fora do Kubernetes.
Para ambientes multi-tenant, considere valores mais baixos (5-10 RPS por instância) e use HPA para escalar horizontalmente.
Passo 4: Habilitar Log de Auditoria O log de auditoria registra cada operação com detalhes de quem, o que e quando:
# values-security.yaml (parcial) security : auditLog : true
# Variável de ambiente equivalente export CHATCLI_AUDIT_LOG = true
Os logs de auditoria incluem:
Usuário autenticado (via JWT claims)
Comando ou operação executada
Timestamp e resultado (sucesso/falha)
IP de origem da requisição
Passo 5: Configurar Allowlist de Comandos do Agente Habilite o modo strict para garantir que apenas comandos aprovados sejam executados:
# values-security.yaml (parcial) security : agentSecurityMode : strict # Se precisar de comandos adicionais: env : - name : CHATCLI_AGENT_ALLOWLIST value : "terraform;ansible;packer;vault" - name : CHATCLI_AGENT_WORKSPACE_STRICT value : "true" - name : CHATCLI_MAX_COMMAND_OUTPUT value : "50000"
No modo strict, mais de 150 comandos comuns já estão pré-aprovados em 8 categorias (arquivo, texto, dev, containers, rede, sistema, editores, shell). Adicione apenas os comandos específicos do seu workflow.
Para garantir que apenas plugins confiáveis sejam carregados:
# Gerar par de chaves Ed25519 openssl genpkey -algorithm Ed25519 -out plugin-sign.key openssl pkey -in plugin-sign.key -pubout -out plugin-sign.pub # Extrair a chave pública em formato base64 PLUGIN_PUB_KEY = $( openssl pkey -in plugin-sign.key -pubout -outform DER | base64 ) # Assinar um plugin openssl pkeyutl -sign -inkey plugin-sign.key \ -rawin -in meu-plugin.so -out meu-plugin.so.sig
Configure o ChatCLI para verificar assinaturas:
export CHATCLI_PLUGIN_VERIFY_SIGNATURES = true export CHATCLI_PLUGIN_TRUSTED_KEYS = " $PLUGIN_PUB_KEY "
Passo 7: Configurar Criptografia de Sessão Habilite criptografia para sessões armazenadas em disco:
# Gerar chave de criptografia AES-256 SESSION_KEY = $( openssl rand -hex 32 ) kubectl -n chatcli create secret generic chatcli-session-key \ --from-literal=key= " $SESSION_KEY "
# values-security.yaml (parcial) security : sessionEncryption : true env : - name : CHATCLI_SESSION_ENCRYPTION_KEY valueFrom : secretKeyRef : name : chatcli-session-key key : key
Passo 8: Configurar Segurança do Operador Para ambientes com o operador K8s, configure proteções adicionais.
Primeiro, crie um Secret com as API keys do operator:
apiVersion : v1 kind : Secret metadata : name : chatcli-operator-secrets namespace : chatcli-system type : Opaque stringData : api-keys : | - key: "<your-api-key>" role: admin description: "Dashboard admin"
Alterações no Secret chatcli-operator-secrets (ou no ConfigMap chatcli-operator-config como fallback) são detectadas automaticamente em até 30 segundos. Nenhum restart do operator é necessário.
Em seguida, configure as variáveis de segurança:
# values-security.yaml (parcial) env : - name : CHATCLI_OPERATOR_FAIL_CLOSED value : "true" - name : CHATCLI_OPERATOR_RESOURCE_ALLOWLIST value : "deployments;services;configmaps;pods" - name : CHATCLI_OPERATOR_LOG_SCRUBBING value : "true"
Configuração Efeito FAIL_CLOSEDBloqueia operações quando o agente está indisponível (vs. permitir fallback inseguro) RESOURCE_ALLOWLISTLimita quais recursos K8s o operador pode manipular LOG_SCRUBBINGRemove tokens, senhas e dados sensíveis dos logs
Combine todas as configurações em um único values-prod.yaml:
# values-prod.yaml llm : provider : CLAUDEAI secrets : existingSecret : chatcli-llm-keys server : token : "" # Usando JWT via jwtSecretRef metricsPort : 9090 tls : enabled : true existingSecret : chatcli-tls-certs security : rateLimitRps : 20 # bindAddress: "0.0.0.0" # Opcional — auto-detectado em Kubernetes agentSecurityMode : strict auditLog : true sessionEncryption : true jwtSecretRef : name : chatcli-jwt key : secret persistence : enabled : true size : 5Gi resources : requests : memory : 256Mi cpu : 200m limits : memory : 1Gi cpu : "1" podSecurityContext : runAsNonRoot : true runAsUser : 1000 runAsGroup : 1000 fsGroup : 1000 seccompProfile : type : RuntimeDefault securityContext : allowPrivilegeEscalation : false readOnlyRootFilesystem : true capabilities : drop : - ALL networkPolicy : enabled : true podDisruptionBudget : enabled : true minAvailable : 1 serviceMonitor : enabled : true interval : 30s
helm install chatcli oci://ghcr.io/diillson/charts/chatcli \ --namespace chatcli --create-namespace \ -f values-prod.yaml
Passo 10: Verificar Segurança Execute esta checklist para confirmar que tudo está configurado corretamente:
Verificar TLS
kubectl -n chatcli get secret chatcli-tls-certs # Deve retornar o secret com type: kubernetes.io/tls
Verificar JWT Secret
kubectl -n chatcli get secret chatcli-jwt # Deve existir com a chave 'secret'
Verificar SecurityContext do Pod
kubectl -n chatcli get pod -l app.kubernetes.io/name=chatcli -o jsonpath='{.items[0].spec.securityContext}' # Deve mostrar runAsNonRoot: true, etc.
Verificar NetworkPolicy
kubectl -n chatcli get networkpolicy # Deve listar a NetworkPolicy do ChatCLI
Verificar gRPC Reflection desabilitado
kubectl -n chatcli exec deploy/chatcli -- env | grep GRPC_REFLECTION # Deve estar vazio ou 'false'
Testar conexão autenticada
chatcli connect chatcli.meudominio.com:50051 --token " $JWT_SECRET " --tls
Verificar rate limiting
# Enviar múltiplas requisições rápidas — deve retornar erro 429 após o limite for i in $( seq 1 30 ); do chatcli -p "ping" --remote chatcli.meudominio.com:50051 & done
Verificar logs de auditoria
kubectl -n chatcli logs deploy/chatcli | grep "audit" # Deve mostrar entradas de auditoria para as operações acima
Checklist Final Item Status JWT Secret criado e referenciado TLS habilitado com certificado válido Rate limiting configurado Log de auditoria habilitado Modo agente strict ativo Workspace strict habilitado Plugins com verificação de assinatura Criptografia de sessão ativa Operador em modo fail-closed Log scrubbing habilitado NetworkPolicy criada PodDisruptionBudget criado SecurityContext restritivo gRPC Reflection desabilitado ServiceMonitor para métricas
Próximos Passos
Segurança e Hardening Documentação completa de todas as medidas de segurança.
Deploy com Docker e Helm Guia completo de deployment containerizado.
Operador K8s Configurar o operador Kubernetes.
Referência de Configuração Todas as variáveis de ambiente disponíveis.
