GoThreatScope

Escáner de SBOM, vulnerabilidades y secretos basado en Go con soporte para MCP.

Documentación

GoThreatScope Logo

GoThreatScope

GoThreatScope es un conjunto de herramientas de seguridad modular y educativo escrito en Go.
Genera un SBOM ligero, verifica dependencias contra osv.dev para detectar vulnerabilidades y paquetes maliciosos conocidos, escanea secretos hardcodeados (usando Gitleaks cuando está disponible, o un respaldo integrado), y registra métricas para cada ejecución (usando pipedream).

Esta herramienta también actúa como un servidor Model Context Protocol (MCP), permitiendo que IDEs como Cursor o Visual Studio Code consulten sus resultados usando lenguaje natural.
Por ejemplo, puedes preguntar:

"Analiza mi proyecto y muéstrame qué dependencias parecen riesgosas."

La interfaz MCP expone herramientas y recursos para que otros sistemas o LLMs puedan recuperar SBOMs estructurados, informes de vulnerabilidades y hallazgos de secretos directamente desde el sistema de archivos local.

Descripción general

GoThreatScope realiza una inspección de seguridad de alto nivel de un directorio de proyecto y organiza los resultados tanto para análisis humano como automatizado.

Combina varias capacidades en un solo flujo de trabajo:

Generación de SBOM: crea un inventario simple de las dependencias del proyecto.
Detección de vulnerabilidades y malware: verifica cada dependencia contra osv.dev para identificar vulnerabilidades conocidas y paquetes maliciosos.
Detección de secretos: busca claves API, contraseñas y tokens privados usando Gitleaks o un escáner de respaldo integrado simple.
Recopilación de métricas: almacena métricas estructuradas para cada ejecución, permitiendo comparar escaneos (configurado con pipedream).

Cada módulo funciona de forma independiente o como parte del pipeline analyze.
Todos los resultados se almacenan localmente bajo gothreatscope_store/ y se reutilizan cuando no se detectan cambios.

Arquitectura

GoThreatScope está organizado en paquetes modulares claros.
Cada paquete maneja una función de seguridad específica o un punto de integración, lo que facilita extender o reutilizar la herramienta en otros proyectos.

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 proyecto escaneado por GoThreatScope recibe su propio identificador, derivado del hash SHA-256 de su ruta absoluta. Todos los resultados se escriben en la carpeta de ese proyecto bajo gothreatscope_store/, y solo se crean nuevos archivos cuando se detectan diferencias en comparación con la ejecución anterior.

Cómo funciona

GoThreatScope opera a través de módulos independientes que pueden ejecutarse individualmente o juntos como parte de un pipeline de análisis completo.

1. Identificación del proyecto

A cada proyecto escaneado se le asigna un identificador único derivado del hash SHA-256 de su ruta absoluta.
Esto garantiza un seguimiento consistente entre ejecuciones sin revelar nombres de directorios.

2. Almacenamiento persistente

Los resultados del escaneo se almacenan bajo el directorio gothreatscope_store/, agrupados por ID de proyecto.
Cada módulo escribe su propio artefacto JSON dentro de una carpeta latest/, y mantiene un historial corto de resultados pasados.

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

3. Detección de cambios

Antes de guardar, GoThreatScope compara los resúmenes (hashes) de los nuevos resultados con los de la ejecución anterior. Si no hay cambios, los archivos almacenados permanecen intactos, evitando escrituras redundantes y entradas de historial innecesarias.

4. Métricas y telemetría

Cada escaneo produce un archivo metrics.json que resume tiempos, hallazgos y detalles del entorno. Las métricas siempre se almacenan localmente y opcionalmente pueden enviarse a un endpoint remoto definido por la variable GOTHREATSCOPE_METRICS_URL.

5. Integración MCP

Cuando se ejecuta en modo --mcp, GoThreatScope expone sus capacidades de análisis como herramientas que pueden ser invocadas directamente por LLMs o IDEs. Los resultados se devuelven como JSON estructurado con URIs file:// que apuntan a los artefactos guardados, permitiendo que el sistema llamador los lea o muestre sin volver a ejecutar escaneos.

Instalación

Requisitos previos

Go 1.21 o superior
(Opcional) Gitleaks v8+ para detección extendida de secretos

Instalación desde el código fuente

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

Después de la instalación, el binario gothreatscope estará disponible en tu ruta $GOBIN.

Compilación 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

Puedes ejecutar GoThreatScope en un contenedor usando el Dockerfile proporcionado.

Construye los metadatos de la imagen desde tu estado local de Git:

# 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) .

Ejecuta un análisis completo contra el repositorio actual:

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

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

Inicia el modo MCP en stdio:

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

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

La imagen de runtime incluye certificados CA de HTTPS y se ejecuta como un usuario no root. Si gitleaks no está presente en el contenedor, GoThreatScope usa automáticamente el escáner de secretos integrado.

Variables de entorno opcionales

