Plugins dsh: como funcionam e como avaliar riscos

O que é um plugin dsh e o que ele pode fazer?

Os plugins dsh são pacotes Node que o DeepSeek Harness carrega no próprio processo. Instalar um deles executa código de terceiros com as permissões do seu agente, na máquina que o agente já consegue alcançar. Nada separa um plugin carregado do restante do harness. Portanto, antes de instalar um plugin, a pergunta é a que partes esse código pode aceder e como limitar esse acesso.

dsh (DeepSeek Harness) é o harness de agentes de código aberto da DeepSeek AI, baseado num framework de plugins chamado Cordis. O README do projeto afirma que tudo é um plugin. O adaptador do modelo é um plugin. A interface web onde escreve é um plugin. Tudo o que instala fora do projeto entra na mesma árvore, com o mesmo nível de confiança das partes fornecidas com ele. Se ainda não iniciou uma instância, comece por o DeepSeek Harness numa VPS e volte antes de lhe adicionar qualquer componente.

Os pontos de extensão que um plugin pode alcançar estão listados no AGENTS.md do repositório. Em agosto de 2026, abrangem:

• LLM (large language model): o fornecedor pago pela sua chave API
• Shell: a capacidade bash, com os fornecedores local e pwsh
• Filesystem: acesso a ficheiros controlado por políticas
• Web: fornecedores de pesquisa e obtenção de conteúdo
• Subprocess: um fornecedor de árvores de processos
• Workflow: threads de trabalho
• Subagent: delegação para outros agentes
• Settings and credentials: a sua configuração guardada e as variáveis de ambiente

Um plugin também regista ferramentas em ctx.tools, e a documentação afirma explicitamente que o esquema de uma ferramenta registada entra na montagem do prompt. Esta segunda parte é frequentemente ignorada. Um plugin pode alterar aquilo que o seu agente decide fazer sem que o próprio código execute algo invulgar, porque a descrição que fornece passa a ser texto lido pelo modelo. É o mesmo tipo de problema que a injeção de prompts contra agentes de programação, com uma diferença: este texto chega quando instala o plugin e permanece até o remover.

Como o dsh encontra e carrega plugins?

Não existe um diretório global de plugins. Um dsh em execução é uma árvore de plugins composta no arranque a partir de camadas ordenadas, e o perfil é a unidade que guarda as suas escolhas. $DSH_HOME usa ~/.dsh por predefinição, e cada perfil fica em $DSH_HOME/profiles/<name>. Os perfis web e headless são criados automaticamente na primeira utilização, a partir dos modelos fornecidos.

Um diretório de perfil contém dois ficheiros que determinam tudo:

• package.json, com as dependências dos plugins externos e um manifesto dsh.profile que contém a lista ordenada de bundles
• cordis.patch.yml, a sua própria camada de correções sobre esses pacotes

ls ~/.dsh
ls ~/.dsh/profiles/web

No arranque, as camadas são aplicadas por esta ordem. As camadas posteriores prevalecem:

1. uma raiz vazia
2. os pacotes do perfil, pela ordem indicada no manifesto
3. o cordis.patch.yml do perfil
4. $DSH_HOME/cordis.patch.yml
5. quaisquer sobreposições --patch <path> passadas na linha de comandos

Duas flags mostram o resultado dessa composição sem iniciar nada:

dsh --profile web --dump-default-config
dsh --profile web --dump-config

--dump-default-config mostra apenas a árvore composta. --dump-config adiciona as camadas de perfil e de correções do diretório pessoal, sendo o equivalente mais próximo de um inventário fiável do que o próximo arranque carregará. Consulte-o antes de confiar numa máquina que herdou.

Existe um aviso importante sobre esses ficheiros de correções. A configuração não é apenas dados inertes, porque o formato permite valores identificados com !!js no bloco config de um plugin. Um excerto cordis.patch.yml copiado de uma publicação num fórum é código. Trate-o como trataria um script de shell da mesma origem.

