Skip to content

Referencia de API Publica - mcp-scan

Documentacion completa de todos los tipos, metodos y estructuras exportados por mcp-scan.

Indice

scanner.Config

Estructura de configuracion para el scanner.

type Config struct {
    // Include define patrones glob de archivos a incluir
    // Por defecto: ["**/*.py", "**/*.ts", "**/*.js"]
    Include []string

    // Exclude define patrones glob de archivos a excluir
    // Por defecto: ["node_modules/**", "venv/**", ".venv/**", "dist/**", "build/**", "**/*.min.js"]
    Exclude []string

    // Mode es el modo de analisis (fast o deep)
    // Por defecto: ModeFast
    Mode Mode

    // Timeout es la duracion maxima del escaneo
    // Por defecto: 5 minutos
    Timeout time.Duration

    // FailOn es la severidad minima para considerar fallo
    // Si hay hallazgos con esta severidad o superior, ExitCode sera 1
    FailOn types.Severity

    // Rules especifica que reglas ejecutar (vacio = todas)
    Rules []string

    // Baseline es la ruta al archivo de linea base
    // Los hallazgos en la linea base se filtran de los resultados
    Baseline string

    // RedactSnippets elimina snippets de codigo de la salida
    // Util para evitar exponer codigo fuente en reportes
    RedactSnippets bool

    // Workers es el numero de workers paralelos
    // 0 = auto (usa runtime.NumCPU())
    Workers int
}

Metodos

DefaultConfig

func DefaultConfig() Config

Retorna una configuracion con valores por defecto sensatos.

Ejemplo:

cfg := scanner.DefaultConfig()
cfg.Mode = scanner.ModeDeep
cfg.Timeout = 10 * time.Minute
cfg.FailOn = types.SeverityHigh

scanner.Scanner

Tipo principal del scanner.

type Scanner struct {
    // campos internos no exportados
}

Constructor

New

func New(config Config) *Scanner

Crea una nueva instancia del scanner con la configuracion especificada.

Ejemplo:

cfg := scanner.Config{
    Mode:    scanner.ModeFast,
    Workers: 4,
}
s := scanner.New(cfg)

Metodos

Scan

func (s *Scanner) Scan(ctx context.Context, path string) (*Result, error)

Ejecuta un escaneo de seguridad en la ruta especificada.

Parametros: - ctx: Contexto para cancelacion y timeout - path: Ruta al directorio o archivo a escanear

Retorna: - *Result: Resultados del escaneo - error: Error si el escaneo falla

Ejemplo:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()

result, err := s.Scan(ctx, "/path/to/mcp-server")
if err != nil {
    log.Fatal(err)
}

GenerateReport

func (s *Scanner) GenerateReport(result *Result, format string) ([]byte, error)

Genera un reporte en el formato especificado.

Parametros: - result: Resultados del escaneo - format: Formato del reporte ("json", "sarif", "evidence")

Retorna: - []byte: Contenido del reporte - error: Error si la generacion falla

Formatos soportados: | Formato | Descripcion | |---------|-------------| | json | JSON estructurado con todos los datos | | sarif | SARIF 2.1.0 para integracion con GitHub/GitLab | | evidence | Bundle de evidencias para auditoria |

Ejemplo:

jsonReport, err := s.GenerateReport(result, "json")
if err != nil {
    log.Fatal(err)
}
os.WriteFile("report.json", jsonReport, 0644)

GenerateBaseline

func (s *Scanner) GenerateBaseline(result *Result, reason string, acceptedBy string) *baseline.Baseline

Crea una linea base a partir de los hallazgos del escaneo.

Parametros: - result: Resultados del escaneo - reason: Razon para aceptar los hallazgos - acceptedBy: Identificador de quien acepta (email, nombre)

Ejemplo:

bl := s.GenerateBaseline(result, "Revisado en auditoria Q1", "security@example.com")
bl.Save("baseline.json")

ApplyBaseline

func (s *Scanner) ApplyBaseline(result *Result, bl *baseline.Baseline) int

Aplica una linea base a los resultados, filtrando hallazgos aceptados. Modifica el resultado in-place.

Parametros: - result: Resultados a filtrar - bl: Linea base a aplicar

Retorna: - int: Numero de hallazgos filtrados

Ejemplo:

bl, _ := scanner.LoadBaseline("baseline.json")
filteredCount := s.ApplyBaseline(result, bl)
fmt.Printf("Filtrados %d hallazgos por linea base\n", filteredCount)

scanner.Result

Estructura que contiene los resultados del escaneo.

