ton-vulnerability-scanner

Visão geral da skill ton-vulnerability-scanner

ton-vulnerability-scanner é uma skill de auditoria focada para contratos inteligentes TON escritos em FunC. Ela ajuda a identificar bugs específicos da plataforma que prompts genéricos de smart contract costumam deixar passar, especialmente em tratamento de booleanos, lógica de Jetton e encaminhamento de gas. Use-a quando precisar de uma primeira revisão rápida de segurança antes de uma análise manual mais profunda ou de uma auditoria externa.

Para que a skill é mais indicada

A skill ton-vulnerability-scanner é mais útil para auditores, engenheiros de protocolo e desenvolvedores revisando código TON antes do lançamento. Ela funciona bem quando você precisa checar se o fluxo de controle, as validações de token ou o tratamento de mensagens de um contrato seguem as convenções do TON. Não é uma skill de revisão geral de código; ela foi desenhada em torno de um conjunto pequeno de falhas TON de alto impacto.

Foco central de vulnerabilidades

O repositório gira em torno de três padrões críticos: uso indevido de inteiro como booleano, tratamento de contratos Jetton falsos e encaminhamento de TON sem checagem adequada de gas. Esse recorte importa porque dá mais precisão à skill do que um prompt amplo de “encontre bugs”. Se o seu objetivo é trabalho de Security Audit em contratos FunC, este é o tipo certo de ferramenta especializada.

Quando não usar

Não espere bons resultados em stacks que não sejam FunC, contratos genéricos de EVM ou revisões de arquitetura que não sejam específicas do TON. Se você busca problemas de estilo, geração de testes ou uma auditoria formal completa, ton-vulnerability-scanner é estreita demais sozinha. Ela funciona melhor como um scanner direcionado dentro de um fluxo maior de revisão.

Como usar a skill ton-vulnerability-scanner

Instalar e localizar os arquivos da skill

Para a etapa ton-vulnerability-scanner install, use o fluxo normal de skills do diretório, por exemplo: npx skills add trailofbits/skills --skill ton-vulnerability-scanner. Depois da instalação, leia primeiro o ponto de entrada da skill e então siga o contexto apontado pelo repositório. Os arquivos de início mais úteis são SKILL.md e resources/VULNERABILITY_PATTERNS.md.

Forneça a entrada certa

O padrão de uso ton-vulnerability-scanner usage funciona melhor quando você informa um contrato concreto, um objetivo de revisão e o limite de escopo. Bons inputs nomeiam o tipo de arquivo e a pergunta de segurança, como: “Revise contracts/wallet.fc quanto à validação de transferência de Jetton, flags booleanas e riscos de forwarding de gas.” Entradas fracas como “analise este código” deixam espaço demais para uma resposta superficial.

Transforme uma tarefa vaga em um prompt forte

Use a ideia de ton-vulnerability-scanner guide como template de prompt: identifique o contrato, diga se ele é um Jetton, wallet ou handler de transferência, e informe o que a skill deve priorizar. Exemplo: “Audite este contrato FunC para os três padrões TON em resources/VULNERABILITY_PATTERNS.md e mostre quaisquer linhas ou condições exatas que possam tratar booleanos incorretamente, falsificar contratos Jetton ou encaminhar valor sem verificar gas.” Esse tipo de prompt melhora a precisão porque pede raciocínio por padrão, e não comentários genéricos.

Fluxo prático e o que inspecionar primeiro

Comece pelos pontos de entrada do contrato, como recv_internal, recv_external, parsing de mensagens e qualquer lógica de notificação de transferência. Depois inspecione flags booleanas, validação do remetente e chamadas que envolvam send_raw_message(), load_msg_addr() ou helpers de carga e armazenamento de coins. Se você precisar entender a skill rapidamente, priorize resources/VULNERABILITY_PATTERNS.md em vez da árvore mais ampla do repositório, porque é ali que aparecem exatamente as falhas que o scanner foi criado para encontrar.

FAQ da skill ton-vulnerability-scanner

Isso serve só para contratos FunC?

Sim, a skill ton-vulnerability-scanner é voltada para contratos TON escritos em FunC, especialmente arquivos .fc e .func. Se o seu projeto usa wrappers, testes ou tooling em TypeScript, isso pode ajudar no contexto, mas a lógica de vulnerabilidade vive no nível do contrato. Para uma Security Audit, o código-fonte do contrato é a entrada principal.

Em que ela difere de um prompt normal?

Um prompt normal pode notar “código suspeito”, mas ton-vulnerability-scanner é ajustada para pressupostos específicos do TON, como valores booleanos e padrões de mensagens Jetton. Isso a torna melhor para encontrar bugs fáceis de passar despercebidos se você não conhece bem a plataforma. Ela é mais estreita do que um revisor genérico de código com IA, mas é justamente essa restrição que traz valor.

Iniciantes conseguem usar?

Sim, desde que consigam apontá-la para um contrato FunC específico e descrever o objetivo da revisão. Iniciantes obtêm os melhores resultados quando pedem uma passagem de segurança por vez, e não uma auditoria completa de um repositório inteiro. A principal limitação não é a complexidade da skill; é se o contrato usa padrões TON que a skill entende.

Quais são os principais limites da skill?

A skill é mais forte em lógica booleana, checagens de autenticidade de Jetton e riscos de forwarding de gas. Ela é mais fraca em revisão de lógica de negócio, design de sistemas entre contratos e problemas que não estejam ligados à semântica de mensagens do TON. Se sua revisão precisa dessas dimensões mais amplas, combine-a com um fluxo de auditoria mais geral.

Como melhorar a skill ton-vulnerability-scanner

Dê alvos de auditoria explícitos

Para obter resultados melhores com ton-vulnerability-scanner, diga quais dos três padrões são mais importantes para o arquivo que você está revisando. Por exemplo, “foco em notificações de transferência e detecção de Jetton falso” é mais útil do que “verifique tudo”. Isso concentra a atenção nos caminhos de código com maior probabilidade de falha.

Forneça contexto do contrato, não só o texto-fonte

A skill funciona melhor quando você informa se o contrato é uma wallet, um minter de Jetton, um handler de transferência ou um receiver. Esse contexto muda como booleanos, endereços em mensagens e valor encaminhado devem ser interpretados. Se você já conhece invariantes esperadas, inclua-as desde o início para que a varredura compare o comportamento do código com elas.

Fique atento aos modos de falha mais comuns

Os erros mais comuns são usar inteiros positivos como booleanos, confiar em mensagens que parecem de token sem verificação e encaminhar TON sem disciplina suficiente de gas. Ao revisar a saída, veja se cada achado aponta para uma linha concreta, uma condição específica e um caminho de exploração realista. Se não apontar, peça uma rechecagem mais precisa com base na checklist de padrões em resources/VULNERABILITY_PATTERNS.md.

Itere com trechos de código e comportamento esperado

Se a primeira passada vier vaga, envie de novo a função suspeita e descreva o comportamento pretendido em uma frase. Por exemplo: “Este handler deve aceitar apenas notificações genuínas de transferência de Jetton vindas do contrato master esperado.” Esse tipo de retorno ajuda a skill ton-vulnerability-scanner a distinguir falsos positivos de padrões típicos do TON e entrega um resultado de Security Audit mais acionável.