dynatrace-oss/koney

# Koney：面向云原生应用的自动化网络诱饵 [](https://github.com/dynatrace-oss/koney/releases/latest) [](LICENSE.txt) **Koney 是一个 Kubernetes operator，使您能够为集群定义所谓的欺骗策略。** Koney 自动化了 honeytoken 和虚假 API endpoint 的设置、轮换和拆除，并使用 eBPF 在您的陷阱被访问时进行检测、记录和转发告警。 目前，Koney 支持 [honeytoken](https://en.wikipedia.org/wiki/Honeytoken) 的部署，即放置在战略位置以检测对敏感数据未经授权访问的看似敏感的文件。很快，我们也将支持其他网络欺骗技术，例如欺骗性的 HTTP endpoint 和 payload。欢迎贡献！ - 🪤 威慑攻击者。 - 🔎 构建威胁情报。 - 🚢 为 Kubernetes 设计。 ## 🚀 快速开始 您可以使用 `kubectl` 或 `helm` 安装 Koney。如果您已安装 Helm，我们推荐使用 Helm。 **选项 A：**（推荐）使用 `helm` 安装 Koney。 ``` helm install koney --create-namespace -n koney-system --wait oci://ghcr.io/dynatrace-oss/koney/charts/koney --version 0.2.0 ``` **选项 B：** 使用 `kubectl` 安装 Koney。 ``` kubectl apply -f https://raw.githubusercontent.com/dynatrace-oss/koney/refs/tags/v0.2.0/dist/install.yaml kubectl wait --for=condition=ready pod -n koney-system -l control-plane=controller-manager ``` ### 配置 honeytoken 并进行测试 部署一个示例欺骗策略。 ``` kubectl apply -f https://raw.githubusercontent.com/dynatrace-oss/koney/main/config/samples/deceptionpolicy-servicetoken.yaml ``` 此策略将在所有设置了 `demo.koney/honeytoken=true` 标签的 pod 中的 `/run/secrets/koney/service_token` 路径下添加一个 honeytoken。 将该标签放置在 pod 或 deployment 上，以查看 honeytoken 的实际运行效果。 ``` kubectl label pod demo.koney/honeytoken=true ``` 尝试访问该 honeytoken。 ``` kubectl exec -it -- cat /run/secrets/koney/service_token ``` ℹ️ **注意：**要监控陷阱并接收告警，还必须安装 [Tetragon](https://tetragon.io/docs/installation/kubernetes/) 并配置 `dnsPolicy=ClusterFirstWithHostNet`。有关更多信息，请参见 [Captor 部署](#captor-deployment)。 等待几秒钟，观察访问 honeytoken 时生成的告警。 ``` kubectl logs -n koney-system -l control-plane=controller-manager -c alerts -f --since 1h ``` ## 🧹 卸载 Koney 在卸载 Koney 之前，您应该先删除所有欺骗策略和告警接收器。 否则，清理已部署陷阱的 finalizer 将永远不会运行，导致欺骗策略卡在无法删除的终止状态。 在卸载之前，请运行以下命令： ``` kubectl delete deceptionpolicy --ignore-not-found --wait --all kubectl delete deceptionalertsink --ignore-not-found --wait --all --all-namespaces ``` **选项 A：**如果是使用 `helm` 安装的，请按以下方式卸载 Koney。 ``` helm uninstall koney -n koney-system ``` **选项 B：**如果是使用 `kubectl` 安装的，请按以下方式卸载 Koney。 ``` kubectl delete -f https://raw.githubusercontent.com/dynatrace-oss/koney/refs/tags/v0.2.0/dist/install.yaml ``` ## 📃 使用说明 | 🚨 **重要提示：Koney 是一个早期研究项目！** 🚨 | | :-------------------------------------------------------------------------------------------------------------------------: | | 我们建议在测试环境中使用 Koney。其 API 和行为可能会在不另行通知的情况下发生更改。使用风险自负。 | 要在集群中部署陷阱，我们需要创建 `DeceptionPolicy` 自定义资源。 ### 欺骗策略 欺骗策略是一个自定义资源定义（CRD），用于定义我们要部署的陷阱以及要将其部署到哪些 pod 中。欺骗策略的 kind 为 `DeceptionPolicy`，并包含一组 `traps`。每个 trap 具有以下字段： - 它的类型（例如，用于 honeytoken 的 `filesystemHoneytoken`）以及一些特定于陷阱的字段。 - 一个 `match` 条目，用于选择将陷阱应用于哪些资源。 - 一个 `decoyDeployment` 条目，用于定义如何部署陷阱本身。 - 一个 `captorDeployment` 条目，用于定义如何部署陷阱的监控。 此外，以下字段适用于整个策略和所有陷阱： - `strictValidation`：一个布尔值，指示是否应对策略进行严格验证。默认值为 `true`，这意味着只有在所有陷阱都有效时，才会部署策略中的陷阱。如果将 `strictValidation` 设置为 `false`，策略仍会被应用，但只会部署有效的陷阱。如果所有必填字段都存在且其值有效，则认为该陷阱是有效的。 - `mutateExisting`：一个布尔值，指示是否应将陷阱部署到策略创建之前已存在的对象中。默认值为 `true`，这意味着陷阱也会被添加到现有对象中。通常，这意味着现有的资源定义将被更新以包含这些陷阱。根据每个单独陷阱的诱饵和捕获器部署策略，这可能需要重启 pod。如果您希望避免重启现有的工作负载，请将 `mutateExisting` 设置为 `false`。 要应用欺骗策略，请使用以下命令： ``` kubectl apply -f .yaml ``` 要删除欺骗策略，请使用以下命令： ``` kubectl delete -f .yaml ``` ℹ️ **注意：**欺骗策略是集群范围的对象，因此未指定 namespace。 #### `filesystemHoneytoken` 陷阱 `filesystemHoneytoken` 陷阱在 pod 的文件系统中部署一个 honeytoken。它具有以下字段： - `filePath`：部署 honeytoken 的路径。它必须是绝对路径并且必须指向一个文件。请注意，如果 `filePath` 是一个符号链接，使用 Tetragon 部署的捕获器将无法捕获对该文件的访问（如[此处](https://isovalent.com/blog/post/file-monitoring-with-ebpf-and-tetragon-part-1/#whats-in-a-pathname)所述）。 - `fileContent`：honeytoken 文件的内容。默认情况下，它是一个空字符串。 - `readOnly`：一个布尔值，指示 honeytoken 文件是否为只读。默认值为 `true`。 🧪 例如，以下 `filesystemHoneytoken` 陷阱将在 `/run/secrets/koney/service_token` 文件中部署一个内容为 `someverysecrettoken` 的只读 honeytoken： ``` traps: - filesystemHoneytoken: filePath: /run/secrets/koney/service_token fileContent: "someverysecrettoken" readOnly: true ``` #### 匹配 `match` 字段用于选择我们要在其中部署陷阱的 Kubernetes 资源（即 pod 或 deployment，以及容器）。它包含 `any` 字段，该字段包含将与逻辑“或”操作匹配的资源过滤器。 `any` 字段是一个列表，包含一个或多个 `resources` 对象，这些对象包含以下过滤器（`namespaces` 和 `selector` 都是可选的，但两者中必须至少存在一个）： - `namespaces`：namespace 列表。它不支持通配符。陷阱仅部署在属于列表中任何 namespace 的 pod 中。 - `selector`：标签选择器。它不支持通配符。陷阱仅部署在标签与选择器匹配的 pod 中。如果指定多个标签或表达式，则所有这些标签或表达式都必须匹配才能部署陷阱。`selector` 有两个字段： - `matchLabels`：键值对映射。 - `matchExpressions`：作为逻辑“与”操作求值的标签选择器要求列表。 **（尚未实现）** - `containerSelector`：选择匹配的 pod 或 deployment 中部署陷阱的容器。 - 如果此字段以 `regex:` 开头，则字符串的其余部分将表示使用 go [regexp](https://golang.org/s/re2syntax) 库匹配的正则表达式。该模式在容器名称内部进行搜索（即部分匹配也算数），因此类似 `regex:app` 的模式会匹配任何名称中包含 `app` 的容器。使用 `^` 和 `$` 锚点来强制执行精确的边界（例如，`regex:^app$` 仅匹配名称完全为 `app` 的容器）。 - 如果字段以 `glob:` 开头，则这是一个 [glob]() 模式，如 go [filepath.Match](https://pkg.go.dev/path/filepath#Match) 库中所述。与正则表达式不同，glob 模式始终与完整的容器名称进行匹配。 - 如果为空，则陷阱将部署在匹配的 pod 中的所有容器中。 - 否则，将完全比较容器的名称。 默认值为空。 🧪 例如，以下 `match` 字段选择 `koney` namespace 中的所有 pod，以及所有具有 `demo.koney/honeytoken: "true"` 标签的 pod： ``` match: any: - resources: namespaces: - koney selector: matchLabels: demo.koney/honeytoken: "true" containerSelector: "regex:.*" ``` ℹ️ **注意**：Tetragon 的 tracing policy 不支持在 `containerSelector` 字段中使用通配符。当 `containerSelector` 字段设置为特定的容器名称或设置为 `regex:.*` 或 `glob:*` 时，这不是问题。但是，当 `containerSelector` 字段设置为一个模式时，所创建的 tracing policy 的 `containerSelector` 字段为空，从而匹配 pod 中的所有容器。有关 tracing policy 的更多信息，请参见 [Captor 部署](#captor-deployment)。此外，tracing policy 不支持 `namespaces` 字段。因此，tracing policy 会匹配所有 namespace 中的 pod。 #### Decoy 部署 `decoyDeployment` 字段定义了如何部署陷阱。它具有以下字段： - `strategy`：用于部署陷阱的策略。它可以是 `volumeMount`、`containerExec` 或 `kyvernoPolicy`。默认值为 `volumeMount`。基于该策略，Koney 会匹配不同类型的资源。这些策略是： - `volumeMount`：通过在匹配的 pod 中挂载卷来部署陷阱。Koney 匹配 deployment。 - `containerExec`：通过在匹配的 pod 的容器中执行命令来部署陷阱。Koney 匹配 pod。 - `kyvernoPolicy`：通过创建一个 Kyverno 策略来部署陷阱，该策略会修改清单以便它们也包含陷阱。要求集群中安装了 [Kyverno](https://kyverno.io/)。 **（尚未实现）** ℹ️ **注意**：目前，Koney 不匹配 ReplicaSet、DaemonSet、StatefulSet 和 Job。 ℹ️ **注意**：某些值是特定于陷阱的。请参阅上面特定于陷阱的文档以了解更多信息。 🧪 例如，以下 `decoyDeployment` 字段使用 `containerExec` 策略在匹配的 pod 中的所有容器内部署一个 honeytoken： ``` decoyDeployment: strategy: containerExec ``` #### Captor 部署 `captorDeployment` 字段定义了如何部署捕获器。它具有以下字段： - `strategy`：用于部署捕获器的策略。目前，它只能是 `tetragon`。默认值为 `tetragon`。这些策略是： - `tetragon`：通过在集群中创建并应用 Tetragon `TracingPolicy` CR 来部署捕获器。要求集群中安装了 [Tetragon](https://tetragon.io/)，并配置了 `dnsPolicy=ClusterFirstWithHostNet`。 - `kive`：使用 `Kive` 部署捕获器，这是一个轻量级的 operator，执行基于 inode 的监控而不是基于路径的监控。要求集群中安装了 [Kive](https://github.com/San7o/kivebpf)。 - `none`：没有为此陷阱部署捕获器。对该陷阱的访问将不被监控或作为告警报告。 🧪 例如，以下 `captorDeployment` 字段使用 `tetragon` 策略部署捕获器： ``` captorDeployment: strategy: tetragon ``` 🚨 **重要提示**：必须将 Tetragon 安装在集群中，`tetragon` 策略才能工作。Tetragon 必须使用 `dnsPolicy=ClusterFirstWithHostNet` 配置进行安装，以便它可以解析 Koney 服务的地址。您可以使用以下命令升级现有的 Tetragon Helm 安装： ``` helm upgrade tetragon cilium/tetragon -n kube-system --set dnsPolicy=ClusterFirstWithHostNet ``` ### 状态状况 `DeceptionPolicy` 资源具有一个 `status` 字段，其中包含状况列表。状态状况用于提供有关欺骗策略部署状态的信息。 每个状况都有一个 `type`、一个 `status`、一个 `reason` 和一个 `message`。`status` 可以是 `True`、`False` 或 `Unknown`。`reason` 和 `message` 字段提供有关该状况的更多信息。`type` 可以是以下之一： - `ResourceFound`：指示 operator 是否已找到欺骗策略且未将其标记为删除。 - `PolicyValid`：指示欺骗策略中的陷阱是否有效。如果所有陷阱均有效，则 `reason` 为 `TrapsSpecValid`；如果至少有一个陷阱无效，则为 `TrapsSpecInvalid`。`message` 提供有关有效陷阱数量与陷阱总数相比的信息（例如，`1/2 traps are valid`）。 - `DecoysDeployed`：指示是否已部署欺骗策略中的诱饵（即陷阱本身）。如果所有诱饵都已部署，则 `reason` 为 `DecoyDeploymentSucceeded`；如果部署了部分而非全部诱饵，则为 `DecoyDeploymentSucceededPartially`；如果至少有一个诱饵未部署，则为 `DecoyDeploymentError`。`message` 提供有关已部署诱饵数量与诱饵总数相比的信息（例如，`1/2 decoys deployed`）。如果 Koney 根据 `match` 字段未匹配到任何资源，则 `reason` 为 `NoObjectsMatched`。 - `CaptorsDeployed`：指示是否已部署欺骗策略中的捕获器（即对陷阱的监控）。如果所有捕获器都已部署，则 `reason` 为 `CaptorDeploymentSucceeded`；如果部署了部分而非全部捕获器，则为 `CaptorDeploymentSucceededPartially`；如果至少有一个捕获器未部署，则为 `DecoyDeploymentError`。`message` 提供有关已部署捕获器数量与捕获器总数相比的信息（例如，`1/2 captors deployed`）。如果 Koney 根据 `match` 字段未匹配到任何资源，则 `reason` 为 `NoObjectsMatched`。 ### 工作负载注解 K 使用注解来跟踪已部署到 pod 的陷阱，并为集群管理员提供一种查看 pod 中部署了哪些陷阱的简便方法。 Koney 使用单个 JSON 结构的注解 `koney/changes`。此注解包含已部署到该 pod 的 `DeceptionPolicy` 名称列表。注解中的每个欺骗策略都包含已部署到该 pod 的陷阱列表。每个陷阱包括： - 陷阱类型以及特定于陷阱的字段。 - 部署策略。 - 部署陷阱的容器列表。 - 两个时间戳：一个用于首次部署陷阱的时间，另一个用于最后更新陷阱的时间。 🧪 例如，以下 `koney/changes` 注解表示已使用 `containerExec` 策略在 pod 的 `nginx` 容器中部署了一个 `filesystemHoneytoken` 陷阱： ``` [ { "deceptionPolicyName": "deceptionpolicy-sample", "traps": [ { "deploymentStrategy": "containerExec", "containers": ["nginx"], "createdAt": "2024-09-09T13:09:14Z", "updatedAt": "2024-09-09T16:11:42Z", "filesystemHoneytoken": { "filePath": "/run/secrets/koney/service_token", "fileContentHash": "75170fc230cd88f32e475ff4087f81d9", "readOnly": true } } ] } ] ``` 要查看 pod 中部署的陷阱，请使用以下命令： ``` kubectl get pod -n -o jsonpath='{.metadata.annotations.koney/changes}' | jq ``` ℹ️ **注意**：`jq` 命令用于格式化 JSON 输出，也可以省略。 ### 清理 当删除一个欺骗策略时，Koney 会从部署了陷阱的 pod 中删除该策略部署的所有陷阱。这是通过使用 `koney/changes` 注解来完成的，该注解被视为已部署陷阱的唯一真实来源。如果手动修改了该注解，Koney 将无法正确清理陷阱。 ## 🧪 示例策略 ### 部署 Honeytoken 以下欺骗策略会在 `koney-demo` namespace 中所有带有 `demo.koney/honeytoken: "true"` 标签的 pod 里的 `/run/secrets/koney/service_token` 文件中，部署一个内容为 `someverysecrettoken` 的 honeytoken。该 honeytoken 仅使用 `containerExec` 策略部署在匹配 pod 的 `nginx` 容器中： ``` apiVersion: research.dynatrace.com/v1alpha1 kind: DeceptionPolicy metadata: name: deceptionpolicy-sample spec: strictValidation: true mutateExisting: true traps: - filesystemHoneytoken: filePath: /run/secrets/koney/service_token fileContent: "someverysecrettoken" readOnly: true match: any: - resources: namespaces: - koney-demo selector: matchLabels: demo.koney/honeytoken: "true" containerSelector: "nginx" decoyDeployment: strategy: containerExec captorDeployment: strategy: tetragon ``` ## 编写策略的资源 正在寻找关于部署什么陷阱的灵感？以下是一些切入点： - **使用 LLM 生成陷阱。** 使用大型语言模型来头脑风暴并生成欺骗策略的 YAML 文件。描述您的集群设置，并让它建议看起来逼真的 honeytoken 和文件路径。 - **探索类似的项目。** 几个开源项目与 Koney 类似，其中一些提供了非常有价值的陷阱蓝图： - [baitroute](https://github.com/utkusen/baitroute)：一个用于向 Web 应用程序添加欺骗性 HTTP endpoint 的软件库，在其仓库的 `/rules` 目录中包含了出色的示例。 - [HASH](https://github.com/DataDog/HASH)：用于创建欺骗性 Web 应用程序的蜜罐。 - [beelzebub](https://github.com/beelzebub-labs/beelzebub)：适用于各种协议的功能丰富的蜜罐框架。 - [beesting](https://github.com/patrickpichler/beesting)：一个将 honeytoken 注入 Kubernetes 工作负载的研究项目。 - **阅读研究论文。** Honeyquest 论文对什么是好的 honeytoken 提供了经验性的见解。一个关键发现：优先选择中等诱惑但可信的文件名（例如 `config.ini`），而不是极具诱惑力但几乎不可信的文件名（例如 `passwords.txt`）。 ## 🚨 告警 Koney 自动从 Tetragon operator 收集告警，并将其记录在 `alerts` 容器中。每一行都包含一个带有以下字段的 JSON 对象： - `timestamp`：访问陷阱的时间戳。 - `deception_policy_name`：创建该陷阱的关联欺骗策略。 - `trap_type`：陷阱的类型（`filesystem_honeytoken`、`http_endpoint`、`http_payload`，或者在出现错误时为 `unknown`）。 - `metadata`：有关陷阱的附加元数据，例如 honeytoken 的文件路径或 HTTP 陷阱的 URL。 - `pod`：有关访问陷阱的 pod 和容器的附加元数据。 - `process`：有关访问陷阱的进程的附加元数据。 🧪 例如，以下告警指示在 `koney-demo` namespace 的 `koney-demo-deployment-5bcbd78875-45qpn` pod 的 `nginx` 容器中访问了 `/run/secrets/koney/service_token` honeytoken： ``` { "timestamp": "2025-01-03T18:47:56Z", "deception_policy_name": "deceptionpolicy-servicetoken", "trap_type": "filesystem_honeytoken", "metadata": { "file_path": "/run/secrets/koney/service_token" }, "pod": { "name": "koney-demo-deployment-5bcbd78875-45qpn", "namespace": "koney-demo", "container": { "id": "e19c1827e255ce7a5c5fd74eb4ee861388f83a16410effd65e30d3b051cd815f", "name": "nginx" } }, "node": { "name": "minikube" }, "process": { "uid": 0, "pid": 148373, "cwd": "/", "binary": "/usr/bin/cat", "arguments": "/run/secrets/koney/service_token" } } ``` 要查看过去一小时的告警，请使用以下命令： ``` kubectl logs -n koney-system -l control-plane=controller-manager -c alerts -f --since 1h | jq ``` ℹ️ **注意**：`jq` 命令用于格式化 JSON 输出，也可以省略。 ### 导出告警 Koney 支持将告警发送到外部系统。 请参阅 📄 [ALERT_SINKS](./docs/ALERT_SINKS.md) 文档以了解 `DeceptionAlertSink` 资源。 ## 💻 开发者指南 请参阅 📄 [DEVELOPER_GUIDE](./docs/DEVELOPER_GUIDE.md) 文档。 ## 💖 贡献 我们重视各种形式的贡献，从 bug 报告、反馈、功能请求到 pull request。 阅读 📄 [CONTRIBUTING](./.github/CONTRIBUTING.md) 文档了解更多信息。 我们感谢所有使这个项目变得更好的贡献者！ | [](https://github.com/blu3r4y) | [](https://github.com/Golim) | [](https://github.com/San7o) | [](https://github.com/jjsanda) | | :---------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------: | | [Mario Kahlhofer](https://github.com/blu3r4y) | [Matteo Golinelli](https://github.com/Golim) | [Giovanni Santini](https://github.com/San7o) | [Josef Šanda](https://github.com/jjsanda) | | Dynatrace
Research | University
of Trento | University
of Trento | Johannes Kepler
University Linz | 如有一般问题或询问，请发送电子邮件至 。 ## 🎤 演讲与视频 - 用 Koney 抓住黑客：面向云原生应用的自动化 Honeytoken – *Cloud Native Days Austria*，2025 年 10 月 **\[[幻灯片](https://doi.org/10.5281/zenodo.17287794)\]** **\[[视频](https://www.youtube.com/watch?v=ha6KcyjR55E)\]** - Koney：面向 Kubernetes 的网络欺骗编排框架 – *第 4 届主动防御与欺骗研讨会 (AD&D)，与 EuroS&P 同地举办*，2025 年 7 月 **\[[幻灯片](https://doi.org/10.5281/zenodo.15793720)\]** - Koney：面向 Kubernetes 的网络欺骗策略 – *The Honeynet Project 年度研讨会*，2025 年 6 月 **\[[幻灯片](https://doi.org/10.5281/zenodo.15575531)\]** **\[[视频](https://youtu.be/uxbzGcIegVU?t=5461)\]** - 用 Koney 抓住更多黑客：面向云原生应用的自动化 Honeytoken – *KubeCon + CloudNativeCon Europe*，2025 年 4 月 **\[[幻灯片](https://doi.org/10.5281/zenodo.15594862)\]** ## ⚖️ 许可证与署名 源代码在 [GNU Affero General Public License (AGPL) 3.0](./LICENSE.txt) 下授权。 简而言之，这意味着您可以使用（甚至用于商业目的）、修改、分发和贡献代码， 但您必须保留原始的版权声明和许可证，并声明更改， 还要根据相同的 AGPL-3.0 许可证对任何衍生作品进行授权， 并在分发衍生作品时提供对衍生作品源代码的访问权限。 当您将 Koney 作为网络服务（例如 SaaS 产品）分发时，此条款同样适用。 请注意，此简要摘要不能替代实际的许可证。 如果您使用 Koney 或想了解更多相关信息，请引用以下作品： _ℹ️ **注意：**Koney 是一个研究项目，Dynatrace 官方不提供支持。_

标签：BOF, Docker镜像, EVTX分析, StruQ, 威胁情报, 子域名突变, 开发者工具, 日志审计, 欺骗防御, 蜜罐, 证书利用