Shield IA: Asistente de Auditoría de Seguridad para Repositorios de GitHub

Shield IA es un asistente automatizado de auditoría de seguridad diseñado para inspeccionar repositorios públicos de GitHub. Detecta vulnerabilidades estáticas (credenciales filtradas, dependencias vulnerables o desactualizadas, malas prácticas en Dockerfiles y permisos excesivos en GitHub Actions), calcula un puntaje de seguridad de 0 a 100 y utiliza la API de Cohere (command-r7b-12-2024) para explicar los riesgos y proporcionar recomendaciones paso a paso para mitigarlos.

---

Características Clave

• Sin Clonación ni Ejecución de Código: Interactúa únicamente mediante la API REST de GitHub. El código fuente nunca se descarga por completo ni se ejecuta en local, eliminando riesgos de ejecución de código remoto (RCE).
• Auditorías MCP Deterministas: Implementa herramientas de análisis estático desacopladas bajo el estándar de Model Context Protocol (MCP).
• Orquestación de Flujo: Utiliza LangGraph para controlar el proceso secuencial (validación → descarga selectiva de archivos → ejecución de análisis estático → generación del reporte con IA).
• Enmascaramiento de Secretos: Escanea y enmascara automáticamente valores de credenciales (AWS, Google, Slack, claves privadas) antes de registrarlos o enviarlos al modelo de lenguaje.
• Integración con n8n: Incluye endpoints HTTP dedicados para integrarse con flujos automatizados de n8n (alertas de riesgos, reportes periódicos y auditorías programadas).
• CI/CD Empresarial: Configuración de GitHub Actions para linter, análisis de tipos, ejecución de pruebas unitarias y empaquetado/publicación automático de imágenes en GitHub Container Registry (GHCR).

---

Flujo de Arquitectura

El sistema ejecuta una secuencia de pasos orquestados mediante una máquina de estados de LangGraph, consumiendo herramientas locales y delegando la síntesis final a Cohere.

graph TD
    A[Inicio: Entrada de URL] --> B[Validar URL y Prevenir SSRF]
    B --> C[Obtener Metadatos y Árbol de Archivos]
    C --> D[Seleccionar y Descargar Archivos Relevantes]
    D --> E[Ejecutar Herramientas de Análisis MCP]
    E --> F[Calcular Puntaje de Seguridad]
    F --> G[Sintetizar Reporte mediante Cohere]
    G --> H[Almacenar AuditResponse y Finalizar]

---

Tecnologías Utilizadas

• Lenguaje: Python 3.12
• Framework: FastAPI (REST Web API)
• Orquestador y Modelo: LangGraph y Cohere SDK (command-r7b-12-2024)
• Protocolo de Contexto: MCP (Model Context Protocol) vía FastMCP
• Modelos de Datos: Pydantic v2 y Pydantic Settings
• Suite de Pruebas: Pytest y Pytest-Cov
• Orquestador de Tareas: n8n
• Contenedores: Docker y Docker Compose

---

Configuración y Despliegue

Requisitos Previos

• Python 3.12 o superior
• Poetry (o pip y virtualenv)
• Una clave de API de Cohere

Instalación Local

1. Clona el repositorio:

   git clone https://github.com/<tu-usuario>/shield-ia.git
   cd shield-ia
   

2. Copia la plantilla de variables de entorno y configúrala:

   cp .env.example .env
   

   Edita el archivo .env agregando tu COHERE_API_KEY (y opcionalmente tu GITHUB_TOKEN para evitar límites de tasa de la API de GitHub).

3. Instala las dependencias del proyecto utilizando Poetry:

   poetry install
   

4. Inicia el servidor de desarrollo de FastAPI:

   poetry run uvicorn app.main:app --reload
   

   La API estará disponible en http://localhost:8000. Puedes inspeccionar y probar los endpoints desde la interfaz de Swagger en http://localhost:8000/docs.

Ejecución con Docker

Puedes construir e iniciar el servicio completo con Docker Compose:

docker-compose up --build

---

Endpoints de la API

1. Estado del Servicio

• Endpoint: GET /health
• Respuesta:

  {
    "status": "ok",
    "environment": "development",
    "service": "Shield IA Auditor API"
  }
  

2. Solicitar Auditoría

• Endpoint: POST /audits
• Cuerpo de la Petición:

  {
    "github_url": "https://github.com/owner/repository"
  }
  

3. Obtener Resultados de Auditoría

• Endpoint: GET /audits/{audit_id}

4. Webhook para n8n

• Endpoint: POST /webhooks/n8n/audit
• Cabecera Requerida: X-Webhook-Token: <tu-secreto-webhook-configurado>
• Cuerpo de la Petición:

  {
    "github_url": "https://github.com/owner/repository"
  }
  

---

Servidor MCP

Shield IA puede ejecutarse como un servidor de Model Context Protocol (MCP) independiente, exponiendo sus herramientas estáticas:

poetry run python app/mcp_server/server.py

Esto permite que otros clientes compatibles con MCP (como Claude Desktop, Cursor o cualquier otro agente) utilicen los escáneres estáticos de Shield IA de forma nativa.

---

Salvaguardas de Seguridad

1. SSRF: Restringe las llamadas HTTP salientes a dominios validados (github.com).
2. Path Traversal: Valida que las rutas de los archivos no contengan null bytes ni secuencias relativas (../) que puedan leer archivos fuera del árbol del repositorio.
3. Sin Ejecución de Código: No ejecuta ningún comando ni script del repositorio auditado.
4. Enmascaramiento: Protege la privacidad bloqueando la filtración de secretos en bases de datos o en llamadas a la API de Cohere.

---

Descargo de Responsabilidad

Shield IA es una herramienta automatizada de análisis estático con fines educativos y de portafolio. No sustituye una revisión manual de código profesional, pruebas de penetración ni auditorías formales de seguridad.