AlienSec MCP Server

Servidor MCP de escaneo de seguridad de endpoints AlienVault OTX listo para producción con integración con VirusTotal

// creado para la comunidad de seguridad — la financiación lo mantiene activo

Resumen

El AlienSec MCP Server es un servidor MCP (Model Context Protocol) de grado de producción que proporciona capacidades integrales de escaneo de seguridad de endpoints mediante AlienVault OTX con integración opcional con VirusTotal.

Este servidor permite a agentes y aplicaciones de IA realizar escaneos de seguridad en varios tipos de endpoints (macOS PKG, Windows PowerShell, Debian APT, Redhat RPM) y recuperar inteligencia de amenazas de las APIs de AlienVault OTX y VirusTotal.

Related MCP server: Velociraptor MCP Server

Características

Capacidades principales

• Escaneo de endpoints multiplataforma

  • Escanear sistemas macOS usando el instalador PKG

  • Escanear endpoints de Windows mediante PowerShell

  • Escanear sistemas Debian/Ubuntu usando APT

  • Escanear sistemas Redhat/CentOS usando RPM

• Integración con VirusTotal

  • Escanear archivos y URLs usando la API de VirusTotal

  • Recuperar resultados de análisis existentes

  • Limitación de velocidad automática y protección con interruptor de circuito

  • Soporte para múltiples claves API (respeta los Términos de Servicio de VirusTotal)

• Inteligencia de amenazas

  • Buscar pulsos de AlienVault OTX

  • Recuperar detalles y eventos de pulsos

  • Acceder a indicadores de compromiso (IoCs)

• Persistencia de datos

  • Base de datos SQLite con cifrado opcional

  • Almacenamiento de resultados de escaneo con marcas de tiempo

  • Registro de solicitudes de API

  • Seguimiento de eventos del interruptor de circuito

• Características listas para producción

  • Manejo integral de errores

  • Registro estructurado con Pino

  • Validación de variables de entorno con Zod

  • Esquemas de API con seguridad de tipos

  • Manejo de apagado elegante

Requisitos previos

Requisitos del sistema

• Node.js: >= 22.0.0

• npm: >= 8.0.0

• Sistema operativo: macOS, Linux o Windows

• Espacio en disco: Mínimo 100MB para dependencias

Claves API requeridas

1. Clave API de AlienVault OTX (Requerida)

   • Regístrese en https://otx.alienvault.com

   • Vaya a Configuración > Claves API

   • Genere una nueva clave API

2. Clave API de VirusTotal (Opcional, para funcionalidad mejorada)

   • Regístrese en https://www.virustotal.com

   • Vaya a Consola de API

   • Genere clave(s) API

   • Nota: El plan gratuito permite 500 solicitudes/día, 4 solicitudes/minuto

Instalación

1. Clonar el repositorio

git clone https://github.com/VRIL-LABS/aliensec-mcp-server.git
cd aliensec-mcp-server

2. Instalar dependencias

npm install

Esto instalará todas las dependencias de producción y desarrollo.

3. Configurar variables de entorno

Copie el archivo de entorno de ejemplo y actualícelo con sus claves API:

cp .env.example .env

Edite .env con sus claves API:

# Server Configuration
NAME=aliensec-mcp-server
VERSION=1.0.0
DEBUG=false
LOG_LEVEL=info

# AlienVault OTX Configuration (Required)
ALIENVAULT_API_KEY=your_alienvault_api_key_here
ALIENVAULT_BASE_URL=https://api.agent.otxb.io
ALIENVAULT_DEFAULT_REGION=us-east-1

# VirusTotal Configuration (Optional)
VIRUSTOTAL_API_KEYS=key1,key2,key3
VIRUSTOTAL_BASE_URL=https://www.virustotal.com/api/v3
VIRUSTOTAL_RATE_LIMIT_PER_MINUTE=4
VIRUSTOTAL_DAILY_LIMIT=500
VIRUSTOTAL_CIRCUIT_BREAKER_TIMEOUT=300