O que dsh plugin add executa?

dsh plugin --profile <name> <args> encaminha os argumentos para o pnpm dentro do diretório desse perfil, portanto o pnpm tem de estar no PATH. Os verbos são os verbos do pnpm:

dsh plugin --profile web add '<package-or-git-spec>'
dsh plugin --profile web remove '<package-name>'
dsh plugin --profile web why '<package-name>'
dsh plugin --profile web update

O modelo de segurança da instalação de um plugin dsh é, portanto, o modelo de segurança da instalação de qualquer dependência ao estilo npm, acrescido de uma etapa em que o resultado é carregado no seu agente. O pacote traz a sua própria árvore de dependências, e todos os pacotes dessa árvore acabam no mesmo processo. Tudo o que se aplica a como os ataques à cadeia de fornecimento do npm chegam a um servidor aplica-se aqui sem alterações.

O pnpm 10 e versões posteriores não executam por predefinição os scripts de compilação de uma dependência, e a aprovação é feita por pacote através de onlyBuiltDependencies ou pnpm approve-builds. Verifique qual versão do pnpm está instalada:

pnpm --version

Essa predefinição é útil, mas também é o recurso de segurança mais interpretado de forma excessivamente otimista no ecossistema. Os scripts de compilação bloqueados impedem a execução de código durante a instalação. Não fazem nada contra o próprio plugin, porque o objetivo de um plugin é que o harness o importe e o execute no arranque seguinte. Um plugin não precisa de um hook postinstall. Foi autorizado a entrar.

O que ler antes de instalar um plugin dsh

Transfira o tarball publicado e leia-o. Nada é executado ao desempacotar um arquivo.

npm pack '<package-name>@<version>'
tar -tzf '<package-name>-<version>.tgz'
tar -xzf '<package-name>-<version>.tgz'
less package/package.json

Os quatro campos nesse package.json informam a maior parte do que precisa de saber. Leia scripts para consultar as entradas preinstall, install e postinstall. Leia dependencies para nomes que não reconhece ou que diferem apenas num carácter de nomes conhecidos. Leia bin para saber o que o pacote quer no seu PATH. Leia main ou exports para encontrar o ficheiro de entrada. Depois, abra esse ficheiro e siga o fluxo.

Em seguida, leia o código que será efetivamente carregado. Um plugin que anuncia uma ferramenta de notificações não tem motivo para ler ~/.ssh, contactar um host que nunca ouviu mencionar ou iniciar uma shell. Se o pacote distribuir apenas JavaScript agrupado ou minificado e não existir código-fonte correspondente num repositório público, essa é a resposta. Prefira plugins cujo código-fonte possa ler e prefira os mais pequenos.

Também pode consultar o registry sem instalar nada:

pnpm view '<package-name>' dependencies
pnpm view '<package-name>' versions

Um pacote publicado na semana passada, com uma versão, sem o campo de repositório e com um nome que imita algo popular é o truque mais antigo de qualquer registry. Verificar transferências com checksums é o hábito complementar: saiba exatamente o que transferiu antes de permitir a sua execução.

Fixe a versão e mantenha o lockfile

Um intervalo de versões flutuante significa que o código dentro do processo do seu agente pode mudar em qualquer instalação ou atualização sem que você decida isso. Fixe a versão.

dsh plugin --profile web add --save-exact '<package-name>@<version>'

A posição das flags varia entre versões do pnpm. Por isso, verifique o resultado em vez de confiar no comando. Abra depois o package.json do perfil e confirme que a dependência aparece como uma versão simples, sem ^ ou ~ à sua frente. Esse ficheiro determina o que é instalado.

Depois, mantenha o lockfile, que fixa toda a árvore transitiva, e não apenas o nome de nível superior:

find ~/.dsh -maxdepth 3 -name 'pnpm-lock.yaml'

