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

Descripción general

El AlienSec MCP Server es un servidor Model Context Protocol (MCP) 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 los agentes y aplicaciones de IA realizar escaneos de seguridad en varios tipos de endpoints (PKG de macOS, PowerShell de Windows, APT de Debian, RPM de Redhat) y recuperar inteligencia de amenazas de las API de AlienVault OTX y VirusTotal.

Related MCP server: Nullcone MCP Server

Características

Capacidades principales

• Escaneo de endpoints multiplataforma

  • Escanear sistemas macOS mediante el instalador PKG

  • Escanear endpoints de Windows mediante PowerShell

  • Escanear sistemas Debian/Ubuntu mediante APT

  • Escanear sistemas Redhat/CentOS mediante RPM

• Integración con VirusTotal

  • Escanear archivos y URL mediante la API de VirusTotal

  • Recuperar resultados de análisis existentes

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

  • Soporte de múltiples claves de 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 de API necesarias

1. Clave de API de AlienVault OTX (obligatoria)

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

   • Vaya a Settings > API Keys

   • Genere una nueva clave de API

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

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

   • Vaya a API Console

   • Genere claves de 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 las variables de entorno

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

cp .env.example .env

Edite .env con sus claves de 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 el uso de múltiples claves de API para eludir los límites de velocidad. Esta implementación respeta dichos límites y utiliza múltiples claves únicamente para redundancia.

4. (Opcional) Instalar dependencias de cifrado de 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 flavor 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)"

PowerShell de Windows

[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 de AlienVault, cliente de VirusTotal

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

3. Patrón Interruptor de Circuito: rotación automática de claves de API ante fallos

4. Limitador de velocidad de cubeta de fichas: 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 flavors de escaneo con interfaz común

Esquema de la base de datos

El servidor utiliza 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 de 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 las herramientas devuelven la forma estándar de resultado MCP con isError: true. El mensaje legible para humanos es el primer bloque de contenido; error contiene 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 utiliza 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 confidenciales (claves de API).

Limitación de velocidad e interruptor de circuito

Limitación de velocidad de VirusTotal

• Algoritmo de cubeta de fichas: limitación de velocidad suave

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

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

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

Configuración del interruptor de circuito

• Umbral de fallos: 5 fallos consecutivos

• Tiempo de espera de reinicio: 300 segundos (5 minutos)

• Estado semia bierto: prueba con 1 solicitud antes de reabrir por completo

Cumplimiento de los Términos de Servicio

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

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

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

• El interruptor de circuito evita reintentos rápidos ante 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: Utilice DATABASE_ENCRYPTION_KEY para cifrar datos sensibles en reposo

2. Seguridad de Claves de API: Las claves de API nunca se registran; utilice 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 de registro del interruptor de circuito y 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 abrumar a 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 Perezosa: Los repositorios se crean bajo demanda

• Consultas Indexadas: Las tablas de la base de datos tienen índices apropiados

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

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

Puntos de Referencia

• Solicitud de Escaneo: ~100-500ms (simulado)

• Solicitud a VirusTotal: ~200-1000ms (dependiente de la red)

• Operaciones de Base de Datos: <10ms (SQLite local)

Solución de Problemas

Problemas Comunes

Fallo de Conexión a la Base de Datos

Error: Failed to connect to database

Solución: Asegúrese de que el directorio de datos exista y tenga 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 Excedido

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 de API (separadas por comas en VIRUSTOTAL_API_KEYS)

• Utilice 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

1. Haga un fork del repositorio

2. Cree una rama de características (git checkout -b feature/amazing-feature)

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

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

5. Abra una Solicitud de Extracción

Directrices para Mensajes de Confirmación

• Utilice 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á licenciado 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