CH 28 · Segurança e Conformidade

Contagem de palavras~3.490 palavrasTempo~20 minPré-requisitosCH 04NívelFoco conceitual

Objetivo do Capítulo

Deixe um Agent que pode executar comandos e escrever arquivos trabalhar no seu computador — você vai se preocupar: ele vai apagar meus arquivos aleatoriamente? Vai enviar minhas chaves secretamente? Vai mudar as configurações do meu sistema?

Essas preocupações são válidas — um Agent sem limites de segurança é uma bomba-relógio. A resposta do dsh são três camadas de proteção: sandbox de arquivos, aprovação de operações, chaves somente escrita. O CH 04 mencionou algumas ao falar do modelo de permissões; este capítulo deixa claros os princípios de cada camada — como ela realmente mantém o Agent sob controle, quais são limites rígidos que não dá para contornar, e quais precisam do seu próprio julgamento. Depois de entender isso, você saberá o que pode entregar com segurança e o que precisa vigiar pessoalmente.

Primeiro Esclarecimento: O Pensamento de Segurança do dsh

O núcleo do design de segurança do dsh são oito caracteres: restrito por padrão, permitir sob demanda.

Não é "dê todas as permissões primeiro, depois confie na sua cautela", mas o contrário — por padrão ele só pode tocar no escopo que você explicitamente permite, e para cruzar a linha ele precisa do seu consentimento. Essa é uma mentalidade completamente diferente de "dê a senha de admin e deixe ele se virar".

Três camadas de proteção, de fora para dentro:

Camada	O que gerencia	Como
Camada 1: sandbox de arquivos	Quais arquivos ele pode tocar	Três níveis de permissão, isolamento no nível do kernel do SO
Camada 2: aprovação de operações	Se operações sensíveis podem ser executadas	Popup perguntando a você, você diz não e ele não roda
Camada 3: chaves somente escrita	Como as API Keys são armazenadas	Somente escrita, não exibidas na UI, armazenamento local não enviado

Cada camada abaixo.

Camada Um: Sandbox de Arquivos

O CH 04 cobriu os três níveis de permissão; aqui está o princípio por trás deles.

O sandbox não é um pedaço de JavaScript fazendo uma verificação if — "se o caminho não está no workspace, erro". Esse tipo de abordagem o modelo pode contornar (por ex. com saltos de caminho relativo, com symlinks). O sandbox do dsh é no nível do kernel do SO: no Windows usa job objects para limitar os recursos que um processo pode acessar, no Linux/macOS usa namespaces e seccomp para filtrar system calls. Não importa que truques o modelo use, se ele não passar pelo kernel, não passa.

Os três níveis de permissão, do estrito ao solto:

Modo	O que pode escrever	Cenários para os quais serve
read-only	Nada	Análise somente leitura, code review, Q&A puro — deixa ver mas não mudar
workspace-write (padrão)	Apenas o diretório do workspace atual + diretório temp do sistema	Trabalho diário — pode mudar arquivos do projeto, não pode tocar no sistema ou em outros projetos
danger-full-access	Sem restrições	Apenas quando você claramente precisa de operação em disco inteiro, por ex. manutenção do sistema, instalar software — o risco é seu

Um ponto facilmente esquecido: o sandbox governa apenas efeitos colaterais do sistema de arquivos, não isolamento de rede ou processos. Isso significa, no modo workspace-write, o Agent não consegue escrever arquivos fora do workspace, mas pode fazer requisições de rede, pode ler arquivos fora do workspace (somente leitura). Então não pense que ligar workspace-write é absolutamente seguro — ele pode enviar conteúdo de arquivos sensíveis do seu workspace para fora via requisições de API (um modelo normal não faria isso, mas é um limite teórico).

A troca foi coberta no CH 04: temporariamente para a sessão atual use /permission, para mudar o padrão vá em Settings → General → Permission (só afeta sessões recém-criadas).

Camada Dois: Aprovação de Operações

O sandbox mantém sob controle "quais arquivos ele pode tocar", a aprovação mantém sob controle "se operações sensíveis podem ser executadas".

Quando o Agent quer fazer algo além do escopo de permissão atual — por ex. escrever um arquivo fora do workspace no modo workspace-write, ou executar um comando que pode mudar o sistema — ele não roda direto, mas primeiro inicia uma requisição de aprovação, a interface abre um diálogo dizendo a você:

• Qual operação ele quer executar (o comando específico ou caminho de arquivo)
• Por que ele quer fazer isso (a razão do modelo)

Então você tem três escolhas: Permitir uma vez, Negar, Cancelar.

Placeholder de imagem: coloque aqui uma captura de "Agent solicita escrita de arquivo fora do workspace, diálogo de aprovação aparece" — você pode ver a operação, a razão do modelo, os botões permitir/negar.

Alguns detalhes importantes:

1. Permitir uma vez significa uma vez — não "sempre permitido no futuro". Na próxima vez que a mesma operação surgir, vai perguntar de novo.
2. Negar significa negar — quando o modelo recebe a negação, ele vai encontrar outro caminho ou te dizer que não consegue fazer, não vai contornar sorrateiramente.
3. Aprovação é um ponto de extensão em nível de plugin — o CH 11 cobriu o pipeline de chamada de ferramenta, aprovação é um estágio. Você pode escrever seu próprio plugin para customizar a política de aprovação, por ex. "permitir automaticamente alguns comandos, negar automaticamente outros".

