AlienSec MCP Server

Готовый к продакшену MCP-сервер для сканирования безопасности конечных точек AlienVault OTX с интеграцией VirusTotal

// создано для сообщества специалистов по безопасности — финансирование поддерживает его развитие

Обзор

AlienSec MCP Server — это производственный MCP-сервер (Model Context Protocol), предоставляющий комплексные возможности сканирования безопасности конечных точек с использованием AlienVault OTX и опциональной интеграцией VirusTotal.

Этот сервер позволяет ИИ-агентам и приложениям выполнять сканирование безопасности различных типов конечных точек (macOS PKG, Windows PowerShell, Debian APT, Redhat RPM) и получать данные об угрозах из API AlienVault OTX и VirusTotal.

Related MCP server: Velociraptor MCP Server

Возможности

Основные возможности

• Многоплатформенное сканирование конечных точек

  • Сканирование систем macOS с использованием установщика PKG

  • Сканирование конечных точек Windows через PowerShell

  • Сканирование систем Debian/Ubuntu с использованием APT

  • Сканирование систем Redhat/CentOS с использованием RPM

• Интеграция VirusTotal

  • Сканирование файлов и URL-адресов через API VirusTotal

  • Получение существующих результатов анализа

  • Автоматическое ограничение скорости и защита автоматическим выключателем

  • Поддержка нескольких ключей API (с соблюдением условий использования VirusTotal)

• Аналитика угроз

  • Поиск пульсов AlienVault OTX

  • Получение деталей и событий пульсов

  • Доступ к индикаторам компрометации (IoC)

• Хранение данных

  • База данных SQLite с опциональным шифрованием

  • Хранение результатов сканирования с временными метками

  • Журналирование запросов к API

  • Отслеживание событий автоматического выключателя

• Функции, готовые к продакшену

  • Комплексная обработка ошибок

  • Структурированное журналирование с Pino

  • Валидация переменных окружения с Zod

  • Типобезопасные схемы API

  • Корректное завершение работы

Предварительные требования

Системные требования

• Node.js: >= 22.0.0

• npm: >= 8.0.0

• Операционная система: macOS, Linux или Windows

• Дисковое пространство: минимум 100 МБ для зависимостей

Требуемые ключи API

1. Ключ API AlienVault OTX (обязательно)

   • Зарегистрируйтесь на https://otx.alienvault.com

   • Перейдите в Settings > API Keys

   • Сгенерируйте новый ключ API

2. Ключ API VirusTotal (опционально, для расширенной функциональности)

   • Зарегистрируйтесь на https://www.virustotal.com

   • Перейдите в API Console

   • Сгенерируйте ключ(и) API

   • Примечание: бесплатный тариф позволяет 500 запросов в день, 4 запроса в минуту

Установка

1. Клонирование репозитория

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

2. Установка зависимостей

npm install

Это установит все зависимости для разработки и продакшена.

3. Настройка переменных окружения

Скопируйте пример файла окружения и обновите его своими ключами API:

cp .env.example .env

Отредактируйте .env, указав свои ключи 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

Примечание: Условия использования VirusTotal запрещают использование нескольких ключей API для обхода ограничений скорости. Эта реализация соблюдает эти ограничения и использует несколько ключей только для обеспечения избыточности.

4. (Опционально) Установка зависимостей шифрования SQLite

Для поддержки шифрованной базы данных на Linux/macOS:

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

# macOS
xcode-select --install

Использование

Режим разработки

Запуск сервера в режиме разработки с автоматической перезагрузкой:

npm run dev

Производственный режим

Сборка и запуск сервера:

npm run build
npm start

Использование с MCP-клиентами

Сервер взаимодействует через stdio (стандартный ввод/вывод). Для использования с MCP-клиентом:

# Direct execution
node dist/index.js

# Or using the npm script
npm start

Пример интеграции с 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);

Доступные инструменты

Инструменты сканирования (5)

