VirusTotal MCP Server

VirusTotal API sorgulama için bir Model Context Protocol (MCP) sunucusu. Bu sunucu, otomatik ilişki veri getirme özelliğine sahip kapsamlı güvenlik analiz araçları sağlar. Claude Desktop gibi MCP uyumlu uygulamalarla sorunsuz bir şekilde entegre edilir.

Hızlı Başlangıç (Önerilen)

Claude Code

claude mcp add --transport stdio --env VIRUSTOTAL_API_KEY=your-key virustotal -- npx -y @burtthecoder/mcp-virustotal

Codex CLI

codex mcp add virustotal --env VIRUSTOTAL_API_KEY=your-key -- npx -y @burtthecoder/mcp-virustotal

Gemini CLI

gemini mcp add -e VIRUSTOTAL_API_KEY=your-key virustotal npx -y @burtthecoder/mcp-virustotal

Smithery Aracılığıyla Kurulum

VirusTotal Server'ı Claude Desktop'ta otomatik olarak Smithery aracılığıyla kurmak için:

npx -y @smithery/cli install @burtthecoder/mcp-virustotal --client claude

Manuel Kurulum

1. Sunucuyu npm aracılığıyla global olarak kurun:

npm install -g @burtthecoder/mcp-virustotal

2. Claude Desktop konfigürasyon dosyanıza ekleyin:

{
  "mcpServers": {
    "virustotal": {
      "command": "mcp-virustotal",
      "env": {
        "VIRUSTOTAL_API_KEY": "your-virustotal-api-key"
      }
    }
  }
}

Konfigürasyon dosyası konumu:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

3. Claude Desktop'ı yeniden başlatın

VS Code ile Kullanım

Bu MCP sunucusunu VS Code'da GitHub Copilot ile kullanmak için:

1. Sunucuyu npm aracılığıyla global olarak kurun:

npm install -g @burtthecoder/mcp-virustotal

2. VS Code MCP konfigürasyon dosyanızı şu konumda oluşturun veya güncelleyin:

   • macOS/Linux: ~/.vscode/mcp.json
   • Windows: %USERPROFILE%\.vscode\mcp.json

3. Aşağıdaki konfigürasyonu ekleyin:

{
  "servers": {
    "virustotal": {
      "command": "mcp-virustotal",
      "env": {
        "VIRUSTOTAL_API_KEY": "your-virustotal-api-key"
      }
    }
  }
}

4. MCP sunucusunu etkinleştirmek için VS Code'u yeniden yükleyin

Daha sonra VS Code'da GitHub Copilot aracılığıyla VirusTotal araçlarını kullanabilirsiniz.

Alternatif Kurulum (Kaynaktan)

Kaynaktan çalıştırmayı veya kodu değiştirmeyi tercih ederseniz:

1. Klonlayın ve derleyin:

git clone <repository_url>
cd mcp-virustotal
npm install
npm run build

2. Claude Desktop konfigürasyonunuza ekleyin:

{
  "mcpServers": {
    "virustotal": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-virustotal/build/index.js"],
      "env": {
        "VIRUSTOTAL_API_KEY": "your-virustotal-api-key"
      }
    }
  }
}

HTTP Streaming Transport

Sunucu, varsayılan stdio transport'a ek olarak HTTP streaming transport'u destekler. Bu, sunucuyu birden fazla istemcinin bağlanabileceği bağımsız bir HTTP hizmeti olarak çalıştırmak için kullanışlıdır.

HTTP Streaming Modunda Çalıştırma

MCP_TRANSPORT ortam değişkenini httpStream olarak ayarlayın:

MCP_TRANSPORT=httpStream MCP_PORT=3000 VIRUSTOTAL_API_KEY=your-key node build/index.js

Ortam Değişkenleri

