Polichombr项目API接口详解与使用指南

项目概述

Polichombr是一个专业的恶意软件分析平台，提供了一套完整的HTTP API接口，方便用户以编程方式与平台交互。本文将从技术角度深入解析Polichombr的API设计、功能特性以及实际应用场景，帮助安全研究人员和开发人员更好地利用这套接口进行恶意软件分析工作。

API基础配置

Polichombr的API采用RESTful风格设计，所有接口均通过/api/1.0/端点提供服务。API支持JSON格式的数据交换，POST请求必须使用JSON格式传递参数。

认证机制

Polichombr采用基于令牌(Token)的认证方式，工作流程如下：

1. 用户首先需要向/auth_token端点提交API密钥
2. 服务器验证通过后返回一个临时令牌
3. 后续请求需要在HTTP头中添加X-Api-Key字段携带该令牌
4. 如果令牌无效，服务器将返回401错误

这种认证机制既保证了安全性，又便于自动化脚本的编写和执行。

样本管理接口

样本上传与查询

创建新样本(POST /samples/)

• 支持multipart/form-data格式上传
• 必需参数：
  • file: 样本文件数据(需使用文件对象格式)
  • filename: 原始文件名
• 可选参数：
  • tlp_level: 样本敏感度级别(参考models.py中的枚举定义)

获取样本列表(GET /samples/)

• 返回系统中所有样本的基本信息

获取特定样本信息

• /samples/<hash>/: 通过MD5/SHA1/SHA256哈希值查询样本
• /samples/<int:sid>/: 通过样本ID获取详细信息

样本分析数据获取

Polichombr提供了丰富的样本分析数据接口：

1. 样本下载

   • /samples/<int:sid>/download/: 获取样本原始二进制文件

2. 家族关联

   • /samples/<int:sid>/families/: 查询样本所属的恶意软件家族

3. 摘要信息

   • /samples/<int:sid>/abstract/: 获取样本的分析摘要

4. 匹配信息

   • /samples/<int:sid>/matches/: 获取样本的匹配信息

5. 命名信息

   • /samples/<int:sid>/names/: 获取样本中重命名的函数
   • 支持按地址或时间戳过滤查询
   • 时间戳格式要求：%Y-%m-%dT%H:%M:%S.%f

6. 注释信息

   • /samples/<int:sid>/comments/: 获取样本中的注释
   • 同样支持地址和时间戳过滤

7. 结构体信息

   • /samples/<int:sid>/structs/: 获取样本中定义的结构体

恶意软件家族管理

家族查询与创建

获取所有家族(GET /families/)

• 返回完整的家族层次结构
• 包含每个家族的以下信息：
  • TLP敏感度级别
  • 摘要(Markdown格式)
  • 家族ID和名称
  • 父家族ID(如果是子家族)
  • 关联样本列表
  • 子家族列表
  • 关联用户信息

创建新家族(POST /family/)

• 必需参数：
  • name: 家族名称
• 可选参数：
  • parent: 父家族名称(用于创建子家族)
  • tlp_level: 敏感度级别
• 返回创建的家族ID

YARA规则管理

规则查询与创建

获取所有规则(GET /yaras/)

• 返回系统中所有YARA规则的详细信息，包括：
  • 规则ID和名称
  • 创建时间
  • 原始规则内容
  • 版本号
  • TLP敏感度级别

创建新规则(POST /yaras/)

• 必需参数：
  • name: 规则名称(需唯一)
  • rule: YARA规则文本
• 可选参数：
  • tlp_level: 敏感度级别
• 返回创建的规则ID

函数匹配接口

Machoc哈希匹配(GET /machoc/)

• 通过Machoc哈希值查询匹配的函数
• 参数：Machoc哈希值(整数形式)
• 返回匹配的函数列表，包含：
  • 函数地址
  • 函数ID
  • Machoc哈希值
  • 函数名称
  • 所属样本ID

最佳实践与使用技巧

1. 批量处理样本

   • 结合样本上传和家族关联接口，可以自动化处理大量样本
   • 先上传样本，获取样本ID后再关联到相应家族

2. 时间戳过滤

   • 在分析大型样本时，可以利用时间戳过滤只获取最新的分析数据
   • 特别适合持续监控样本分析进度

3. YARA规则管理

   • 建议将常用检测规则存储在Polichombr中
   • 通过版本号追踪规则变更历史

4. 函数匹配分析

   • 利用Machoc哈希匹配可以快速发现样本间的代码复用
   • 适用于家族关联分析和变种检测

总结

Polichombr的API设计全面考虑了恶意软件分析的实际需求，从样本管理到分析结果查询，再到家族关联和规则管理，提供了一套完整的编程接口。通过合理利用这些接口，安全研究人员可以构建自动化分析流程，提高工作效率。本文详细介绍了各接口的功能和使用方法，希望能为使用者提供有价值的参考。