solidity-security

Visão geral da skill solidity-security

Para que serve a solidity-security

A skill solidity-security é um guia focado de auditoria e codificação segura para smart contracts em Solidity. Ela funciona melhor quando você quer que um agente revise a lógica do contrato em busca de classes comuns de exploração, sugira padrões mais seguros e explique por que um design é arriscado antes de o código chegar à produção ou a uma auditoria formal.

Quem deve instalar esta skill

Esta skill é indicada para:

• desenvolvedores Solidity que vão publicar contratos em mainnet ou testnets
• auditores fazendo uma revisão inicial
• equipes preparando contratos DeFi, tokens, vaults ou contratos com controle administrativo para uma Security Audit externa
• engenheiros que querem um feedback de segurança mais estruturado do que um prompt genérico do tipo “revise este código”

Ela é menos útil para projetos fora do ecossistema EVM ou para análises puramente econômico-protocolares.

O trabalho real que ela resolve

Na prática, os usuários não querem apenas uma lista de vulnerabilidades. Eles querem ajuda para transformar objetivos vagos, como “verifique este vault em busca de reentrancy e problemas de privilégio”, em um fluxo de revisão repetível, cobrindo caminhos de exploração, implementações mais seguras e prioridades de correção. É aí que a solidity-security é mais forte do que um prompt comum.

O que diferencia a solidity-security

A skill é enxuta e prática. Em vez de trazer conselhos amplos sobre blockchain, ela se concentra nos principais modos de falha do Solidity, como:

• reentrancy
• casos extremos de aritmética
• erros de controle de acesso
• chamadas externas inseguras
• padrões de implementação orientados à segurança

Isso faz dela uma boa escolha quando precisão importa mais do que abrangência.

O que saber antes de adotar

O repositório é leve: o conteúdo da skill fica principalmente em SKILL.md, sem regras extras, scripts ou arquivos de referência. Isso é ótimo para adoção rápida, mas também significa que a qualidade da saída depende bastante do contexto que você fornece. Se você mandar apenas “audite este contrato”, espere achados genéricos. Se incluir propósito do contrato, threat model, papéis privilegiados e funções-chave, a solidity-security skill se torna bem mais útil.

Como usar a skill solidity-security

Como instalar a solidity-security

Instale a partir do repositório com um cliente compatível com skills. Um padrão comum é:

npx skills add https://github.com/wshobson/agents --skill solidity-security

Se a sua plataforma de agentes usar outro mecanismo de instalação, adicione a skill a partir de:

https://github.com/wshobson/agents/tree/main/plugins/blockchain-web3/skills/solidity-security

O que ler primeiro no repositório

Comece por:

• plugins/blockchain-web3/skills/solidity-security/SKILL.md

Como essa skill não tem README.md, rules/ ou references/ de apoio na pasta, o SKILL.md é o manual operacional completo. Leia primeiro a seção “When to Use This Skill” e as seções sobre vulnerabilidades para entender qual lente de revisão ela aplica.

Quais entradas a skill precisa para funcionar bem

A qualidade do solidity-security usage depende de contexto concreto do contrato. Forneça:

• versão do Solidity
• arquivos do contrato ou trechos principais
• propósito do contrato
• papéis de usuário e papéis privilegiados
• fluxos de ativos: quem deposita, saca, emite, queima, liquida, atualiza
• integrações externas: oracles, ERC20s, bridges, routers, callbacks
• premissas sobre atores confiáveis
• qual tipo de saída você quer: quick scan, checklist de auditoria profunda, cenários de exploração ou remediações

Sem isso, a skill só consegue gerar uma aula genérica sobre vulnerabilidades.

O melhor formato de prompt para uma primeira revisão

Um bom prompt inicial é:

“Use the solidity-security skill to review these contracts for reentrancy, access control, unsafe external calls, arithmetic or accounting mistakes, and other high-severity issues. For each finding, include impact, exploit path, affected functions, and a concrete remediation. Distinguish confirmed issues from areas needing more context.”

Esse prompt funciona porque pede:

• classes específicas de problemas
• saída priorizada
• raciocínio sobre exploração
• orientação de implementação
• tratamento explícito de incerteza

Como transformar um objetivo vago em um prompt completo

