AlienSec MCP Server

Produktionsreifer AlienVault OTX Endpoint-Sicherheits-Scanning-MCP-Server mit VirusTotal-Integration

// für die Sicherheits-Community erstellt — Finanzierung hält es am Laufen

Überblick

Der AlienSec MCP Server ist ein produktionsreifer Model Context Protocol (MCP)-Server, der umfassende Endpoint-Sicherheits-Scanning-Funktionen mithilfe von AlienVault OTX mit optionaler VirusTotal-Integration bereitstellt.

Dieser Server ermöglicht es KI-Agenten und Anwendungen, Sicherheitsscans für verschiedene Endpoint-Typen (macOS PKG, Windows PowerShell, Debian APT, Redhat RPM) durchzuführen und Bedrohungsinformationen von den AlienVault OTX- und VirusTotal-APIs abzurufen.

Related MCP server: Nullcone MCP Server

Funktionen

Kernfunktionen

• Multi-Plattform-Endpoint-Scanning

  • Scan von macOS-Systemen mit PKG-Installer-Flavor

  • Scan von Windows-Endpoints über PowerShell

  • Scan von Debian/Ubuntu-Systemen mit APT

  • Scan von Redhat/CentOS-Systemen mit RPM

• VirusTotal-Integration

  • Scan von Dateien und URLs über die VirusTotal-API

  • Abruf vorhandener Analyseergebnisse

  • Automatisches Rate Limiting und Circuit-Breaker-Schutz

  • Unterstützung mehrerer API-Schlüssel (respektiert die VirusTotal-ToS)

• Bedrohungsinformationen

  • Suche in AlienVault OTX-Pulsen

  • Abruf von Pulse-Details und Ereignissen

  • Zugriff auf Indicators of Compromise (IoCs)

• Datenpersistenz

  • SQLite-Datenbank mit optionaler Verschlüsselung

  • Speicherung von Scan-Ergebnissen mit Zeitstempeln

  • Protokollierung von API-Anfragen

  • Tracking von Circuit-Breaker-Ereignissen

• Produktionsreife Funktionen

  • Umfassende Fehlerbehandlung

  • Strukturierte Protokollierung mit Pino

  • Validierung von Umgebungsvariablen mit Zod

  • Typsichere API-Schemas

  • Sauberes Herunterfahren (Graceful Shutdown)

Voraussetzungen

Systemanforderungen

• Node.js: >= 22.0.0

• npm: >= 8.0.0

• Betriebssystem: macOS, Linux oder Windows

• Speicherplatz: Mindestens 100MB für Abhängigkeiten

Erforderliche API-Schlüssel

1. AlienVault OTX API-Schlüssel (erforderlich)

   • Registrieren unter https://otx.alienvault.com

   • Navigieren Sie zu Einstellungen > API-Schlüssel

   • Generieren Sie einen neuen API-Schlüssel

2. VirusTotal API-Schlüssel (optional, für erweiterte Funktionen)

   • Registrieren unter https://www.virustotal.com

   • Navigieren Sie zur API-Konsole

   • Generieren Sie API-Schlüssel

   • Hinweis: Der kostenlose Tarif erlaubt 500 Anfragen/Tag, 4 Anfragen/Minute

Installation

1. Repository klonen

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

2. Abhängigkeiten installieren

npm install

Dadurch werden alle Produktions- und Entwicklungsabhängigkeiten installiert.

3. Umgebungsvariablen konfigurieren

Kopieren Sie die Beispiel-Umgebungsdatei und aktualisieren Sie sie mit Ihren API-Schlüsseln:

cp .env.example .env

Bearbeiten Sie .env mit Ihren API-Schlüsseln:

# 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

Hinweis: Die VirusTotal-ToS verbieten die Verwendung mehrerer API-Schlüssel zur Umgehung von Rate Limits. Diese Implementierung respektiert diese Limits und verwendet mehrere Schlüssel nur für Redundanz.

4. (Optional) SQLite-Verschlüsselungs-Abhängigkeiten installieren

Für verschlüsselte Datenbankunterstützung unter Linux/macOS:

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

# macOS
xcode-select --install

Verwendung

Entwicklungsmodus

Server im Entwicklungsmodus mit automatischem Neuladen ausführen:

npm run dev

Produktionsmodus

Server bauen und ausführen:

npm run build
npm start

Verwendung mit MCP-Clients

Der Server kommuniziert über stdio (Standard-Eingabe/Ausgabe). Zur Verwendung mit einem MCP-Client:

# Direct execution
node dist/index.js