Copie-o para um local incluído nos backups, juntamente com o package.json do perfil. Esses dois ficheiros reconstroem a mesma árvore numa máquina nova. Execute dsh plugin --profile web update quando tiver decidido mudar de versão, nunca como limpeza de rotina, e leia o diff do lockfile depois.

Para um plugin instalado a partir do git, e não de um registry, fixe o commit em vez da branch. Uma especificação no formato github:owner/repo#<full commit sha> fornece uma árvore fixa. Um nome de branch fornece o conteúdo dessa branch na próxima vez que o pnpm a resolver. Nesse caso, você entrega essa decisão a outra pessoa. O próprio harness exige a mesma disciplina, porque cada build dsh publicada é uma release candidate e uma instalação sem versão fixa pode resolver para outra em qualquer dia. É daí que vem a maioria dos erros de instalação e versão do dsh.

O mercado de plugins e o valor real de uma lista «curada»

O dsh tem um marketplace, que é instalado como um plugin. Isto revela algo sobre a arquitetura:

dsh plugin --profile web add dshmarket

Depois de reiniciar, o plugin aparece em Settings e, em seguida, em Plugin Market. O README explica claramente as limitações. As instalações estão restritas às fontes listadas num registo curado, e qualquer outra fonte é rejeitada. Os scripts de compilação estão bloqueados por predefinição, e ativá-los exige aprovação por pacote. Os plugins de terminal são sinalizados antes de serem incluídos num perfil web. A frase mais importante é que estar listado não significa ser recomendado, porque os plugins são código de terceiros.

Uma lista curada estabelece um nível mínimo de qualidade. Não analisa o código por si, nem pode indicar o que a próxima versão de um plugin fará depois de a conta do responsável mudar de mãos. Trate uma instalação com um clique da mesma forma que trataria curl | bash do mesmo autor. Vale a pena repetir outra linha desse README: uma cópia de segurança exportada pode conter credenciais do seu ficheiro de configuração de perfil. Por isso, nunca a anexe a um problema público nem a publique num site de pastas. Se pretende uma lista inicial, em vez de um método, plugins dsh que vale a pena instalar é o artigo complementar deste.

Execute dsh com o seu próprio utilizador, não como root

A verificação reduz a frequência com que algo malicioso entra. O princípio do menor privilégio limita o que essa ameaça consegue alcançar quando entra. Num VPS, configurar essa segunda camada é simples.

Crie uma conta Unix própria para o harness, com o seu próprio diretório pessoal, e nunca o execute como root:

sudo adduser --disabled-password --gecos "" dshrun
sudo -iu dshrun

Nessa sessão, inicie o harness para que ele grave o seu diretório pessoal nessa conta:

npx @deepseek-ai/dsh web

Por predefinição, a interface Web fica disponível em http://127.0.0.1:3080. Mantenha-a nessa porta. Qualquer pessoa que consiga chegar a essa porta pode controlar um agente com acesso a uma shell. Publicar a porta 3080 equivale, portanto, a publicar uma shell remota sem privilégios de root, com uma interface amigável. Aceda-lhe a partir do seu portátil através de um túnel SSH:

ssh -L 3080:127.0.0.1:3080 you@your-vps

Depois, confirme que não existe nenhum processo à escuta num endereço público:

ss -lnt | grep 3080

O endereço local deve aparecer como 127.0.0.1:3080. Se aparecer como 0.0.0.0:3080, a firewall é a única barreira entre um estranho e o seu agente. Os princípios por trás de executar o Claude Code com segurança num VPS aplicam-se ao dsh sem alterações. Dê ao agente um único diretório de trabalho que ele possa danificar e mantenha fora dessa máquina tudo o que não possa recriar. Melhor ainda, trate o sistema como uma VM descartável para agentes de programação, porque recriar um VPS demora uma hora, enquanto auditá-lo demora uma semana.

Onde ficam as suas chaves e por que as permissões de ficheiros têm limites

