cognis-digital/oradeck
GitHub: cognis-digital/oradeck
纯 Python 实现的气隙环境 OCI 镜像搬运工具，可将容器镜像及其签名、SBOM、attestation 等供应链元数据完整迁移至断网 registry。
Stars: 0 | Forks: 0
# oradeck
**适用于气隙集群的 OCI registry 镜像与 artifact 拷贝工具。** 将容器镜像及其 referrers（签名、SBOM、attestation）拉取到一个可移植的内容寻址存储中，将其跨越物理隔离边界携带，并推送回一个断网的 registry 中。
**Cognis Neural Suite** 的一部分。纯 Python 标准库实现——不需要 Docker daemon、外部 registry 客户端，也不需要 pip 依赖。
## 🔎 示例输出
工具运行的真实、可复现的输出——完全在离线状态下运行：
```
$ oradeck-emit --version
oradeck 0.1.0
```
```
$ oradeck-emit --help
usage: oradeck [-h] [--version]
{copy,push,inspect,plan,parse,verify,gc,referrers,mcp} ...
OCI registry mirror & artifact copy — move images and their
signatures/SBOMs/attestations across an air-gap.
positional arguments:
{copy,push,inspect,plan,parse,verify,gc,referrers,mcp}
copy Copy an image (+referrers) into a local store.
push Push a stored artifact to a destination registry.
inspect List artifacts and blobs in a store.
plan Plan a many-image mirror (source -> dest).
parse Parse a reference into its parts.
verify Verify store integrity (blob hashes + reachable
blobs).
gc Garbage-collect blobs unreachable from the index.
referrers List stored manifests that reference a subject.
mcp Run as an MCP server (stdio JSON-RPC).
options:
-h, --help show this help message and exit
--version show program's version number and exit
```
**示例结果格式** _（演示用数据——请在你自己的数据上运行以获取真实结果）：_
```
{
"timestamp": "2023-02-16T14:30:00Z",
"actor": {
"name": "John Doe"
},
"object": {
"type": "indicator",
"guid": "1234567890abcdef",
"confidence": 80,
"labels": ["malware", "ransomware"],
"data": {
"ip": "192.168.1.100",
"port": 443
}
},
"findings": [
{
"id": "F-20230216-143000-001",
"type": "indicator",
"guid": "1234567890abcdef",
"description": "Suspicious network activity detected"
}
]
}
```
## 为什么需要
物理隔离和涉密环境在部署时无法访问 Docker Hub 或 GHCR。oradeck 直接遵循 **OCI Distribution Spec**，因此你可以将所需的 artifact——*连同其供应链元数据完好无损地*——精确镜像到可移动存储介质上，并在隔离网络内部署私有 registry。
## 命令
```
# 将 image（及其 sigs/SBOMs/attestations）复制到本地 OCI store 中。
python -m oradeck copy ghcr.io/cognis/app:1.0.0 --store ./oci-store
# 列出 store 中的 artifacts 和 blob 统计信息。
python -m oradeck inspect --store ./oci-store
# 将已存储的 artifact 推送到目标 registry 中。
python -m oradeck push localhost:5000/cognis/app:1.0.0 --store ./oci-store --insecure
# 规划多 image 镜像（source -> destination）。
python -m oradeck plan nginx:1.27 redis:7 --to localhost:5000
# 从保存在 git 中的声明式 mirror-set FILE（纯列表或 JSON）进行规划。
python -m oradeck plan --from mirror-set.txt --format json
# 解析任何 reference（处理 host:port、tags、@sha256 digests）。
python -m oradeck parse ghcr.io/cognis/app:1.0.0
# 使用内置的 fixture image 在零网络环境下尝试它。
python -m oradeck copy x --demo --store /tmp/oci-store
# 作为本地 MCP server 运行（stdio JSON-RPC）。
python -m oradeck mcp
```
## oradeck 的独特之处
- **感知 Referrers。** 发现并拷贝分离式签名以及 SBOM/attestation 的 referrers（Referrers API + digest-tag 回退机制），确保你的供应链证据能随镜像一同跨越气隙。
- **OCI 布局存储。** Blob 采用内容寻址并进行去重；该存储是标准的 OCI 镜像布局，可被其他工具读取。
- **处理 Bearer + Basic Auth** 认证流程（Docker 风格的 `WWW-Authenticate`）。
- **原生支持 MCP**（`copy` / `inspect` / `plan`），并提供选配的本地 fleet AI 钩子（默认关闭），可通过简单的自然语言描述推荐镜像集。
- **与 [airlock](https://github.com/cognis-digital/airlock) 搭配使用。** oradeck 负责移动 registry artifact；airlock 负责打包整个声明式应用。
## Mirror-set 文件（声明式，版本控制）
`plan --from FILE` 从 **mirror-set 文件**中读取需要跨越隔离边界的确切镜像集——它类似于气隙环境下的 lockfile，与应用代码一同保存在 git 中。支持两种格式，可根据内容自动识别：
```
# mirror-set.txt — 每行一个 ref；忽略 `#` 注释和空行
registry: factory-registry.local:5000 # sets the destination
nginx:1.27-alpine
ghcr.io/cognis/inference-app:2.3.1
```
```
{ "registry": "registry.internal:5000",
"images": ["prom/prometheus:v2.54.1", "grafana/grafana:11.2.0"] }
```
命令行中的 `--to` 参数会覆盖文件内定义的 `registry`。同样的 `from_file` 参数也可以在 MCP `plan` 工具中使用。
## 演示
位于 [`demos/`](demos/) 目录下的可运行、零网络 walkthrough——每个演示都包含一个工具原生格式的真实输入文件，以及一个 `SCENARIO.md`，其中包含确切的运行命令和预期结果：
| 演示 | 展示内容 |
| --- | --- |
| [01-basic](demos/01-basic) | 将离线测试镜像及其 SBOM 镜像到存储中 |
| [02-mirror-set-edge-stack](demos/02-mirror-set-edge-stack) | `plan --from` 包含内置 `registry:` 的简单 mirror-set |
| [03-mirror-set-json-observability](demos/03-mirror-set-json-observability) | JSON 格式的 mirror-set + `--to` CI 覆盖 |
| [04-reference-shapes](demos/04-reference-shapes) | `parse` 解析各种真实的引用格式（端口、标签、`@sha256` 固定版本） |
| [05-inspect-store](demos/05-inspect-store) | 在传输前对存储进行盘点 |
| [06-verify-integrity](demos/06-verify-integrity) | 使用 `verify` 检测传输损坏（通过退出码控制） |
| [07-gc-orphans](demos/07-gc-orphans) | 垃圾回收孤立的 blob 以缩小存储介质占用 |
| [08-referrers-supply-chain](demos/08-referrers-supply-chain) | 确认 SBOM/签名 referrers 成功跨越气隙 |
| [09-offline-copy-walkthrough](demos/09-offline-copy-walkthrough) | 完整的 copy -> inspect -> verify -> push 循环 |
| [10-mcp-agent](demos/09-offline-copy-walkthrough) | 通过 MCP stdio JSON-RPC 服务器调用 `plan` |
## 测试
```
python -m pytest -q # or: python -m unittest discover -s tests
```
## 互操作性
`oradeck` 可与包含 300 多个工具的 Cognis 套件组合使用——统一的 JSON 输入/输出，并共享兼容 OpenAI 的 `/v1` 骨干网络。请参阅 **[INTEROP.md](INTEROP.md)** 了解套件图谱、组合模式以及参考技术栈。
## 集成
通过 [`cognis-connect`](https://github.com/cognis-digital/cognis-connect) 将 `oradeck` 的结果转发至 STIX/MISP/Sigma/Splunk/Elastic/Slack/webhooks。请参阅 **[INTEGRATIONS.md](INTEGRATIONS.md)**。
## 许可证
Cognis Open Collaboration License (COCL) 1.0 — 见 [`LICENSE`](LICENSE)。
© 2026 Cognis Digital LLC。原始的 Cognis 工作实现了开放的 OCI Distribution Spec；不包含任何第三方代码、名称或品牌。
## 领域
**主要领域：** AI & ML · **JTF MERIDIAN 部门：** ATHENA-PRIME · SAGE
**主题：** `cognis` `ai` `llm` `machine-learning` `sbom`
**Cognis Neural Suite** 的一部分 —— 包含 300 多个源代码可用工具，按 JTF MERIDIAN 指挥结构划分为 12 个领域。请参阅 [GitHub 上的套件](https://github.com/cognis-digital) 以及 [jtf-meridian](https://github.com/cognis-digital/jtf-meridian) 以了解各组件如何协同工作。
## 用法 —— 分步说明
`oradeck` 可将 OCI 镜像**及其 referrers**（签名、SBOM、attestation）镜像到一个可移植的存储中，方便你跨越气隙携带。
1. **安装**（纯标准库实现，需 Python 3.10+）：
pip install "git+https://github.com/cognis-digital/oradeck.git"
2. **拷贝镜像及其 referrers** 到本地内容寻址存储中（建议先尝试 `--demo` 进行零网络测试）：
oradeck copy ghcr.io/cognis/app:1.0.0 --store ./oci-store
oradeck copy x --demo --store /tmp/oci-store
3. 在移动之前**检查并验证**存储内容：
oradeck inspect --store ./oci-store
oradeck verify --store ./oci-store
4. 将其**推送**到隔离区另一端的断网目标 registry 中：
oradeck push localhost:5000/cognis/app:1.0.0 --store ./oci-store --insecure
5. **自动化批量镜像** —— 规划多个镜像（或使用版本控制的 mirror-set 文件；通过 `--format json` 提供给工具链），并对孤立的 blob 进行垃圾回收：
oradeck plan nginx:1.27 redis:7 --to localhost:5000 --format json
oradeck plan --from mirror-set.txt --format json --out plan.json
oradeck gc --store ./oci-store --apply
或者将其作为本地 MCP 服务器运行：`oradeck mcp`。
标签：容器, 离线环境, 运维, 逆向工具, 镜像仓库