GoThreatScope

Scanner de SBOM, vulnerabilidades e segredos baseado em Go com suporte a MCP.

Documentação

GoThreatScope Logo

GoThreatScope

GoThreatScope é uma ferramenta de segurança educacional e modular escrita em Go.
Ela gera um SBOM leve, verifica dependências no osv.dev em busca de vulnerabilidades e pacotes maliciosos conhecidos, procura por segredos hardcoded (usando Gitleaks quando disponível, ou um fallback embutido) e registra métricas para cada execução (usando pipedream).

Esta ferramenta também atua como um servidor Model Context Protocol (MCP), permitindo que IDEs como Cursor ou Visual Studio Code consultem seus resultados usando linguagem natural.
Por exemplo, você pode perguntar:

"Analise meu projeto e mostre quais dependências parecem arriscadas."

A interface MCP expõe ferramentas e recursos para que outros sistemas ou LLMs possam recuperar SBOMs estruturados, relatórios de vulnerabilidades e descobertas de segredos diretamente do sistema de arquivos local.

Visão Geral

O GoThreatScope realiza uma inspeção de segurança de alto nível em um diretório de projeto e organiza os resultados para análise humana e automatizada.

Ele combina várias capacidades em um único fluxo de trabalho:

Geração de SBOM: cria um inventário simples das dependências do projeto.
Detecção de vulnerabilidades e malware: verifica cada dependência no osv.dev para identificar vulnerabilidades conhecidas e pacotes maliciosos.
Detecção de segredos: procura por chaves de API, senhas e tokens privados usando Gitleaks ou um scanner fallback embutido simples.
Coleta de métricas: armazena métricas estruturadas para cada execução, permitindo comparação entre varreduras (configurado com pipedream).

Cada módulo funciona de forma independente ou como parte do pipeline analyze.
Todos os resultados são armazenados localmente em gothreatscope_store/ e reutilizados quando nenhuma alteração é detectada.

Arquitetura

O GoThreatScope é organizado em pacotes modulares e claros.
Cada pacote lida com uma função de segurança específica ou ponto de integração, facilitando a extensão ou reutilização da ferramenta em outros projetos.

GoThreatScope
│
├── cmd/gothreatscope/         # CLI entrypoint and MCP server mode
│   └── main.go                # CLI commands and MCP wiring
│
├── pkg/
│   ├── sbom/                  # SBOM generation logic
│   ├── vuln/                  # OSV-based vulnerability and malware detection
│   ├── secrets/               # Gitleaks and builtin secret scanner
│   ├── analysis/              # Full pipeline and storage/diff logic
│   ├── metrics/               # Local and remote metrics sender
│   └── mcp/                   # MCP tools and resources implementation
│
└── gothreatscope_store/       # Automatically generated per-project store
    └── <project_id>/
        ├── latest/
        │   ├── sbom.json
        │   ├── vuln.json
        │   ├── secrets.json
        │   ├── metrics.json
        │   └── bundle.json
        └── history/<run_id>/

Cada projeto analisado pelo GoThreatScope recebe seu próprio identificador, derivado do hash SHA-256 do seu caminho absoluto. Todos os resultados são gravados na pasta do projeto em gothreatscope_store/, e novos arquivos só são criados quando diferenças são detectadas em comparação com a execução anterior.

Como Funciona

O GoThreatScope opera por meio de módulos independentes que podem ser executados individualmente ou juntos como parte de um pipeline de análise completo.

1. Identificação do projeto

Cada projeto analisado recebe um identificador único derivado do hash SHA-256 do seu caminho absoluto.
Isso garante rastreamento consistente entre execuções sem revelar nomes de diretórios.

2. Armazenamento persistente

Os resultados da varredura são armazenados no diretório gothreatscope_store/, agrupados por ID do projeto.
Cada módulo grava seu próprio artefato JSON dentro de uma pasta latest/ e mantém um breve histórico de resultados anteriores.

gothreatscope_store/
└── a93bf44e3e9c/
    ├── latest/
    │   ├── sbom.json
    │   ├── vuln.json
    │   ├── secrets.json
    │   └── metrics.json
    └── history/20251007T215959Z/

3. Detecção de alterações

Antes de salvar, o GoThreatScope compara os digests (hashes) dos novos resultados com os da execução anterior. Se não houver alterações, os arquivos armazenados permanecem intactos, evitando gravações redundantes e entradas de histórico desnecessárias.

4. Métricas e telemetria

Cada varredura produz um arquivo metrics.json resumindo tempo, descobertas e detalhes do ambiente. As métricas são sempre armazenadas localmente e podem opcionalmente ser enviadas para um endpoint remoto definido pela variável GOTHREATSCOPE_METRICS_URL.

5. Integração MCP