type Result struct {
    // Findings es la lista de vulnerabilidades detectadas
    Findings []types.Finding

    // Summary contiene estadisticas agregadas
    Summary *types.Summary

    // Manifest contiene informacion de archivos escaneados
    Manifest *types.Manifest

    // MCPSurface contiene la superficie MCP detectada
    MCPSurface *surface.MCPSurface

    // MSSSScore contiene la puntuacion de cumplimiento MSSS
    MSSSScore *msss.Score

    // ScanDuration es la duracion del escaneo
    ScanDuration time.Duration

    // Mode es el modo usado para el escaneo
    Mode Mode

    // ExitCode es el codigo de salida sugerido
    // 0 = exito, 1 = hallazgos por encima de FailOn
    ExitCode int

    // BaselinedCount es el numero de hallazgos filtrados por linea base
    BaselinedCount int
}

types.Summary

type Summary struct {
    // Total de hallazgos
    Total int

    // BySeverity cuenta por nivel de severidad
    BySeverity map[string]int

    // ByClass cuenta por clase de vulnerabilidad
    ByClass map[string]int

    // ByLanguage cuenta por lenguaje
    ByLanguage map[string]int
}

types.Manifest

type Manifest struct {
    // TotalFiles numero de archivos escaneados
    TotalFiles int

    // Languages cuenta de archivos por lenguaje
    Languages map[string]int

    // Files lista de archivos con metadatos
    Files []FileInfo

    // ConfigHash hash SHA-256 de la configuracion usada
    ConfigHash string
}

type FileInfo struct {
    Path     string          // Ruta del archivo
    Hash     string          // SHA-256 del contenido
    Size     int64           // Tamano en bytes
    Language types.Language  // Lenguaje detectado
}

scanner.Mode

Tipo que representa el modo de analisis.

type Mode string

const (
    // ModeFast analisis intra-procedural (dentro de funciones)
    // Rapido, adecuado para CI/CD
    ModeFast Mode = "fast"

    // ModeDeep analisis inter-procedural (a traves de funciones)
    // Mas preciso, usa call graph
    ModeDeep Mode = "deep"
)

Comparacion de modos:

Caracteristica Fast Deep
Velocidad Alta Media
Analisis taint Intra-procedural Inter-procedural
Call graph No Si
Uso de memoria Bajo Medio
Falsos negativos Posibles Menos
Caso de uso CI/CD, PRs Certificacion, Auditorias

types.Finding

Representa un hallazgo de seguridad.

type Finding struct {
    // ID identificador unico del hallazgo (SHA-256 truncado)
    ID string

    // RuleID identificador de la regla (ej: "MCP-A003")
    RuleID string

    // Title titulo corto del hallazgo
    Title string

    // Severity nivel de severidad
    Severity Severity

    // Confidence nivel de confianza en la deteccion
    Confidence Confidence

    // Class clase de vulnerabilidad (A-N)
    Class VulnClass

    // Language lenguaje del codigo fuente
    Language Language

    // Location ubicacion en el codigo fuente
    Location Location

    // MCPContext contexto MCP (tool, handler, transport)
    MCPContext *MCPContext

    // Trace traza de flujo de datos (si aplica)
    Trace *TaintTrace

    // Evidence evidencia del hallazgo
    Evidence Evidence

    // Description descripcion detallada
    Description string

    // Remediation guia de remediacion
    Remediation string
}

types.MCPContext

type MCPContext struct {
    ToolName    string  // Nombre del tool MCP
    HandlerName string  // Nombre de la funcion handler
    Transport   string  // Tipo de transporte (stdio, http, websocket)
}

types.Evidence

type Evidence struct {
    // Snippet fragmento de codigo vulnerable
    Snippet string

    // SnippetHash hash del snippet
    SnippetHash string

    // Trace pasos de la traza de taint
    Trace []TraceStep

    // LLMAnalysis analisis de LLM (si esta habilitado)
    LLMAnalysis string

    // LLMConfidence confianza del analisis LLM
    LLMConfidence float64

    // LLMCategory categoria detectada por LLM
    LLMCategory string

    // CodeQLConfirmed confirmado por CodeQL
    CodeQLConfirmed bool
}

types.TaintTrace

type TaintTrace struct {
    Source Location     // Ubicacion del source
    Sink   Location     // Ubicacion del sink
    Steps  []TraceStep  // Pasos intermedios
}

type TraceStep struct {
    Location Location  // Donde ocurre este paso
    Action   string    // Tipo: "assign", "concat", "call_arg", "return"
    Variable string    // Variable afectada
    Note     string    // Nota adicional
}

types.Severity

Nivel de severidad de un hallazgo.

type Severity string

const (
    SeverityInfo     Severity = "info"     // Informativo, sin impacto directo
    SeverityLow      Severity = "low"      // Bajo impacto
    SeverityMedium   Severity = "medium"   // Impacto moderado
    SeverityHigh     Severity = "high"     // Alto impacto
    SeverityCritical Severity = "critical" // Impacto critico
)