# Database Configuration
DATABASE_PATH=./data/aliensec.db
DATABASE_ENCRYPTION_KEY=your_encryption_key_here
DATABASE_TIMEOUT=5000

Nota: Los Términos de Servicio de VirusTotal prohíben usar múltiples claves API para eludir los límites de velocidad. Esta implementación respeta esos límites y usa múltiples claves solo para redundancia.

4. (Opcional) Instalar dependencias de cifrado SQLite

Para soporte de base de datos cifrada en Linux/macOS:

# Ubuntu/Debian
sudo apt-get install build-essential

# macOS
xcode-select --install

Uso

Modo de desarrollo

Ejecute el servidor en modo de desarrollo con recarga automática:

npm run dev

Modo de producción

Compile y ejecute el servidor:

npm run build
npm start

Uso con clientes MCP

El servidor se comunica mediante stdio (entrada/salida estándar). Para usarlo con un cliente MCP:

# Direct execution
node dist/index.js

# Or using the npm script
npm start

Ejemplo de integración con cliente MCP

import { Client } from '@modelcontextprotocol/client';
import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';

const client = new Client({ name: 'my-client', version: '1.0.0' });
const transport = new StdioClientTransport({
  command: 'node',
  args: ['dist/index.js'],
});

await client.connect(transport);

// Call a scan tool
const result = await client.callTool({
  name: 'scan_macos_pkg',
  arguments: {
    target: '192.168.1.100',
    useVirusTotal: true,
  },
});

console.log(result.content);

Herramientas disponibles

Herramientas de escaneo (5)

Herramientas de VirusTotal (2)

Herramientas de AlienVault OTX (3)

Herramientas de base de datos (4)

Herramientas del sistema (1)

Comandos de arranque

El servidor proporciona comandos de arranque preconfigurados para cada tipo de endpoint. <api-key> a continuación es el valor resuelto de su ALIENVAULT_API_KEY, y TARGET=<target> solo se incluye cuando se proporciona un target.

Instalador PKG de macOS

API_KEY=<api-key> [TARGET=<target>] bash -c "$(curl -s https://api.agent.otxb.io/osquery-api-otx/bootstrap?flavor=pkg)"

Windows PowerShell