# Or using the npm script
npm start

Beispiel für MCP-Client-Integration

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);

Verfügbare Tools

Scan-Tools (5)

VirusTotal-Tools (2)

AlienVault OTX-Tools (3)

Datenbank-Tools (4)

System-Tools (1)

Bootstrap-Befehle

Der Server stellt vorkonfigurierte Bootstrap-Befehle für jeden Endpoint-Flavor bereit. <api-key> unten ist Ihr aufgelöster ALIENVAULT_API_KEY-Wert, und TARGET=<target> wird nur eingefügt, wenn ein target angegeben ist.

macOS PKG-Installer

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)"

Projektstruktur

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

Architektur

Schichtenarchitektur

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

Wichtige Entwurfsmuster

1. Singleton-Muster: Datenbank, AlienVault-Client, VirusTotal-Client

2. Repository-Muster: ScanRepository, CircuitBreakerRepository, APILogRepository

3. Circuit-Breaker-Muster: Automatische API-Schlüssel-Rotation bei Fehlern

4. Token-Bucket-Rate-Limiter: Rate Limiting für die VirusTotal-API

5. Factory-Muster: MCP-Server-Erstellung mit Dependency Injection

6. Strategie-Muster: Verschiedene Scan-Flavors mit gemeinsamer Schnittstelle

Datenbankschema

Der Server verwendet SQLite mit den folgenden Tabellen:

scan_records

Speichert alle Scan-Ergebnisse mit Befunden, VirusTotal-Daten und Zeitstempeln.

circuit_breaker_events

Verfolgt Circuit-Breaker-Zustandsänderungen für API-Schlüssel.

api_logs

Protokolliert alle API-Anfragen mit Antwortzeiten, Statuscodes und Fehlern.

schema_version

Verfolgt die Datenbankschema-Version für Migrationen.

Fehlerbehandlung

Benutzerdefinierte Fehlerklassen

• AlienSecError: Basis-Fehlerklasse mit Code und statusCode

• AlienVaultAPIError: AlienVault-spezifische Fehler

• VirusTotalAPIError: VirusTotal-spezifische Fehler mit Rate-Limit-Erkennung

• DatabaseError: Datenbankbezogene Fehler

• ConfigurationError: Konfigurationsvalidierungsfehler

Fehlerantwortformat

Tool-Fehler geben die Standard-MCP-Ergebnisform mit isError: true zurück. Die menschenlesbare Nachricht ist der erste Inhaltsblock; error enthält die JSON-stringifizierten Kontextdaten (Scan-ID, Flavor, Ziel usw.), die den Fehler ausgelöst haben:

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

Protokollierung

Der Server verwendet Pino für strukturierte Protokollierung mit den folgenden Ebenen:

• error: Kritische Fehler

• warn: Warnungen und potenzielle Probleme

• info: Normaler Betrieb und Statusaktualisierungen

• debug: Detaillierte Debug-Informationen

• trace: Sehr ausführliche Protokollierung für die Entwicklung

Protokolle werden automatisch geschwärzt, um zu verhindern, dass sensible Daten (API-Schlüssel) protokolliert werden.

Rate Limiting & Circuit Breaker

VirusTotal-Rate-Limiting

• Token-Bucket-Algorithmus: Gleichmäßiges Rate Limiting

• Konfigurierbare Limits: Über Umgebungsvariablen festlegbar

• Automatisches Warten: Option zum Warten bei Rate-Limit

• Circuit Breaker: Blockiert automatisch API-Schlüssel, die wiederholt fehlschlagen

Circuit-Breaker-Konfiguration

• Fehlerschwelle: 5 aufeinanderfolgende Fehler

• Reset-Timeout: 300 Sekunden (5 Minuten)

• Halb-offener Zustand: Test mit 1 Anfrage vor vollständigem Wiederöffnen

ToS-Konformität

Die Implementierung respektiert die Nutzungsbedingungen von VirusTotal:

• Mehrere API-Schlüssel dienen der Redundanz, nicht der Umgehung von Limits

• Jeder API-Schlüssel respektiert individuelle Rate Limits

• Der Circuit Breaker verhindert schnelle Wiederholungsversuche bei Fehlern

• Die tägliche Anfragezählung verhindert die Erschöpfung des Kontingents

Entwicklung

Tests ausführen

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npx vitest run --coverage

Linting & Formatierung

# Run linting
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format code
npm run format

Typprüfung

npm run typecheck

Build-Überprüfung

# Clean build
npm run clean
npm run build

# Check build output
ls -la dist/

Umgebungsvariablen