Metodos

Level

func (s Severity) Level() int

Retorna el nivel numerico para comparaciones.

Severidad Nivel
info 0
low 1
medium 2
high 3
critical 4

SeverityFromString

func SeverityFromString(s string) Severity

Parsea una cadena a Severity.

Ejemplo:

sev := types.SeverityFromString("high")
// sev == types.SeverityHigh

types.Confidence

Nivel de confianza en la deteccion.

type Confidence string

const (
    ConfidenceLow    Confidence = "low"    // Baja confianza, posible FP
    ConfidenceMedium Confidence = "medium" // Confianza media
    ConfidenceHigh   Confidence = "high"   // Alta confianza
)

Factores que afectan la confianza: - Longitud de la traza de taint (mas larga = menor confianza) - Flujo inter-archivo (reduce confianza) - Confirmacion por CodeQL (aumenta confianza) - Presencia de sanitizers parciales (reduce confianza)

types.Location

Ubicacion en el codigo fuente.

type Location struct {
    File      string  // Ruta del archivo
    StartLine int     // Linea de inicio (1-indexed)
    StartCol  int     // Columna de inicio (0-indexed)
    EndLine   int     // Linea final
    EndCol    int     // Columna final
}

Metodos

String

func (l Location) String() string

Retorna representacion legible: "archivo.py:10:5"

types.VulnClass

Clase de vulnerabilidad (A-N).

type VulnClass string

const (
    ClassA       VulnClass = "A"       // RCE (Remote Code Execution)
    ClassB       VulnClass = "B"       // Filesystem Traversal
    ClassC       VulnClass = "C"       // SSRF/Network
    ClassD       VulnClass = "D"       // SQL Injection
    ClassE       VulnClass = "E"       // Secrets/Tokens
    ClassF       VulnClass = "F"       // Auth/OAuth
    ClassG       VulnClass = "G"       // Tool Poisoning
    ClassH       VulnClass = "H"       // Prompt Injection
    ClassI       VulnClass = "I"       // Privilege Escalation
    ClassJ       VulnClass = "J"       // Cross-Tool Flows
    ClassK       VulnClass = "K"       // AuthN/AuthZ
    ClassL       VulnClass = "L"       // Plugin Lifecycle
    ClassM       VulnClass = "M"       // Hidden Network
    ClassN       VulnClass = "N"       // Supply Chain
    ClassUnknown VulnClass = "unknown" // Sin clasificar
)

surface.MCPSurface

Superficie MCP detectada en el codigo.

type MCPSurface struct {
    // Tools lista de tools MCP detectados
    Tools []Tool

    // Resources lista de recursos MCP detectados
    Resources []Resource

    // Prompts lista de prompts MCP detectados
    Prompts []Prompt

    // Transport tipo de transporte detectado
    Transport TransportType

    // AuthSignals senales de autenticacion detectadas
    AuthSignals []AuthSignal
}

surface.Tool

type Tool struct {
    Name        string                 // Nombre del tool
    Description string                 // Descripcion
    Schema      map[string]interface{} // Esquema de entrada/salida
    Handler     *HandlerRef            // Referencia al handler
    Decorators  []string               // Decoradores aplicados
    Location    types.Location         // Ubicacion en codigo
}

surface.Resource

type Resource struct {
    Name        string          // Nombre del recurso
    Description string          // Descripcion
    Handler     *HandlerRef     // Referencia al handler
    Location    types.Location  // Ubicacion en codigo
}

surface.Prompt

type Prompt struct {
    Name        string          // Nombre del prompt
    Description string          // Descripcion
    Handler     *HandlerRef     // Referencia al handler
    Location    types.Location  // Ubicacion en codigo
}

surface.HandlerRef

type HandlerRef struct {
    FunctionName string          // Nombre de la funcion
    FileName     string          // Archivo donde esta definida
    Location     types.Location  // Ubicacion exacta
}

surface.TransportType

type TransportType string

const (
    TransportSTDIO     TransportType = "stdio"     // Entrada/salida estandar
    TransportHTTP      TransportType = "http"      // HTTP REST
    TransportWebSocket TransportType = "websocket" // WebSocket
    TransportUnknown   TransportType = "unknown"   // No determinado
)

surface.AuthSignal

type AuthSignal struct {
    Type     string          // "cookie", "header", "oauth_state", "oauth_nonce"
    Name     string          // Nombre de la funcion/variable
    Location types.Location  // Ubicacion en codigo
}

msss.Score

Puntuacion de cumplimiento MSSS (MCP Server Security Standard).