Değişken	Varsayılan	Açıklama
VIRUSTOTAL_API_KEY	(gerekli)	VirusTotal API anahtarınız
MCP_TRANSPORT	stdio	Transport modu: stdio veya httpStream
MCP_PORT	3000	HTTP sunucu portu (yalnızca httpStream için)
MCP_ENDPOINT	/mcp	HTTP endpoint yolu (yalnızca httpStream için)

Docker ile HTTP Streaming

docker build -t mcp-virustotal .
docker run -p 3000:3000 \
  -e VIRUSTOTAL_API_KEY=your-key \
  -e MCP_TRANSPORT=httpStream \
  mcp-virustotal

Sunucu, HTTP streaming modunda çalışırken /health konumunda bir sağlık kontrolü endpoint'i açığa çıkarır.

Özellikler

• Kapsamlı Analiz Raporları: Her analiz aracı otomatik olarak VirusTotal'ın ?relationships= sorgusunu kullanarak ilgili ilişki verilerini temel raporla birlikte getirir, API çağrılarını en aza indirmek için toplu işleme yapılır
• URL Analizi: Önbelleğe alınmış rapor öncelikli aramaları ve otomatik tarama geri dönüşü, iletişim kurulan etki alanları, indirilen dosyalar ve tehdit aktörleri
• Dosya Analizi: Dosya hash'lerinin davranışlar, bırakılan dosyalar ve ağ bağlantıları dahil olmak üzere ayrıntılı analizi
• IP Analizi: Geçmiş veriler, çözümlemeler ve ilgili tehditler içeren güvenlik raporları
• Etki Alanı Analizi: DNS bilgileri, WHOIS verileri, SSL sertifikaları ve alt etki alanları
• Ayrıntılı İlişki Analizi: Sayfalandırma desteği ile belirli ilişki türlerini sorgulamak için ayrılmış araçlar
• Corpus Araması: Dosyalar, URL'ler, etki alanları, IP'ler ve yorumlar arasında serbest metin araması (VTI tarzı değiştirici sözdizimi dahil: type:peexe positives:5+)
• Sandbox Davranış Özeti: Işlemler, dosyalar, kayıt defteri, ağ, MITRE ATT&CK, IDS uyarıları ve imza eşleşmelerinin birleştirilmiş görünümü
• Tehdit Koleksiyonları: Herhangi bir raporun ilişkilerinden başvurulan APT, malware-family, campaign ve intel-report nesnelerini okuyun
• Zengin Biçimlendirme: Analiz sonuçlarının ve ilişki verilerinin net kategorilendirmesi ve sunumu

Araçlar

Rapor Araçları (Otomatik İlişki Getirme ile)

1. URL Rapor Aracı