Инструменты VirusTotal (2)

Инструменты AlienVault OTX (3)

Инструменты базы данных (4)

Системные инструменты (1)

Команды начальной загрузки

Сервер предоставляет предварительно настроенные команды начальной загрузки для каждого типа конечной точки. <api-key> ниже — это ваше разрешённое значение ALIENVAULT_API_KEY, а TARGET=<target> включается только при указании target.

Установщик macOS PKG

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

Структура проекта

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

Архитектура

Многоуровневая архитектура

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

Ключевые паттерны проектирования

1. Паттерн Singleton: База данных, клиент AlienVault, клиент VirusTotal

2. Паттерн Repository: ScanRepository, CircuitBreakerRepository, APILogRepository

3. Паттерн автоматического выключателя: Автоматическая ротация ключей API при сбоях

4. Ограничитель скорости Token Bucket: Ограничение скорости для API VirusTotal

5. Паттерн Factory: Создание MCP-сервера с внедрением зависимостей

6. Паттерн Strategy: Различные типы сканирования с общим интерфейсом

Схема базы данных

Сервер использует SQLite со следующими таблицами:

scan_records

Хранит все результаты сканирования с находками, данными VirusTotal и временными метками.

circuit_breaker_events

Отслеживает изменения состояния автоматического выключателя для ключей API.

api_logs

Журналирует все запросы к API с временем ответа, кодами состояния и ошибками.

schema_version

Отслеживает версию схемы базы данных для миграций.

Обработка ошибок

Пользовательские классы ошибок

• AlienSecError: Базовый класс ошибки с кодом и statusCode

• AlienVaultAPIError: Ошибки, специфичные для AlienVault

• VirusTotalAPIError: Ошибки, специфичные для VirusTotal, с обнаружением ограничения скорости

• DatabaseError: Ошибки, связанные с базой данных

• ConfigurationError: Ошибки валидации конфигурации

Формат ответа об ошибке

Ошибки инструментов возвращают стандартную форму результата MCP с isError: true. Человекочитаемое сообщение находится в первом блоке содержимого; error содержит JSON-строку контекстных данных (ID сканирования, flavor, target и т. д.), которые вызвали сбой:

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

Журналирование

Сервер использует Pino для структурированного журналирования со следующими уровнями:

• error: Критические сбои

• warn: Предупреждения и потенциальные проблемы

• info: Обычные операции и обновления статуса

• debug: Подробная отладочная информация

• trace: Очень подробное журналирование для разработки

Журналы автоматически редактируются для предотвращения записи конфиденциальных данных (ключей API).

Ограничение скорости и автоматический выключатель

Ограничение скорости VirusTotal

• Алгоритм Token Bucket: Плавное ограничение скорости

• Настраиваемые лимиты: Задаются через переменные окружения

• Автоматическое ожидание: Опция ожидания при ограничении скорости

• Автоматический выключатель: Автоматически блокирует ключи API, которые многократно дают сбои

Конфигурация автоматического выключателя

• Порог сбоев: 5 последовательных сбоев

• Таймаут сброса: 300 секунд (5 минут)

• Состояние полуоткрытия: Тест с 1 запросом перед полным повторным открытием

Соответствие условиям использования

Реализация соблюдает условия использования VirusTotal:

• Несколько ключей API предназначены для избыточности, а не для обхода лимитов

• Каждый ключ API соблюдает индивидуальные ограничения скорости

• Автоматический выключатель предотвращает быстрые повторные попытки при сбоях

• Подсчёт ежедневных запросов предотвращает исчерпание квоты

Разработка

Запуск тестов

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npx vitest run --coverage

Линтинг и форматирование

# Run linting
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format code
npm run format

Проверка типов

npm run typecheck

Проверка сборки

# Clean build
npm run clean
npm run build

# Check build output
ls -la dist/

Переменные окружения

Соображения безопасности

Защита данных

