BIT Security MCP

Herramienta de seguridad de código para el equipo BIT. Funciona en dos modos:

| Modo | Cuándo usarlo | Cómo | |------|--------------|------| | MCP local | Mientras desarrollas, en Claude Code | Servidor MCP conectado a Claude Code | | CI/CD | En cada PR y push | CLI bit-security-audit vía npm |

Activa 7 agentes especializados sobre el código y lo enriquece con OWASP A1–A10, Agentic T1–T15 y CWEs. Funciona con cualquier lenguaje: JS, TS, Python, Java, Go, C#, PHP, Ruby, C/C++.

Modo 1 — MCP local (para devs)

Usa tu cuenta Claude Team. Sin API key adicional.

Requisitos

• Node.js 20+
• Claude Code (npm install -g @anthropic-ai/claude-code)
• Cuenta Claude Team activa (claude login)

Setup (una sola vez por máquina)

# Clonar el repo del MCP
git clone [email protected]:BusinessITEcuador/BIT-MCP-Claude-Code-Security.git
cd BIT-MCP-Claude-Code-Security
npm install

Agrega el servidor a ~/.claude/mcp_settings.json:

{
  "mcpServers": {
    "bit-security": {
      "command": "node",
      "args": ["/ruta/absoluta/a/BIT-MCP-Claude-Code-Security/src/index.js"]
    }
  }
}

Verifica que está activo:

claude mcp list
claude mcp get bit-security

Uso desde Claude Code

Dentro de cualquier proyecto, escríbele a Claude:

# Archivo específico
> Corre un security audit del archivo src/auth/login.js

# Carpeta completa
> run_security_audit en toda la carpeta src/api/

# Todo el proyecto
> Corre un security audit completo de src/

# Solo los cambios de esta rama (ideal antes de un PR)
> Analiza los archivos del git diff con main

Parámetros del tool run_security_audit

Desde v3.0 el MCP usa la misma lógica que el CLI (mismo modelo, prompt, batching, parsing JSON), así que devuelve resultados equivalentes a bit-security-audit. Dos modos:

Single-file — pegás código en code:

| Param | Default | Descripción | |-------|---------|-------------| | code | — | Código fuente a auditar | | filename | — | Nombre/path del archivo | | context | — | Framework, lenguaje, tipo de proyecto |

Repo — Claude lee el árbol de archivos del path:

| Param | Default | Descripción | |-------|---------|-------------| | path | — | Path absoluto del directorio | | diff | — | Auditar solo archivos cambiados vs esta rama | | strictDiff | false | Enviar solo líneas cambiadas como contexto (requiere diff) | | exclude | [] | Globs/paths a ignorar | | maxFiles | ilimitado | Cap de archivos |

Comunes (parity con CLI):

| Param | Default | Descripción | |-------|---------|-------------| | model | claude-sonnet-4-6 | Modelo Claude a usar | | customRulesPath | — | Markdown con reglas custom | | autoFix | false | Pide al modelo fixed_code en cada finding | | jsonOutput | true | Devuelve JSON estructurado (igual schema que CLI --format json) | | cache | false | Activar cache por archivo (repo mode únicamente) | | cacheDir | path | Dónde guardar .bit-audit-cache.json |

Validación: pasar exactamente uno de code o path.

Análisis automático al guardar (watch mode)

Abre una terminal en tu proyecto y ejecuta:

node /ruta/a/BIT-MCP-Claude-Code-Security/scripts/watch.js ./src

Los resultados se escriben en .security-alerts.md en tiempo real. Agrégate al .gitignore:

echo ".security-alerts.md" >> .gitignore

Con VS Code: instala la extensión Run on Save (emeraldwalk.runonsave), copia .vscode/settings.json de este repo a tu proyecto y ajusta la ruta.

Actualizar agentes

cd /ruta/a/BIT-MCP-Claude-Code-Security
git pull

Modo 2 — CI/CD (para pipelines)

El CLI está publicado en npm como bit-security-mcp (binario bit-security-audit). Se instala con una línea y funciona en cualquier repo sin configuración adicional.

npm install -g bit-security-mcp
bit-security-audit --path ./src --fail-on critical,high --format junit --output results.xml

Requisito: variable secreta ANTHROPIC_API_KEY en el pipeline.

Templates listos en templates/azure-devops.yml y templates/github-actions.yml.

Azure DevOps

1. Crear el Variable Group

En Pipelines → Library → + Variable group:

• Nombre: BIT-Security-Secrets
• Variable: ANTHROPIC_API_KEY → marcar como secret

2. Agregar a azure-pipelines.yml

variables:
  - group: BIT-Security-Secrets

