🔐 Secure-Scan: Herramienta SAST Profesional

Secure-Scan es una herramienta profesional de Análisis Estático de Seguridad de Aplicaciones (SAST) diseñada para detectar vulnerabilidades y código malicioso en repositorios de código sin ejecutarlos.

🎯 Características Principales

🔍 Análisis de Código Fuente

• ✅ Análisis Estático Puro - Sin ejecución, compilación ni interpretación de código
• 🔍 Detección de Vulnerabilidades - SQL Injection, XSS, CSRF, Command Injection, Path Traversal, etc.
• 🦠 Detección de Malware - Backdoors, keyloggers, cryptominers, web shells, payloads ocultos
• 🌐 Multi-lenguaje - JavaScript, Python, PHP, Java, C/C++, C#, IaC (Docker, Terraform, Kubernetes)

📦 Análisis de Composición de Software (SCA)

• 📋 Análisis de Manifiestos - package.json, requirements.txt, composer.json, pom.xml, etc.
• 🔓 Detección de CVEs - Vulnerabilidades conocidas en dependencias
• ⚠️ Typosquatting - Detecta paquetes maliciosos con nombres similares
• 🔐 Análisis de Lock Files - package-lock.json, yarn.lock, composer.lock, Pipfile.lock

🔬 Escaneo de Dependencias Instaladas (NUEVO)

• 📂 Escaneo de node_modules - Análisis profundo de paquetes npm/yarn instalados
• 🐍 Escaneo de venv/site-packages - Paquetes Python instalados
• 🐘 Escaneo de vendor - Dependencias PHP Composer
• 🦠 Detección de Malware en Dependencias:
  • 🚪 Backdoors (reverse shells, conexiones C2, robo de SSH keys)
  • ⛏️ Cryptominers (minería de criptomonedas oculta)
  • 🔓 Data Stealers (robo de credenciales, variables de entorno, tokens)
  • 📥 Malicious Loaders (descarga de payloads remotos)
  • 🔐 Código Ofuscado (base64 eval, hex encoding, anti-análisis)
  • 📤 Exfiltración de Datos (DNS tunneling, HTTP POST de datos)
  • 🛡️ Técnicas Anti-Análisis (detección de debuggers, sandbox evasion)
• ✅ Verificación de Integridad - Compara versiones instaladas vs lock files
• ⚡ Análisis de Post-Install Scripts - Detecta scripts maliciosos en hooks

📊 Reportes y Estándares

• 📊 Reportes HTML Profesionales - Estilo auditoría de seguridad
• 🤖 IA Integrada - Análisis inteligente con modelos locales o en la nube
• 📋 Mapeo a Estándares - OWASP Top 10, CWE, MITRE ATT&CK, SANS Top 25
• 🌍 Multiidioma - Reportes en español (por defecto) o inglés
• 📈 Puntuación de Riesgo - Score 0-100 basado en severidad y cantidad de hallazgos

🏗️ Arquitectura

secure-scan/
├── src/
│   ├── cli/                    # Interfaz de línea de comandos
│   ├── core/                   # Núcleo del sistema
│   │   ├── scanner/            # Escáner de archivos
│   │   ├── engine/             # Motor de reglas
│   │   └── scoring/            # Motor de puntuación de riesgo
│   ├── analyzers/              # Analizadores por lenguaje (plugins)
│   │   ├── javascript/
│   │   ├── python/
│   │   ├── php/
│   │   ├── java/
│   │   ├── c-cpp/
│   │   ├── csharp/
│   │   └── iac/                # Infraestructura como Código
│   ├── dependencies/           # Análisis de Dependencias (SCA)
│   │   ├── parsers/            # Parsers por ecosistema (npm, pip, composer, etc.)
│   │   ├── detectors/          # Detectores de vulnerabilidades
│   │   ├── database/           # Base de datos CVE y paquetes maliciosos
│   │   └── installed/          # Escáner de dependencias instaladas (malware)
│   ├── rules/                  # Reglas de detección
│   │   ├── vulnerabilities/
│   │   └── malware/
│   ├── ai/                     # Motor de IA
│   ├── reports/                # Generador de reportes
│   ├── i18n/                   # Traducciones (español/inglés)
│   ├── types/                  # Definiciones TypeScript
│   └── utils/                  # Utilidades
├── test-samples/               # Archivos de prueba
└── docs/                       # Documentación

🚀 Instalación

Opción 1: Instalación Global (Recomendada)

# Clonar el repositorio
git clone https://github.com/your-org/secure-scan.git
cd secure-scan

# Instalar dependencias y compilar
npm install

# Instalar globalmente
npm link

# Verificar instalación
secure-scan --version

Instalación de IA Local con Ollama (Opcional pero Recomendado)

La IA local permite análisis avanzado sin costos y con privacidad total. Sigue estos pasos:

Paso 1: Instalar Ollama

Windows:

# Usando winget (recomendado)
winget install Ollama.Ollama

# O descarga el instalador desde https://ollama.ai

Linux:

curl -fsSL https://ollama.ai/install.sh | sh

macOS:

brew install ollama

Paso 2: Descargar un modelo de IA