[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12; API_KEY=<api-key> (new-object Net.WebClient).DownloadString("https://api.agent.otxb.io/osquery-api-otx/bootstrap?flavor=powershell") | iex; install_agent -apikey <api-key> [-target <target>]

Debian APT

API_KEY=<api-key> [TARGET=<target>] bash -c "$(curl -s https://api.agent.otxb.io/osquery-api-otx/bootstrap?flavor=apt)"

Redhat RPM

API_KEY=<api-key> [TARGET=<target>] bash -c "$(curl -s https://api.agent.otxb.io/osquery-api-otx/bootstrap?flavor=rpm)"

Estructura del proyecto

aliensec-mcp-server/
├── src/
│   ├── config/
│   │   └── index.ts           # Environment configuration & validation
│   ├── core/
│   │   ├── alienVault.ts      # AlienVault OTX API client
│   │   └── virusTotal.ts      # VirusTotal API client
│   ├── database/
│   │   └── index.ts           # SQLite database with repositories
│   ├── types/
│   │   └── index.ts           # TypeScript type definitions
│   └── index.ts               # Main MCP server entry point
├── package.json
├── tsconfig.json
├── .env.example
├── .gitignore
├── eslint.config.js
├── .prettierrc
└── README.md

Arquitectura

Diseño en capas

┌─────────────────────────────────────┐
│           MCP Server Layer           │  ← src/index.ts
├─────────────────────────────────────┤
│         Core Service Layer           │  ← src/core/
├─────────────────────────────────────┤
│         Data Access Layer            │  ← src/database/
├─────────────────────────────────────┤
│        Configuration Layer           │  ← src/config/
├─────────────────────────────────────┤
│           Type Definitions           │  ← src/types/
└─────────────────────────────────────┘

Patrones de diseño clave

1. Patrón Singleton: Base de datos, cliente AlienVault, cliente VirusTotal

2. Patrón Repositorio: ScanRepository, CircuitBreakerRepository, APILogRepository

3. Patrón Interruptor de Circuito: Rotación automática de claves API en fallos

4. Limitador de velocidad con cubeta de tokens: Limitación de velocidad para la API de VirusTotal

5. Patrón Fábrica: Creación del servidor MCP con inyección de dependencias

6. Patrón Estrategia: Diferentes sabores de escaneo con interfaz común

Esquema de base de datos

El servidor usa SQLite con las siguientes tablas:

scan_records

Almacena todos los resultados de escaneo con hallazgos, datos de VirusTotal y marcas de tiempo.

circuit_breaker_events

Realiza un seguimiento de los cambios de estado del interruptor de circuito para las claves API.

api_logs

Registra todas las solicitudes de API con tiempos de respuesta, códigos de estado y errores.

schema_version

Realiza un seguimiento de la versión del esquema de la base de datos para migraciones.

Manejo de errores

Clases de error personalizadas

• AlienSecError: Clase de error base con código y statusCode

• AlienVaultAPIError: Errores específicos de AlienVault

• VirusTotalAPIError: Errores específicos de VirusTotal con detección de límite de velocidad

• DatabaseError: Errores relacionados con la base de datos

• ConfigurationError: Errores de validación de configuración

Formato de respuesta de error

Los errores de herramientas devuelven la forma estándar de resultado MCP con isError: true. El mensaje legible para humanos es el primer bloque de contenido; error lleva los datos de contexto serializados en JSON (ID de escaneo, flavor, target, etc.) que provocaron el fallo:

{
  "content": [
    { "type": "text", "text": "Scan failed: <error message>" }
  ],
  "isError": true,
  "error": "{\n  \"scanId\": \"...\",\n  \"flavor\": \"pkg\",\n  \"target\": \"...\",\n  \"error\": \"<error message>\"\n}"
}

Registro

El servidor usa Pino para el registro estructurado con los siguientes niveles:

• error: Fallos críticos

• warn: Advertencias y problemas potenciales

• info: Operaciones normales y actualizaciones de estado

• debug: Información de depuración detallada

• trace: Registro muy detallado para desarrollo

Los registros se redactan automáticamente para evitar que se registren datos sensibles (claves API).

Limitación de velocidad e interruptor de circuito

Limitación de velocidad de VirusTotal

• Algoritmo de cubeta de tokens: Limitación de velocidad suave

• Límites configurables: Se establecen mediante variables de entorno

• Espera automática: Opción para esperar cuando se alcanza el límite de velocidad

• Interruptor de circuito: Bloquea automáticamente las claves API que fallan repetidamente

Configuración del interruptor de circuito

• Umbral de fallos: 5 fallos consecutivos

• Tiempo de reinicio: 300 segundos (5 minutos)

• Estado semiabierto: Prueba con 1 solicitud antes de reabrir completamente

Cumplimiento de los Términos de Servicio

La implementación respeta los Términos de Servicio de VirusTotal:

• Las múltiples claves API son para redundancia, no para eludir límites

• Cada clave API respeta los límites de velocidad individuales

• El interruptor de circuito evita reintentos rápidos en fallos

• El conteo diario de solicitudes evita el agotamiento de la cuota

Desarrollo

Ejecutar pruebas

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npx vitest run --coverage

Linting y formato

# Run linting
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format code
npm run format

Verificación de tipos

npm run typecheck

Verificación de compilación

# Clean build
npm run clean
npm run build

# Check build output
ls -la dist/

Variables de entorno

Consideraciones de Seguridad

Protección de Datos

1. Cifrado de base de datos: use DATABASE_ENCRYPTION_KEY para cifrar datos sensibles en reposo

2. Seguridad de claves API: las claves API nunca se registran; use variables de entorno o bóvedas seguras

3. Seguridad de memoria: las cadenas sensibles se cifran con PBKDF2 (120.000 iteraciones) antes de almacenarse en las tablas del interruptor de circuito y de registro de la API

Seguridad de Red

1. Solo HTTPS: toda la comunicación con la API utiliza HTTPS

2. Validación de certificados: la validación de certificados TLS está habilitada por defecto

3. User-Agent: un user agent personalizado identifica la versión del servidor

Límite de Peticiones

1. Límite de peticiones del lado del cliente: evita saturar las API externas

2. Interruptor de circuito: evita fallos en cascada

3. Contrapresión: espera automática cuando se alcanza el límite de peticiones

Rendimiento

Optimizaciones

• Agrupación de conexiones: las conexiones a la base de datos se reutilizan

• Carga diferida: los repositorios se crean bajo demanda

• Consultas indexadas: las tablas de la base de datos tienen índices apropiados

• Caché: los hashes de las claves API se almacenan en caché para las comprobaciones del interruptor de circuito

• Async/Await: operaciones de E/S no bloqueantes

Puntos de Referencia

• Petición de escaneo: ~100-500ms (simulada)

• Petición a VirusTotal: ~200-1000ms (depende de la red)

• Operaciones de base de datos: <10ms (SQLite local)

Solución de Problemas

Problemas Comunes

Error de Conexión a la Base de Datos

Error: Failed to connect to database

Solución: asegúrese de que el directorio de datos existe y tiene permisos de escritura:

mkdir -p data
chmod 755 data

Falta ALIENVAULT_API_KEY

Missing required environment variables:
  - ALIENVAULT_API_KEY

Solución: establezca la variable de entorno:

export ALIENVAULT_API_KEY=your_api_key_here
# or add to .env file

Límite de Peticiones de VirusTotal Superado

Error: Rate limit exceeded for API key 0

Solución:

• Espere a que se restablezca el límite de peticiones (por defecto: 4 peticiones/minuto)

• Añada más claves API (separadas por comas en VIRUSTOTAL_API_KEYS)

• Use el parámetro wait: true para esperar automáticamente

Interruptor de Circuito Abierto

Error: API key 0 is blocked by circuit breaker

Solución: espere a que expire el tiempo de espera del interruptor de circuito (por defecto: 5 minutos). El circuito se reabrirá automáticamente después del tiempo de espera.

Modo de Depuración

Habilite el registro de depuración para una solución de problemas detallada:

DEBUG=true LOG_LEVEL=debug npm run dev

Contribuciones

Solicitudes de Extracción (Pull Requests)

1. Haga un fork del repositorio

2. Cree una rama de funcionalidad (git checkout -b feature/amazing-feature)

3. Haga commit de sus cambios (git commit -m 'Add amazing feature')

4. Haga push a la rama (git push origin feature/amazing-feature)

5. Abra una Pull Request

Directrices para Mensajes de Commit

• Use el formato Conventional Commits

• Prefije con el tipo: feat:, fix:, docs:, style:, refactor:, test:, chore:

• Mantenga la línea de asunto por debajo de 72 caracteres

• Proporcione una descripción detallada en el cuerpo si es necesario

Revisión de Código

• Todas las PR requieren la aprobación de al menos un mantenedor

• El pipeline de CI/CD debe pasar (lint, typecheck, tests)

• El código debe seguir los patrones y estilos existentes

Licencia

Este proyecto está bajo la Licencia MIT - consulte el archivo LICENSE para más detalles.

Agradecimientos

• Model Context Protocol: https://modelcontextprotocol.io

• AlienVault OTX: https://otx.alienvault.com

• VirusTotal: https://www.virustotal.com

• TypeScript: https://www.typescriptlang.org

• Zod: https://github.com/colinhacks/zod

• Pino: https://github.com/pinojs/pino

• better-sqlite3-multiple-ciphers: https://github.com/m4heshd/better-sqlite3-multiple-ciphers

Referencias

• Documentación de AlienVault OTX

• Documentación de la API de VirusTotal

• Especificación del Model Context Protocol

• SDK de TypeScript para MCP

Construido con ❤️ para la comunidad de seguridad