内容
# 受管安全狩猎（GSH）框架
[](LICENSE)
[](https://github.com/sunilgentyala/gsh-framework)
[](https://github.com/sunilgentyala/gsh-framework#research)
[](https://sunilgentyala.github.io/gsh-framework/)
[](https://atlas.mitre.org/)
[](https://www.nist.gov/cyberframework)
[](https://github.com/sunilgentyala/gsh-framework/stargazers)
**作者：** 孙毅 IEEE高级会员 | HCLTech 网络安全和人工智能安全顾问
**联系方式：** [sunil.gentyala@ieee.org](mailto:sunil.gentyala@ieee.org)
**网站：** [sunilgentyala.github.io/gsh-framework](https://sunilgentyala.github.io/gsh-framework/)
**许可证：** [Apache 2.0](LICENSE)
---
大多数企业安全栈并非为应对自主人工智能代理创建的威胁而设计。端点代理无法监控LLM网关的活动。安全信息和事件管理（SIEM）系统缺乏针对多代理工具调用链的基线。GSH框架弥补了这一空白。
GSH是一个开源的研究成果，用于自主人工智能威胁狩猎。它提供了结构化的检测剧本、行为基线逻辑和策略驱动的强制引擎（Sovereign Sentinel），适用于认知网络领域：大型语言模型、自主代理和多代理流水线与企业基础设施交互的运营层。
所有检测信号都映射到MITRE ATLAS和NIST CSF 2.0，为从业者提供了与框架一致的覆盖范围，他们可以立即实施。
---
## 当前状态
狩猎剧本、检测逻辑、阈值和策略模式已完成并记录。
**Hunt-001至Hunt-004** (`scripts/gsh-sentinel-deploy.py`, `scripts/gsh-probe-eval.py`) 实现了完整的基线、偏移评分和ZTLV强制逻辑端到端，但附带一个**合成遥测生成器**（在脚本输出中明确标记为`SIMULATION MODE`，在源代码中标记为`# Replace this block`），以便您可以在没有实时环境的情况下先查看检测逻辑。 将 `--target` 连接到真正的LLM网关事件流是您在实际执行前完成的集成步骤。
**Hunt-005** (`adapters/mcp_proxy.py`, `scripts/gsh-mcp-proxy.py`) 不同：它是真正的MCP JSON-RPC stdio代理，拦截**实际**工具定义和工具调用 在真正的MCP主机和真正的MCP服务器之间 - 批准时间模式哈希、偏移检测、语义中毒扫描和每次调用强制（许可/警报/阻止）都在实时流量上运行，而不是合成数据。参见 `tests/test_mcp_proxy.py` 以获取CLI的端到端子进程测试。已知缺陷：金丝雀/响应不对称比较和工具返回值的扫描尚未实现（参见 `playbooks/hunt-005-mcp-tool-poisoning.md` 第5.2节了解详细信息），并且仅支持stdio传输（不支持流式HTTP/SSE MCP服务器）。
**SIEM输出** (`adapters/splunk_hec.py`, `adapters/elastic_bulk.py`, `adapters/windows_eventlog.py`) 也是真实的： 在您的策略YAML中设置 `siem_output: splunk`、`siem_output: elastic` 或 `siem_output: windows_eventlog` （参见 `configs/sentinel-policy-default.yaml`），`gsh-sentinel-deploy.py` 和 `gsh-mcp-proxy.py` 都会将发现结果发送到那里（Splunk HEC / Elasticsearch `_bulk` 通过真正的HTTP，或本地Windows应用程序事件日志中的注册源）。如果发送失败或未配置，总是会回退到本地文件输出 - 永远不会静默丢弃发现结果。 Windows事件日志适配器仅适用于Windows，需要`pywin32`；在其他平台上（或没有`pywin32`），它会记录警告并像其他未配置的目标一样回退。 参见 `tests/test_siem_adapters.py` 和 `tests/test_windows_eventlog.py` （后者包括一个测试，写入真正的事件并读取它，而不仅仅是模拟的事件）。
**LangChain遥测** (`adapters/langchain_callback.py`) 是第四个真实集成：`GSHCallbackHandler` 通过 `config={"callbacks": [handler]}` 附加到任何LangChain `Runnable`/代理，并根据Hunt-001/Hunt-004阈值评估真实工具调用率、令牌速度、未经授权的工具调用和可疑调用参数 - 没有合成数据。 **重要限制：** LangChain回调处理程序是通知钩子，而不是门控 - 默认情况下，LangChain会吞噬回调内部引发的异常，而不是停止工具调用，因此此适配器只能警报，永远不能阻止。 它发出的每个发现结果都明确标记为 `enforcement_mode: "alert_only"` 和 `action_taken: "ALERTED"`，无论策略模式如何。 它也无法看到DNS查询（Hunt-002）。 参见 `tests/test_langchain_callback.py`，针对 `langchain-core` 1.4.x进行测试。
参见 [开放问题](https://github.com/sunilgentyala/gsh-framework/issues) 以获取剩余工作（SARIF报告、Hunt-006剧本和Docker Compose演示）。
---
## 版本历史
完整的发行说明（包括每次发行的已知限制）都在 [发行页面](https://github.com/sunilgentyala/gsh-framework/releases) 上。 摘要：
| 版本 | 亮点 |
|---|---|
| [v1.5.0](https://github.com/sunilgentyala/gsh-framework/releases/tag/v1.5.0) | 真实的Windows应用程序事件日志输出适配器 (`adapters/windows_eventlog.py`)；可选，仅限Windows，安全无操作 |
| [v1.4.0](https://github.com/sunilgentyala/gsh-framework/releases/tag/v1.4.0) | 真实的LangChain回调适配器 (`adapters/langchain_callback.py`) 用于Hunt-001/Hunt-004遥测 - 仅限警报设计，因为LangChain回调无法阻止工具调用 |
| [v1.3.0](https://github.com/sunilgentyala/gsh-framework/releases/tag/v1.3.0) | 真实的Splunk HEC和Elastic批量SIEM输出适配器，通过共享调度器连接到Sentinel和MCP代理；失败/未配置的SIEM发送现在始终回退到本地文件输出 |
| [v1.2.0](https://github.com/sunilgentyala/gsh-framework/releases/tag/v1.2.0) | 真实的MCP JSON-RPC stdio代理用于Hunt-005 (`adapters/mcp_proxy.py`) - 模式哈希偏移检测、语义中毒扫描和针对实时MCP流量的实时每次调用强制 |
| [v1.1.0](https://github.com/sunilgentyala/gsh-framework/releases/tag/v1.1.0) | 完成Hunt-004（流氓代理）；添加Hunt-005（MCP供应链/工具中毒）作为剧本；启动项目网站 |
| v1.0.0-beta | 初始公开版本：Hunt-001至Hunt-003剧本、Sentinel参考脚本（合成遥测）、默认策略模式 |
---
## 框架组件
| 组件 | 描述 |
|---|---|
| **主权哨兵** | 与LLM网关一起部署的策略驱动行为强制代理 |
| **狩猎剧本** | 用于高风险人工智能威胁的结构化威胁检测剧本 |
| **DDI-AI融合** | 具有人工智能代理感知基线的DNS/DHCP/IPAM遥测层 |
| **零信任逻辑验证（ZTLV）门控** | 每调用一次的工具调用授权引擎 |
| **行为基线引擎** | 连续模型输出偏移检测和探针评估管道 |
---
## 狩猎剧本
| 剧本 | 威胁类别 | 严重程度 | 状态 |
|---|---|---|---|
| [Hunt-001](playbooks/hunt-001-agentic-loop-detection.md) | 代理循环 / 资源耗尽 | 高 | 活动 |
| [Hunt-002](playbooks/hunt-002-ddi-tunneling-anomaly.md) | DDI隐蔽通道 / DNS C2 | 关键 | 活动 |
| [Hunt-003](playbooks/hunt-003-model-poisoning-baseline.md) | 机器学习模型中毒 / 行为偏移 | 关键 | 活动 |
| [Hunt-004](playbooks/hunt-004-rogue-agent-detection.md) | 流氓代理 / 未授权工具使用 | 关键 | 活动 |
| [Hunt-005](playbooks/hunt-005-mcp-tool-poisoning.md) | MCP供应链 / 工具中毒 | 关键 | 活动 |
---
## 快速入门
### 1. 克隆仓库
```bash
git clone https://github.com/sunilgentyala/gsh-framework.git
cd gsh-framework
pip install -r requirements.txt
```
### 2. 审查Sentinel策略
```bash
cat configs/sentinel-policy-default.yaml
```
编辑它以设置您的组织名称、SIEM输出目标和出口允许列表，然后再部署。
### 3. 部署主权哨兵
在主动模式下启动以建立7天的行为基线，然后切换到标准强制：
```bash
python scripts/gsh-sentinel-deploy.py \
--target "llm-gateway-01" \
--mode passive \
--playbooks "hunt-001,hunt-002,hunt-003,hunt-004,hunt-005" \
--policy configs/sentinel-policy-default.yaml \
--baseline-window 7d
```
按原样发货，这会生成合成遥测（`SIMULATION MODE`，在启动时记录），以便您可以立即运行基线和评分逻辑。 替换脚本中注明的遥测生成块（真正的LLM网关/API指标或LangChain回调），以针对实时流量运行。
### 4. 运行MCP代理（Hunt-005 - 真实强制，非模拟）
与步骤3不同，此操作针对真实的MCP流量运行。 首先记录服务器工具定义的批准时间快照：
```bash
python scripts/gsh-probe-eval.py --mode mcp-snapshot \
--server "corp-tools-mcp-01" \
--server-cmd "npx -y @modelcontextprotocol/server-filesystem /srv/data"
```
然后配置您的MCP主机启动代理，而不是直接启动真正的服务器：
```bash
python scripts/gsh-mcp-proxy.py \
--server-cmd "npx -y @modelcontextprotocol/server-filesystem /srv/data" \
--server-id "corp-tools-mcp-01" \
--mode standard \
--baseline reports/baselines/mcp/corp-tools-mcp-01.json
```
代理将警报（或在 `--mode aggressive` 下阻止）定义偏移、毒害的工具描述、不可见的Unicode内容和未经授权的工具调用。 有关完整的检测逻辑，请参见 `playbooks/hunt-005-mcp-tool-poisoning.md`。
### 5. 将LangChain代理连接到Sentinel（真实遥测，仅限警报）
```bash
pip install langchain-core
```
```python
from adapters.langchain_callback import GSHCallbackHandler
handler = GSHCallbackHandler(
target="my-langchain-agent",
allowlist=["web_search", "calculator"], # 未列出的工具会立即触发警报
)
# 通过标准的LangChain回调配置将代理附加到任何LLM、工具或链：
llm.invoke(prompt, config={"callbacks": [handler]})
my_tool.invoke(args, config={"callbacks": [handler]})
handler.flush() # 在运行结束时评估任何部分窗口
```
这是仅限警报的，而不是强制 - 有关为什么LangChain回调处理程序不能可靠地阻止工具调用，请参见 `adapters/langchain_callback.py` 模块文档字符串。
### 6. 运行狩猎剧本
每个剧本都是一个自包含的Markdown文档，包含检测逻辑、数据源、MITRE ATLAS映射、分类决策树和响应操作。 从Hunt-001开始检测循环：
```bash
cat playbooks/hunt-001-agentic-loop-detection.md
```
---
## 研究
一篇涵盖完整技术原理、设计决策和威胁模型的配套研究论文正在准备中，尚未提交。 根据出版政策，手稿不包含在此仓库中。 如有研究查询，请联系 [sunil.gentyala@ieee.org](mailto:sunil.gentyala@ieee.org).
---
## 仓库结构
```
gsh-framework/
├── README.md
├── LICENSE
├── CITATION.cff
├── CONTRIBUTING.md
├── requirements.txt
├── adapters/
│ ├── mcp_proxy.py # 真实的MCP JSON-RPC代理（Hunt-005）
│ ├── langchain_callback.py # 真实的LangChain遥测，仅限警报（Hunt-001/004）
│ ├── splunk_hec.py # 真实的Splunk HTTP事件收集器输出
│ ├── elastic_bulk.py # 真实的Elasticsearch/OpenSearch _bulk输出
│ ├── windows_eventlog.py # 真实的Windows应用程序事件日志输出
│ └── siem_dispatch.py # 所有三个SIEM适配器使用的共享调度器
├── configs/
│ └── sentinel-policy-default.yaml
├── docs/
│ └── index.html # 项目网站（GitHub Pages）
├── playbooks/
│ ├── hunt-001-agentic-loop-detection.md
│ ├── hunt-002-ddi-tunneling-anomaly.md
│ ├── hunt-003-model-poisoning-baseline.md
│ ├── hunt-004-rogue-agent-detection.md
│ └── hunt-005-mcp-tool-poisoning.md
├── probes/
│ └── standardized-probe-set-v1.json
├── scripts/
│ ├── ddi-log-parser-ai.py
│ ├── gsh-mcp-proxy.py # adapters/mcp_proxy.py的CLI
│ ├── gsh-probe-eval.py
│ └── gsh-sentinel-deploy.py
├── tests/
│ ├── test_mcp_proxy.py
│ ├── test_siem_adapters.py
│ ├── test_windows_eventlog.py
│ ├── test_langchain_callback.py
│ └── fixtures/
│ ├── mock_mcp_server.py # 用于测试的最小MCP stdio服务器
│ └── mock_http_sink.py # 用于测试SIEM适配器的最小HTTP服务器
├── baselines/
└── reports/
```
---
## 威胁覆盖
| 威胁 | MITRE ATLAS | MITRE ATT&CK | NIST CSF 2.0 |
|---|---|---|---|
| 代理循环 / 资源耗尽 | AML.T0048, AML.T0040 | | DE.AE-02, DE.CM-01, RS.MI-01 |
| DDI隐蔽通道外泄 | AML.T0048, AML.T0051 | T1071.004, T1048, T1568 | DE.CM-01, DE.AE-04, PR.DS-01 |
| 机器学习模型中毒 / 行为偏移 | AML.T0020, AML.T0043, AML.T0044 | | ID.RA-01, DE.AE-02, DE.CM-06 |
| 流氓代理 / 未授权工具使用 | AML.T0051, AML.T0053, AML.T0054 | | PR.PS-04, DE.CM-01, RS.AN-03 |
| MCP供应链 / 工具中毒 | AML.T0010, AML.T0051, AML.T0053 | T1195 | ID.SC-04, PR.PS-04, DE.CM-06 |
---
## 贡献
欢迎安全从业者、人工智能安全研究人员和检测工程师。 在打开拉取请求之前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。
高优先级贡献包括：额外的狩猎剧本、精细的检测阈值以及LangChain、AutoGen、CrewAI和MCP主机平台的集成适配器。
---
## 引用
如果您在研究中使用GSH框架，请引用：
```bibtex
@misc{gentyala2026gsh,
author = {Gentyala, Sunil},
title = {受管安全狩猎（GSH）：用于防御认知网络领域的自主代理框架},
year = {2026},
howpublished = {开源研究成果，GitHub},
url = {https://github.com/sunilgentyala/gsh-framework}
}
```
---
## 安全漏洞
如果您在GSH框架本身中发现漏洞，请发送电子邮件至 [sunil.gentyala@ieee.org](mailto:sunil.gentyala@ieee.org)，主题为 `[GSH安全漏洞] - [简要描述]`。 不要公开的GitHub问题。 有关完整的责任披露政策，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
---
## 相关工作
- [ContextGuard](https://github.com/sunilgentyala/contextguard): Model Context Protocol（MCP）服务器安全零信任中间件。 精确率100%，召回率96.7%，F1 98.3%，延迟为1.005毫秒。
- [ARGUS](https://github.com/sunilgentyala/argus): LLM应用程序安全扫描器。
- IEEE高级会员简介： [ORCID 0009-0005-2642-3479](https://orcid.org/0009-0005-2642-3479)
连接信息
猜你喜欢
暂无推荐服务器