Quando executado no modo --mcp, o GoThreatScope expõe suas capacidades de análise como ferramentas que podem ser invocadas diretamente por LLMs ou IDEs. Os resultados são retornados como JSON estruturado com URIs file:// apontando para artefatos salvos, permitindo que o sistema chamador os leia ou exiba sem reexecutar varreduras.

Instalação

Pré-requisitos

Go 1.21 ou mais recente
(Opcional) Gitleaks v8+ para detecção estendida de segredos

Instalação a partir do código-fonte

go install github.com/anotherik/gothreatscope/cmd/gothreatscope@latest

Após a instalação, o binário gothreatscope estará disponível no seu caminho $GOBIN.

Build local

# Navigate to the project directory
cd /path/to/GoThreatScope

# Build the binary
go build -o ./bin/gothreatscope ./cmd/gothreatscope

# Make it executable
chmod +x ./bin/gothreatscope

Docker / Podman

Você pode executar o GoThreatScope em um contêiner usando o Dockerfile fornecido.

Construa os metadados da imagem a partir do estado Git local:

# Docker
docker build -t gothreatscope:latest \
  --build-arg VERSION=0.0.0 \
  --build-arg COMMIT=$(git rev-parse --short HEAD) \
  --build-arg DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ) .

# Podman
podman build -t gothreatscope:latest \
  --build-arg VERSION=0.0.0 \
  --build-arg COMMIT=$(git rev-parse --short HEAD) \
  --build-arg DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ) .

Execute uma análise completa no repositório atual:

# Docker
docker run --rm -v "$PWD":/workspace gothreatscope:latest analyze --path /workspace

# Podman
podman run --rm -v "$PWD":/workspace gothreatscope:latest analyze --path /workspace

Inicie o modo MCP no stdio:

# Docker
docker run --rm -i -v "$PWD":/workspace gothreatscope:latest --mcp

# Podman
podman run --rm -i -v "$PWD":/workspace gothreatscope:latest --mcp

A imagem de runtime inclui certificados CA HTTPS e é executada como um usuário não root. Se gitleaks não estiver presente no contêiner, o GoThreatScope usa automaticamente o scanner de segredos embutido.

Variáveis de ambiente opcionais

Variável	Descrição	Padrão
`GOTHREATSCOPE_METRICS_URL`	Endpoint remoto para coleta de telemetria	URL de demonstração embutida
`GTS_KEEP_HISTORY`	Número de snapshots de histórico a manter por projeto	`1`
`GTS_DISABLE_METRICS`	Desativa métricas remotas (armazena métricas apenas localmente)	não definido
`GTS_MCP_MODE`	Ativa o modo MCP (reduz saída verbosa)	`1`
`GTS_QUIET`	Reduz a verbosidade da saída	`1`
`GTS_DEBUG`	Para habilitar o log de depuração	`0`

Se Gitleaks não estiver instalado, o GoThreatScope usa automaticamente seu mecanismo interno de varredura de segredos.

Uso via CLI

O GoThreatScope pode ser usado diretamente pela linha de comando para realizar varreduras individuais ou executar o pipeline completo de análise.

# Generate a Software Bill of Materials (SBOM)
gothreatscope sbom --path ./project

# Check dependencies for vulnerabilities and malicious packages
gothreatscope vuln --path ./project

# Scan for hardcoded secrets
gothreatscope secrets --path ./project [--engine auto|gitleaks|builtin]

# Run the complete pipeline (SBOM + Vulnerabilities + Secrets)
gothreatscope analyze --path ./project

# Display version and global help
gothreatscope --version
gothreatscope --help

Cada comando armazena seus resultados em gothreatscope_store/<project_id>/latest/ e os atualiza somente se novas descobertas forem detectadas. Isso facilita manter registros de longo prazo das varreduras do projeto sem reprocessamento desnecessário.

Modo Servidor MCP

O GoThreatScope também pode ser executado como um servidor Model Context Protocol (MCP), permitindo que IDEs ou LLMs interajam com seus resultados de análise por meio de respostas JSON estruturadas.

O que é MCP?

O Model Context Protocol (MCP) é um padrão que permite que assistentes de IA se conectem com segurança a fontes de dados e ferramentas. O GoThreatScope implementa um servidor MCP que expõe ferramentas de análise de segurança para IDEs como o Cursor.

Para iniciar o servidor:

gothreatscope --mcp

Ao executar no modo MCP, o GoThreatScope expõe várias ferramentas e recursos que podem ser invocados programaticamente ou por meio de editores compatíveis, como Cursor ou VS Code (com suporte a MCP).

Ferramentas MCP disponíveis

O GoThreatScope expõe as seguintes ferramentas via Model Context Protocol (MCP).
Essas ferramentas são registradas e descritas automaticamente em tools.json.