O dsh mantém as chaves de API em $DSH_HOME/.credentials.yaml e os valores de ambiente em $DSH_HOME/.env, com as definições do modelo em $DSH_HOME/settings.yaml e o histórico de sessões em $DSH_HOME/storages. A questão de qual chave deve ficar em cada um desses ficheiros e do que sai efetivamente da máquina em cada modo é abordada em configurar as chaves de API, os modelos e os endpoints do dsh. Vale a pena resolver isso antes de adicionar um plugin, porque cada chave que configurar é mais um dado que um plugin pode ler. Restrinja as permissões dos dois ficheiros sensíveis:

chmod 600 ~/.dsh/.credentials.yaml ~/.dsh/.env
ls -l ~/.dsh

O modo 600 permite ao proprietário ler e escrever e não concede permissões a mais ninguém. É útil conhecer esta notação e a equivalente (modos numéricos e simbólicos do chmod). Seja claro sobre o que esta proteção oferece. Os modos dos ficheiros protegem esses ficheiros contra outras contas no servidor. Não protegem contra um plugin, porque o plugin é executado como o utilizador que é proprietário dos ficheiros, dentro do processo que os lê. Por isso, manter os segredos fora do alcance de um agente de IA significa não os colocar na máquina. Um servidor dsh deve conter apenas a chave do modelo de que precisa. As suas credenciais de cloud e as suas chaves de assinatura devem ficar noutro local.

Por que um plugin que lê a Web altera o modelo de ameaças

A interface Web disponibiliza aos plugins fornecedores de pesquisa e obtenção de conteúdo. Um plugin que carrega uma página para a sua sessão está a carregar texto que um atacante pode escrever. Um prompt de modelo não separa instruções de dados. Por isso, uma página obtida pode conter uma linha dirigida ao seu agente, e um harness com acesso ao shell fica a um passo obediente de a executar.

O controlo já existe no harness. dsh-base, o primeiro bundle de cada perfil, fornece o sandbox e a política de aprovação. Utilize-o. Uma sessão que possa obter páginas não confiáveis deve exigir aprovação para qualquer operação que escreva ou execute algo. Assim, uma instrução obtida não se pode transformar numa ação por si só. Colocar as ações do agente atrás de aprovações explica como decidir onde estabelecer esse limite. A relação também funciona nos dois sentidos, porque o seu próprio servidor é uma página que o agente de alguém vai obter. Esse é o caso de bloquear crawlers de IA no seu servidor.

Como verifico o que um plugin alterou?

Crie um snapshot antes da instalação, instale o plugin, crie outro snapshot e leia as diferenças.

dsh --profile web --dump-config > /tmp/dsh-before.txt
dsh plugin --profile web add '<package-name>@<version>'
dsh --profile web --dump-config > /tmp/dsh-after.txt
diff -u /tmp/dsh-before.txt /tmp/dsh-after.txt

O diff mostra quais entradas do plugin a instalação adicionou à árvore composta. Se um plugin instalado para uma funcionalidade pequena adicionar várias entradas que não consegue justificar, pare e leia o código-fonte antes de o iniciar. dsh plugin --profile web why <package-name> responde à outra questão: qual das suas dependências diretas trouxe um determinado pacote.

Os pacotes instalados ficam em $DSH_HOME/profiles/node_modules. Por isso, também pode consultar a árvore no disco:

ls ~/.dsh/profiles/node_modules

Mantenha um segundo perfil onde nunca faz experiências. Se uma instalação danificar o harness, iniciar dsh --profile <clean-name> permite confirmar em segundos se o plugin foi a causa.

Como removo um plugin do dsh?

dsh plugin --profile web remove '<package-name>'
dsh --profile web --dump-config > /tmp/dsh-after-removal.txt
diff -u /tmp/dsh-before.txt /tmp/dsh-after-removal.txt

Remover a dependência nem sempre remove a configuração. As entradas gravadas no cordis.patch.yml do perfil permanecem no local, porque esse ficheiro é seu e o harness não o reescreve por si. Abra o ficheiro e elimine qualquer bloco que indique o pacote removido.

