开发文档 | 迪妙网络·蜜罐研究中心

01 · 系统分层

代码结构与数据流向

前端 H5/JS五页面 · 零CDN依赖
API离线自动切离线快照

→

接口层 PHP7.4config.php公共函数
events/honeypots/stats/intel

→

采集层 collect.php令牌鉴权 · 字段收敛
jsonl留档 · 环形缓冲

→

情报管道 FeedFetcher多渠道拉取 · 镜像回退
归一化 · 去重合并

→

数据层data/*.json
data/cache/ logs/*.jsonl

02 · API 参考

接口全集

端点	方法	鉴权	说明
/api/events.php	GET	无	事件查询，参数 limit(≤200)、since(时间戳增量轮询)
/api/honeypots.php	GET	无	蜜罐节点状态列表
/api/stats.php	GET	无	KPI统计；今日攻击数由事件流实时校准
/api/intel.php	GET	无	合并IOC情报+数据源健康度，limit(≤1000)
/api/collect.php	POST	X-HP-Token	事件采集入口（HFish/探针/webhook）
/scripts/fetch_feeds.php	CLI	仅CLI	情报源定时拉取（crontab调用，Web访问返回403）

collect.php 请求契约

字段	类型	约束
src_ip 必填	string	合法IPv4/IPv6
src_geo	string	归属地，可空
dst_service / dst_port	string / int	如 SSH/22
attack_type	string	≤32字符
severity	int	1-3，越界自动收敛
honeypot	string	对应 honeypots.json 节点ID
payload	string	≤512字符，自动截断

探针上报示例（Python SDK）

import requests

TOKEN = "你的collect_token"
URL   = "https://mi.dimiao.cn/api/collect.php"

def report(src_ip, service, port, atype, sev, payload=""):
    requests.post(URL,
        headers={"X-HP-Token": TOKEN},
        json={"src_ip": src_ip, "dst_service": service,
              "dst_port": port, "attack_type": atype,
              "severity": sev, "honeypot": "hp-ssh-01",
              "payload": payload[:512]},
        timeout=5)

# report("185.220.101.45","SSH",22,"暴力破解",2,"root/123456")

03 · 情报管道

FeedFetcher 工作机制

TTL判断
缓存未过期直接复用（feeds.json 每源独立ttl），降低对上游的压力、遵守各源抓取条款。
镜像链回退
按 urls 数组顺序尝试，首个2xx响应即采用（如 FireHOL 走 jsDelivr，GitHub Raw 作回退）。
解析归一化
四种解析器（iplist/netset/json/csv）输出统一结构：ioc / type(ip·cidr·url) / feed / threat / confidence / first_seen。
去重合并
按IOC去重后写入 merged_ioc.json（上限5000条），intel.php 直接服务，前端零解析负担。
可观测性
每次拉取写入 logs/feeds.log；api/intel.php 附带各源条目数与最近刷新时间，页面上可视化健康度。

新增一个数据源（零代码示例）

// 编辑 data/feeds.json，在 feeds 数组追加：
{
  "id": "my_feed",
  "name": "我的情报源",
  "format": "iplist",          // iplist | netset | json | csv
  "ttl": 3600,
  "confidence": "中",
  "threat": "自定义威胁类型",
  "urls": ["https://example.com/list.txt", "https://mirror.example.com/list.txt"]
}
// 然后执行：php scripts/fetch_feeds.php，页面自动生效

04 · 安全设计规范

二次开发必须遵守

平台侧

collect.php 已做令牌鉴权与字段收敛，新增接口必须复用 config.php 的 hp_response 输出
任何写文件操作必须经 .tmp 临时文件 + rename 原子写入
接口层不得直接暴露文件路径参数（防路径穿越）
fetch_feeds.php 仅CLI可执行（PHP_SAPI 校验）
上游内容一律视为不可信输入：IP/URL格式白名单校验后才入库

蜜罐侧（部署红线）

蜜罐网络与业务网隔离，出口仅放行分析服务器
仅观测诱捕，不做反控、不反打、不主动触碰攻击源
高交互沙箱容器与任何内网零连接
遵守《网络安全法》《数据安全法》及情报源使用条款
完整法律条款见 docs/DISCLAIMER.md

05 · 前端开发规范

新增页面/功能的落点

新增页面
复制任一页面的 nav/footer 骨架（本目录五个页面同构）；页面专属逻辑在 honeypot.js 的 DOMContentLoaded 中按元素存在性分发，所有初始化函数均已采用该模式，天然互不影响。
新增统计接口
api/ 下新建 xxx.php → require config.php → hp_read_json 读数 → hp_response 输出；前端 fetchJSON 自动兼容，无需改动架构。
图表需求
优先纯CSS/Canvas实现（本平台环图与态势图均为零依赖实现），必须引库时遵循官网引擎多源回退模式。

06 · 版本路线图

迭代规划

版本	目标	关键交付
v1.0 当前	平台基线	五页面、一键安装（脚本/向导/Compose）、多渠道情报管道、采集接口、离线兜底
v1.1	真实接入	HFish集群接入、离线GeoIP归属地、节点心跳自动上下线
v1.2	分析引擎	攻击聚类、IOC自动提取去重、与威胁情报社区API直推
v2.0	生态闭环	演练场景自动生成、观测员账号体系（api/lib/Auth.php）、月报自动产出

蜜罐开发文档