Sicherheitsaspekte

Datenschutz

1. Datenbankverschlüsselung: Verwenden Sie DATABASE_ENCRYPTION_KEY zur Verschlüsselung sensibler Daten im Ruhezustand

2. API-Schlüsselsicherheit: API-Schlüssel werden niemals protokolliert; verwenden Sie Umgebungsvariablen oder sichere Tresore

3. Speichersicherheit: Sensible Zeichenfolgen werden mit PBKDF2 (120.000 Iterationen) gehasht, bevor sie in den Circuit-Breaker- und API-Protokolltabellen gespeichert werden

Netzwerksicherheit

1. Nur HTTPS: Die gesamte API-Kommunikation verwendet HTTPS

2. Zertifikatsvalidierung: Die TLS-Zertifikatsvalidierung ist standardmäßig aktiviert

3. User-Agent: Ein benutzerdefinierter User-Agent identifiziert die Serverversion

Ratenbegrenzung

1. Clientseitige Ratenbegrenzung: Verhindert die Überlastung externer APIs

2. Circuit Breaker: Verhindert kaskadierende Ausfälle

3. Gegendruck: Automatisches Warten bei Ratenbegrenzung

Leistung

Optimierungen

• Verbindungspooling: Datenbankverbindungen werden wiederverwendet

• Lazy Loading: Repositories werden bei Bedarf erstellt

• Indizierte Abfragen: Datenbanktabellen verfügen über geeignete Indizes

• Caching: API-Schlüssel-Hashes werden für Circuit-Breaker-Prüfungen zwischengespeichert

• Async/Await: Nicht blockierende E/A-Operationen

Benchmarks

• Scan-Anfrage: ~100-500ms (simuliert)

• VirusTotal-Anfrage: ~200-1000ms (netzwerkabhängig)

• Datenbankoperationen: <10ms (lokales SQLite)

Fehlerbehebung

Häufige Probleme

Datenbankverbindung fehlgeschlagen

Error: Failed to connect to database

Lösung: Stellen Sie sicher, dass das Datenverzeichnis existiert und über Schreibrechte verfügt:

mkdir -p data
chmod 755 data

Fehlender ALIENVAULT_API_KEY

Missing required environment variables:
  - ALIENVAULT_API_KEY

Lösung: Legen Sie die Umgebungsvariable fest:

export ALIENVAULT_API_KEY=your_api_key_here
# or add to .env file

VirusTotal-Ratenlimit überschritten

Error: Rate limit exceeded for API key 0

Lösung:

• Warten Sie, bis sich das Ratenlimit zurückgesetzt hat (Standard: 4 Anfragen/Minute)

• Fügen Sie weitere API-Schlüssel hinzu (durch Kommas getrennt in VIRUSTOTAL_API_KEYS)

• Verwenden Sie den Parameter wait: true, um automatisch zu warten

Circuit Breaker offen

Error: API key 0 is blocked by circuit breaker

Lösung: Warten Sie, bis das Timeout des Circuit Breakers abgelaufen ist (Standard: 5 Minuten). Der Circuit wird nach Ablauf des Timeouts automatisch wieder geöffnet.

Debug-Modus

Aktivieren Sie die Debug-Protokollierung für eine detaillierte Fehlerbehebung:

DEBUG=true LOG_LEVEL=debug npm run dev

Mitwirken

Pull Requests

1. Forken Sie das Repository

2. Erstellen Sie einen Feature-Branch (git checkout -b feature/amazing-feature)

3. Committen Sie Ihre Änderungen (git commit -m 'Add amazing feature')

4. Pushen Sie den Branch (git push origin feature/amazing-feature)

5. Öffnen Sie einen Pull Request

Richtlinien für Commit-Nachrichten

• Verwenden Sie das Format Conventional Commits

• Präfix mit Typ: feat:, fix:, docs:, style:, refactor:, test:, chore:

• Halten Sie die Betreffzeile unter 72 Zeichen

• Geben Sie bei Bedarf eine ausführliche Beschreibung im Textkörper an

Code-Review

• Alle PRs benötigen die Genehmigung von mindestens einem Maintainer

• Die CI/CD-Pipeline muss erfolgreich sein (Lint, Typprüfung, Tests)

• Der Code muss den vorhandenen Mustern und Stilen folgen

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert – siehe die Datei LICENSE für Details.

Danksagungen

• 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

Referenzen

• AlienVault-OTX-Dokumentation

• VirusTotal-API-Dokumentation

• Model-Context-Protocol-Spezifikation

• MCP-TypeScript-SDK