1. Шифрование базы данных: Используйте DATABASE_ENCRYPTION_KEY для шифрования конфиденциальных данных в состоянии покоя

2. Безопасность ключей API: Ключи API никогда не записываются в журналы; используйте переменные окружения или защищенные хранилища

3. Безопасность памяти: Конфиденциальные строки хэшируются с помощью PBKDF2 (120 000 итераций) перед сохранением в таблицах автоматического выключателя и журнала API

Сетевая безопасность

1. Только HTTPS: Все взаимодействия с API используют HTTPS

2. Проверка сертификатов: Проверка TLS-сертификатов включена по умолчанию

3. User-Agent: Пользовательский агент идентифицирует версию сервера

Ограничение скорости

1. Клиентское ограничение скорости: Предотвращает перегрузку внешних API

2. Автоматический выключатель: Предотвращает каскадные сбои

3. Обратное давление: Автоматическое ожидание при ограничении скорости

Производительность

Оптимизации

• Пул соединений: Соединения с базой данных переиспользуются

• Ленивая загрузка: Репозитории создаются по требованию

• Индексированные запросы: Таблицы базы данных имеют соответствующие индексы

• Кэширование: Хэши ключей API кэшируются для проверок автоматического выключателя

• Async/Await: Неблокирующие операции ввода-вывода

Бенчмарки

• Запрос сканирования: ~100-500 мс (симуляция)

• Запрос VirusTotal: ~200-1000 мс (зависит от сети)

• Операции с базой данных: <10 мс (локальная SQLite)

Устранение неполадок

Частые проблемы

Не удалось подключиться к базе данных

Error: Failed to connect to database

Решение: Убедитесь, что каталог данных существует и имеет права на запись:

mkdir -p data
chmod 755 data

Отсутствует ALIENVAULT_API_KEY

Missing required environment variables:
  - ALIENVAULT_API_KEY

Решение: Установите переменную окружения:

export ALIENVAULT_API_KEY=your_api_key_here
# or add to .env file

Превышен лимит запросов VirusTotal

Error: Rate limit exceeded for API key 0

Решение:

• Подождите, пока сбросится лимит запросов (по умолчанию: 4 запроса в минуту)

• Добавьте больше ключей API (через запятую в VIRUSTOTAL_API_KEYS)

• Используйте параметр wait: true для автоматического ожидания

Автоматический выключатель открыт

Error: API key 0 is blocked by circuit breaker

Решение: Подождите, пока истечет тайм-аут автоматического выключателя (по умолчанию: 5 минут). Выключатель автоматически закроется после истечения тайм-аута.

Режим отладки

Включите подробное журналирование для детального устранения неполадок:

DEBUG=true LOG_LEVEL=debug npm run dev

Внесение вклада

Пул-реквесты

1. Сделайте форк репозитория

2. Создайте ветку функции (git checkout -b feature/amazing-feature)

3. Зафиксируйте изменения (git commit -m 'Add amazing feature')

4. Отправьте изменения в ветку (git push origin feature/amazing-feature)

5. Откройте пул-реквест

Рекомендации по сообщениям коммитов

• Используйте формат Conventional Commits

• Добавляйте префикс с типом: feat:, fix:, docs:, style:, refactor:, test:, chore:

• Держите тему сообщения не длиннее 72 символов

• При необходимости добавьте подробное описание в тело сообщения

Ревью кода

• Все пул-реквесты требуют одобрения как минимум одного мейнтейнера

• Конвейер CI/CD должен быть пройден (lint, typecheck, тесты)

• Код должен соответствовать существующим паттернам и стилю

Лицензия

Этот проект лицензирован под лицензией MIT - подробнее см. в файле LICENSE.

Благодарности

• 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

Ссылки

• Документация AlienVault OTX

• Документация VirusTotal API

• Спецификация Model Context Protocol

• MCP TypeScript SDK

Создано с ❤️ для сообщества специалистов по безопасности