[开源] API语义异常检测网关：面向医保与安全团队的实时请求风控系统，基于多维规则+时间序列建模识别薅羊毛与误操作
本项目是一个嵌入在API网关链路中的语义级异常检测中间件，专为医院信息科、医保办和网络安全团队设计，解决「日志有流量、但看不出业务逻辑是否异常」的盲区问题。它不替代传统WAF或日志审计，而是在路由转发阶段同步解析请求内容，对患者ID、计费项、医嘱类型、时间戳等字段做跨维度语义关联分析，比如同一患者10分钟内触发37次西药计费、凌晨2点批量提交手术医嘱、连续5次调用高值耗材接口却无对应诊断编码。系统输出结构化可疑日志，并通过CLI命令行与Web看板双通道提供实时告警、聚合统计与规则配置能力。技术上采用TypeScript构建核心引擎、CLI与Web服务，Python（pandas）承担日志格式适配与轻量时序计算，支持JSON/XML/Text自动识别，告警可推送至钉钉、企业微信与邮件。
定位与能力范围
我们不做通用日志平台，也不做离线批处理分析。本项目的边界非常明确：只处理已进入API网关的、结构化或半结构化HTTP请求日志，且聚焦三类高价值语义异常：
- 计费异常
：同一患者短周期高频计费、非诊疗时段集中开单、计费项目与历史就诊模式显著偏离；
- 医嘱异常
：非常规时间提交医嘱、无前置检查即开高风险药品、医嘱组合违反临床路径逻辑；
- 时间序列异常
：请求节奏突变（如RPS从5骤升至200）、周期性行为断裂（如每日早8点定时调用突然中断3天后爆发式补调）。
这些不是靠正则或阈值能覆盖的场景，必须结合业务实体（患者、科室、药品）与上下文（时间窗、调用链、前后置动作）建模。因此系统不提供原始日志存储，也不对接HIS底层数据库；它只消费网关导出的标准日志流，输出「该不该人工复核」的判断结论。
核心功能模块
系统能力按数据流向组织为五个协同层，每层职责清晰、松耦合、可独立启用或调试：
模块 | 职责说明 | 典型输入 | 输出形态 |
|---|---|---|---|
日志适配层 | 自动识别JSON/XML/Text格式，提取timestamp、patientId、endpoint、body等关键字段，统一转为内部Schema | 原生日志文件或标准输入流 | 规范化事件对象（含字段类型校验） |
语义分析引擎 | 加载预置规则集（如 | 规范化事件 + 配置阈值 | 异常评分（0–100）、异常类型标签、触发规则ID |
告警管理器 | 对引擎输出做分级（INFO/WARN/HIGH/CRITICAL）、聚合（同患者同规则5分钟内仅报1次）、抑制（连续相同告警去重） | 异常事件流 | 告警摘要对象（含唯一ID、聚合计数、首次/末次时间） |
CLI工具集 | 提供 | 终端指令 + 参数 | 控制台日志、JSON结果、退出码 |
Web看板 | 实时展示告警列表、TOP5异常类型分布、小时级RPS热力图、规则命中率趋势、PDF报告生成入口 | HTTP请求 | 浏览器渲染界面（无需额外部署前端服务） |
所有模块均围绕「让一线人员快速定位真问题」设计：医保办同事可直接用batch扫上周门诊日志找疑似套保线索；安全工程师用monitor盯住灰产IP的实时行为；信息科用Web看板导出月度异常报告交院务会。
使用与配置流程
入门只需三步，全程无编译、无Docker、不改网关代码：
npm installnpx api-semantic-guardian serve访问 http://localhost:3000 即可见告警看板。此时系统已加载默认规则（含计费突增、夜间医嘱等6条基础策略），等待日志输入。
日常使用分三类场景：
调试单条请求：复制网关日志中任意一行JSON，执行
npx api-semantic-guardian analyze --json '{"timestamp":"2024-01-01 10:00:00","patientId":"P001","endpoint":"/api/billing","body":{"itemId":"MED001","qty":1}}'输出含异常类型、评分、匹配规则名及建议动作（如“建议核查该患者近3日是否重复挂号”）。批量回溯分析：将导出的日志文件（
.json/.xml/.log）放入data/examples/目录，运行npx api-semantic-guardian batch ./data/examples/*.json结果自动生成report_20240101.json，含各规则触发次数、TOP10高危患者清单。生产环境监控：指定网关输出的实时日志文件（如
/var/log/nginx/access.log），启动持续监听npx api-semantic-guardian monitor --watch-file ./logs/access.log所有告警同步推送到配置的钉钉群，Web看板实时刷新。
全部配置集中于data/config.json，可通过CLI交互式修改：
api-semantic-guardian config set rules.billing_burst.window_minutes 15 api-semantic-guardian config set alerting.dingtalk.webhook https://oapi.dingtalk.com/...工程结构与技术选型依据
目录结构严格反映职责分离原则：
src/ ├── adapter/ # 纯函数式解析器，无副作用，支持扩展新格式（如HL7） ├── engine/ # 规则引擎核心，每个规则为独立TS类，实现check()与explain() ├── rules/ # 内置规则定义（计费/医嘱/时间三类），支持JSON配置开关 ├── cli/ # Commander.js封装，命令即模块，便于测试与复用 └── web/ # Express服务，静态资源内嵌，无外部依赖 python/ # 仅用于适配层：pandas处理XML/Text的复杂嵌套与时序对齐选型决策基于真实交付约束：
用TypeScript而非Go/Rust：因医院信息科运维人员普遍熟悉Node.js生态，CLI可直接
npx运行，免安装全局二进制；Python仅限适配层：pandas对非标准日志（如带HTML标签的Text日志、属性嵌套过深的XML）解析效率远超JS原生库，且与现有ETL脚本兼容；
不用Kafka/Flink：目标场景是单机或小集群日志流（日均<5GB），内置内存队列+滑动窗口已满足毫秒级响应；
Web服务不分离前端：所有静态资源打包进Node进程，避免Nginx反向代理配置门槛，适合信息科自助部署。
数据与扩展机制
系统不强制要求日志字段全量，而是按需映射。只要日志含以下任一字段组合，即可启用对应检测：
检测类型 | 必需字段 | 可选增强字段 | 说明文档示例字段 |
|---|---|---|---|
计费异常 | patientId, | body.itemId, | patientId须为字符串， |
医嘱异常 | patientId, | body.orderType, | orderType值域预设 |
时间序列 | timestamp, | responseTime, | 支持按IP或患者做滑动窗口聚合 |
新增规则只需在src/rules/下新建TS类，实现RuleInterface，并在rules/index.ts注册；新增日志格式只需在src/adapter/写解析器，注入到AdapterFactory。所有扩展无需重启服务，CLI命令rules reload可热加载。
限制与说明
本系统明确不覆盖以下场景，避免用户预期偏差：
不替代WAF：不检测SQL注入、XSS等协议层攻击，仅分析业务语义；
不对接数据库：不查询患者历史就诊记录，所有判断基于当前日志上下文窗口（默认15分钟）；
不提供根因分析：告警仅指出“此处可疑”，不自动关联HIS系统查医生工号或设备编号；
不支持分布式追踪：不解析OpenTracing头，仅处理单条HTTP请求日志。
规则精度依赖日志质量：若网关未透传patientId或时间戳为服务器本地时间（非客户端采集时间），检测效果将下降。建议在网关侧统一添加X-Patient-ID与X-Request-Time头。详细字段要求与常见问题排查指引见项目文档中的《日志接入规范》章节。
项目地址：
https://github.com/nexorin9/api-semantic-guardian