🧠 Seekurity Review: Triagem de Vulnerabilidades SAST com LLM Local (DeepSeek-R1) · usrbinenv

A análise estática de segurança de código (SAST) é uma etapa fundamental para identificar vulnerabilidades em aplicações. No entanto, uma grande dificuldade do SAST tradicional é o elevado volume de falsos positivos, alertas de vulnerabilidade que na verdade não representam um risco real. Esse trabalho de triagem manual consome tempo e atenção, podendo atrasar entregas e causar fadiga na equipe de segurança.

Diante desse cenário, surge a necessidade de automatizar a triagem de vulnerabilidades, filtrando os achados reais e descartando os falsos positivos de forma eficiente.

É exatamente esse o objetivo do Seekurity Review, uma ferramenta que utiliza inteligência artificial generativa para ajudar desenvolvedores e times de segurança a revisar findings de SAST de forma contextual, rápida e documentada, aliviando o pesado fardo da análise manual com uma "segunda opnião".

O que é o Seekurity Review?

O Seekurity Review é um sistema de triagem automatizada de vulnerabilidades SAST. Em vez de ser mais um scanner, ele atua após a execução de uma ferramenta SAST de sua preferência. A ferramenta consome os resultados brutos do SAST (um arquivo JSON padronizado com os achados de vulnerabilidade) e então usa um modelo de linguagem de IA (LLM) local para revisar cada achado de maneira contextual. Para cada potencial vulnerabilidade reportada, o Seekurity Review determina automaticamente se trata-se de um risco real (vulnerabilidade válida) ou um falso positivo, fornecendo uma justificativa técnica estruturada junto com recomendações de mitigação.

Em outras palavras, o Seekurity Review age como um par extra de olhos, alimentado por IA, que faz a revisão de código como um especialista em segurança faria, porém de forma automatizada. O resultado dessa revisão é incorporado de volta ao relatório, enriquecendo-o com campos adicionais indicando o veredito da IA e sua análise detalhada. Assim, ao final, você obtém um novo JSON de saída com cada achado marcado como "Valid" ou "False Positive", acompanhado de um mini-relatório explicando o porquê daquela classificação e sugestões de correção (quando aplicável).

Por que precisamos dessa ferramenta?

Equipes de desenvolvimento e AppSec frequentemente enfrentam o dilema de lidar com dezenas ou centenas de alertas de segurança gerados por scanners estáticos. A maioria desses alertas pode não representar uma falha explorável de fato.

Esse “ruído” elevado leva à perda de tempo em análises improdutivas, e pior: pode fazer com que vulnerabilidades reais passem despercebidas ou sejam subestimadas em meio à enxurrada de falsos positivos (o efeito “procurando agulha no palheiro”).

Diversos estudos ilustram o problema. A NIST, por exemplo, encontrou taxas de falso positivo em SAST de até 78% em certos cenários. Essa sobrecarga impacta a produtividade e erode a confiança dos desenvolvedores nas ferramentas de segurança – afinal, se a maioria dos avisos é irrelevante, a tendência é começar a ignorá-los (efeito “Cry Wolf”).

O Seekurity Review tem o objetivo de combater a fadiga de triagem e melhorar a eficiência do processo de segurança. Automatizando a validação inicial dos findings com o apoio de um LLM.

Além disso, ao fornecer uma cadei de pensamento e justificativa técnica para cada decisão, a ferramenta também educa e contextualiza, ajudando a equipe a entender por que certo trecho de código é vulnerável ou não, fomentando boas práticas de segurança de forma colaborativa.

Como funciona o Seekurity Review?

flowchart TB
    subgraph Input [Input do JSON SAST]
        GH[GitHub Repo sast-output.json] --> Decision{GH_PAT definido?}
        Local[Arquivo local sast-output.json] --> Decision
    end

    Decision -->|Sim| Fetch[Busca JSON via GitHub API]
    Decision -->|Não| ReadLocal[Lê arquivo JSON local]

    Fetch --> Parse[Parse do JSON]
    ReadLocal --> Parse

    Parse --> Loop[Para cada Vulnerabilidade SAST]

    subgraph Processo [Análise com LLM]
        Loop --> Prompt[Gera prompt com código e descrição da vulnerabilidade]
        Prompt --> LLM[Executa LLM local DeepSeek-R1 via Ollama]
        LLM --> Think[Executa a triagem com raciocínio]
        Think --> Report[Output estruturado]
    end

    Report --> Consolidate[Atualiza JSON com resultados consolidados]

    Consolidate -->|GH_PAT definido| Commit[Commit no GitHub via API]
    Consolidate -->|Sem GH_PAT| Save[Salva JSON localmente]