Aprovação e sandbox trabalham juntos: o sandbox é um limite rígido (nível de kernel, não dá para contornar), aprovação é um limite flexível (nível de política, pode deixar passar). Uso diário de workspace-write + popup de aprovação é o equilíbrio de "seguro por padrão, permitir manualmente quando necessário".

Camada Três: Chaves Somente Escrita

A API Key é a coisa mais sensível — se perdida, outros podem usar sua cota, até usar sua identidade para chamar APIs. O tratamento do dsh para chaves é somente escrita.

O que significa somente escrita? Depois que você preenche a API Key em Settings → Models e clica em salvar, a Key na interface "desaparece", sobrando apenas um descritor redigido (por ex. deepseek://sk-...x8f2). Você nunca consegue ler de volta a Key em texto puro completo pela interface.

Isso não é um bug, é design deliberado:

• A Key em texto puro só vai para o $DSH_HOME/.credentials.yaml local (no Windows: C:\Users\<seu-usuário>\.dsh\.credentials.yaml)
• A interface e settings.yaml só armazenam uma referência (como o campo apiKeyEnv), não o texto puro
• Memória do navegador, logs de rede, estado do front-end não vão expor secundariamente a Key completa

Placeholder de imagem: coloque aqui uma captura da "página Settings → Models, cartão DeepSeek depois de salvar mostra apenas o descritor redigido" — você pode ver que o campo da chave virou o formato deepseek://sk-...xxxx.

Prioridade da chave (do mais alto para o mais baixo):

1. Variável de ambiente do processo (export DEEPSEEK_API_KEY=sk-xxx)
2. Arquivo $DSH_HOME/.credentials.yaml
3. Arquivo .env do diretório do projeto

Variável de ambiente tem a prioridade mais alta, adequada para uso temporário; método de arquivo é o mais usado, adequado para configuração de longo prazo.

Lembrete de segurança: o arquivo .credentials.yaml tem permissões 0600 (só você pode ler/escrever), mas se você fizer backup de todo o diretório ~/.dsh para a nuvem ou compartilhar com outros, as chaves vão junto. Tenha cuidado de redigir ao fazer backup.

Privacidade de Dados

Além das chaves, todos os dados que o dsh produz também são locais:

Dado	Onde é armazenado	Será enviado?
Registros de sessão	~/.dsh/sessions/	Não
Trajectory	Incorporado nos registros de sessão	Não
Configuração de plugins	~/.dsh/profiles/	Não
API Key	~/.dsh/.credentials.yaml	Não
Arquivos do workspace	Diretório de workspace que você escolheu	Não

O dsh não tem sincronização na nuvem, não tem sistema de contas, não tem relatório de telemetria. O conteúdo da sua conversa com o modelo só é enviado ao provedor do modelo (DeepSeek etc.) quando você envia a requisição, o dsh em si não mantém uma cópia na nuvem.

Isso significa:

• Benefício: dados estão completamente nas suas mãos, privacidade é controlável
• Custo: trocar de computador requer migrar manualmente o diretório ~/.dsh, sem sincronização com um clique

Melhores Práticas de Segurança

Colocando os mecanismos acima no uso diário, lembre-se destas:

1. Use workspace-write no dia a dia, não mantenha full access ligado — sob full access o sandbox efetivamente some, o Agent pode tocar em todo o seu disco rígido. Só ligue temporariamente quando precisar claramente de operação em nível de sistema, e volte atrás quando terminar.
2. Não envie o diretório ~/.dsh direto para o GitHub — tem uma chave em texto puro .credentials.yaml dentro dele. Se precisar fazer backup da config, exporte settings.yaml separado (sem chaves), e gerencie as chaves separadamente.
3. Implantação Docker em equipe: note que não tem isolamento multiusuário — o CH 27 cobriu, na versão atual todos usam o mesmo Basic Auth para logar e veem a mesma sessão e configuração. Quando a equipe compartilha, não armazene informações sensíveis, ou faça cada pessoa implantar uma instância independente.
4. Escolha um diretório limpo como workspace — não defina o C:\Users inteiro ou o diretório home como workspace. Escolha um diretório de projeto dedicado, e o alcance que o Agent pode tocar fica limitado a ele.

O Que Você Aprendeu Neste Capítulo

Você passa se conseguir completar os itens abaixo:

• [ ] Saber a ideia central do design de segurança do dsh: restrito por padrão, permitir sob demanda
• [ ] Saber quais são as três camadas de proteção: sandbox de arquivos, aprovação de operações, chaves somente escrita
• [ ] Saber que o sandbox é no nível do kernel do SO, não verificação if em JS, o modelo não pode contornar
• [ ] Conseguir declarar claramente as diferenças entre os três níveis de permissão (read-only / workspace-write / danger-full-access) e os cenários aplicáveis
• [ ] Saber que a aprovação é "permitir uma vez", não permanente
• [ ] Saber que a API Key é somente escrita, depois de salvar a interface não ecoa de volta, o texto puro só está no .credentials.yaml local
• [ ] Saber que todos os dados do dsh são locais, sem sincronização na nuvem
• [ ] Conseguir citar pelo menos 3 melhores práticas de segurança diárias