cognis-digital/admitd
GitHub: cognis-digital/admitd
admitd 是一个纯 Python 实现的 Kubernetes 准入控制引擎，通过声明式策略在 CI 和集群中统一执行 CIS/NSA 加固基线，提供允许、拒绝和自动变更三种决策模式。
Stars: 0 | Forks: 0
# admitd — Kubernetes 策略即代码准入引擎
[](https://github.com/cognis-digital/admitd/actions)
[](LICENSE)
[](https://github.com/cognis-digital)
**Kubernetes 准入的声明式允许 / 拒绝 / 变更 —— 内置了 CIS / NSA-CISA 加固策略库。**
`admitd` 根据一组声明式策略对 Kubernetes 对象（`Pod`、`Deployment`、`DaemonSet` 等）或完整的 `AdmissionReview` 进行评估，并为每个违规行为返回 **允许**、**拒绝** 或 **变更** (JSONPatch) 决定，同时附带人类可读的原因。它可以通过两种方式使用：
- **在 CI 中** —— 当清单违反策略时，`admitd eval manifests/ ` 会导致流水线失败，并提供用于代码扫描的 SARIF 输出。
- **在集群中** —— `admitd serve` 是一个基于标准库 HTTPS 的 `ValidatingWebhookConfiguration` / `MutatingWebhookConfiguration` 后端。
仅使用标准库。无需代理，无需安装 CRD，没有第三方引擎 —— 一个完全可自托管的 Python 包。
## 用法 —— 逐步指南
1. 从源码**安装**（Python 3.9+）：
pip install .
2. 根据内置策略对清单或 AdmissionReview 进行**评估**：
admitd eval deployment.yaml
3. **列出**活动策略（内置 + 从目录中加载的任何策略）：
admitd policies --policies ./policies --format json
4. **使用输出**：输出 SARIF 或 JSON 以用于代码扫描仪表板：
admitd eval manifests/ --policies ./policies --format sarif --out admitd.sarif
5. **在 CI 中设门禁 / 作为 webhook 服务** —— 遇到发现项时失败，或运行实时准入 webhook：
admitd eval manifests/ --format json --fail-on high
admitd serve --port 8443 --tls-cert tls.crt --tls-key tls.key --mutate
此外：`admitd draft ""`（可选的 AI 策略草稿）和 `admitd mcp`。
## 为什么还要另一个准入工具
- **一个工件，两个界面。** 相同的策略同时为 CI *和* 实时准入把关 —— “Linter 检查的内容”与“集群执行的内容”之间没有偏差。
- **可读的判定。** 每个拒绝决定都包含违规的 JSON 路径、映射的加固控制措施以及具体的修复建议。
- **开箱即用的加固。** 十个内置策略重新表达了广泛发布的 Kubernetes 加固指南（CIS Benchmark、NSA/CISA Kubernetes Hardening Guidance）。
- **标准库，可编写脚本，可审计。** 没有 pip 依赖；整个引擎都是您可以阅读的纯 Python 代码。
## 领域
**主要领域：** 网络与安全 · **JTF MERIDIAN 部门：** NULLBYTE · SPECTER
**主题：** `cognis` `security` `infosec` `cybersecurity` `blue-team` `kubernetes`
**Cognis Neural Suite** 的一部分 —— 包含 300 多个源码可用工具，组织在 JTF MERIDIAN 指挥结构下的 12 个领域中。请参阅 [GitHub 上的套件](https://github.com/cognis-digital) 和 [jtf-meridian](https://github.com/cognis-digital/jtf-meridian) 以了解各部分如何协同工作。
## 安装
```
pip install -e ".[dev]" # from this repo
# 或者直接就地运行：
python -m admitd --version
```
## 快速开始
```
# 在 CI 中评估 manifest（deny 时非零退出）：
python -m admitd eval demos/01-basic/insecure-pod.yaml # -> DENY, exit 1
python -m admitd eval demos/01-basic/hardened-pod.yaml # -> ALLOW, exit 0
# 支持 code-scanning 的机器可读格式 + SARIF：
python -m admitd eval manifests/ --format json
python -m admitd eval manifests/ --format sarif --out admitd.sarif --fail-on high
# 列出内置 + 已加载的 policies：
python -m admitd policies
# 运行 admission webhook（真实集群使用 HTTPS）：
python -m admitd serve --tls-cert tls.crt --tls-key tls.key --port 8443 --mutate
# 作为本地 MCP server 暴露（Cognis.Studio / Claude Desktop / Cursor）：
python -m admitd mcp
```
## 策略语言
策略是一个小型的声明式文档（JSON 或 YAML 子集）：
```
id: ADMITD-PRIV-001
title: Deny privileged containers
severity: critical
control: NSA-CISA K8s Hardening / CIS 5.2.1
action: deny # deny | warn | mutate
match:
kinds: [Pod, Deployment, DaemonSet, StatefulSet, Job, CronJob]
rules:
- forbid_field: {path: securityContext.privileged, equals: true}
```
使用 `--policies ` 加载您自己的策略；通过 `--no-builtin` 与内置策略组合或替换它们。
### 规则动词
| 动词 | 触发条件… |
|------|-------------|
| `forbid_field` | 任何容器设置了 `path`（可选 `==` 某个值） |
| `require_field` | 任何容器缺少 `path`（或者它 `!=` 某个值） |
| `forbid_pod_field` / `require_pod_field` | 同上，针对 PodSpec |
| `forbid_image_tag` | 镜像使用了被禁止 / 隐式的（`:latest`）标签 |
| `require_registry` | 镜像不是来自允许的 registry 前缀 |
| `require_drop_caps` | 容器没有 drop 列出的 Linux capabilities |
| `forbid_volume_type` | PodSpec 挂载了被禁止的卷类型（例如 `hostPath`） |
| `require_resource_limits` | 容器缺少 CPU / 内存限制 |
`mutate` 策略会将其 `require_*` 规则转换为 JSONPatch，以便 webhook 可以自动修复（例如注入 `runAsNonRoot: true`，`capabilities.drop: [ALL]`）。
## 内置加固库
| 策略 | 严重程度 | 映射至 |
|--------|----------|---------|
| `ADMITD-PRIV-001` | critical | 拒绝特权容器 |
| `ADMITD-PRIVESC-002` | high | 拒绝权限提升 |
| `ADMITD-HOSTNS-003` | high | 拒绝 hostNetwork / hostPID / hostIPC |
| `ADMITD-HOSTPATH-004` | high | 拒绝 hostPath 卷 |
| `ADMITD-NONROOT-005` | high | 要求 `runAsNonRoot` |
| `ADMITD-ROFS-006` | medium | 要求只读根文件系统 |
| `ADMITD-DROPCAPS-007` | medium | 要求 drop `ALL` capabilities |
| `ADMITD-LATEST-008` | medium | 拒绝 `:latest` / 未打标签的镜像 |
| `ADMITD-LIMITS-009` | low | 要求 CPU + 内存限制 |
| `ADMITD-SECCOMP-010` | medium | 要求 seccomp profile |
这些是对公开的 Kubernetes 加固概念（CIS Kubernetes Benchmark、NSA/CISA Kubernetes Hardening Guidance）的原创重新表达。未复制任何第三方的策略文本。
## 输出格式
- **表格**（默认） —— 人类可读的单个对象判定。
- **JSON** —— 用于流水线的机器可读决策。
- **SARIF** —— 直接导入 GitHub 代码扫描 / IDE 问题面板。
## 作为准入 webhook
`admitd serve` 响应 `POST /validate` 并且（使用 `--mutate` 时）响应 `POST /mutate`，返回标准的 `AdmissionReview` 响应 —— 包含 `allowed`、列出了拒绝策略的 403 `status.message`，以及用于变更的 base64 JSONPatch。将 `ValidatingWebhookConfiguration` 指向它；API server 要求使用 TLS，因此请传入 `--tls-cert`/`--tls-key`。
在没有集群的情况下进行冒烟测试：
```
python -m admitd serve --self-test # binds localhost, posts a privileged Pod, asserts deny
```
## 可选的 AI 策略起草（默认关闭）
`admitd draft "deny any pod that mounts the docker socket"` 可以使用 Cognis 共享的 AI 后端，根据纯英文规则起草新策略。它**默认关闭**，并且只与您配置的**本地** fleet 端点（`COGNIS_AI_BACKEND` / `COGNIS_AI_ENDPOINT`）通信——不会有任何数据离开您的机器。草稿在打印之前始终会通过策略解析器进行验证，因此格式错误的建议永远不会成为可执行的策略。在使用前请审查每一个草稿。
## 它如何融入 Cognis Neural Suite
`admitd` 是 [Cognis Neural Suite](https://github.com/cognis-digital) 中的一个工具。每个工具都提供了一个 MCP server，因此 [Cognis.Studio](https://cognis.studio) 代理可以将它们作为具有作用域的能力进行调用。
## 架构与路线图
- 设计文档：[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
- 计划工作：[`ROADMAP.md`](ROADMAP.md)
## 互操作性
`admitd` 可以与包含 300 多个工具的 Cognis 套件组合使用 —— JSON 输入/输出和共享的、兼容 OpenAI 的 `/v1` 骨干网络。请参阅 **[INTEROP.md](INTEROP.md)** 以获取套件图谱、组合模式和参考技术栈。
## 集成
通过 [`cognis-connect`](https://github.com/cognis-digital/cognis-connect) 将 `admitd` 的发现结果转发至 STIX/MISP/Sigma/Splunk/Elastic/Slack/webhook。请参阅 **[INTEGRATIONS.md](INTEGRATIONS.md)**。
## 许可证
在 **Cognis Open Collaboration License (COCL) v1.0** 下源码可用 —— 可免费用于个人、内部评估、研究和教育用途；**商业 / 生产用途需要许可证** (licensing@cognis.digital)。请参阅 [LICENSE](LICENSE)。
## 负责任的使用
这是安全治理软件。仅对您拥有或获得书面明示授权进行测试的集群、清单和身份使用它，并遵守适用法律。
## 关于
**[Cognis Digital](https://cognis.digital)** — 美国怀俄明州 · *让明天更美好：高级网络安全、AI 创新和区块链专业知识。*
标签：子域名突变, 安全合规, 策略即代码, 网络代理, 聊天机器人安全, 逆向工具