Ferramenta	Descrição
analyzeRepo	Executa o pipeline completo (SBOM → Vulnerabilidades → Segredos).
scanRepoSBOM	Gera um SBOM e retorna seu URI de arquivo.
vulnCheck	Verifica vulnerabilidades e pacotes maliciosos usando OSV.dev.
secretScan	Procura por segredos (usando Gitleaks ou o mecanismo embutido).

Recursos MCP expostos

Após a conclusão de uma varredura, o GoThreatScope também expõe recursos que podem ser acessados por clientes MCP compatíveis (por exemplo, Cursor, VS Code). Esses recursos permitem que os clientes MCP busquem saídas de análise estruturadas, como:

SBOMs — armazenados como sbom.json
Relatórios de vulnerabilidades — armazenados como vuln.json
Descobertas de segredos — armazenados como secrets.json
Métricas — armazenadas como metrics.json

Os recursos são listados automaticamente por meio dos métodos do protocolo MCP:

resources/list lista todos os artefatos armazenados nos projetos analisados.
resources/read recupera o conteúdo de um arquivo específico via URI file:// (por exemplo, caminho de artefato local).

Exemplo de saída MCP

{
  "uri": "file:///home/user/gothreatscope_store/a93bf44e3e9c/latest/vuln.json",
  "changed": true,
  "counts": { "vulns": 5 },
  "note": "Vulnerability report updated (change detected)"
}

Usando esses endpoints, IDEs ou LLMs conectados podem solicitar resultados de análise, abrir os artefatos JSON correspondentes ou cruzar referências de descobertas sem reexecutar varreduras.

Exemplo de Integração (Cursor)

O GoThreatScope pode ser usado diretamente no Cursor ou em qualquer IDE que suporte o Model Context Protocol (MCP).

Após a instalação, configure o Cursor para reconhecer o GoThreatScope como um servidor MCP:

Opção A: Configuração Global Adicione às configurações do Cursor (Arquivo → Preferências → Configurações → Extensões → MCP):

{
  "mcpServers": {
    "gothreatscope": {
      "command": "/absolute/path/to/gothreatscope",
      "args": ["--mcp"],
      "env": {
        "GTS_MCP_MODE": "1"
      }
    }
  }
}

Opção B: Configuração do Workspace Crie um arquivo .cursor/mcp.json na raiz do seu workspace:

{
  "mcpServers": {
    "gothreatscope": {
      "command": "./gothreatscope",
      "args": ["--mcp"],
      "env": {
        "GTS_MCP_MODE": "1"
      }
    }
  }
}

Após reiniciar o Cursor, você pode interagir com o GoThreatScope usando prompts em linguagem natural.
Por exemplo:

Abra um repositório no Cursor
Use a interface de chat para solicitar análise de segurança:
- "GoThreatScope, analise meu projeto atual e mostre se alguma dependência parece arriscada ou contém segredos."
- "Analise este repositório em busca de problemas de segurança"
- "Gere um SBOM para este projeto"
- "Verifique vulnerabilidades nas dependências"
- "Procure por segredos neste código"
Acesse os resultados armazenados por meio do sistema de recursos MCP

O Cursor chamará automaticamente as ferramentas MCP (analyzeRepo, scanRepoSBOM, vulnCheck, secretScan), lerá os artefatos JSON armazenados e raciocinará sobre os resultados de SBOM, vulnerabilidades e segredos para fornecer uma avaliação orientada por IA.

Testando o Servidor MCP

Para fins de depuração, aqui estão alguns exemplos para testar o servidor MCP.

Individualmente:

  `echo '{"id":2,"jsonrpc":"2.0","method":"ping"}' | gothreatscope --mcp`

Todos de uma vez (ou copie o que deseja testar):

printf '%s\n' \
'{"id":1,"jsonrpc":"2.0","method":"initialize"}' \
'{"id":2,"jsonrpc":"2.0","method":"ping"}' \
'{"id":3,"jsonrpc":"2.0","method":"tools/list"}' \
'{"id":4,"jsonrpc":"2.0","method":"tools/call","params":{"name":"scanRepoSBOM","arguments":{"path":"."}}}' \
'{"id":5,"jsonrpc":"2.0","method":"tools/call","params":{"name":"vulnCheck","arguments":{"path":"."}}}' \
'{"id":6,"jsonrpc":"2.0","method":"tools/call","params":{"name":"secretScan","arguments":{"path":".","engine":"auto"}}}' \
'{"id":7,"jsonrpc":"2.0","method":"tools/call","params":{"name":"analyzeRepo","arguments":{"path":"."}}}' \
'{"id":8,"jsonrpc":"2.0","method":"resources/list"}' \
| gothreatscope --mcp

Autores e Licença

Criado por anotherik
Lançado para uso educacional e de pesquisa sob a Licença Apache-2.0.

O GoThreatScope é um projeto educacional e aberto que visa demonstrar boas práticas em análise segura de software e varredura integrada a modelos.
Contribuições, feedback e colaborações de pesquisa são sempre bem-vindos.