• Ad: get_url_report
• Açıklama: Güvenlik taraması sonuçları ve kilit ilişkiler (iletişim kurulan dosyalar, iletişim kurulan etki alanları/IP'ler, indirilen dosyalar, yönlendirmeler, tehdit aktörleri) dahil olmak üzere kapsamlı URL analiz raporu alın. Mevcut olduğunda önbelleğe alınmış VirusTotal raporunu döndürür; yalnızca önbellek kaçırıldığında URL'yi tarama için gönderir ve tamamlanması için yoklar
• Parametreler:
  • url (gerekli): Analiz edilecek URL

2. Dosya Rapor Aracı

• Ad: get_file_report
• Açıklama: Hash (MD5/SHA-1/SHA-256) kullanarak kapsamlı dosya analiz raporu alın. Algılama sonuçları, dosya özellikleri ve kilit ilişkiler (davranışlar, bırakılan dosyalar, ağ bağlantıları, gömülü içerik, tehdit aktörleri) içerir
• Parametreler:
  • hash (gerekli): Dosyanın MD5, SHA-1 veya SHA-256 hash'i

3. IP Rapor Aracı

• Ad: get_ip_report
• Açıklama: Coğrafi konum, itibar verileri ve kilit ilişkiler (iletişim kurulan dosyalar, geçmiş sertifikalar/WHOIS, çözümlemeler) dahil olmak üzere kapsamlı IP adresi analiz raporu alın
• Parametreler:
  • ip (gerekli): Analiz edilecek IP adresi

4. Etki Alanı Rapor Aracı

• Ad: get_domain_report
• Açıklama: DNS kayıtları, WHOIS verileri ve kilit ilişkiler (SSL sertifikaları, alt etki alanları, geçmiş veriler) dahil olmak üzere kapsamlı etki alanı analiz raporu alın
• Parametreler:
  • domain (gerekli): Analiz edilecek etki alanı adı
  • relationships (isteğe bağlı): Rapora dahil edilecek belirli ilişkiler dizisi

İlişki Araçları (Ayrıntılı Analiz İçin)

1. URL İlişki Aracı

• Ad: get_url_relationship
• Açıklama: Sayfalandırma desteği ile bir URL için belirli bir ilişki türünü sorgulayın. Analizler, iletişim kurulan dosyalar, iletişim kurulan etki alanları/IP'ler, indirilen dosyalar, grafikler, yönlendiren kaynaklar, yönlendirmeler, tehdit aktörleri, koleksiyonlar ve oylar dahil olmak üzere 22 ilişki türünden seçim yapın
• Parametreler:
  • url (gerekli): İlişkileri almak istediğiniz URL
  • relationship (gerekli): Sorgulanacak ilişki türü
    • Mevcut ilişkiler: analyses, collections, comments, communicating_files, contacted_domains, contacted_ips, downloaded_files, embedded_js_files, graphs, last_serving_ip_address, network_location, referrer_files, referrer_urls, redirecting_urls, redirects_to, related_comments, related_references, related_threat_actors, submissions, urls_related_by_tracker_id, user_votes, votes
  • limit (isteğe bağlı, varsayılan: 10): Alınacak ilişkili nesne sayısı üst sınırı (1-40)
  • cursor (isteğe bağlı): Sayfalandırma için devam işaretçisi

2. Dosya İlişki Aracı

• Ad: get_file_relationship
• Açıklama: Sayfalandırma desteği ile bir dosya için belirli bir ilişki türünü sorgulayın. Davranışlar, ağ bağlantıları, bırakılan dosyalar, gömülü içerik, yürütme zinciri ve tehdit aktörleri dahil olmak üzere 40 ilişki türünden seçim yapın
• Parametreler:
  • hash (gerekli): Dosyanın MD5, SHA-1 veya SHA-256 hash'i
  • relationship (gerekli): Sorgulanacak ilişki türü
    • Mevcut ilişkiler: analyses, behaviours, bundled_files, carbonblack_children, carbonblack_parents, ciphered_bundled_files, ciphered_parents, collections, comments, compressed_parents, contacted_domains, contacted_ips, contacted_urls, dropped_files, email_attachments, email_parents, embedded_domains, embedded_ips, embedded_urls, execution_parents, graphs, itw_domains, itw_ips, itw_urls, memory_pattern_domains, memory_pattern_ips, memory_pattern_urls, overlay_children, overlay_parents, pcap_children, pcap_parents, pe_resource_children, pe_resource_parents, related_references, related_threat_actors, similar_files, submissions, screenshots, urls_for_embedded_js, votes
  • limit (isteğe bağlı, varsayılan: 10): Alınacak ilişkili nesne sayısı üst sınırı (1-40)
  • cursor (isteğe bağlı): Sayfalandırma için devam işaretçisi

3. IP İlişki Aracı

• Ad: get_ip_relationship
• Açıklama: Sayfalandırma desteği ile bir IP adresi için belirli bir ilişki türünü sorgulayın. İletişim kurulan dosyalar, geçmiş SSL sertifikaları, WHOIS kayıtları, çözümlemeler, tehdit aktörleri ve oylar dahil olmak üzere 15 ilişki türünden seçim yapın
• Parametreler:
  • ip (gerekli): Analiz edilecek IP adresi
  • relationship (gerekli): Sorgulanacak ilişki türü
    • Mevcut ilişkiler: collections, comments, communicating_files, downloaded_files, graphs, historical_ssl_certificates, historical_whois, related_comments, related_references, related_threat_actors, referrer_files, resolutions, urls, user_votes, votes
  • limit (isteğe bağlı, varsayılan: 10): Alınacak ilişkili nesne sayısı üst sınırı (1-40)
  • cursor (isteğe bağlı): Sayfalandırma için devam işaretçisi

4. Etki Alanı İlişki Aracı

• Ad: get_domain_relationship
• Açıklama: Sayfalandırma desteği ile bir etki alanı için belirli bir ilişki türünü sorgulayın. SSL sertifikaları, alt etki alanları, geçmiş veriler, DNS kayıtları ve koleksiyonlar dahil olmak üzere 24 ilişki türünden seçim yapın
• Parametreler:
  • domain (gerekli): Analiz edilecek etki alanı adı
  • relationship (gerekli): Sorgulanacak ilişki türü
    • Mevcut ilişkiler: caa_records, cname_records, collections, comments, communicating_files, downloaded_files, graphs, historical_ssl_certificates, historical_whois, immediate_parent, mx_records, ns_records, parent, referrer_files, related_comments, related_references, related_threat_actors, resolutions, soa_records, siblings, subdomains, urls, user_votes, votes
  • limit (isteğe bağlı, varsayılan: 10): Alınacak ilişkili nesne sayısı üst sınırı (1-40)
  • cursor (isteğe bağlı): Sayfalandırma için devam işaretçisi

Arama ve Pivot Araçları

1. Corpus Araması

• Ad: search_vt
• Açıklama: Sorguyla eşleşen dosyalar, URL'ler, etki alanları, IP'ler veya yorumlar için VirusTotal corpus'unda arama yapın. Düz IOC'leri (hash, URL, etki alanı, IP), yorumlar hakkında serbest metni veya VTI tarzı arama değiştiricilerini kabul eder
• Parametreler:
  • query (gerekli): Arama sorgusu. Örnekler: SHA-256 hash, evil.com, 8.8.8.8, type:peexe size:90kb+ tag:signed positives:5+
  • limit (isteğe bağlı, varsayılan: 20): Maksimum sonuç sayısı (1-300)
  • cursor (isteğe bağlı): Sayfalandırma için devam işaretçisi

2. Dosya Davranış Özeti

• Ad: get_file_behaviour_summary
• Açıklama: Bir dosya için birleştirilmiş sandbox davranış özetini alın, her sandbox tarafından analiz edilen verileri birleştirin. Işlemler, dosyalar, kayıt defteri, ağ aktivitesi, DNS aramaları, MITRE ATT&CK teknikleri, IDS uyarıları ve imza eşleşmelerini tek bir görünümde döndürür — bireysel davranış raporlarını yinelemekten çok daha kullanışlı
• Parametreler:
  • hash (gerekli): Dosyanın MD5, SHA-1 veya SHA-256 hash'i

3. Koleksiyon Araması

• Ad: get_collection
• Açıklama: VirusTotal koleksiyonunu ID'ye göre alın. Koleksiyonlar tehdit aktörleri, malware aileleri, kampanyalar, intel raporları ve seçilmiş IOC kümeleri temsil eder — genellikle diğer araçlardaki related_threat_actors ve collections ilişkilerinden başvurulur. İsteğe bağlı olarak üye IOC'leri aynı çağrıda getirmek için ilişkileri ekleyin
• Parametreler:
  • id (gerekli): Koleksiyon ID'si (örneğin threat-actor--<uuid>, malware-family--<id>)
  • relationships (isteğe bağlı): Dahil edilecek ilişki adlarının dizisi
    • Mevcut ilişkiler: autogenerated_graphs, comments, domains, files, ip_addresses, owner, references, related_collections, related_references, threat_actors, urls

Gereksinimler

• Node.js (v20 veya üstü)
• Geçerli bir VirusTotal API Anahtarı

Sorun Giderme

API Anahtarı Sorunları

"Yanlış API anahtarı" hataları görürseniz:

1. macOS üzerinde /tmp/mcp-virustotal-server.log konumundaki günlük dosyasını kontrol edin
2. API anahtarınızı doğrulayın:
   • Geçerli bir VirusTotal API anahtarı olmalıdır (genellikle 64 karakter)
   • Anahtar etrafında boşluk veya tırnak işareti olmamalıdır
   • VirusTotal hesabınızdaki API Keys bölümünden olmalıdır
3. Herhangi bir konfigürasyon değişikliğinden sonra:
   • Konfigürasyon dosyasını kaydedin
   • Claude Desktop'ı yeniden başlatın
   • Yeni API anahtarı durumu için günlükleri kontrol edin

Geliştirme

Sıcak yeniden yükleme ile geliştirme modunda çalıştırmak için:

npm run dev

Test

Birim testleri

Biçimlendirici test paketini çalıştırın (API anahtarı yok, ağ yok):

npm test

Canlı smoke testi

Tüm 11 aracı gerçek VirusTotal API'sine karşı uçtan uca test edin:

VIRUSTOTAL_API_KEY=your-key npm run smoke

Smoke test çağrıları 20 saniyede bir hızlandırarak 4 istek/dakika genel katman hız sınırı altında kalır. Çok azaltılmış ücretsiz katmanlarla uyumlu değildir (örneğin 1 arama/gün) — bunlar için scripts/smoke-test.mjs dosyasını düzenleyerek ve doğrulamak istediğiniz aracı seçerek tek bir araç çalıştırın.

Hata İşleme

Sunucu şunlar için kapsamlı hata işleme içerir:

• Geçersiz API anahtarları
• Hız sınırlaması
• Ağ hataları
• Geçersiz giriş parametreleri
• Geçersiz hash biçimleri
• Geçersiz IP biçimleri
• Geçersiz URL biçimleri
• Geçersiz ilişki türleri
• Sayfalandırma hataları

Sürüm Geçmişi

• v1.0.0: Temel işlevsellik ile ilk yayın
• v1.1.0: URL'ler, dosyalar ve IP adresleri için ilişki analiz araçları eklendi
• v1.2.0: İyileştirilmiş hata işleme ve günlüğe kaydetme eklendi
• v1.3.0: İlişki sorguları için sayfalandırma desteği eklendi
• v1.4.0: Rapor araçlarında otomatik ilişki getirme ve etki alanı analiz desteği eklendi
• v1.5.0: FastMCP framework'e geçiş ve HTTP streaming transport desteği
• v1.6.0: search_vt, get_file_behaviour_summary, get_collection ve get_domain_relationship araçları eklendi; ilişki listeleri güncel VirusTotal v3 doklariyle senkronize edildi (kaldırılan clues, uygulanabilir yerlere collections/votes/user_votes/embedded_js_files/urls_related_by_tracker_id eklendi); get_url_report artık her çağrıda yeniden taramak yerine mevcut olduğunda önbelleğe alınmış raporu döndürür; rapor araçları API çağrılarını önemli ölçüde azaltmak için toplu ?relationships= sorguları kullanır

Katkıda Bulunma

1. Depoyu fork edin
2. Bir özellik dalı oluşturun (git checkout -b feature/amazing-feature)
3. Değişikliklerinizi işleyin (git commit -m 'Add amazing feature')
4. Dalı push edin (git push origin feature/amazing-feature)
5. Bir Pull Request açın

Lisans

Bu proje MIT Lisansı altında lisanslanmıştır - ayrıntılar için LICENSE dosyasına bakın.