less ~/.dsh/profiles/web/cordis.patch.yml

Depois, trate da parte que nenhum comando de desinstalação consegue corrigir. Se removeu um plugin porque deixou de confiar nele, tudo o que ele podia ler já foi lido. Faça a rotação da chave da API do DeepSeek na consola do fornecedor e rode também qualquer outra credencial que estivesse em $DSH_HOME. Depois, determine a que recursos da restante rede o account Unix com que o plugin era executado podia aceder.

A versão resumida

• Leia o tarball publicado antes da instalação, começando em scripts e no ficheiro de entrada
• Fixe a versão exata ou o commit exato para uma especificação git e mantenha o lockfile
• Instale num único perfil e mantenha um perfil limpo que possa arrancar quando algo falhar
• Compare --dump-config antes e depois de cada instalação
• Execute o harness com o seu próprio utilizador Unix, na interface de loopback, com acesso por SSH
• Mantenha uma chave de API no servidor e faça a rotação no dia em que remover um plugin em que já não confia

Nada disto é motivo para evitar plugins. O modelo de plugins é o motivo pelo qual o dsh é útil, e um harness que não pode ser estendido é um harness que irá substituir. O objetivo é saber o que instalou, de quem, em que versão, e executar tudo num local que possa reconstruir.

FAQ

Os plugins do dsh ficam isolados uns dos outros?

Não. Um plugin é carregado no processo do harness através do Cordis e pode aceder às interfaces de capacidade documentadas, incluindo shell, sistema de ficheiros, web, subprocessos, subagente e credenciais. dsh-base, o primeiro bundle de cada perfil, fornece o sandbox e a política de aprovação que controlam o que as ferramentas do agente podem fazer. É dessa política que vem a sua proteção. Não existe um limite de permissões por plugin. O modelo correto é considerar que instalar um plugin estende a sua confiança ao respetivo autor e a todos os pacotes da árvore de dependências.

Posso instalar um plugin dsh sem executar os respetivos scripts de instalação?

O pnpm 10 e versões posteriores bloqueiam por predefinição os scripts de compilação das dependências, e o dsh plugin ... add encaminha para o pnpm. Assim, numa versão atual do pnpm, a instalação não executa scripts de pacotes, exceto se aprovar esse pacote. Confirme a versão com pnpm --version. Isto não torna seguro um plugin que não tenha sido analisado. O próprio código do plugin é executado no arranque seguinte, porque o harness o carrega deliberadamente. Nenhuma restrição aplicada durante a instalação impede isso.

Onde ficam realmente os plugins dsh e a respetiva configuração?

Por predefinição, $DSH_HOME aponta para ~/.dsh. Os perfis ficam em $DSH_HOME/profiles/<name>. Cada perfil contém um package.json com as dependências dos respetivos plugins, o manifesto dsh.profile de bundles ordenados e uma camada de correções cordis.patch.yml. Os pacotes instalados ficam em $DSH_HOME/profiles/node_modules. As chaves ficam em $DSH_HOME/.credentials.yaml, os valores de ambiente em $DSH_HOME/.env e um $DSH_HOME/cordis.patch.yml ao nível do diretório pessoal aplica-se a todos os perfis. Execute dsh --profile web --dump-config para ver o resultado composto sem fazer o arranque.

É seguro instalar a partir do mercado de plugins dsh?

O mercado limita as instalações a fontes de um registry selecionado e bloqueia os scripts de compilação, exceto se os aprovar por pacote. Isto é uma melhoria real em relação a colar o nome de um pacote a partir de uma janela de chat. O próprio README continua a indicar que a listagem não constitui uma recomendação, porque os plugins são código de terceiros criado por outras pessoas. Leia o código-fonte e fixe a versão. Mantenha o harness numa conta de utilizador e, idealmente, numa máquina que possa perder.