AlienSec MCP 서버

VirusTotal 통합을 갖춘 프로덕션 준비 완료 AlienVault OTX 엔드포인트 보안 스캐닝 MCP 서버

// 보안 커뮤니티를 위해 제작됨 — 후원금은 유지보수에 사용됩니다

개요

AlienSec MCP 서버는 AlienVault OTX와 선택적 VirusTotal 통합을 사용하여 포괄적인 엔드포인트 보안 스캐닝 기능을 제공하는 프로덕션 등급의 Model Context Protocol (MCP) 서버입니다.

이 서버는 AI 에이전트와 애플리케이션이 다양한 엔드포인트 유형(macOS PKG, Windows PowerShell, Debian APT, Redhat RPM)에 대한 보안 스캔을 수행하고 AlienVault OTX 및 VirusTotal API에서 위협 인텔리전스를 검색할 수 있게 합니다.

Related MCP server: Velociraptor MCP Server

기능

핵심 기능

• 멀티 플랫폼 엔드포인트 스캐닝

  • PKG 설치 프로그램 플레이버를 사용한 macOS 시스템 스캔

  • PowerShell을 통한 Windows 엔드포인트 스캔

  • APT를 사용한 Debian/Ubuntu 시스템 스캔

  • RPM을 사용한 Redhat/CentOS 시스템 스캔

• VirusTotal 통합

  • VirusTotal API를 사용한 파일 및 URL 스캔

  • 기존 분석 결과 검색

  • 자동 속도 제한 및 회로 차단기 보호

  • 다중 API 키 지원(VirusTotal ToS 준수)

• 위협 인텔리전스

  • AlienVault OTX 펄스 검색

  • 펄스 세부 정보 및 이벤트 검색

  • 침해 지표(IoC) 접근

• 데이터 영속성

  • 선택적 암호화가 포함된 SQLite 데이터베이스

  • 타임스탬프가 포함된 스캔 결과 저장

  • API 요청 로깅

  • 회로 차단기 이벤트 추적

• 프로덕션 준비 완료 기능

  • 포괄적인 오류 처리

  • Pino를 사용한 구조화된 로깅

  • Zod를 사용한 환경 변수 검증

  • 타입 안전 API 스키마

  • 정상 종료 처리

사전 요구 사항

시스템 요구 사항

• Node.js: >= 22.0.0

• npm: >= 8.0.0

• 운영 체제: macOS, Linux 또는 Windows

• 디스크 공간: 종속성 설치를 위한 최소 100MB

필수 API 키

1. AlienVault OTX API 키 (필수)

   • https://otx.alienvault.com에서 가입

   • 설정 > API 키로 이동

   • 새 API 키 생성

2. VirusTotal API 키 (선택 사항, 향상된 기능용)

   • 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

API 키로 .env를 편집합니다:

# 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 ToS는 속도 제한을 우회하기 위해 여러 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. 싱글턴 패턴: 데이터베이스, AlienVault 클라이언트, VirusTotal 클라이언트

2. 리포지토리 패턴: ScanRepository, CircuitBreakerRepository, APILogRepository

3. 회로 차단기 패턴: 실패 시 자동 API 키 순환

4. 토큰 버킷 속도 제한기: VirusTotal API 속도 제한

5. 팩토리 패턴: 의존성 주입을 통한 MCP 서버 생성

6. 전략 패턴: 공통 인터페이스를 가진 다양한 스캔 플레이버

데이터베이스 스키마

서버는 다음 테이블과 함께 SQLite를 사용합니다:

scan_records

발견 사항, VirusTotal 데이터 및 타임스탬프와 함께 모든 스캔 결과를 저장합니다.

circuit_breaker_events

API 키에 대한 회로 차단기 상태 변경을 추적합니다.

api_logs

응답 시간, 상태 코드 및 오류와 함께 모든 API 요청을 기록합니다.

schema_version

마이그레이션을 위한 데이터베이스 스키마 버전을 추적합니다.

오류 처리

사용자 정의 오류 클래스

• AlienSecError: 코드와 statusCode를 가진 기본 오류 클래스

• AlienVaultAPIError: AlienVault 관련 오류

• VirusTotalAPIError: 속도 제한 감지가 포함된 VirusTotal 관련 오류

• DatabaseError: 데이터베이스 관련 오류

• ConfigurationError: 구성 검증 오류

오류 응답 형식

도구 오류는 isError: true가 포함된 표준 MCP 결과 형태를 반환합니다. 사람이 읽을 수 있는 메시지는 첫 번째 콘텐츠 블록이며, error는 실패를 유발한 컨텍스트 데이터(스캔 ID, 플레이버, 대상 등)의 JSON 문자열화된 값을 전달합니다:

{
  "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 속도 제한

• 토큰 버킷 알고리즘: 부드러운 속도 제한

• 구성 가능한 제한: 환경 변수로 설정

• 자동 대기: 속도 제한 시 대기 옵션

• 회로 차단기: 반복적으로 실패하는 API 키를 자동으로 차단

회로 차단기 구성

• 실패 임계값: 연속 5회 실패

• 리셋 제한 시간: 300초(5분)

• 반개방 상태: 완전히 다시 열기 전에 1회 요청으로 테스트

ToS 준수

이 구현은 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. 메모리 안전성: 민감한 문자열은 회로 차단기 및 API 로그 테이블에 저장되기 전에 PBKDF2(120,000회 반복)로 해시됩니다

네트워크 보안

1. HTTPS 전용: 모든 API 통신은 HTTPS를 사용합니다

2. 인증서 검증: TLS 인증서 검증이 기본적으로 활성화되어 있습니다

3. User-Agent: 사용자 지정 user agent가 서버 버전을 식별합니다

속도 제한

1. 클라이언트 측 속도 제한: 외부 API에 과부하가 걸리는 것을 방지합니다

2. 회로 차단기: 연쇄 실패를 방지합니다

3. 역압(Backpressure): 속도 제한 시 자동 대기

성능

최적화

• 연결 풀링: 데이터베이스 연결이 재사용됩니다

• 지연 로딩: 리포지토리가 필요할 때 생성됩니다

• 인덱스 쿼리: 데이터베이스 테이블에 적절한 인덱스가 있습니다

• 캐싱: 회로 차단기 확인을 위해 API 키 해시가 캐시됩니다

• Async/Await: 비차단 I/O 작업

벤치마크

• 스캔 요청: ~100-500ms(시뮬레이션)

• VirusTotal 요청: ~200-1000ms(네트워크에 따라 다름)

• 데이터베이스 작업: <10ms(로컬 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자 미만으로 유지하세요

• 필요한 경우 본문에 자세한 설명을 제공하세요

코드 리뷰

• 모든 PR은 최소 한 명의 관리자 승인이 필요합니다

• 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

보안 커뮤니티를 위해 ❤️로 제작되었습니다