O fluxo de utilização do Seekurity Review é simples e aproveita os artefatos existentes do seu processo de SAST:

Input – Resultado do SAST: Primeiro, você deve fornecer ao Seekurity Review o arquivo JSON com os resultados do scan SAST (por exemplo, cx-sast-output.json). Esse arquivo contém a lista de vulnerabilidades identificadas pela ferramenta estática original (por exemplo, Checkmarx, Horusec, Snyk, etc.). O Seekurity Review espera um formato específico de JSON – que pode ser adaptado de qualquer engine SAST, desde que contenha informações como severidade, linguagem, descrição do achado, e o trecho de código vulnerável. Obs.: O repositório do projeto inclui exemplos e instruções de como converter a saída da sua ferramenta para o formato suportado.

Exemplo de input JSON para uma projeto chamado 'myproject-repo', mas podem ter varios projeto, cada um com diversas vulnerabilidades.

{
  "project-name": {
    "branch": "main",
    "scan_id": "123abc",
    "vulnerabilities": [
      {
        "severity": "High",
        "language": "JavaScript",
        "description": "Possible XSS via innerHTML",
        "vuln_files": [
          {
            "file_name": "app.js",
            "file_content": "<código vulnerável como string>",
            "file_sha": "sha123",
            "file_size": 1024
          }
        ]
      }
    ]
  }
}

Análise com LLM (DeepSeek-R1): Para cada vulnerabilidade listada no JSON de entrada, o Seekurity Review extrai os dados relevantes – especialmente o trecho de código fonte associado – e envia para análise de um modelo de linguagem large (LLM) especializado em segurança, o DeepSeek-R1. Esse modelo roda localmente (via engine Ollama) e foi instruído a agir como um especialista em segurança da informação, realizando uma revisão contextual do código. O script constrói um prompt bem estruturado para o LLM, incluindo:
- Uma descrição da vulnerabilidade reportada (ex: "Possible XSS via innerHTML").
- O trecho de código fonte potencialmente vulnerável.
- Um roteiro em passos que o modelo deve seguir, semelhante a um checklist mental de um code review seguro: compreender o que o código faz, verificar se há proteções, avaliar se a vulnerabilidade é explorável de fato naquele contexto e, por fim, dar recomendações de correção ou explicar por que seria um falso positivo.
O LLM então processa essa solicitação e produz duas saídas: (a) um raciocínio interno detalhado, onde “pensa alto” passo a passo sobre o problema, e (b) um relatório final formatado, resumindo as conclusões.

flowchart TB
    Start[Início da análise de uma vulnerabilidade SAST em um projeto]

    subgraph Coleta de dados por vulnerabilidade
        Lang[Identifica a linguagem do código do projeto]
        Desc[Obtém a descrição da vulnerabilidade reportada]
        Code[Obtém o trecho/linha de código afetada]
        Meta[Obtém o nome do arquivo]
    end

    Start --> Lang --> Desc --> Code --> Meta

    Meta --> Prompt[Constrói o prompt com todos os dados extraídos e instruções técnicas para Review SAST]

    Prompt --> LLM[Envia o prompt ao modelo DeepSeek-R1 via Ollama para análise]

    LLM --> Output[Retorna o raciocínio técnico e o relatório final da triagem]

Enriquecimento dos resultados: O Seekurity Review captura ambas as saídas do modelo. O raciocínio passo a passo (chamado internamente de secure_review_think) é armazenado principalmente para auditoria e compreensão profunda – ele mostra como o modelo chegou à conclusão, incluindo considerações e verificação de hipóteses. Já o relatório final estruturado (secure_review_result) é a parte principal que interessa para o usuário: um resumo contendo o status (Valid/False Positive) para o achado, uma análise objetiva explicando o veredito e, se aplicável, uma recomendação de mitigação.
Output – Relatório de revisão: Após processar todos os findings, a ferramenta gera um novo arquivo JSON, por padrão nomeado output-secure-review.json. Este arquivo terá o mesmo conteúdo do input original, porém agora cada vulnerabilidade contará com os campos adicionais secure_review_think e secure_review_result preenchidos. Em outras palavras, é o resultado original enriquecido com a “segunda opinião” da IA para cada item. Opcionalmente, o Seekurity Review pode persistir esses resultados automaticamente em seu repositório Git (mais detalhes a seguir), criando um histórico versionado das revisões de segurança.