Prompt fraco:

• “Check this Solidity code.”

Prompt melhor:

• “Use solidity-security for Security Audit preparation on this vault contract. Focus on withdrawal flow, share accounting, admin powers, pausing, upgradeability assumptions, and external token interactions. Identify critical and high findings first, then list medium-risk hardening opportunities.”

A versão melhor delimita o escopo às superfícies mais críticas para o negócio, o que melhora o sinal e reduz conteúdo de preenchimento.

Fluxo de trabalho recomendado para auditorias

Um fluxo prático com o solidity-security guide é:

1. Peça um resumo do threat model a partir do conjunto de contratos.
2. Solicite um mapa de risco função por função.
3. Aprofunde nos caminhos com chamadas externas que alteram estado.
4. Revise funções restritas por papel e a lógica de inicialização.
5. Peça exemplos de remediação para os principais achados.
6. Rode a skill novamente sobre o código corrigido e pergunte quais riscos ainda permanecem.

Esse fluxo em etapas costuma gerar uma saída melhor do que pedir uma auditoria gigante em uma única passada.

Áreas de revisão de alto valor para enfatizar

Ao acionar a solidity-security, peça explicitamente que o agente foque em:

• funções de saque e pagamento
• interações com tokens que suportam callback
• lógica de transferência de papéis e ownership
• caminhos de inicialização e upgrade
• invariantes contábeis
• dependências de oracle ou precificação
• controles de emergência
• premissas sobre conformidade com ERC20

Essas são as áreas em que prompts superficiais costumam deixar riscos relevantes passarem.

O que a skill parece cobrir melhor

Pelo conteúdo-fonte, a skill é mais forte nas classes comuns de vulnerabilidade em Solidity e em padrões seguros de implementação, especialmente reentrancy e hábitos defensivos relacionados, como checks-effects-interactions. Use-a como assistente de revisão e codificação com foco em segurança, não como substituta de verificação formal ou de modelagem econômica em nível de protocolo.

Dicas práticas que melhoram a qualidade da saída

Para obter resultados melhores com solidity-security usage:

• cole as funções exatas que movem fundos
• marque quais papéis são confiáveis e quais são controlados externamente
• indique se os contratos são upgradeable ou usam proxy
• peça pré-requisitos de exploração, não apenas nomes de bugs
• solicite classificação de severidade com justificativa
• peça ao modelo para separar fatos do código de premissas

Esses pequenos acréscimos melhoram de forma material a qualidade da decisão.

O que não esperar da skill

Não espere que a solidity-security skill automaticamente:

• rode testes
• inspecione bytecode implantado
• prove invariantes matematicamente
• substitua uma Security Audit manual completa
• detecte problemas específicos do ecossistema que você nunca mencionou

Ela é mais eficaz como uma estrutura especializada de revisão para o contexto de código e arquitetura que você fornecer.

FAQ da skill solidity-security

A solidity-security é boa para preparação de Security Audit?

Sim. solidity-security for Security Audit é um caso de uso forte quando você quer capturar problemas óbvios e moderadamente sutis em Solidity antes de pagar por uma auditoria externa. Ela ajuda equipes a endurecer o código, documentar premissas e chegar à auditoria com menos achados evitáveis.

Isso é melhor do que um prompt genérico do tipo “audite meu contrato”?

Na maioria dos casos, sim. Um prompt genérico costuma devolver uma lista boilerplate de riscos de smart contracts. A solidity-security dá ao agente um enquadramento de segurança mais estreito, o que tende a melhorar o foco em caminhos de exploração, padrões seguros e detalhes de remediação.

A solidity-security é adequada para iniciantes?

Sim, com ressalvas. Iniciantes podem usá-la para aprender superfícies comuns de ataque em Solidity e padrões mais seguros de codificação. Mas ela não deve ser tratada como um currículo completo. Se você está começando, peça que a skill explique cada achado em linguagem simples e mostre alternativas seguras.

Quando a solidity-security é uma escolha ruim?

Ela é pouco indicada para:

• chains que não usam Solidity
• segurança de wallet no front-end
• revisão de design de tokenomics
• teoria dos jogos aplicada à governança
• resposta a incidentes em produção sem contexto de código

