cognis-digital/canarynet
GitHub: cognis-digital/canarynet
一款自托管的金丝雀令牌网络工具，通过生成和监控多种类型的诱饵凭证来检测未授权访问和入侵行为。
Stars: 0 | Forks: 0
# CANARYNET — 自托管 canary token 网络 — AWS keys、DNS、文档、Web URL
[](https://pypi.org/project/cognis-canarynet/)
[](https://github.com/cognis-digital/canarynet/actions)
[](LICENSE)
[](https://github.com/cognis-digital)
**自托管 canary token 网络 — AWS keys、DNS、文档、Web URL。**
*蓝队 / 防御 — 为小团队提供的检测、欺骗与监控。*
## 使用 — 分步指南
1. **安装** `canarynet` 命令：
pip install cognis-canarynet # 或者：从该 repo 运行 pip install -e .
2. **生成 token。** `new TYPE LABEL` 会将 token 持久化保存到存储中（`TYPE` 可以是 `aws`、`dns`、`web` 或 `doc`）；将生成的工件放置在入侵者可能会发现的地方：
canarynet new aws "prod-backup-keys"
canarynet new web "internal-wiki-link" --base-url https://canary.example.com
3. **检查存储** — 列出所有 token，或者显示特定 token 的完整材料：
canarynet list
canarynet show
4. **扫描日志** 以查找被触发的 token；当任何 canary 触发时，`scan` 会以退出码 `2` 结束，以便 cron/CI 能够做出反应：
canarynet scan /var/log/auth.log /var/log/nginx/access.log
5. **自动化检测。** 使用 `--format json`（并使用 `--store` 指定 token 文件）来获取机器可读的输出，并根据退出码来设置警报触发：
canarynet --format json scan /var/log/*.log || echo "CANARY TRIGGERED"; alert.sh
## 为什么
安全和情报团队需要自托管的 canary token 网络 — AWS keys、DNS、文档、Web URL，而无需搭建繁重的基础设施。`canarynet` 是单一用途、可脚本化、对 CI 友好且可自托管的：将其指向目标，即可获取以您的工作流所使用的格式（表格、JSON、SARIF、HTML）输出的优先级排序结果，并在需要其自主运行时通过 MCP 将其接入 agents。
## 安装
```
pip install cognis-canarynet
# 或者，从这个 repo：
pip install -e ".[dev]"
```
## 快速开始
```
canarynet --version
canarynet scan demos/ # run against the bundled demo
canarynet scan demos/ --format sarif --out r.sarif --fail-on high
canarynet scan demos/ --format html --out report.html
canarynet mcp # expose as an MCP server (Cognis.Studio / Claude Desktop / Cursor)
```
## 内置演示场景
每个场景文件夹都包含一个 `SCENARIO.md`，用于描述情境和预期结果。
- [`demos/01-aws-key-honeytoken-tripped/`](demos/01-aws-key-honeytoken-tripped/SCENARIO.md)
- [`demos/01-basic/`](demos/01-basic/SCENARIO.md)
- [`demos/02-document-canary-tripped/`](demos/02-document-canary-tripped/SCENARIO.md)
- [`demos/03-mixed-status/`](demos/03-mixed-status/SCENARIO.md)
## 输出格式
- **表格**（默认）— 人类可读的终端摘要
- **JSON** — 供 pipeline 使用的机器可读结果
- **SARIF** — 可直接接入 GitHub 代码扫描 / IDE 问题面板
- **HTML** — 包含严重性汇总的可共享报告
## 它如何融入 Cognis Neural Suite
`canarynet` 是 [Cognis Neural Suite](https://github.com/cognis-digital) 中 **52 个工具**之一。每个工具都提供了一个 MCP server，因此 [Cognis.Studio](https://cognis.studio) 的 agents 可以将它们作为受限范围内的能力进行调用。
**`blue-team` 中的同级工具：** [`sentrylog`](https://github.com/cognis-digital/sentrylog)、[`edrgap`](https://github.com/cognis-digital/edrgap)、[`phishforge`](https://github.com/cognis-digital/phishforge)、[`sbomgate`](https://github.com/cognis-digital/sbomgate)、[`honeytrace`](https://github.com/cognis-digital/honeytrace)
## 架构与路线图
- 设计说明：[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
- 规划工作：[`ROADMAP.md`](ROADMAP.md)
## 互操作性
`canarynet` 可与超过 300 个工具的 Cognis suite 组合使用 — JSON 输入/输出以及共享的
兼容 OpenAI 的 `/v1` 主干。请参阅 **[INTEROP.md](INTEROP.md)** 以获取
suite 映射、组合模式和参考技术栈。
## 集成
通过 [`cognis-connect`](https://github.com/cognis-digital/cognis-connect) 将 `canarynet` 的发现结果转发至 STIX/MISP/Sigma/Splunk/Elastic/Slack/webhooks。
请参阅 **[INTEGRATIONS.md](INTEGRATIONS.md)**。
## 许可证
在 **Cognis Open Collaboration License (COCL) v1.0** 下开源 — 可免费用于个人、内部评估、研究和教育用途；**商业 / 生产环境使用需要许可证** (licensing@cognis.digital)。请参阅 [LICENSE](LICENSE)。
## 负责任的使用
这是双用途安全软件。仅对您拥有或获得明确书面授权进行测试的系统、数据和身份使用它，并遵守适用法律。
## 关于
**[Cognis Digital](https://cognis.digital)** — 美国怀俄明州 · *让明天更美好：高级网络安全、AI 创新与区块链专业知识。*
标签：PFX证书, Python, StruQ, 攻击检测, 无后门, 蜜罐, 证书利用, 逆向工具, 防御欺骗