Como exemplo simplificado, imagine que o SAST reportou uma possível vulnerabilidade de Cross-Site Scripting (XSS) no arquivo app.js. O relatório enriquecido gerado poderia ser algo assim:

# Secure code review report

Vulnerability: Possible XSS via innerHTML  
File: app.js  
Language: JavaScript  
Status: Valid  

**Analysis:**  
O código utiliza `innerHTML` para injetar entrada do usuário no DOM **sem sanitização**, o que permite ataques de XSS caso dados maliciosos sejam inseridos.

**Recommendation:**  
Substituir o uso de `innerHTML` por inserção de texto seguro (por exemplo, usando `textContent`) ou sanitizar a entrada do usuário com uma biblioteca confiável (como DOMPurify) antes da injeção no DOM.

No exemplo acima, o modelo confirmou que a vulnerabilidade era válida (Status: Valid) e explicou tecnicamente o porquê (análise), além de sugerir uma correção. Caso fosse um falso positivo, o Status viria marcado como "False Positive" e a análise explicaria por que aquele código, apesar de parecer vulnerável, não representa risco real (por exemplo, talvez a função nunca seja chamada com input externo, etc.).

Exemplo do json atualizado com o review de segurança, incluindo as keys "secure_review_think" e "secure_review_result" em cada uma das vulnerabilidades.

{
  "project-name": {
    "branch": "main",
    "scan_id": "123abc",
    "vulnerabilities": [
      {
        "severity": "High",
        "language": "JavaScript",
        "description": "Possible XSS via innerHTML",
        "vuln_files": [
          {
            "file_name": "app.js",
            "file_content": "<código vulnerável como string>",
            "file_sha": "sha123",
            "file_size": 1024,
            "secure_review_think": "<raciocínio técnico interno do modelo>",
            "secure_review_result": "<relatório final estruturado>"
          }
        ]
      }
    ]
  }
}

DeepSeek-R1: IA de Raciocínio a Serviço da Segurança de Código

Um dos componentes centrais do Seekurity Review é o modelo de IA utilizado para as análises: DeepSeek-R1. Diferentemente de LLMs populares voltados a conversação genérica, o DeepSeek-R1 é um modelo de última geração com foco especial em raciocínio passo a passo (chain-of-thought) e resolução de problemas complexos. Isso o torna particularmente adequado para tarefas de code review, onde é preciso seguir pistas no código, relacionar conceitos e tirar conclusões técnicas fundamentadas.

Algumas características do DeepSeek-R1 e sua integração no projeto:

LLM Local (14B): O modelo DeepSeek-R1 utilizado possui 14 bilhões de parâmetros e roda localmente através do mecanismo Ollama. Isso significa que o código fonte analisado não sai do ambiente local, garantindo confidencialidade (um ponto crítico em revisões de segurança, já que enviar código sensível para serviços externos pode ser inviável). É importante notar que, para utilizar o Seekurity Review com o modelo, é preciso ter o Ollama instalado e executar o download da imagem do modelo deepseek-r1:14b previamente. Uma vantagem de ser open-source e rodar local é que a solução pode ser integrada em pipelines internos sem riscos de vazamento de propriedade intelectual.
Cadeia de raciocínio explícita: O DeepSeek-R1 foi treinado para “pensar alto” durante a análise. No contexto do Seekurity Review, aproveitamos essa capacidade usando marcadores especiais no prompt (ex.: tags <think>...</think>) para capturar o raciocínio interno que o modelo gera. Assim, para cada vulnerabilidade avaliada, temos não apenas a resposta final, mas também um log do caminho lógico que o modelo percorreu: interpretação do código, checagem de proteções existentes, argumentação sobre exploitabilidade, etc. Esse nível de transparência ajuda os desenvolvedores a confiar mais no veredito da IA, além de possibilitar auditoria.
Especialização em segurança e código: O prompt utilizado conduz o modelo por uma sequência de etapas típica de revisão segura (conforme descrito na seção anterior). Com isso, o DeepSeek-R1 consegue atuar de fato como um especialista em segurança da informação, usando seu conhecimento de desenvolvimento seguro. Ele identifica, por exemplo, se há validação/sanitização presente no código que mitigue o problema, se a função vulnerável é chamada de forma perigosa, ou se aquele alerta do SAST depende de um contexto que na prática não ocorre. Essa análise contextual é o que diferencia uma simples identificação de padrão (como um lint estático faria) de uma triagem inteligente.

