尧图网页设计 
Zulip Thinkst Canarytoken 集成将蜜罐令牌告警实时投递到 Zulip【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip导读Zulip 内置的Thinkst Canarytoken 集成允许你将 canarytokens.org 为核心骨架结合该集成在仓库中的视图实现、测试用例与示例负载完整讲解从创建机器人、生成 Webhook URL、在 canarytokens.org 上配置令牌到告警消息实际落地的全过程并深入剖析其底层消息渲染逻辑。读完本文你将能够独立完成该集成的配置、验证与消息格式定制。一、集成概览适用于 canarytokens.org 的公共蜜罐服务Zulip 为 Thinkst 生态提供了两套彼此独立的集成它们对应的 Webhook 服务虽然同名但请求负载schema完全不同切勿混淆集成适用服务仓库位置Canarytoken 集成canarytokens.orgThinkst 集成Thinkst 付费商业产品Canary 与 Canarytokenzerver/webhooks/thinkst/原文档开篇即强调这一点本集成仅面向 canarytokens.org 的免费公共令牌Thinkst 付费产品的告警请改用 Thinkst 集成。这一区分在源码层也有明确印证——api_canarytoken_webhook的文档字符串中注明Canarytokens from Thinksts paid product have a different schema而 zerver/webhooks/thinkst/view.py 则按AlertType字段区分 Canary 与 Canarytoken 两种事件。两个集成的view.py甚至引用了同一份 Thinkst 官方 schema 文档链接足见二者负载差异之大。从集成注册表看该集成在 zerver/lib/integrations.py 中被声明为IncomingWebhookIntegration(canarytoken, [monitoring], ...)显示名称为Thinkst Canarytokens归类于monitoring监控告警类别并以canarytoken_real.json作为截图示例负载——这意味着它在 Zulip 的集成目录/integrations/canarytoken中可供所有用户直接查阅配置步骤。二、配置步骤从机器人到令牌创建以下是完整的四步配置流程请严格按序操作。1. 创建 Incoming webhook 机器人在 Zulip 中创建一个Incoming webhook类型的机器人进入 Zulip 的设置页面按 添加机器人或集成 的指引创建机器人Bot type 必须选择Incoming webhook创建完成后保存页面展示的API key它是 Webhook URL 的鉴权凭证。这一步对应仓库中的共用模板 templates/zerver/integrations/include/create-an-incoming-webhook.md。2. 生成集成 URL决定该集成告警要投递到哪个频道并按 生成集成 URL 的指引生成专属 URL。URL 格式遵循 Zulip 标准 Webhook URL 规范详见 Webhook URL 规范形如https://your-zulip.example.com/api/v1/external/canarytoken?stream频道名api_key机器人API key其中/api/v1/external/canarytokencanarytoken 集成的固定端点路径{webhook_dir_name}即canarytokenstream接收告警的频道名可选缺省时使用机器人的默认频道api_key步骤 1 创建的机器人的 API key用于鉴权。URL 模板的精确格式可以在测试基类 zerver/lib/test_classes.py 中看到DEFAULT_URL_TEMPLATE /api/v1/external/{webhook_dir_name}?stream{stream}api_key{api_key}。另外还可以通过追加topic主题名参数来自定义告警消息的主题下文第 4 节详述。这一步对应共用模板 templates/zerver/integrations/include/generate-webhook-url-basic.md。3. 在 canarytokens.org 上创建令牌打开 canarytokens.org在Select your token选择令牌类型下拉框中选择你想要创建的Webhook 类型令牌在Provide an email address or webhook URL提供邮箱或 Webhook URL字段中粘贴步骤 2 生成的完整 URL填写一条reminder note备忘备注方便日后识别该令牌的用途点击Create my Canarytoken完成创建。4. 验证配置完成后触发一次令牌例如访问一次令牌指向的 URL即可在 Zulip 对应频道看到类似下面的告警消息原文档配图 static/images/integrations/canarytoken/001.png 展示了真实效果:alert: Canarytoken has been triggered on time:2020-06-09T14:04:4700:00! Canarytoken example Manage this canarytoken三、负载解析与消息渲染源码级原理收到 canarytokens.org 的 POST 请求后Zulip 侧的处理入口是 zerver/webhooks/canarytoken/view.py 中的api_canarytoken_webhook函数。整个处理链路如下canarytokens.org POST │ ▼ webhook_view(Canarytokens) ── 鉴权 校验 (zerver/decorator.py) │ ▼ typed_endpoint ── 解析 JSON bodyJsonBodyPayload[WildValue]与可选 topic 参数 │ ▼ api_canarytoken_webhook ── 提取 time / memo / manage_url构造消息正文 │ ▼ check_send_webhook_message ── 投递到目标频道与主题 (zerver/lib/webhooks/common.py) │ ▼ json_success ── 返回 200 JSON 成功响应1. 请求的三种关键字段从示例负载 zerver/webhooks/canarytoken/fixtures/canarytoken_new.json 与 zerver/webhooks/canarytoken/fixtures/canarytoken_real.json 可见canarytokens.org 发送的 POST 负载核心字段如下字段类型说明消息中的用途timestring触发时间格式YYYY-MM-DD HH:MM:SS (UTC)有时省略(UTC)显示为:alert:前缀后的时间戳memostring创建令牌时填写的 reminder note 备忘显示在时间戳下一行manage_urlstring管理该令牌的跳转链接渲染为Manage this canarytoken链接channelstring触发渠道如HTTP当前版本未渲染additional_dataobject补充信息src_ip、useragent、referer、location等当前版本未渲染值得说明的是负载中还携带了additional_data源 IP、User-Agent、Referer、地理位置与channel等字段但当前 Zulip 实现仅消费time、memo、manage_url三个字段来构造消息其余字段被忽略。2. 消息正文的构造逻辑核心渲染逻辑view.py非常精简topic_name canarytoken alert time message[time].tame(check_string) formatted_time datetime_to_global_time( datetime.fromisoformat(time.replace((UTC), ).strip() 00:00) ) body ( f**:alert: Canarytoken has been triggered on {formatted_time}!**\n\n f{message[memo].tame(check_string)} \n\n fManage this canarytoken}) )几点实现细节值得关注时间解析time字段先通过str.replace((UTC), ).strip()去掉时区标记文本再补上00:00后缀交给datetime.fromisoformat解析为UTC 时间随后经datetime_to_global_time转换为 Zulip 全局时间渲染格式输出为time:...语义标签前端会按查看者所在时区展示。这正是测试期望中出现time:2020-06-09T14:04:3900:00的原因——负载中的2020-06-09 14:04:39被认定为 UTC 时间。字段校验三个字段均通过check_string校验WildValue.tame()会在字段缺失或类型不符时抛出校验错误保证消息格式安全。链接渲染manage_url被直接嵌入 Markdown 链接方便收件人一键跳转管理该令牌。3. 主题的默认值消息主题固定为canarytoken alert除非调用方在 URL 中显式传入topic参数见 view.pyif user_specified_topic is not None: topic_name user_specified_topic也就是说向 Webhook URL 追加?topicsecurity-alerts注意与stream/api_key用连接即可覆盖默认主题。4. 消息投递最终由check_send_webhook_messagezerver/lib/webhooks/common.py统一完成投递。该函数还负责 Zulip 通用的事件过滤能力当第三方服务支持事件类型complete_event_type时可配合only_events/exclude_events参数按通配符模式过滤事件。不过当前 canarytoken 集成只处理单一种类的告警未启用该机制。投递成功后返回json_success(request)即 HTTP 200 JSON 响应。四、测试验证如何确认集成行为仓库为 canarytoken 集成提供了完整的单元测试 zerver/webhooks/canarytoken/tests.py基于WebhookTestCase基类编写共覆盖三种场景测试方法负载期望主题期望消息正文关键内容test_canarytoken_newcanarytoken_new.jsoncanarytoken alerttime:2020-06-09T14:04:3900:00、Congrats! The newly saved webhook works、http://example.com/test/url/for/webhooktest_canarytoken_realcanarytoken_real.jsoncanarytoken alerttime:2020-06-09T14:04:4700:00、Canarytoken example、https://canarytokens.org/manage?tokenfooauthbartest_canarytoken_with_specific_topiccanarytoken_real.jsonfooURL 中topicfoo与上一条正文一致测试中通过build_webhook_url(topicfoo)构造带主题参数的 URL实现见 zerver/lib/test_classes.py并以content_typeapplication/x-www-form-urlencoded提交负载——这表明 canarytokens.org 发送的请求是URL 编码的表单格式而非裸 JSON尽管负载本体是 JSON 字符串。你可以在自己的部署中运行这些测试来验证集成行为# 在 Zulip 仓库根目录下执行 ./tools/test-backend zerver/webhooks/canarytoken/tests.py三个测试共同验证了默认主题与自定义主题、时间戳的 UTC 解析与全局渲染、memo 与 manage_url 的透传渲染等关键行为是理解该集成输出格式的最佳参考样例。五、常见问题与排查建议收不到告警先确认 URL 中的api_key与stream是否正确再到 canarytokens.org 的令牌详情页检查 Webhook URL 是否完整粘贴含https://前缀与全部查询参数。误用了 Thinkst 付费产品canarytokens.org 与 Thinkst 商业产品的负载 schema 不同若你的令牌来自 Thinkst 付费平台请改用 Thinkst 集成 对应的 Webhook URL/api/v1/external/thinkst其消息会附带更丰富的告警字段如SourceIP、ReverseDNS、AdditionalDetails等。想修改消息格式消息模板集中在 zerver/webhooks/canarytoken/view.py 的body构造处调整该处的 f-string 即可改变输出样式修改后务必同步更新 tests.py 中的期望消息并运行测试。时间显示与预期不符注意负载中的time会被视为UTC 时间解析并转换为全局时间标签Zulip 前端会按每个用户的本地时区展示因此不同成员看到的本地时刻可能不同这是预期行为。相关文档Webhook URL 规范说明Thinkst付费产品集成文档集成注册与分类zerver/lib/integrations.py视图实现zerver/webhooks/canarytoken/view.py测试用例zerver/webhooks/canarytoken/tests.py示例负载canarytoken_new.json / canarytoken_real.json【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Zulip Thinkst Canarytoken 集成：将蜜罐令牌告警实时投递到 Zulip
Zulip Thinkst Canarytoken 集成将蜜罐令牌告警实时投递到 Zulip【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip导读Zulip 内置的Thinkst Canarytoken 集成允许你将 canarytokens.org 为核心骨架结合该集成在仓库中的视图实现、测试用例与示例负载完整讲解从创建机器人、生成 Webhook URL、在 canarytokens.org 上配置令牌到告警消息实际落地的全过程并深入剖析其底层消息渲染逻辑。读完本文你将能够独立完成该集成的配置、验证与消息格式定制。一、集成概览适用于 canarytokens.org 的公共蜜罐服务Zulip 为 Thinkst 生态提供了两套彼此独立的集成它们对应的 Webhook 服务虽然同名但请求负载schema完全不同切勿混淆集成适用服务仓库位置Canarytoken 集成canarytokens.orgThinkst 集成Thinkst 付费商业产品Canary 与 Canarytokenzerver/webhooks/thinkst/原文档开篇即强调这一点本集成仅面向 canarytokens.org 的免费公共令牌Thinkst 付费产品的告警请改用 Thinkst 集成。这一区分在源码层也有明确印证——api_canarytoken_webhook的文档字符串中注明Canarytokens from Thinksts paid product have a different schema而 zerver/webhooks/thinkst/view.py 则按AlertType字段区分 Canary 与 Canarytoken 两种事件。两个集成的view.py甚至引用了同一份 Thinkst 官方 schema 文档链接足见二者负载差异之大。从集成注册表看该集成在 zerver/lib/integrations.py 中被声明为IncomingWebhookIntegration(canarytoken, [monitoring], ...)显示名称为Thinkst Canarytokens归类于monitoring监控告警类别并以canarytoken_real.json作为截图示例负载——这意味着它在 Zulip 的集成目录/integrations/canarytoken中可供所有用户直接查阅配置步骤。二、配置步骤从机器人到令牌创建以下是完整的四步配置流程请严格按序操作。1. 创建 Incoming webhook 机器人在 Zulip 中创建一个Incoming webhook类型的机器人进入 Zulip 的设置页面按 添加机器人或集成 的指引创建机器人Bot type 必须选择Incoming webhook创建完成后保存页面展示的API key它是 Webhook URL 的鉴权凭证。这一步对应仓库中的共用模板 templates/zerver/integrations/include/create-an-incoming-webhook.md。2. 生成集成 URL决定该集成告警要投递到哪个频道并按 生成集成 URL 的指引生成专属 URL。URL 格式遵循 Zulip 标准 Webhook URL 规范详见 Webhook URL 规范形如https://your-zulip.example.com/api/v1/external/canarytoken?stream频道名api_key机器人API key其中/api/v1/external/canarytokencanarytoken 集成的固定端点路径{webhook_dir_name}即canarytokenstream接收告警的频道名可选缺省时使用机器人的默认频道api_key步骤 1 创建的机器人的 API key用于鉴权。URL 模板的精确格式可以在测试基类 zerver/lib/test_classes.py 中看到DEFAULT_URL_TEMPLATE /api/v1/external/{webhook_dir_name}?stream{stream}api_key{api_key}。另外还可以通过追加topic主题名参数来自定义告警消息的主题下文第 4 节详述。这一步对应共用模板 templates/zerver/integrations/include/generate-webhook-url-basic.md。3. 在 canarytokens.org 上创建令牌打开 canarytokens.org在Select your token选择令牌类型下拉框中选择你想要创建的Webhook 类型令牌在Provide an email address or webhook URL提供邮箱或 Webhook URL字段中粘贴步骤 2 生成的完整 URL填写一条reminder note备忘备注方便日后识别该令牌的用途点击Create my Canarytoken完成创建。4. 验证配置完成后触发一次令牌例如访问一次令牌指向的 URL即可在 Zulip 对应频道看到类似下面的告警消息原文档配图 static/images/integrations/canarytoken/001.png 展示了真实效果:alert: Canarytoken has been triggered on time:2020-06-09T14:04:4700:00! Canarytoken example Manage this canarytoken三、负载解析与消息渲染源码级原理收到 canarytokens.org 的 POST 请求后Zulip 侧的处理入口是 zerver/webhooks/canarytoken/view.py 中的api_canarytoken_webhook函数。整个处理链路如下canarytokens.org POST │ ▼ webhook_view(Canarytokens) ── 鉴权 校验 (zerver/decorator.py) │ ▼ typed_endpoint ── 解析 JSON bodyJsonBodyPayload[WildValue]与可选 topic 参数 │ ▼ api_canarytoken_webhook ── 提取 time / memo / manage_url构造消息正文 │ ▼ check_send_webhook_message ── 投递到目标频道与主题 (zerver/lib/webhooks/common.py) │ ▼ json_success ── 返回 200 JSON 成功响应1. 请求的三种关键字段从示例负载 zerver/webhooks/canarytoken/fixtures/canarytoken_new.json 与 zerver/webhooks/canarytoken/fixtures/canarytoken_real.json 可见canarytokens.org 发送的 POST 负载核心字段如下字段类型说明消息中的用途timestring触发时间格式YYYY-MM-DD HH:MM:SS (UTC)有时省略(UTC)显示为:alert:前缀后的时间戳memostring创建令牌时填写的 reminder note 备忘显示在时间戳下一行manage_urlstring管理该令牌的跳转链接渲染为Manage this canarytoken链接channelstring触发渠道如HTTP当前版本未渲染additional_dataobject补充信息src_ip、useragent、referer、location等当前版本未渲染值得说明的是负载中还携带了additional_data源 IP、User-Agent、Referer、地理位置与channel等字段但当前 Zulip 实现仅消费time、memo、manage_url三个字段来构造消息其余字段被忽略。2. 消息正文的构造逻辑核心渲染逻辑view.py非常精简topic_name canarytoken alert time message[time].tame(check_string) formatted_time datetime_to_global_time( datetime.fromisoformat(time.replace((UTC), ).strip() 00:00) ) body ( f**:alert: Canarytoken has been triggered on {formatted_time}!**\n\n f{message[memo].tame(check_string)} \n\n fManage this canarytoken}) )几点实现细节值得关注时间解析time字段先通过str.replace((UTC), ).strip()去掉时区标记文本再补上00:00后缀交给datetime.fromisoformat解析为UTC 时间随后经datetime_to_global_time转换为 Zulip 全局时间渲染格式输出为time:...语义标签前端会按查看者所在时区展示。这正是测试期望中出现time:2020-06-09T14:04:3900:00的原因——负载中的2020-06-09 14:04:39被认定为 UTC 时间。字段校验三个字段均通过check_string校验WildValue.tame()会在字段缺失或类型不符时抛出校验错误保证消息格式安全。链接渲染manage_url被直接嵌入 Markdown 链接方便收件人一键跳转管理该令牌。3. 主题的默认值消息主题固定为canarytoken alert除非调用方在 URL 中显式传入topic参数见 view.pyif user_specified_topic is not None: topic_name user_specified_topic也就是说向 Webhook URL 追加?topicsecurity-alerts注意与stream/api_key用连接即可覆盖默认主题。4. 消息投递最终由check_send_webhook_messagezerver/lib/webhooks/common.py统一完成投递。该函数还负责 Zulip 通用的事件过滤能力当第三方服务支持事件类型complete_event_type时可配合only_events/exclude_events参数按通配符模式过滤事件。不过当前 canarytoken 集成只处理单一种类的告警未启用该机制。投递成功后返回json_success(request)即 HTTP 200 JSON 响应。四、测试验证如何确认集成行为仓库为 canarytoken 集成提供了完整的单元测试 zerver/webhooks/canarytoken/tests.py基于WebhookTestCase基类编写共覆盖三种场景测试方法负载期望主题期望消息正文关键内容test_canarytoken_newcanarytoken_new.jsoncanarytoken alerttime:2020-06-09T14:04:3900:00、Congrats! The newly saved webhook works、http://example.com/test/url/for/webhooktest_canarytoken_realcanarytoken_real.jsoncanarytoken alerttime:2020-06-09T14:04:4700:00、Canarytoken example、https://canarytokens.org/manage?tokenfooauthbartest_canarytoken_with_specific_topiccanarytoken_real.jsonfooURL 中topicfoo与上一条正文一致测试中通过build_webhook_url(topicfoo)构造带主题参数的 URL实现见 zerver/lib/test_classes.py并以content_typeapplication/x-www-form-urlencoded提交负载——这表明 canarytokens.org 发送的请求是URL 编码的表单格式而非裸 JSON尽管负载本体是 JSON 字符串。你可以在自己的部署中运行这些测试来验证集成行为# 在 Zulip 仓库根目录下执行 ./tools/test-backend zerver/webhooks/canarytoken/tests.py三个测试共同验证了默认主题与自定义主题、时间戳的 UTC 解析与全局渲染、memo 与 manage_url 的透传渲染等关键行为是理解该集成输出格式的最佳参考样例。五、常见问题与排查建议收不到告警先确认 URL 中的api_key与stream是否正确再到 canarytokens.org 的令牌详情页检查 Webhook URL 是否完整粘贴含https://前缀与全部查询参数。误用了 Thinkst 付费产品canarytokens.org 与 Thinkst 商业产品的负载 schema 不同若你的令牌来自 Thinkst 付费平台请改用 Thinkst 集成 对应的 Webhook URL/api/v1/external/thinkst其消息会附带更丰富的告警字段如SourceIP、ReverseDNS、AdditionalDetails等。想修改消息格式消息模板集中在 zerver/webhooks/canarytoken/view.py 的body构造处调整该处的 f-string 即可改变输出样式修改后务必同步更新 tests.py 中的期望消息并运行测试。时间显示与预期不符注意负载中的time会被视为UTC 时间解析并转换为全局时间标签Zulip 前端会按每个用户的本地时区展示因此不同成员看到的本地时刻可能不同这是预期行为。相关文档Webhook URL 规范说明Thinkst付费产品集成文档集成注册与分类zerver/lib/integrations.py视图实现zerver/webhooks/canarytoken/view.py测试用例zerver/webhooks/canarytoken/tests.py示例负载canarytoken_new.json / canarytoken_real.json【免费下载链接】zulipZulip server and web application. Open-source team chat that helps teams stay productive and focused.项目地址: https://gitcode.com/GitHub_Trending/zu/zulip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考