Identity AIops

Identity AIops

面向可自托管身份提供商的受治理 AI 运维——Keycloak + authentik。

identity-aiops 为 AI Agent（以及监督它们的人类）提供安全、可审计的方式，用于运维自建及中小型基础设施的身份平面：谁可以登录、发生了什么故障及其原因、哪些 OAuth 客户端配置有误，以及哪些用户仍未设置第二重身份验证。它专为自行运行 Keycloak 或 authentik、希望借助 Agent 运维身份系统并留有凭证的团队打造——每次工具调用都会经过审计，写入操作会标注风险等级，并提供试运行预览和撤销令牌。

验证状态：基于公开的 Keycloak 管理 REST API 和 authentik API v3 建模，并通过模拟响应进行了测试；目前尚无针对实时实例的端到端运行记录。identity-aiops doctor 是最快的实时检查方式——请参阅 docs/VERIFICATION.md。

功能

领域	工具
Realm / 系统	概览、Realm 设置（暴力破解防护、密码/OTP 策略）、身份提供商
用户	列表/搜索、详情、数量、会话、凭据（MFA 范围）、群组、成员、锁定状态
事件	身份验证事件、管理员/配置变更事件
客户端	列表、详情、单个客户端会话、会话统计
旗舰级根因分析	login_failure_rca — 区分暴力破解（喷洒式/定向）与客户端配置错误、凭据过期风暴或账户锁定风暴；stale_access_audit — 识别休眠用户、从未登录的账户、以交互方式使用的服务账户、孤立会话；client_misconfig_audit — 识别通配符/http 重定向 URI、带密钥的公共客户端、隐式流、缺少 PKCE、密码授权（按风险排序）；mfa_coverage_analysis — 覆盖率、缺口清单
受治理的写入操作	disable_user / enable_user（成对撤销）、revoke_user_sessions、require_password_reset（撤销时清除标记）、update_client_redirect_uris（撤销时恢复此前的列表）、rotate_client_secret（屏蔽 priorState）

共 29 个 MCP 工具：21 个读取工具（包括 4 项分析）+ 6 个受治理的写入工具 + 2 个撤销工具（undo_list、undo_apply）。两种平台使用相同的工具——每个目标的 platform 字段会选择相应的 API 格式（身份验证流程 + 资源路径）。

支持的平台

平台	API	身份验证
keycloak	管理 REST API（/admin/realms/{realm}/...）	针对 /realms/{realm}/protocol/openid-connect/token 使用 OAuth2 客户端凭据授权；收到 401 时自动刷新短期令牌
authentik	API v3（/api/v3/...）	长期有效的 API 令牌（Bearer）

平台说明：require_password_reset、rotate_client_secret、client_sessions、client_session_stats 和 user_lockout_status 均采用 Keycloak 格式（authentik 没有对应的端点——这些工具会返回说明性错误）。authentik 提供全局会话列表，供过期访问审计检查孤立会话时使用。

缺少你需要的平台（Authelia、Zitadel、Ory……）、端点或分析功能？欢迎通过 issue/PR 提交功能需求——请前往 https://github.com/AIops-tools/Identity-AIops 提交 issue 或 PR，欢迎提出功能需求。

此工具能做什么、不能做什么

它会准确执行身份提供商操作（读取和写入），并记录每一项操作。它不会决定是否允许执行写入操作。这取决于 Agent 的判断，或你连接的账户权限：只为 Keycloak 服务账户（或 authentik 令牌）授予你希望 Agent 拥有的角色——view-users / view-events / view-clients，不要授予任何 manage-* 角色——这样写入操作就会在服务端被拒绝，因为权限实际由服务端控制。

因此，没有只读开关、策略文件或需要配置的审批关卡。此工具唯一保证的是，不会有任何操作悄无声息：每次调用，无论通过 MCP 还是 CLI，都会写入审计记录，保存在 ~/.identity-aiops/audit.db 中；可撤销的写入操作仍会保存操作前状态（通过获取而非猜测），并记录可重放的逆操作。

每个工具都会声明一个 risk_level，并将其作为描述性级别写入审计记录，方便审核者快速看出某条记录是否属于高风险密钥轮换等操作。它只是标签，不是关卡。

正在运行较小的模型或本地模型？请参阅 agent-guardrails.md——其中列出了此工具现已为你实施的护栏（因此你无需在提示词中重复说明），并提供了一份现成的系统提示词，用于处理剩余事项。

快速开始

作为 Claude Code 插件

一次安装即可为 Agent 同时提供技能和 MCP 服务：

/plugin marketplace add AIops-tools/marketplace
/plugin install identity-aiops@aiops-tools

MCP 服务通过 uv 获取，并固定到此插件声明的软件包版本，以便将审计记录追溯到写入记录的代码。凭据仍通过 identity-aiops init 配置——详见下文。

作为 OpenClaw 插件

同一套插件也发布在 ClawHub 上，一次安装即可同时提供技能和 MCP 服务：