type Score struct {
    // Total puntuacion total (0-100)
    Total float64

    // Categories puntuaciones por categoria
    Categories map[string]CategoryScore

    // Version version de MSSS usada
    Version string

    // Compliant indica si cumple el minimo (Level >= 1)
    Compliant bool

    // Level nivel de cumplimiento (0-3)
    Level int

    // Details detalles del calculo
    Details *ScoreDetails
}

Niveles de Cumplimiento

Nivel Nombre Requisitos
0 No Cumple Score < 60 o hallazgos criticos
1 Basico Score >= 60, <= 3 hallazgos high
2 Enterprise Score >= 80, sin hallazgos high
3 Certificado Score >= 90, sin hallazgos high

msss.CategoryScore

type CategoryScore struct {
    Score     float64  // Puntuacion actual
    MaxScore  float64  // Puntuacion maxima posible
    Weight    float64  // Peso de la categoria
    Findings  int      // Numero de hallazgos
    Penalties float64  // Penalizaciones aplicadas
}

msss.ScoreDetails

type ScoreDetails struct {
    BaseScore       float64             // Puntuacion base (100)
    Penalties       float64             // Total de penalizaciones
    Bonuses         float64             // Bonificaciones (futuro)
    FindingsPenalty map[string]float64  // Penalizacion por hallazgo
}

Pesos por Categoria

Clase Peso Descripcion
A 22% RCE
B 13% Filesystem
C 10% SSRF
D 10% SQLi
E 10% Secrets
F 8% Auth
G 8% Tool Poisoning
H 5% Prompt Injection
I 4% Privilege Escalation
J 3% Cross-Tool
K 3% AuthN/AuthZ
N 4% Supply Chain

baseline.Baseline

Linea base de hallazgos aceptados.

type Baseline struct {
    // Version version del formato
    Version string

    // CreatedAt fecha de creacion
    CreatedAt time.Time

    // UpdatedAt ultima actualizacion
    UpdatedAt time.Time

    // Description descripcion opcional
    Description string

    // Entries lista de entradas
    Entries []Entry
}

baseline.Entry

type Entry struct {
    RuleID       string     // ID de la regla
    LocationHash string     // Hash de ubicacion (16 chars hex)
    Reason       string     // Razon de aceptacion
    AcceptedAt   time.Time  // Cuando se acepto
    AcceptedBy   string     // Quien acepto
    OriginalFile string     // Archivo original
    OriginalLine int        // Linea original
}

Metodos de Baseline

Contains

func (b *Baseline) Contains(finding types.Finding) bool

Verifica si un hallazgo esta en la linea base.

Filter

func (b *Baseline) Filter(findings []types.Finding) (filtered []types.Finding, baselinedCount int)

Filtra hallazgos, retornando solo los que NO estan en la linea base.

AddFinding

func (b *Baseline) AddFinding(finding types.Finding, reason string, acceptedBy string)

Agrega un hallazgo a la linea base.

RemoveFinding

func (b *Baseline) RemoveFinding(finding types.Finding) bool

Elimina un hallazgo de la linea base.

Merge

func (b *Baseline) Merge(other *Baseline) int

Combina otra linea base con esta. Retorna el numero de entradas agregadas.

GetStats

func (b *Baseline) GetStats() Stats

Retorna estadisticas de la linea base.

type Stats struct {
    TotalEntries int            // Total de entradas
    ByRuleID     map[string]int // Conteo por regla
    ByFile       map[string]int // Conteo por archivo
}

Save

func (b *Baseline) Save(path string) error

Guarda la linea base en un archivo JSON.

Funciones de Conveniencia

scanner.Scan

func Scan(ctx context.Context, path string, config Config) (*Result, error)

Funcion de conveniencia que crea un scanner y ejecuta un escaneo en una sola llamada.

Ejemplo:

result, err := scanner.Scan(ctx, "/path/to/code", scanner.DefaultConfig())

scanner.LoadBaseline

func LoadBaseline(path string) (*baseline.Baseline, error)

Carga una linea base desde un archivo.

scanner.NewBaseline

func NewBaseline() *baseline.Baseline

Crea una nueva linea base vacia.

scanner.SaveBaseline

func SaveBaseline(bl *baseline.Baseline, path string) error

Guarda una linea base en un archivo.

Tipos de Lenguaje

type Language string

const (
    Python     Language = "python"
    TypeScript Language = "typescript"
    JavaScript Language = "javascript"
    Go         Language = "go"
)

Soporte por lenguaje:

Lenguaje Parsing Reglas Taint
Python Completo Completo Completo
TypeScript Completo Completo Completo
JavaScript Completo Completo Completo
Go Completo Parcial Parcial