VisiCore/vct-splunk-cli

# splunk 一个小巧、可脚本化的 CLI，用于通过其文档化的 REST API 读取、搜索、健康检查和安全管理 **Splunk Enterprise** —— 专为 AI CLI 代理和人类设计。 [](https://github.com/VisiCore/vct-splunk-cli/actions/workflows/ci.yml) [](./LICENSE) [](https://www.python.org/) [](https://github.com/astral-sh/ruff) [](https://microsoft.github.io/pyright/) [](https://github.com/pre-commit/pre-commit) ## 这是什么？ Splunk 是一个收集和搜索机器数据（日志、指标、事件）的平台。管理它通常意味着点击其 Web UI 或手动调用其 REST API。此工具将该 API 封装在一个可预测的命令 `splunk` 中，以便人或 AI 代理可以从终端或脚本中检查 Splunk 服务器、运行搜索，并进行经过严密防护的更改。读取操作始终是安全的；任何更改服务器的操作都会先进行预览，在执行前询问，并留下审计追踪。 ## 安装 ``` uv venv uv pip install -e ".[dev]" # editable install with test deps splunk --help ``` 要求 Python 3.10+。还提供了 Nix dev shell：`nix develop`（或 `direnv allow`）会为你提供一个包含 Python、`uv` 和 `ruff` 的 shell。 ## 使用说明 使用环境变量进行身份验证（token 绝不作为标志传递）： ``` export SPLUNK_URL="https://your-search-head:8089" export SPLUNK_TOKEN="" # a JWT; the primary path # 可选：也接受 Splunk session key 作为替代，即 SPLUNK_SESSION_KEY # fallback：SPLUNK_USERNAME + SPLUNK_PASSWORD 登录以获取 session key # （不推荐 —— 首选 token；由 CI 用于针对 Docker Splunk） # 可选： export SPLUNK_CA_BUNDLE="/path/to/ca.pem" # custom CA for on-prem export SPLUNK_VERIFY="true" # TLS verification (default true) ``` 你也可以使用 **session key** 而不是 token 进行身份验证（`splunk auth login` 会生成一个；设置 `SPLUNK_SESSION_KEY`），并将针对特定目标的设置保存在通过 `--profile` / `SPLUNK_PROFILE` 选择的配置文件 **profile** 中（优先级：标志 > 环境变量 > profile）。 命令（单数名词 → 动词）： ``` splunk server info # connectivity, identity, version splunk api get /services/data/indexes # GET-only raw escape hatch (any read endpoint) splunk index list # list indexes splunk index get main # one index splunk search run --query 'index=_internal | stats count by sourcetype' --earliest -1h splunk search run --query 'index=main' --export --max-rows 5000 # bounded stream from the export endpoint splunk search list # running / finished search jobs splunk search get # one job by SID splunk search cancel # cancel a job (gated write) splunk saved-search list --app my_app # saved searches in an app splunk saved-search create nightly --search 'index=main | stats count' --app my_app --cron '0 2 * * *' splunk health check # native health; exits 5 if warn/fail splunk index create payments --max-gb 50 --frozen-secs 7776000 # gated write ``` 许多管理资源 —— `user`、`role`、`monitor-input`、`hec-token`、`macro`、`eventtype`、`kvstore-collection`、`app` 等 —— 都是生成的 CRUD 组。运行 `splunk --help` 列出它们，并运行 `splunk --help` 查看每个组的信息。 输出是 **TTY 自适应** 的：在终端上显示人类可读的表格，在通过管道输出或使用 `--output json` 时输出 JSON。stdout 是纯数据；诊断和提示信息会发送到 stderr，因此这是安全的： ``` splunk index list --output json | jq '.data[] | select(.disabled) | .name' ``` ### namespace（owner + app） 大多数搜索和知识对象存在于一个 namespace 中 —— 一个 **owner** 加上一个 **app** (`/servicesNS///...`)。两个通用选项可以设置它： ``` splunk saved-search list --app my_app --owner nobody # narrow a read splunk saved-search create nightly --search '...' --app my_app # writes require an app export SPLUNK_APP=my_app SPLUNK_OWNER=nobody # or set defaults once ``` 读取默认使用 `-` 通配符（每个 owner 和 app）。**写入需要明确的 app**，并且永远不会回退到默认的 `search` app，因此对象绝不会在你无意的地方创建。 ### 写入受控 每次写入 —— index 生命周期、`saved-search create`/`update`/`delete`、`search cancel` 以及所有生成的组变更 —— 默认都是安全的： ``` splunk index create payments --dry-run # preview the request; sends nothing splunk index create payments # prompts for confirmation on a TTY splunk index create payments --yes # --yes is required when non-interactive ``` 没有 `--yes` 的非交互式写入会快速失败（exit 2），而不是挂起。每次执行的写入都会追加到本地审计日志中：如果设置了 `$VCT_SPLUNK_AUDIT` 则记录到那里，否则记录到 `$XDG_STATE_HOME/vct-splunk/audit.log`，再否则记录到 `~/.local/state/vct-splunk/audit.log`。 ### 退出码 | 代码 | 含义 | | --- | --- | | 0 | 成功 | | 1 | API / 传输 / 操作错误 | | 2 | 使用或配置错误（例如没有 `--yes` 拒绝写入） | | 3 | 身份验证错误 (401/403) | | 4 | 未找到 (404) | | 5 | `health check` 成功但某些发现状态为 `warn`/`fail` | ### 契约稳定性 JSON 输出 —— 成功时为 `{"data": ..., "meta": ...}`，失败时为 `{"error": {"code", "message"}}` —— 以及上述退出码是一个 **稳定的、仅限新增的契约**：字段和代码可能会随着时间增加，但绝不重命名或删除，因此脚本、AI 代理和后端服务可以依赖它们。远程 Splunk 结果文本仅被视为数据，绝不会驱动写入。 ## 范围 主要的、认证的目标是 **Splunk Enterprise 本地部署**，使用你自己的凭据访问文档化的 REST API。它不使用、捆绑或代理任何 Splunk 分发的应用。 **透明支持 Splunk Cloud。** 当 `SPLUNK_URL` 是 `*.splunkcloud.com` 主机时，CLI 会推断出 Cloud 后端，并且 *相同的扁平命令* 会通过 Cloud ACS API 进行读取，而不是 splunkd —— 你无需选择后端。ACS 读取需要 `SPLUNK_ACS_TOKEN`（stack 从 URL 推导）。ACS 源默认为商业端点 `https://admin.splunk.com`；对于 FedRAMP stack，请设置 `SPLUNK_ACS_BASE_URL=https://admin.splunkcloudgc.com`。 Cloud 覆盖范围是 **只读的**，尚未通过在线 stack 认证，因此它无法提供的操作会以明确的 `unsupported_backend` 错误停止（exit 4），而不是进行猜测。`splunk inspect` 会报告推断出的后端及其支持的内容，供想了解的人参考。MCP wrapper 是计划中的后续工作。 ## 测试 ``` .venv/bin/python -m pytest # unit tests (mocked HTTP) SPLUNK_INTEGRATION_TEST=true .venv/bin/python -m pytest -m integration # against a live/Docker Splunk ``` CI 会在 x86 runner 上针对 Docker 化的 `splunk/splunk` 运行集成测试套件，其中 KV Store（及其捆绑的 MongoDB）原生运行。在 Apple Silicon 上，该 MongoDB 需要模拟镜像中缺失的 AVX 指令，因此在启动本地容器时需 **禁用** KV Store（通过镜像的 `default.yml` / `SPLUNK_DEFAULTS_URL` 设置 `server.conf [kvstore] disabled = true`）。除 KV Store 外的所有内容都可在本地运行；依赖 KV Store 的检查仅在 CI 中运行。 ## 贡献 该包将不依赖 Click 的核心与轻量级 CLI shell 分开： - `src/vct_splunk/core/` — 纯函数和类型化错误；从不导入 Click。 - `src/vct_splunk/commands/` — Click 适配器（每个命令组一个模块）以及共享的 `context` 和 `output` 辅助程序。 保持模块小巧且用途单一。测试在 `tests/unit/` 和 `tests/integration/` 下映射此布局。有关设置和 pre-PR 检查，请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)；有关架构和约定，请参阅 [AGENTS.md](./AGENTS.md)。 ## 许可证 参见 [LICENSE](./LICENSE)。 更多内容请访问 [docs.dryvist.com](https://docs.dryvist.com)。