HTTP API 参考

IconHash 服务器提供 9 个 RESTful 端点，覆盖哈希、发现、查询与指纹管理。

端点总览

9 个端点 RESTful 部分需认证

IconHash 服务器提供 9 个 RESTful 端点，覆盖 哈希 / 发现 / 查询 / 指纹管理 四大类能力。下图按访问约束将端点分为公开、哈希、查询、AI 集成四组。

认证机制

可选 Bearer / Query

两种传递 token 的方式：

方式一：通过 Authorization Header（推荐）

curl -H "Authorization: Bearer your-token" http://localhost:8000/hash/url?url=...

Header 方式不会把 token 写入 URL 日志，生产环境优先使用。

方式二：通过 Query 参数

curl "http://localhost:8000/hash/url?url=...&token=your-token"

适合临时调试、浏览器直接访问等不便设置 Header 的场景；token 会出现在 URL 中，注意日志泄露风险。

认证规则

• 认证可选：仅当以 --auth-token 启动服务器时才启用
• /health 端点始终免认证，便于健康探活
• token 校验失败统一返回 401

---

端点详情

GET /health — 健康检查 公开 无需认证

curl http://localhost:8000/health

{ "status": "ok", "version": "v2.0.0" }

用途

常用于负载均衡器、Kubernetes liveness/readiness 探针或监控系统周期性探活，不消耗指纹库，可高频调用。

---

GET|POST /hash/url — 从 URL 哈希 需认证 常用

参数	位置	说明
url	query/body	图标 URL
format	query	输出引擎格式
uint32	query	uint32 哈希

curl "http://localhost:8000/hash/url?url=https://example.com/favicon.ico&format=shodan"

{
  "hash": -1161367058,
  "uint32": 3133600238,
  "fingerprint": { "service": "nginx", "tags": ["web"] },
  "search": { "shodan": "http.favicon.hash:-1161367058" }
}

返回字段速查

• hash：MurmurHash3 的 有符号 int32（与 FOFA/Shodan 口径一致）
• uint32：同一哈希的无符号表示，便于跨语言处理
• fingerprint：命中内置 700+ 指纹库时返回，否则缺省
• search：按 format 拼好的搜索引擎查询串，可直接粘贴

---

POST /hash/file — 从上传文件哈希 需认证 multipart

curl -X POST http://localhost:8000/hash/file \
  -F "file=@favicon.ico"

文件限制

• 表单字段名必须为 file
• 文件过大可能被服务器拒绝，建议上传图标尺寸的文件（通常 < 1MB）
• 支持 .ico / .png / .svg / .gif 等常见图标格式

---

POST /hash/base64 — 从 base64 哈希 需认证 无网络下载

curl -X POST http://localhost:8000/hash/base64 \
  -H "Content-Type: application/json" \
  -d '{"data":"AAABAA..."}'

适用场景

当图标字节流已在本地（例如从数据库、缓存或抓包结果中获取），可跳过 /hash/url 的下载环节，直接提交 base64 进行哈希。不会触发外部网络请求，速度最快。

---

POST /hash/batch — 批量哈希 需认证 并发

curl -X POST http://localhost:8000/hash/batch \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://a.com/favicon.ico", "https://b.com/favicon.ico"]}'

批量调用建议

• 单次建议 ≤ 50 个 URL，避免下游限流或超时
• 响应为 JSON 数组，顺序不保证与请求一致，按 hash 字段自行对账
• 单条失败不影响其他条目，失败项会标注 error 字段

---

GET|POST /hash/discover — 发现图标 需认证 站点级

curl "http://localhost:8000/hash/discover?url=https://example.com"

返回网站所有图标 URL 列表（含哈希）。

发现策略

该端点会综合三种来源：HTML 中的 <link rel="icon|shortcut icon"> 标签、apple-touch-icon，以及根路径 /favicon.ico 的主动探测。多源交叉保证不漏掉隐藏图标。

---

GET|POST /lookup — 指纹查询 需认证 纯查询

curl "http://localhost:8000/lookup?hash=-1161367058"

{
  "hash": -1161367058,
  "found": true,
  "fingerprint": {
    "service": "nginx",
    "category": "web-server",
    "tags": ["nginx"]
  }
}

与 /hash 的区别

/lookup 只查不下载：输入已有哈希值，纯查指纹库。若你已有图标 URL 且想一步到位，直接用 /hash/url 即可；若只是反查某条已知哈希对应的组件，用本端点更轻量。

---

GET /fingerprints — 浏览指纹库 需认证 只读

# 列出
curl "http://localhost:8000/fingerprints"

# 搜索
curl "http://localhost:8000/fingerprints?q=nginx"

用法说明

• 不带 q 参数时返回指纹库分页列表
• 带 q 参数时按 service / tags 等字段模糊匹配
• 该端点为只读，不会修改指纹库；如需更新库，参考 指纹管理

---

POST /mcp — MCP 端点 需认证 MCP 协议

标准 MCP 协议入口，详见 MCP 集成。

与 REST 端点的关系

/mcp 是给 AI 客户端（如 Claude）调用的 MCP JSON-RPC 入口，内部复用 /hash/* 与 /lookup 的核心能力。REST 集成用上方各端点即可，AI 集成走本端点。

---

响应格式

统一 JSON format 可选

所有端点统一返回 JSON。format 参数控制哈希输出格式：

字段约定

• 基础字段（hash / uint32）：所有哈希类端点必返回
• 指纹字段（fingerprint）：仅在命中内置 700+ 指纹库时出现
• 搜索字段（search）：键名随 format 变化，如 fofa → icon_hash=、shodan → http.favicon.hash:

错误码

4xx/5xx JSON body

HTTP 状态	含义
200	成功
400	请求参数错误
401	未认证或 token 无效
404	资源不存在
500	服务器内部错误

排查建议

• 400：检查 url / format 等参数是否缺失或拼写错误
• 401：确认服务器是否启用 --auth-token，以及 token 是否通过 Authorization: Bearer 或 ?token= 正确传递
• 404：常见于 /lookup 查询的哈希在指纹库中不存在（此时也可能返回 200 + found:false，以实际实现为准）
• 500：查看服务器日志，可能是图标下载失败、上游站点超时等

---

下一篇：MCP 集成。