# CodeLlama 7B Instruct - Recomendado para análisis de código
ollama pull codellama:7b-instruct

# Alternativas según tu hardware:
# - PC con 8GB+ RAM: codellama:7b-instruct (3.8 GB)
# - PC con 16GB+ RAM: codellama:13b-instruct (7.4 GB)
# - PC con poca RAM: llama3.2:3b (2 GB)

Paso 3: Verificar que Ollama esté funcionando

# Ollama se inicia automáticamente como servicio en Windows
# Para verificar que funciona:
ollama list

# Si no está corriendo, iniciarlo manualmente:
ollama serve

Paso 4: Ejecutar escaneo con IA local

# Escaneo básico con IA local
secure-scan scan ./mi-proyecto --ai --ai-provider local

# Con reporte de salida
secure-scan scan ./mi-proyecto --ai --ai-provider local -o ./reporte-seguridad

💡 Nota: La primera ejecución puede tardar más mientras el modelo se carga en memoria. Las siguientes serán más rápidas.

Opción 2: Usar con npx

# Ejecutar directamente sin instalar
npx secure-scan scan ./mi-proyecto

Opción 3: Instalación desde npm (próximamente)

npm install -g secure-scan

📖 Uso

VISO MODIFICAR EL ARCHIVO secure-scan.config.json PARA CONFIGURAR LA HERRAMIENTA SEGÚN TUS NECESIDADES.

Escaneo Básico

# Escanear un proyecto
secure-scan scan ./mi-proyecto

# O usando la ruta completa
secure-scan scan "C:\Users\TuUsuario\Proyectos\mi-proyecto"

Opciones Disponibles

# Escanear con reporte HTML personalizado
secure-scan scan ./proyecto -o ./mi-reporte

# Modo verbose (más detalles)
secure-scan scan ./proyecto -v

# Usar análisis de IA (requiere API key)
secure-scan scan ./proyecto --ai --api-key TU_API_KEY

# Especificar lenguajes
secure-scan scan ./proyecto --languages javascript,python

# Reporte en inglés
secure-scan scan ./proyecto --lang en

# Reporte en español (por defecto)
secure-scan scan ./proyecto --lang es

Combinación de Opciones

Puedes combinar múltiples opciones en un solo comando:

# Escaneo completo con IA, verbose y reporte personalizado
secure-scan scan ./proyecto -v --ai --api-key "TU_API_KEY" -o "./reporte-seguridad"

# Escaneo con IA local (Ollama), lenguajes específicos y reporte en inglés
secure-scan scan ./proyecto --ai --ai-provider local -o "./security-report" --lang en --languages javascript,python

# Escaneo rápido solo críticos con salida JSON
secure-scan scan ./proyecto --min-severity critical --json

# Escaneo completo excluyendo carpetas
secure-scan scan ./proyecto -v --exclude "tests,docs,examples" -o "./audit-report"

Referencia de Opciones

Proveedores de IA Soportados

La herramienta auto-detecta el proveedor basándose en el formato de tu API key:

# OpenAI (auto-detectado)
secure-scan scan ./proyecto --ai --api-key "sk-proj-abc123..."

# Google Gemini (auto-detectado)
secure-scan scan ./proyecto --ai --api-key "AIzaSyAbc123..."

# Anthropic Claude (auto-detectado)
secure-scan scan ./proyecto --ai --api-key "sk-ant-abc123..."

# Especificar modelo manualmente
secure-scan scan ./proyecto --ai --api-key "sk-..." --ai-model gpt-4o

# IA Local con Ollama (sin API key)
secure-scan scan ./proyecto --ai --ai-provider local

Comandos Adicionales

# Ver ayuda
secure-scan --help

# Ver versión
secure-scan --version

# Inicializar configuración
secure-scan init

# Listar reglas disponibles
secure-scan rules

# Filtrar reglas por lenguaje
secure-scan rules -l python

🦠 Detección de Malware en Dependencias

Secure-Scan escanea las dependencias instaladas en busca de código malicioso. Actualmente detecta 17 patrones de malware:

Categorías de Malware Detectado

Directorios Escaneados

📂 node_modules/      → Paquetes npm/yarn
📂 vendor/            → Dependencias PHP Composer  
📂 venv/              → Entornos virtuales Python
📂 site-packages/     → Paquetes Python globales
📂 .venv/             → Entornos virtuales alternativos

Verificación de Integridad

El escáner también verifica que las versiones instaladas coincidan con las declaradas en los lock files:

• ✅ package-lock.json vs node_modules/*/package.json
• ✅ yarn.lock vs node_modules/*/package.json
• ✅ composer.lock vs vendor/*/composer.json
• ✅ Pipfile.lock vs venv/lib/python*/site-packages/

🌍 Idiomas

Secure-Scan soporta reportes en múltiples idiomas:

# Reporte en español (por defecto)
secure-scan scan ./proyecto -o reporte

# Reporte en inglés
secure-scan scan ./proyecto -o report --lang en

📊 Niveles de Severidad

🛡️ Estándares de Seguridad

Todos los hallazgos se mapean a estándares reconocidos:

Ejemplos de Mapeo

🔧 Configuración