Variable	Descripción	Predeterminado
`GOTHREATSCOPE_METRICS_URL`	Endpoint remoto para recopilación de telemetría	URL de demostración integrada
`GTS_KEEP_HISTORY`	Número de instantáneas de historial a mantener por proyecto	`1`
`GTS_DISABLE_METRICS`	Deshabilitar métricas remotas (almacenar métricas solo localmente)	sin establecer
`GTS_MCP_MODE`	Habilita el modo MCP (reduce la salida verbosa)	`1`
`GTS_QUIET`	Reduce la verbosidad de la salida	`1`
`GTS_DEBUG`	Para habilitar el registro de depuración	`0`

Si Gitleaks no está instalado, GoThreatScope usa automáticamente su motor interno de escaneo de secretos.

Uso desde la línea de comandos

GoThreatScope puede usarse directamente desde la línea de comandos para realizar escaneos individuales o ejecutar el pipeline de análisis completo.

# 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 almacena sus resultados bajo gothreatscope_store/<project_id>/latest/ y los actualiza solo si se detectan nuevos hallazgos. Esto facilita mantener registros a largo plazo de los escaneos del proyecto sin reprocesamiento innecesario.

Modo servidor MCP

GoThreatScope también puede ejecutarse como un servidor Model Context Protocol (MCP), permitiendo que IDEs o LLMs interactúen con sus resultados de análisis a través de respuestas JSON estructuradas.

¿Qué es MCP?

El Model Context Protocol (MCP) es un estándar que permite a los asistentes de IA conectarse de forma segura a fuentes de datos y herramientas. GoThreatScope implementa un servidor MCP que expone herramientas de análisis de seguridad a IDEs como Cursor.

Para iniciar el servidor:

gothreatscope --mcp

Cuando se ejecuta en modo MCP, GoThreatScope expone varias herramientas y recursos que pueden invocarse programáticamente o a través de editores compatibles como Cursor o VS Code (con soporte MCP).

Herramientas MCP disponibles

GoThreatScope expone las siguientes herramientas a través del Model Context Protocol (MCP).
Estas herramientas se registran y describen automáticamente en tools.json.

Herramienta	Descripción
analyzeRepo	Ejecuta el pipeline completo (SBOM → Vulnerabilidades → Secretos).
scanRepoSBOM	Genera un SBOM y devuelve su URI de archivo.
vulnCheck	Verifica vulnerabilidades y paquetes maliciosos usando OSV.dev.
secretScan	Escanea secretos (usando Gitleaks o el motor integrado).

Recursos MCP expuestos

Una vez que se completa un escaneo, GoThreatScope también expone recursos que pueden ser accedidos por clientes MCP compatibles (por ejemplo, Cursor, VS Code). Estos recursos permiten que los clientes MCP obtengan salidas de análisis estructuradas como:

SBOMs — almacenados como sbom.json
Informes de vulnerabilidades — almacenados como vuln.json
Hallazgos de secretos — almacenados como secrets.json
Métricas — almacenadas como metrics.json

Los recursos se listan automáticamente a través de los métodos del protocolo MCP:

resources/list lista todos los artefactos almacenados en los proyectos escaneados.
resources/read recupera el contenido de un archivo específico a través de una URI file:// (por ejemplo, ruta de artefacto local).

Ejemplo de salida MCP

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

Usando estos endpoints, los IDEs o LLMs conectados pueden solicitar resultados de análisis, abrir los artefactos JSON correspondientes o hacer referencias cruzadas de hallazgos sin volver a ejecutar los escaneos.

Ejemplo de integración (Cursor)

GoThreatScope puede usarse directamente dentro de Cursor o cualquier IDE que soporte el Model Context Protocol (MCP).

Una vez instalado, configura Cursor para reconocer GoThreatScope como un servidor MCP:

Opción A: Configuración global Agrega a la configuración de Cursor (Archivo → Preferencias → Configuración → Extensiones → MCP):

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

Opción B: Configuración del espacio de trabajo Crea un archivo .cursor/mcp.json en la raíz de tu espacio de trabajo:

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

Después de reiniciar Cursor, puedes interactuar con GoThreatScope usando indicaciones en lenguaje natural.
Por ejemplo:

Abre un repositorio en Cursor
Usa la interfaz de chat para solicitar análisis de seguridad:
- "GoThreatScope, analiza mi proyecto actual y muéstrame si alguna dependencia parece riesgosa o contiene secretos."
- "Analiza este repositorio en busca de problemas de seguridad"
- "Genera un SBOM para este proyecto"
- "Verifica vulnerabilidades en las dependencias"
- "Escanea secretos en este código"
Accede a los resultados almacenados a través del sistema de recursos MCP

Cursor llamará automáticamente a las herramientas MCP (analyzeRepo, scanRepoSBOM, vulnCheck, secretScan), leerá los artefactos JSON almacenados y razonará sobre los resultados de SBOM, vulnerabilidades y secretos para proporcionar una evaluación impulsada por IA.

Probando el servidor MCP

Con fines de depuración, aquí puedes encontrar algunos ejemplos para probar el servidor MCP.

Individualmente:

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

Todos a la vez (o copia el que quieras probar):

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 y licencia

Creado por anotherik
Publicado para uso educativo y de investigación bajo la Licencia Apache-2.0.

GoThreatScope es un proyecto educativo y abierto que tiene como objetivo demostrar mejores prácticas en análisis de software seguro y escaneo integrado con modelos.
Las contribuciones, comentarios y colaboraciones de investigación siempre son bienvenidos.