openclaw plugins install clawhub:@zw008/identity-aiops
openclaw skills info identity-aiops          # expect: Visible to model: yes

之后请重启 OpenClaw 网关，使其加载插件。MCP 服务通过 uv 获取，并固定到此确切版本，因此 uvx 必须位于 PATH 中——如果没有，技能仍会安装，但会报告 Visible to model: no。凭据按下文所述配置。

作为 CLI 或独立 MCP 服务

uv tool install identity-aiops        # or: pipx install identity-aiops

identity-aiops init      # wizard: target + realm + credential (encrypted)
identity-aiops doctor    # token acquisition + user-count probe per target
identity-aiops overview  # one-shot estate summary

对于 Keycloak，请创建一个启用了 Service accounts roles 的机密客户端，并向其服务账户授予你希望 Agent 拥有的 realm-management 角色（先从 view-users、view-events、view-clients 开始；只有希望允许受管控的写入操作时，才添加 manage-users / manage-clients）。对于 authentik，请为（权限遵循最小化原则的）管理员用户创建 API 令牌。

CLI 功能：users（list/show/sessions/credentials + disable/enable/ revoke-sessions/require-reset）、clients（list/show + set-redirect-uris/ rotate-secret）、events、overview、doctor、secret、init、mcp。 写入命令支持 --dry-run，并始终要求二次确认；实际执行委托给受管控的 MCP 对应工具，因此 CLI 写入操作也会写入审计日志。

MCP 配置

{
  "mcpServers": {
    "identity-aiops": {
      "command": "uvx",
      "args": ["--from", "identity-aiops", "identity-aiops-mcp"],
      "env": {
        "IDENTITY_AIOPS_MASTER_PASSWORD": "<master password for secrets.enc>"
      }
    }
  }
}

env-block 注意事项：MCP 客户端会在最小化环境中启动服务——不会继承 shell 配置文件中的变量。服务需要的所有内容（IDENTITY_AIOPS_MASTER_PASSWORD、备用的 IDENTITY_AIOPS_HOME、用于在审计记录中标注写入操作者的 IDENTITY_AUDIT_APPROVED_BY）都必须在上方的 env 块中设置。

治理

每个 MCP 工具都通过随项目提供的治理框架运行 （identity_aiops/governance/，零外部依赖）：

• 审计 — 每次调用（包括错误）都会记录到 ~/.identity-aiops/audit.db，包含参数、状态和风险级别，以及任何 可选的审批人／理由注释。它负责记录，不负责授权。
• 预算 — 每个会话的调用次数／时间预算，以及失控熔断器 （IDENTITY_MAX_TOOL_CALLS、IDENTITY_MAX_TOOL_SECONDS、 IDENTITY_RUNAWAY_MAX）——这是安全后备措施，而非授权关卡。
• 风险等级 — 读取操作为 low；控制／卫生类写入（disable_user、 revoke_user_sessions、require_password_reset）为 medium； 授予访问权限或替换边界的写入（enable_user、 update_client_redirect_uris、rotate_client_secret）为 high。该等级 是附加到审计记录上的描述性标签，而非关卡——是否执行写入由 Agent 判断 或连接账户的权限决定。IDENTITY_AUDIT_APPROVED_BY / IDENTITY_AUDIT_RATIONALE 是可选注释，设置后会记录，但从不强制要求。
• 撤销 — 可逆写入会捕获真实的先前状态（在变更前获取，绝不猜测），并在 ~/.identity-aiops/undo.db 中记录可重放的逆向描述符。不可逆写入 （revoke_user_sessions、rotate_client_secret）仅记录 priorState——密钥会以 遮蔽形式存储，绝不明文保存。
• 清理 — IdP 返回的每个字符串都会经过注入安全规范化处理（限制长度、剔除控制字符）， 再提供给 Agent。
• 密钥 — 凭据使用 Fernet 加密（密钥由 scrypt 派生），存储于 ~/.identity-aiops/secrets.enc，绝不以明文形式写入磁盘；旧版 IDENTITY_<TARGET>_SECRET 环境变量仍可作为回退方式使用，并且 identity-aiops secret migrate 可将其迁移进来。TLS 验证默认开启。

配置

~/.identity-aiops/config.yaml（由 init 创建）：

targets:
  - name: sso1
    platform: keycloak
    base_url: https://sso.example.com
    realm: master
    username: identity-aiops-agent   # the confidential client's client_id
    verify_ssl: true
  - name: ak1
    platform: authentik
    base_url: https://auth.example.com
    verify_ssl: true

设置 IDENTITY_AIOPS_HOME 可更改所有状态文件（配置、密钥、审计、 撤销）的存放位置。IDENTITY_AIOPS_CONFIG 用于为 MCP 服务指定备用 配置文件。

开发

uv sync
uv run pytest -q
uv run ruff check .

MIT 许可证。属于 AIops-tools 系列 — 面向可自托管基础设施的治理型 AI 运维工具。