关于 k9-ownership-byod-setup
帮助客户创建 Datadog 参考表，以配置 Ownership Agent 如何判断存在安全发现的云资源所有者。内容涵盖 CSV 准备、上传方式、验证步骤和偏好设置的行为。
主要功能
- 01指导配置三类所有权偏好
- 02准备包含 12 列的 CSV
- 03通过 UI、云存储、Terraform 或 API 配置
- 04说明偏好设置行为与验证规则
- 05提供上传后的验证步骤
适用场景
- 01将云资源标签映射到所有者
- 02排除机器人或共享账户作为所有者
- 03添加组织专属的所有权判断指导
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/k9-ownership-byod-setup确认已加载。
附带文件assets/example.csvreferences/schema.md
详细介绍
BYOD 偏好设置参考表配置
帮助客户创建并上传 k9_ownership_preferences 参考表，自定义 Ownership Agent 确定资源所有者的方式。
请先阅读
references/schema.md— 完整架构、列详情、验证规则和各类型示例assets/example.csv— 包含全部三种偏好类型的完整可用 CSV
概述
Ownership Agent 会推断存在安全问题的云资源的所有者。客户可以通过 所有权偏好设置 自定义此过程，方法是在 Datadog 参考表中提供规则。Agent 会自动读取这些规则。
通过偏好设置，你可以：
- 将标签映射到所有者：具有特定标签值的资源归属于特定团队或人员
- 排除账号：阻止机器人账号或共享基础设施显示为所有者
- 提供自定义指导：向 AI 引擎提供组织特定的背景信息
参考表详情
- 表名：
k9_ownership_preferences（必须完全匹配） - 生效延迟：上传后 24 小时内生效
- 架构：12 列，全部为 STRING — 详情请参阅
references/schema.md
工作流
第 1 步：确定需求
询问客户：
- 标签映射：“你的云资源上是否有能表明所有权的标签？（例如
cost-center、team、project）” - 排除项：“是否有不应显示为所有者的机器人账号、服务账号或共享账号？”
- 提示词文本：“是否有助于确定所有权的组织特定背景信息？（例如命名规范、团队结构）”
第 2 步：生成 CSV
阅读 references/schema.md，了解完整的列规范；并参考 assets/example.csv 获取可用模板。创建包含全部 12 个列标题的 CSV。每行都应有唯一且按顺序递增的 id，并填写与其 preference_type 相关的列，其余列留空。
第 3 步：上传说明
选项 A — 上传 CSV（UI）：
- 在 Datadog 中前往 Integrations > Reference Tables
- 点击 New Reference Table
- 上传 CSV
- 将表名设为
k9_ownership_preferences - 选择主键：
preference_type, tag_key, tag_value, handle - 保存
手动上传的文件大小上限为 4 MB。
选项 B — 云存储同步（S3、Azure Blob、GCS）： 适用于自动定期更新。将 CSV 存储在云存储桶中，Datadog 会定期导入该文件。
- 将 CSV 上传到 S3 / Azure Blob / GCS
- 在 Datadog 中前往 Integrations > Reference Tables
- 点击 New Reference Table，选择 Cloud Storage 作为来源
- 提供存储路径和凭据
- 将表名设为
k9_ownership_preferences - Datadog 会定期重新导入该文件
云存储上传的文件大小上限为 200 MB。
选项 C — Terraform：
使用 Datadog Terraform 提供程序中的 datadog_reference_table 资源，以基础设施即代码的方式管理此表。
选项 D — API： 你可以通过 Reference Tables API 以编程方式管理参考表。有关可用端点，请参阅 API 文档。如适用，请将 API 域名替换为你的 Datadog 站点 URL。
第 4 步：验证
更改会在 24 小时内生效。验证方法：
- 找到一个符合某项标签映射的资源
- 24 小时后，在 Datadog UI 中检查该资源的所有权建议
- 建议的所有者应与配置的映射一致
关键行为
- 不区分大小写的匹配：标签键、标签值、句柄、排除类型和资源类型均不区分大小写
- 排除条件采用 AND 逻辑：所有非空排除字段都必须匹配。空字段视为通配符
- 标签映射是补充，而非覆盖：直接所有权标识（如
team:或service:标签）优先。标签映射是补充，不会取代它们 - 优雅降级：如果表不存在或为空，所有权检测仍会正常工作，不受偏好设置影响
- 空表会清除偏好设置：删除所有行或删除该表都会导致缓存的偏好设置过期并清空
- 验证全有或全无：任何验证失败都会导致本轮的整组偏好设置被拒绝
故障排查
| 问题 | 可能原因 | 解决方法 |
|---|---|---|
| 24 小时后偏好设置仍未生效 | 表名错误 | 必须准确命名为 k9_ownership_preferences |
| 24 小时后偏好设置仍未生效 | 缺少列标题 | CSV 中必须包含全部 12 个列标题 |
| 24 小时后偏好设置仍未生效 | 组织未启用此功能 | 联系支持团队启用所有权偏好设置 |
| 所有偏好设置均被拒绝 | 字符无效 | 请参阅 references/schema.md 中的允许字符。不得包含尖括号、花括号或竖线 |
| 所有偏好设置均被拒绝 | 缺少必填字段 | 请查看 references/schema.md 中各类偏好设置的必填字段 |
| 所有偏好设置均被拒绝 | 存在重复或冲突的行 | 请参阅 references/schema.md 中的重复项检测 |
| 所有偏好设置均被拒绝 | 超出大小限制 | 50 个标签映射、20 个排除项、3 段提示词文本。每个字段 1024 字节，每段提示词 4096 字节 |
| 标签映射未匹配 | 拼写不一致 | 匹配不区分大小写，但请确认资源上的标签键/值完全一致 |
| 排除项未生效 | 范围过窄 | 所有非空字段都必须匹配（AND）。如需广泛排除，请将筛选条件留空 |
| 偏好设置意外清空 | 表被清空或删除 | 两种情况都会导致缓存的偏好设置过期。上传有效的 CSV 即可恢复 |