Integração com GitHub e Modo Offline

O Seekurity Review foi projetado para ser flexível e fácil de encaixar no fluxo de trabalho dos desenvolvedores. Ele pode rodar tanto de forma 100% local/offline quanto integrado a um repositório GitHub remoto, conforme a necessidade:

Modo Offline (Local): Se você simplesmente baixar o repositório do Seekurity Review e rodar o script em sua máquina local, ele irá buscar o arquivo de input (cx-sast-output.json) localmente no diretório e processá-lo. O resultado (output-secure-review.json) ficará disponível localmente e nenhuma comunicação externa será feita (exceto, claro, a interação com o modelo via Ollama, que também é local). Esse modo é útil para casos em que você exportou o resultado do SAST manualmente e quer rodar a triagem assistida em um ambiente isolado – por exemplo, analisando um projeto internamente sem subir nada para nuvem.
Modo Integrado com GitHub: Você pode opcionalmente configurar algumas variáveis de ambiente para permitir que o Seekurity Review busque automaticamente o JSON de input de um repositório GitHub e também versione o output de volta no repositório. Os parâmetros são:
- GH_PAT: um Personal Access Token do GitHub (com permissões de leitura/escrita no repo em questão).
- GH_ORG e GH_REPO: identificando a organização/usuário e nome do repositório onde estão os arquivos.
- BRANCH: o nome da branch padrão (ex: main).
Com essas variáveis configuradas, ao rodar o script, ele vai utilizar a GitHub API para localizar dentro do repositório o arquivo cx-sast-output.json mais recente. Por padrão, espera-se que os resultados SAST sejam versionados no próprio repo sob o caminho cx-scan/sast/ANO/<mês>/<dia>/cx-sast-output.json (ou seja, organizados por data de scan). Essa estrutura cronológica facilita o Seekurity Review encontrar o scan do dia automaticamente. Uma vez encontrado, o script baixa o JSON do GitHub, realiza todo o processamento com o LLM, e então faz o commit do arquivo de saída de volta no mesmo caminho de data, nomeando-o como cx-secure-review-output.json. O commit é feito com uma mensagem padronizada incluindo o nome do arquivo adicionado, por exemplo: "Add: Secure review file cx-secure-review-output.json".

Esse modo integrado é muito útil para pipelines CI/CD: você pode automatizar para que, após uma ferramenta SAST gerar o relatório e subir no repo, o Seekurity Review rode (via GitHub Actions ou outro mecanismo) para produzir o relatório de triagem e comitar no repo. Assim, todos os envolvidos no projeto podem acessar facilmente o relatório de segurança enriquecido, e ele fica historicamente registrado. Caso o token GH_PAT não esteja definido, o script simplesmente assume o modo offline, evitando qualquer chamada externa.

Em ambos os modos, a ferramenta não altera nenhum código fonte do projeto, apenas lê o relatório estático e escreve resultados em arquivos JSON. No modo GitHub, é recomendado já versionar o JSON de input no repo para que a ferramenta possa localizá-lo; caso contrário, em modo offline, garanta que o arquivo de input esteja disponível localmente. No repositório do Seekurity Review, o README detalha exemplos de como configurar as variáveis e executar o script em cada caso.

Considerações Finais.

É importante reforçar que a ferramenta não elimina a necessidade de um especialista humano, mas provê um assistente incansável que faz o trabalho braçal inicial. A palavra final deve ser dada por alguém da equipe, especialmente em decisões críticas.

O projeto é open-source e está disponível no GitHub (usrbinbrain/seekurity-review). Contribuições são bem-vindas! Se você tem interesse em aprimorar a ferramenta – seja ajustando o prompt, testando com outros modelos LLM compatíveis, ou adicionando novos recursos – sinta-se convidado a abrir issues ou pull requests.