Crea un archivo secure-scan.config.json en la raíz del proyecto:

{
  "exclude": ["node_modules", "dist", "vendor"],
  "languages": ["javascript", "python", "php"],
  "minSeverity": "low",
  "language": "es",
  "ai": {
    "enabled": false,
    "provider": "openai",
    "model": "gpt-4"
  },
  "rules": {
    "disabled": [],
    "custom": []
  }
}

Opciones de Configuración

🤖 Uso de Modelos de IA Locales

Secure-Scan soporta el uso de modelos de IA locales para análisis de seguridad sin depender de APIs externas.

Requisitos de Hardware

Configuración para IA Local

Modifica la sección ai en secure-scan.config.json:

{
  "ai": {
    "enabled": true,
    "provider": "local",
    "model": "codellama:7b-instruct",
    "endpoint": "http://localhost:11434/api/generate",
    "enhanceFindings": true,
    "generateSummary": true,
    "maxTokens": 4096,
    "temperature": 0.1
  }
}

Herramientas de IA Local Compatibles

Ejemplo con Ollama (Recomendado)

1. Instalar Ollama: Descarga desde ollama.ai

2. Descargar un modelo optimizado para código:

   # CodeLlama - especializado en código
   ollama pull codellama
   
   # DeepSeek Coder - excelente para análisis de seguridad
   ollama pull deepseek-coder
   
   # Mistral - buen balance rendimiento/calidad
   ollama pull mistral

3. Ollama se ejecuta automáticamente en http://localhost:11434

4. Ejecutar escaneo con IA local:

   secure-scan scan ./mi-proyecto --ai

Ejemplo con LM Studio

1. Descarga LM Studio
2. Descarga un modelo GGUF (ej: codellama-7b-instruct.Q4_K_M.gguf)
3. Inicia el servidor local en LM Studio
4. Configura el endpoint:

   {
     "ai": {
       "enabled": true,
       "provider": "local",
       "endpoint": "http://localhost:1234/v1/completions"
     }
   }

Ventajas de IA Local

• 🔒 Privacidad total - Tu código nunca sale de tu máquina
• 💰 Sin costos - No requiere suscripciones ni API keys
• ⚡ Sin límites - Analiza todo el código que necesites
• 🌐 Offline - Funciona sin conexión a internet

📈 Hoja de Ruta

• Fase 1: Análisis estático básico (JavaScript, Python, PHP, Java, C/C++, C#)
• Fase 2: Integración de IA (OpenAI, Anthropic, modelos locales con Ollama)
• Fase 3: Soporte multiidioma (reportes en español/inglés)
• Fase 4: Análisis de dependencias (SCA)
  • Parsers para 6 ecosistemas (npm, pip, composer, maven, nuget, go)
  • Detección de CVEs y vulnerabilidades conocidas
  • Detección de typosquatting
  • Escaneo de dependencias instaladas con detección de malware
  • 17 patrones de malware (backdoors, cryptominers, stealers, etc.)
  • Verificación de integridad (lock files vs instalados)
• Fase 5: Integración CI/CD (GitHub Actions, GitLab CI, Azure DevOps)
• Fase 6: Análisis dinámico (DAST)
• Fase 7: Dashboard web en tiempo real

⚠️ Advertencias de Seguridad

• Esta herramienta NUNCA ejecuta código del proyecto analizado
• Diseñada exclusivamente para auditoría defensiva
• No genera ni contiene malware funcional
• Uso responsable y ético únicamente

💻 Ejemplo de Salida

🔐 Secure-Scan v2.0.0

📂 Escaneando: ./mi-proyecto
🔍 Archivos analizados: 156
📏 Líneas de código: 24,853
⏱️  Tiempo: 2.34s

📊 Resultados del Escaneo:
┌──────────────────────────────────────────────────────────────┐
│  🔴 Crítico: 5    │  🟠 Alto: 12    │  🟡 Medio: 23         │
│  🟢 Bajo: 8       │  🔵 Info: 3     │  Total: 51            │
└──────────────────────────────────────────────────────────────┘

📦 Dependencias Analizadas:
┌──────────────────────────────────────────────────────────────┐
│  📋 Manifiestos: 3      │  📦 Paquetes: 847               │
│  🔓 CVEs: 12            │  🦠 Malware: 0                   │
│  ⚠️  Typosquatting: 1   │  ✅ Integridad: OK              │
└──────────────────────────────────────────────────────────────┘

📈 Puntuación de Riesgo: 72/100 (Alto)

📄 Reporte generado: ./security-report.html

📄 Licencia

MIT License - Ver LICENSE

🤝 Contribuir

1. Fork el repositorio
2. Crea una rama (git checkout -b feature/nueva-funcionalidad)
3. Commit tus cambios (git commit -m 'Añadir nueva funcionalidad')
4. Push a la rama (git push origin feature/nueva-funcionalidad)
5. Abre un Pull Request

📞 Soporte

• 📧 Email: soporte@secure-scan.dev
• 🐛 Issues: GitHub Issues
• 📖 Documentación: docs/

Desarrollado con ❤️ para la comunidad de seguridad

Autor: Luis000923