adanb13/cirdan

# Cirdan [](https://pypi.org/project/cirdanops/) [](https://www.npmjs.com/package/@cirdanops/cli) [](https://pypi.org/project/cirdanops/) [](https://pepy.tech/projects/cirdanops) [](https://github.com/adanb13/cirdan/actions/workflows/ci.yml) [](LICENSE) [](https://github.com/adanb13/cirdan/stargazers) **Cirdan 是一个独立的 AI 基础设施制图与运维 daemon —— 相当于实时基础设施的 Graphify。** 它像 skill 一样安装到 AI agent 中，但它不仅对代码进行制图，还会对 agent 可以访问的实时基础设施进行指纹识别和图谱构建：Docker、Kubernetes、云账户、IaC、数据库、遥测数据。它会持续监视该图谱，检测事件，并为 agent（及人类）提供一种结构化的方式来理解和操作系统。 ``` Cirdan fingerprints the system. Cirdan graphs the system. Cirdan watches the system. Cirdan lets the agent operate inside the system using the access the agent already has. Cirdan generates views only when the human asks to see something. ``` ## 快速入门 ``` uv tool install "cirdanops[all]" # or npm / brew / curl — see Install below cirdan setup # one command: hook your agents, register MCP, # arm the responder, build the first map, start the daemon ``` `cirdan setup` 会引导您完成整个流程，并且只提示缺失的部分，因此 重复运行是安全的。两个实用的 flag： - `cirdan setup --all` — 无需提示即可运行所有步骤（适用于脚本 / CI） - `cirdan setup --system` — 在 `~/.cirdan` 而不是 repo 中设置机器级别的感知 就是这样 —— Cirdan 现在已经可以进行映射、监视并准备好供 agent 使用了。请继续阅读了解其余所有内容。 ## 安装 **通过 PyPI（推荐）：** ``` uv tool install "cirdanops[all]" # 或 pipx install "cirdanops[all]" pip install "cirdanops[all]" ``` **无需 Python —— 使用 npm / Homebrew / curl：** ``` npx -y @cirdanops/cli serve-mcp # run the MCP server, zero install npm install -g @cirdanops/cli # or put the `cirdan` command on your PATH brew install adanb13/tap/cirdan # macOS / Linux (Homebrew) curl -LsSf https://raw.githubusercontent.com/adanb13/cirdan/main/packaging/install.sh | sh # Windows: irm https://raw.githubusercontent.com/adanb13/cirdan/main/packaging/install.ps1 | iex ``` 这些都附带一个独立的二进制文件 —— 不需要 Python 3.11+。支持平台：macOS (arm64)、Linux x64/arm64 (glibc)、Windows x64。在 Intel Mac、Alpine/musl 或其他平台上，请使用上面的 PyPI 安装。 **然后使用一条命令进行设置**（参见[快速入门](#quickstart)）： ``` cirdan setup --system # map + watch your whole machine, agent-ready # 或在 repo 内： cirdan install --project ``` 两者都会引导您完成整个流程：挂载您的 AI agent、武装事件响应器、构建第一张映射图，并启动常驻 daemon。 定向安装：`cirdanops[mcp]`、`cirdanops[api]`、`cirdanops[terraform]`，或组合如 `cirdanops[terraform,mcp]`。Docker/Kubernetes/AWS/systemd 适配器不需要额外依赖 —— 它们使用您 PATH 中已有的 CLI。 **各平台前置条件**（Python 3.11+ 和 `uv` 或 `pipx`）： ``` # macOS brew install python@3.12 uv # Windows winget install astral-sh.uv # Ubuntu / Debian sudo apt install python3.12 python3-pip pipx # 或获取 uv： curl -LsSf https://astral.sh/uv/install.sh | sh ``` **Docker（无需 Python）：** ``` # 针对主机的 Docker 运行常驻 daemon，监视当前目录 docker run -d \ -v "$PWD":/workspace:ro \ -v /var/run/docker.sock:/var/run/docker.sock \ -p 127.0.0.1:8090:8090 \ ghcr.io/adanb13/cirdan ``` （或使用提供的 [docker-compose.yml](docker-compose.yml) 运行 `docker compose up`） **从源码构建：** ``` pip install "cirdanops[all] @ git+https://github.com/adanb13/cirdan.git" ``` 会安装两个命令： | 命令 | 用途 | |---|---| | `cirdan` | 人类/agent CLI | | `cirdand` | 长期运行的常驻 ON daemon | ## 升级 不会有任何自动操作发生 —— PyPI 仅支持拉取，因此已安装的版本会保持原样运行，直到您进行升级。全新安装始终会获取最新发布版本。升级只需一条命令，与您的安装方式相对应： | 安装方式 | 升级命令 | |---|---| | `uv tool install` | `uv tool upgrade cirdanops` | | `pipx install` | `pipx upgrade cirdanops` | | `pip install` | `pip install -U cirdanops` | | npm (`-g`) | `npm install -g @cirdanops/cli@latest`（或者直接使用 `npx @cirdanops/cli@latest …`） | | Homebrew | `brew upgrade cirdan` | | curl 安装脚本 | 重新运行安装脚本（它会获取最新版本） | | Docker | `docker pull ghcr.io/adanb13/cirdan:latest`（然后重启容器） | 两点运维说明：现有的 `cirdan-out/` 产物和 SQLite 图谱在目前的各个版本间是兼容的（在 1.0 之前会加入 schema-version 键和迁移机制）。此外，当存在更新版本时，CLI 会在 stderr 上打印一行暗色提示（最多每天检查一次，仅限交互式终端）—— 可以通过设置 `CIRDAN_NO_UPDATE_CHECK=1` 来静音。 ## 首张映射图 ``` cirdan map . ``` 这会对环境进行指纹识别（repo 文件**以及**当前 session 可达的实时 runtime），构建图谱，并写入： ``` cirdan-out/ ├── infra.html # interactive infrastructure map ├── INFRA_REPORT.md # plain-English report ├── infra.graph.json # machine-readable graph for agents ├── fingerprint.json # evidence-backed environment classification ├── access.json # what this session can currently reach ├── services.json ├── dependencies.json ├── runtime-state.json ├── incidents/ # active.json + history.jsonl ├── views/generated/ # on-demand Agentic UI views └── audit.jsonl # everything Cirdan observed, generated, executed, verified ``` ## 访问模型 **Cirdan 继承了 agent 的执行上下文。** 它不是权限管理器，而是一面镜子。如果 session 能够读取 repo、运行 shell、访问 `/var/run/docker.sock`、使用 `kubectl` 或调用 AWS —— Cirdan 就能使用相同的上下文，仅此而已。运行 `cirdan access .` 以查看实时能力报告。 ## 命令 ``` cirdan map . # full pipeline: fingerprint → graph → artifacts cirdan fingerprint . # what is this system? (with confidence + evidence) cirdan access . # capability mirror for the current session cirdan query "what is running right now?" cirdan query "what depends on postgres?" cirdan query "what broke in the last hour?" cirdan query "what can the agent do here?" cirdan show "state" # workload state table cirdan show "show me the infrastructure map" cirdan show "show checkout-api as a dependency graph" cirdan show "show last night's incidents as a timeline" cirdan incidents # detection pass + list cirdan explain # evidence-backed explanation cirdan actions list # what can be done with current access cirdan actions run --yes cirdan verify # did the system actually recover? cirdan watch . # foreground event stream cirdan serve-mcp # MCP server over stdio cirdan setup # set up all of Cirdan: agents + MCP + responder + map + daemon cirdan setup --all # same, non-interactive (every step, no prompts) cirdan setup --system # set up machine-level scope in ~/.cirdan cirdan install --project # alias for the project-scope guided setup ``` ## 常驻 ON ``` cirdand serve # watch, refresh, detect, export — forever cirdand serve --mcp # + MCP (stdio) cirdand serve --http --mcp --host 0.0.0.0 --port 8090 # shared team server ``` daemon 运行着受监督的循环：访问刷新、指纹刷新、图谱刷新、Docker/Kubernetes 事件监视、遥测数据摄取、事件检测、验证以及产物导出。崩溃的循环会被记录并重启；它绝不会导致 daemon 宕机。 每个作用域仅限一个实例：针对同一作用域的第二个 `cirdand serve`（或 `cirdan watch`）会被拒绝，并提示正在运行的 pid。`cirdan status` / `cirdan stop`（在 `cirdand` 上也可用）用于检查并关闭它。 ## 监视整台机器 项目并不是唯一的作用域。实时适配器（Docker、Kubernetes、AWS、systemd）能看到 session 可达的所有内容，无论目录如何 —— 因此 Cirdan 拥有一个**系统作用域**，可以独立于任何 repo 自主监视所有内容： ``` cirdan setup --system # guided: map everything + start the machine-level daemon cirdan map --system # fingerprint + graph everything this session can reach cirdan query "what broke?" --system cirdan status --system # the system daemon ``` 系统作用域位于 `~/.cirdan/`（包含图谱、事件、摘要、daemon，以及用于响应器/webhook 设置的可选 `cirdan.yaml`），并跳过 repo 扫描 —— 声明与实际状态的漂移仍然是每个项目的关注点，而系统 daemon 则负责监视真实运行的世界：每一个 container、cluster、云账户和失败的单元。项目 daemon 和系统 daemon 独立运行。 一旦 `~/.cirdan/` 存在，该 flag 基本上是可选的：在任何 Cirdan 项目之外运行的命令（没有 `cirdan.yaml`、`cirdan-out/` 或已注册的 `.mcp.json`）会自动回退到系统作用域 —— 并在 stderr 上给出单行提示 —— 而不是散布 `cirdan-out/` 目录或在不可写的位置失败。在项目内部，项目作用域始终优先。 `cirdan setup --system` 还会在用户级别挂载您的 agent（指令文件中的示例带有 `--system`），并将 Cirdan 注册为支持此功能的 agent CLI 的**用户级 MCP 服务器** —— Claude Code 和 Codex 通过它们各自的 `mcp add`，VS Code 通过 `code --add-mcp`，Cursor、Gemini、Windsurf、opencode 和 Goose 则通过它们的全局配置 —— 这样无需针对每个 repo 进行设置，MCP 工具就可以在每个项目中使用。 ## Agent 集成 ``` cirdan install --project # full guided setup (recommended, see below) cirdan setup # re-run the guided setup anytime, step by step cirdan install --platform claude # .claude/skills/cirdan/SKILL.md + CLAUDE.md + .mcp.json cirdan install --platform codex # AGENTS.md + .codex/cirdan.md cirdan install --platform cursor # .cursor/rules/cirdan.mdc + .cursor/mcp.json cirdan install --platform gemini # GEMINI.md cirdan install --platform vscode # .github/copilot-instructions.md + .vscode/mcp.json cirdan install --platform windsurf # .windsurf/rules/cirdan.md (MCP: global config) cirdan install --platform roo # .roo/rules/cirdan.md + .roo/mcp.json cirdan install --platform cline # .clinerules/cirdan.md (MCP: editor UI) cirdan install --platform opencode # AGENTS.md + opencode.json cirdan install --platform goose # .goosehints (MCP: global config) cirdan install --platform generic # .agents/skills/cirdan/SKILL.md + AGENTS.md ``` `cirdan install --project` 是一个引导式设置，能让 Cirdan 得到充分使用，而不仅仅是停留在文档说明层面： 1. **检测您机器上的 agent**（claude/codex/cursor/gemini/vscode/windsurf/opencode/goose 的配置或 CLI），并专门为它们写入指令文件（加上通用的 `AGENTS.md`） 2. **在 `.mcp.json` 中注册 MCP 服务器** 3. **武装事件响应器**，使 daemon 警报能路由到您的 agent 4. **运行首次映射**（图谱 + 位于 `cirdan-out/` 中的产物） 5. **启动常驻 ON daemon**（已分离；`cirdand status` / `cirdand stop`） 步骤 3–5 会进行提示（默认为 yes），也可以通过 flag 驱动脚本执行：`--responder/--no-responder`、`--map/--no-map`、`--daemon/--no-daemon`、`--all-platforms`。之后随时可以使用 `cirdan setup` 重新运行其中任何步骤，它会显示每个步骤的当前状态，并且只提示缺失的部分。 安装是幂等的，绝不会触及 Cirdan 自身标记块之外的内容。MCP 工具包括 `query_infra_graph`、`get_node`、`get_neighbors`、`shortest_path`、`get_recent_errors`、`get_logs`、`get_state`、`list_incidents`、`explain_incident`、`list_available_actions`、`execute_action`、`verify_action`、`generate_view` 等。 **支持的 agent。** 一等公民自动注册（原生指令文件 + agent 支持可写配置情况下的 MCP）涵盖 Claude Code、Codex、Cursor、Gemini、VS Code（+ GitHub Copilot）、Windsurf、Roo Code、Cline、opencode 和 Goose。任何其他 agent 均可通过通用的 `AGENTS.md` + `.agents/skills/cirdan/SKILL.md` 运行。自动检测能够发现 claude/codex/cursor/gemini/vscode/windsurf/opencode/goose；显式传入 `--platform roo` 或 `--platform cline`（它们是没有 CLI 可供检测的 VS Code 扩展，并且 Cline 将 MCP 配置保存在编辑器存储中，因此需通过其 UI 添加该配置）。 对于未列出的任何 MCP 客户端，可手动注册 Cirdan —— 无需 Python： ``` // npx form — zero install { "command": "npx", "args": ["-y", "@cirdanops/cli", "serve-mcp"] } // or, if `cirdan` is already on PATH (pip / npm -g / brew / curl install): { "command": "cirdan", "args": ["serve-mcp"] } ``` ## 图谱 每个节点和边都带有**证据**和**置信度标签**（`EXTRACTED`、`INFERRED`、`AMBIGUOUS`、`UNKNOWN`）： ``` { "source": "service:checkout-api", "target": "database:postgres-prod", "relation": "CONNECTS_TO", "confidence": "INFERRED", "evidence": ["DATABASE_URL references postgres://postgres-prod… in k8s/checkout.yaml"] } ``` Cirdan 维护着一个**静态图谱**（repo 中声明应存在的内容：Compose、Kubernetes YAML、Terraform/OpenTofu、Helm、CI、SQL、nginx、systemd 单元）和一个**实时图谱**（实际存在的内容：Docker Engine、Kubernetes API、AWS、systemd、Prometheus），将它们合并，并报告偏差（drift） —— 声明但未运行、运行但未声明、容量降级、状态不健康。 ## Agent 不仅仅是读取图谱 —— 它们还构建图谱 就像 Graphify 的混合模型（用于代码的确定性 tree-sitter 通道，用于文档/语义的 LLM 通道）一样，Cirdan 的图谱也有两条通道。适配器提取可解析的内容 —— 这是一条始终开启、不消耗 token 的通道，标记为 `EXTRACTED`。Agent 贡献那些无法被解析的内容：README 和 runbook 中描述的关系、代码中暗示的关系，或操作人员已知的关系。贡献需要提供证据引用，其上限为 `INFERRED`/`AMBIGUOUS`（agent 永远不能覆盖确定性的声明），并带有贡献 agent 的名称。 ``` cirdan enrich # hand your agent a brief of what the scanners left # unconnected (isolated nodes, unlinked IaC, docs to read) cirdan enrich --dry-run # just see the brief cirdan graph add-edge payment-worker orders DEPENDS_ON \ --evidence "ARCHITECTURE.md: 'the worker drains the orders queue nightly'" ``` 连接到 MCP 的 agent 也能将这些操作作为工具使用：`upsert_node`、`upsert_edge`、`annotate_node`、`get_enrichment_targets`。贡献会显示在 `INFRA_REPORT.md` 的“Agent-contributed knowledge”下，并在 `infra.html` 中表现为虚线边。 ## 事件响应器：agent 循环 检测是自动的；响应也可以如此。当发生高/严重事件时，daemon 会写入一份**事件摘要**（`cirdan-out/incidents/briefs/.md` —— 包含证据、爆炸半径、可用操作、指令），并且如果配置了响应器命令，它还会**据此调用您的 agent**： ``` # cirdan.yaml — 通常由 `cirdan install --project` 配置，该命令会检测 # PATH 上的 claude/codex/gemini/aider 并询问您一次 responder: command: 'claude -p "Respond to the Cirdan incident brief at {brief_file}"' webhook_url: https://hooks.slack.com/services/… # optional notify on open/resolve ``` Agent 通过 Cirdan 自身的工具（`cirdan actions run … --yes`）进行调查和修复，每个操作都会附加到事件中并进行验证，当情况持续正常时，事件会自动解除，整个交互过程都会记录到 `audit.jsonl` 中。调用受每个事件情况的冷却时间限制。可以通过 `cirdan respond --dry-run` 来测试您的设置。 ## 操作与验证 Cirdan 会检测在当前 session 的访问权限下哪些操作在*技术上是可行的*（`docker restart`、`kubectl rollout restart`、`systemctl restart`、……），将它们作为附加到图谱上的能力暴露出来，仅通过 session 自工具执行，在审计跟踪中记录操作前/后的状态，并验证结果（工作负载就绪、健康检查通过、错误集群静默）。这里没有单独的凭证存储，也没有权限提升。 ## HTTP API 通过 `[api]` 扩展，`cirdand serve --http` 会暴露 `/health`、`/fingerprint`、`/graph`、`/graph/query`、`/services`、`/incidents`、`/actions`、`/views/generate`、`/audit`，并在 `/v1/logs` 处提供一个最小化的 OTLP/HTTP JSON 接收器。添加 `--mcp` 以将 MCP 服务器挂载到 `/mcp`。 ## 配置 零配置即可运行。可以通过 `cirdan.yaml` 进行微调 —— 参见 [`cirdan.yaml.example`](cirdan.yaml.example)。 ## 许可证 Apache-2.0

标签：Docker, MCP, MITM代理, 人工智能, 基础设施, 安全防御评估, 用户模式Hook绕过, 监控, 系统图谱, 请求拦截, 运维工具, 逆向工具