VirusTotal MCP Server

这是一个用于查询VirusTotal API的模型上下文协议（MCP）服务器。该服务器提供全面的安全分析工具，并自动获取相关数据。它与兼容MCP的应用程序无缝集成，如Claude Desktop。

快速开始（待定）

通过Smithery安装

要通过Smithery自动为Claude Desktop安装virustotal-mcp：

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

手动安装

待定

特性

• 全面分析报告：每个分析工具都会自动获取相关的关联数据以及基本报告，提供一次请求中的完整安全概览
• URL分析：带有自动获取联系域名、下载文件和威胁行为者的安全报告
• 文件分析：详细分析文件哈希值，包括行为、释放文件和网络连接
• IP分析：带有历史数据、解析和相关威胁的安全报告
• 域名分析：DNS信息、WHOIS数据、SSL证书和子域
• 详细的关联分析：专门用于查询特定类型关系的工具，支持分页
• 高级搜索：VT情报搜索能力，适用于跨VirusTotal数据集的复杂查询
• 丰富的格式化：清晰分类和展示分析结果及关联数据

工具

报告工具（带自动关联获取）

1. URL报告工具

• 名称：get_url_report
• 描述：获取一个全面的URL分析报告，包括安全扫描结果和关键关系（通信文件、联系的域名/IP、下载的文件、重定向、威胁行为者）
• 参数：
  • url（必需）：要分析的URL
• 示例：

await get_url_report(url="http://example.com/suspicious")

2. 文件报告工具

• 名称：get_file_report
• 描述：使用文件的哈希值（MD5/SHA-1/SHA-256）获取全面的文件分析报告。包括检测结果、文件属性和关键关系（行为、释放文件、网络连接、嵌入内容、威胁行为者）
• 参数：
  • hash（必需）：文件的MD5、SHA-1或SHA-256哈希值
• 示例：

await get_file_report(hash="44d88612fea8a8f36de82e1278abb02f")

3. IP报告工具

• 名称：get_ip_report
• 描述：获取一个全面的IP地址分析报告，包括地理位置、信誉数据和关键关系（通信文件、历史证书/WHOIS、解析）
• 参数：
  • ip（必需）：要分析的IP地址
• 示例：

await get_ip_report(ip="8.8.8.8")

4. 域名报告工具

• 名称：get_domain_report
• 描述：获取一个全面的域名分析报告，包括DNS记录、WHOIS数据和关键关系（SSL证书、子域、历史数据）
• 参数：
  • domain（必需）：要分析的域名
• 示例：

await get_domain_report(domain="example.com")

关系工具（用于详细分析）

1. URL关系工具

• 名称：get_url_relationship
• 描述：查询URL的特定关系类型，支持分页
• 参数：
  • url（必需）：要获取关系的URL
  • relationship（必需）：要查询的关系类型
    • 可用关系：analyses, comments, communicating_files, contacted_domains, contacted_ips, downloaded_files, graphs, last_serving_ip_address, network_location, referrer_files, referrer_urls, redirecting_urls, redirects_to, related_comments, related_references, related_threat_actors, submissions
  • limit（可选，默认：10）：要检索的相关对象的最大数量（1-40）
  • cursor（可选）：分页继续游标
• 示例：

await get_url_relationship(
    url="http://example.com/suspicious",
    relationship="communicating_files",
    limit=20
)

2. 文件关系工具

• 名称：get_file_relationship
• 描述：查询文件的特定关系类型，支持分页
• 参数：
  • hash（必需）：文件的MD5、SHA-1或SHA-256哈希值
  • relationship（必需）：要查询的关系类型
    • 可用关系：analyses, behaviours, bundled_files, carbonblack_children, carbonblack_parents, ciphered_bundled_files, ciphered_parents, clues, 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（可选，默认：10）：要检索的相关对象的最大数量（1-40）
  • cursor（可选）：分页继续游标
• 示例：

await get_file_relationship(
    hash="44d88612fea8a8f36de82e1278abb02f",
    relationship="behaviours",
    limit=20
)

3. IP关系工具

• 名称：get_ip_relationship
• 描述：查询IP地址的特定关系类型，支持分页
• 参数：
  • ip（必需）：要分析的IP地址
  • relationship（必需）：要查询的关系类型
    • 可用关系：comments, communicating_files, downloaded_files, graphs, historical_ssl_certificates, historical_whois, related_comments, related_references, related_threat_actors, referrer_files, resolutions, urls
  • limit（可选，默认：10）：要检索的相关对象的最大数量（1-40）
  • cursor（可选）：分页继续游标
• 示例：

await get_ip_relationship(
    ip="8.8.8.8",
    relationship="communicating_files",
    limit=20
)

4. 域名关系工具

• 名称：get_domain_relationship
• 描述：查询域名的特定关系类型，支持分页
• 参数：
  • domain（必需）：要分析的域名
  • relationship（必需）：要查询的关系类型
    • 可用关系：caa_records, cname_records, comments, communicating_files, downloaded_files, 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
  • limit（可选，默认：10）：要检索的相关对象的最大数量（1-40）
  • cursor（可选）：分页继续游标
• 示例：

await get_domain_relationship(
    domain="example.com",
    relationship="historical_ssl_certificates",
    limit=20
)

5. 高级搜索工具

• 名称：advanced_corpus_search
• 描述：使用VT情报查询语法在VirusTotal数据集中执行高级搜索
• 参数：
  • query（必需）：VT情报搜索查询字符串
  • limit（可选，默认：20）：每页返回的结果最大数量
  • cursor（可选）：分页继续游标
  • descriptors_only（可选）：如果为true，则仅检索对象描述符而不是完整对象
• 示例：

await advanced_corpus_search(
    query="type:peexe size:100kb+ positives:5+",
    limit=20,
    cursor=None
)

要求

• Python >= 3.11
• 有效的VirusTotal API密钥
• 必需的Python包：
  • aiohttp >= 3.9.0
  • mcp[cli] >= 1.4.1
  • python-dotenv >= 1.0.0
  • typing-extensions >= 4.8.0

错误处理

服务器包含对以下情况的全面错误处理：

• 无效的API密钥
• 速率限制
• 网络错误
• 无效的输入参数
• 无效的哈希格式
• 无效的IP格式
• 无效的URL格式
• 无效的关系类型
• 分页错误

开发

要在开发模式下运行：

python -m virustotal_mcp

贡献

1. 分支仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m '添加惊人的功能'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开拉取请求

许可证

本项目根据Apache许可证2.0发布 - 详情见LICENSE文件。

致谢

• VirusTotal提供API和威胁情报平台
• MCP项目提供服务器框架
• 贡献者和维护者

支持

如有需要，请：

1. 查看文档
2. 搜索现有问题
3. 如有必要，创建新问题

安全

• 切勿提交API密钥或敏感凭证
• 使用环境变量进行配置
• 在处理威胁情报数据时遵循最佳安全实践