AlienSec MCP Server

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

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

Обзор

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

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

Related MCP server: Nullcone 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

   • Перейдите в Настройки > Ключи API

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

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

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

   • Перейдите в Консоль API

   • Сгенерируйте ключ(и) 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. Паттерн Circuit Breaker: Автоматическая ротация ключей API при сбоях

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

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

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

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

Сервер использует 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: пользовательский 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

Участие в разработке

Pull Request

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

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

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

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

5. Откройте Pull Request

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

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

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

• Держите строку темы не длиннее 72 символов

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

Ревью кода

• Все PR требуют одобрения как минимум одного мейнтейнера

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

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

Лицензия

Этот проект лицензирован по лицензии 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

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

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

• MCP TypeScript SDK