Para esses trabalhos, use um processo de segurança blockchain mais amplo ou outra skill especializada.

Ela consegue revisar um único arquivo ou precisa do codebase inteiro?

Ela pode revisar um único arquivo, mas os resultados melhoram com o contexto ao redor. Por exemplo, um contrato de vault sem o contexto do token, oracle, controle de acesso ou proxy pode parecer seguro quando as premissas críticas estão definidas em outro lugar.

A skill cobre só bugs clássicos?

Não, mas bugs clássicos são o seu centro de gravidade. Espere o melhor desempenho nos riscos conhecidos de implementação em Solidity, mais do que em explorações econômico-protocolares sob medida. Se sua principal preocupação for insolvência, manipulação de oracle ou design de liquidação, diga isso explicitamente.

Como melhorar a skill solidity-security

Forneça o threat model logo de início para a solidity-security

A forma mais rápida de melhorar a saída da solidity-security é definir:

• capacidades do atacante
• papéis confiáveis
• ativos protegidos
• resultados inaceitáveis

Exemplo:

• “Assume any external user is adversarial, admin key is trusted but fallible, and loss of user deposits is the top-risk outcome.”

Isso ajuda o agente a priorizar problemas reais em vez de feedback de estilo.

Forneça invariantes, não só código

Entradas fortes incluem regras do sistema como:

• total shares should never exceed claimable assets
• only governance can change fee parameters
• user withdrawals must not depend on untrusted callbacks

Quando você fornece invariantes, a skill consegue testar a lógica contra o comportamento pretendido em vez de apenas procurar padrões sintáticos.

Peça narrativas de exploração

Um modo comum de falha é receber uma lista chapada de achados sem prova de relevância. Melhore isso pedindo:

• condição de entrada
• passos do ataque
• impacto esperado
• se o problema é realista ou apenas teórico

Isso força a solidity-security skill a raciocinar como um auditor, não como um linter.

Torne os pedidos de remediação específicos

Não pergunte apenas “como corrigir isso?”. Peça:

• patch mínimo
• alternativa de design mais segura
• tradeoffs de cada correção
• se o patch altera custos de gas ou UX

Prompts de remediação específicos produzem saídas mais acionáveis do que conselhos genéricos de secure coding.

Rode novamente na versão corrigida do código

Após a primeira passada, cole a função ou o contrato revisado e pergunte:

• qual risco foi removido
• qual risco residual permanece
• se a correção introduziu novos edge cases
• quais testes devem ser adicionados

Essa é uma das formas de maior valor para aproveitar bem o tempo investido em solidity-security install depois da adoção.

Modos de falha comuns para observar

Mesmo com a skill, fique atento a:

• superestimar vulnerabilidades especulativas
• perder premissas escondidas em contratos herdados
• ignorar detalhes de gestão de papéis
• dar conselhos padrão de reentrancy quando o problema mais profundo é o design contábil
• tratar todas as chamadas externas como igualmente perigosas

Você pode reduzir esses erros fornecendo contexto de herança e pedindo ao modelo que cite o caminho exato da função por trás de cada afirmação.

Prompts melhores para revisões mais profundas

Um bom prompt de segunda rodada:

“Use solidity-security to review only the withdrawal, reward-claim, and admin-setter paths. Ignore gas micro-optimizations. For each issue, cite the function, state variable, attacker capability required, exploit sequence, and the safest realistic remediation for this codebase.”

Isso funciona porque restringe o escopo e o formato de saída ao mesmo tempo.

Combine a skill com testes e revisão manual

O melhor fluxo não é usar só a skill. Use a solidity-security para gerar hipóteses e depois valide com:

• testes unitários
• testes de invariantes
• fuzzing
• revisão manual linha por linha

Essa combinação é muito mais forte do que prompting comum ou leitura estática isolada.

Como saber se a skill está ajudando

O solidity-security guide está funcionando se ele ajuda você a:

• identificar mais rápido as funções mais perigosas
• explicar a explorabilidade com clareza
• produzir candidatos de patch melhores
• preparar perguntas mais limpas para auditores externos
• reduzir a adivinhação típica de prompts genéricos

Se a saída continuar vaga depois de duas iterações, a causa mais comum é falta de contexto do contrato, não a instalação em si.