stages:
  - stage: SecurityAudit
    displayName: 'BIT Security Audit'
    jobs:
      - job: RunAudit
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - task: NodeTool@0
            displayName: 'Setup Node.js 20'
            inputs:
              versionSpec: '20.x'

          - script: npm install -g bit-security-mcp
            displayName: 'Install BIT Security MCP'

          - script: |
              if [ "$(Build.Reason)" = "PullRequest" ]; then
                bit-security-audit \
                  --diff origin/$(System.PullRequest.TargetBranch) \
                  --fail-on critical,high \
                  --format junit \
                  --output $(Build.ArtifactStagingDirectory)/security-results.xml
              else
                bit-security-audit \
                  --path ./src \
                  --fail-on critical,high \
                  --format junit \
                  --output $(Build.ArtifactStagingDirectory)/security-results.xml
              fi
            displayName: 'Run BIT Security Audit'
            env:
              ANTHROPIC_API_KEY: $(ANTHROPIC_API_KEY)
            continueOnError: true

          - task: PublishTestResults@2
            displayName: 'Publish Security Results'
            condition: always()
            inputs:
              testResultsFormat: 'JUnit'
              testResultsFiles: '$(Build.ArtifactStagingDirectory)/security-results.xml'
              testRunTitle: 'BIT Security Audit'
              failTaskOnFailedTests: true

Los resultados aparecen en la pestaña Tests del pipeline. El build falla si hay hallazgos critical o high.

GitHub Actions

1. Configurar el secret

Para un solo repo: Settings → Secrets and variables → Actions → New repository secret

Para todos los repos de la organización: Organization Settings → Secrets → New organization secret

• Nombre: ANTHROPIC_API_KEY

2. Crear .github/workflows/security.yml

name: BIT Security Audit

on:
  push:
    branches: [main, develop, 'feature/**']
  pull_request:
    branches: [main, develop]

jobs:
  security-audit:
    runs-on: ubuntu-latest
    permissions:
      security-events: write  # necesario para subir SARIF
      contents: read

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # necesario para --diff en PRs

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install BIT Security MCP
        run: npm install -g bit-security-mcp

      - name: Run BIT Security Audit
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            bit-security-audit \
              --diff origin/${{ github.base_ref }} \
              --fail-on critical,high \
              --format sarif \
              --output results.sarif
          else
            bit-security-audit \
              --path ./src \
              --fail-on critical,high \
              --format sarif \
              --output results.sarif
          fi
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        continue-on-error: true

      - name: Upload to GitHub Security tab
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: results.sarif

Los hallazgos aparecen en Security → Code scanning con links directos al código.

Opciones del CLI

| Opción | Default | Descripción | |--------|---------|-------------| | --path <dir> | . | Carpeta a auditar | | --diff <branch> | — | Solo archivos cambiados vs esta rama | | --strict-diff | off | Solo enviar líneas cambiadas como contexto (requiere --diff) | | --fail-on <levels> | critical,high | Severidades que fallan el build | | --format <fmt> | table | table | json | sarif | junit | | --output <file> | stdout | Escribir resultado a archivo | | --model <model> | claude-sonnet-4-6 | Modelo Claude a usar | | --max-files <n> | ilimitado | Cap de archivos a auditar | | --exclude <globs> | — | Globs/paths a ignorar separados por coma (docs,*.test.js) | | --rules <file> | — | Markdown con reglas custom adicionales | | --fix | off | Aplicar auto-fix sugerido por Claude (escribe cambios al archivo) | | --no-cache | off | Desactivar cache incremental |

Lenguajes: .js .ts .jsx .tsx .py .java .go .php .rb .cs .cpp .c

Caché incremental y prompt caching

• Caché de archivo: .bit-audit-cache.json en el directorio de ejecución. Hash SHA-256 por archivo — si no cambió, reusa hallazgos previos. Agrégalo al .gitignore.
• Prompt caching: el bloque estático (BIT-STANDARDS + 7 agentes + task) se marca con cache_control: ephemeral. Ahorro ~78% en input tokens entre batches del mismo run (TTL 5 min).
• Batching: el CLI agrupa archivos en lotes de hasta 50 KB para minimizar llamadas a la API.

Agentes de seguridad

| Agente | Detecta | |--------|---------| | AGENT-SECRETS | Credenciales hardcodeadas, API keys, tokens en código | | AGENT-AUTH | Autenticación débil, sesiones sin expiración, MFA ausente | | AGENT-DATA | Exposición de PII, datos sin cifrar, logging de info sensible | | AGENT-INPUT | SQL injection, XSS, path traversal, falta de validación | | AGENT-DEPS | Dependencias con CVEs conocidos, versiones desactualizadas | | AGENT-INCIDENTS | Controles de seguridad deshabilitados, backdoors | | AGENT-AGENTIC | Vulnerabilidades específicas de sistemas AI/LLM (T1–T15) |

Cada hallazgo se enriquece automáticamente con su categoría OWASP y CWE desde la base de conocimiento BIT Security Standards.

Formato del reporte

### AUDIT RESULT: PASSED / FAILED

#### AGENT-SECRETS
| # | File | Line | Regla | OWASP | CWE | Severidad | Fix |
|---|------|------|-------|-------|-----|-----------|-----|
| 1 | src/auth.js | 12 | Hardcoded JWT secret | A2 | CWE-798 | Critical | Usar variable de entorno |

### BIT Master Control Checklist
- [✓] A1: Injection — sin vulnerabilidades encontradas
- [✗] A2: Broken Auth — sesión sin timeout, secret hardcodeado
- [N/A] T1: Prompt injection — no aplica (sin componentes AI)