identity-aiops 0.1.0__tar.gz

identity_aiops-0.1.0/.github/workflows/mcp-publish.yml

@@ -0,0 +1,55 @@
+name: mcp-publish
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish-mcp:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Wait for PyPI
+        # The release event also triggers the PyPI publish workflow; the MCP
+        # registry validates that the package version exists on PyPI, so poll
+        # until it has propagated (every 15s, up to 10 minutes).
+        run: |
+          python3 - <<'EOF'
+          import json
+          import sys
+          import time
+          import urllib.error
+          import urllib.request
+
+          with open("server.json", encoding="utf-8") as f:
+              package = json.load(f)["packages"][0]
+          name, version = package["identifier"], package["version"]
+          url = f"https://pypi.org/pypi/{name}/{version}/json"
+          deadline = time.monotonic() + 600
+          while True:
+              try:
+                  with urllib.request.urlopen(url, timeout=10):
+                      print(f"{name}=={version} is available on PyPI.")
+                      sys.exit(0)
+              except (urllib.error.URLError, OSError) as exc:
+                  print(f"{name}=={version} not on PyPI yet ({exc}); "
+                        "retrying in 15s...")
+              if time.monotonic() >= deadline:
+                  sys.exit(f"Timed out after 10 minutes waiting for "
+                           f"{name}=={version} to appear on PyPI. "
+                           "Check the PyPI publish workflow, then re-run "
+                           "this workflow via workflow_dispatch.")
+              time.sleep(15)
+          EOF
+      - name: Install mcp-publisher
+        run: |
+          curl -sL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+      - name: Login to MCP Registry (GitHub OIDC)
+        run: ./mcp-publisher login github-oidc
+      - name: Publish server.json
+        run: ./mcp-publisher publish

identity_aiops-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+# Trusted Publishing (OIDC) — publishes from GitHub's runners with no API token,
+# sidestepping the local-IP / account new-project rate limit. Configure a matching
+# "trusted publisher" for this package on PyPI (see the repo release notes).
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

identity_aiops-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+dist/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+.coverage

identity_aiops-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## v0.1.0 — 2026-07-17
+
+Initial preview release.
+
+- **27 MCP tools** (21 read incl. 4 flagship analyses, 6 governed writes) across
+  **Keycloak** (admin REST API, client-credentials grant with refresh-on-401)
+  and **authentik** (API v3, Bearer token), selected per target by a
+  name-keyed platform registry.
+- **Flagship analyses**: `login_failure_rca` (password spray / targeted
+  brute-force / stale stored credential / misconfigured client /
+  expired-credential storm / lockout storm), `stale_access_audit` (idle users,
+  never-logged-in accounts, interactive service accounts, orphaned sessions),
+  `client_misconfig_audit` (wildcard/http redirect URIs, public clients with
+  secrets, implicit flow, missing PKCE, password grant — ranked riskScore),
+  `mfa_coverage_analysis` (overall + per-group coverage %, gap list).
+- **Governed writes** with dry-run previews, fetched prior state, and undo where
+  reversible: `disable_user` / `enable_user` (undo pair),
+  `revoke_user_sessions` (priorState session count, no undo),
+  `require_password_reset` (undo clears the flag via `clear=True`),
+  `update_client_redirect_uris` (undo replays the prior list),
+  `rotate_client_secret` (masked priorState, no undo).
+- **Secure by default**: with no `rules.yaml`, high-risk writes require a named
+  approver (`IDENTITY_AUDIT_APPROVED_BY`); `init` seeds a dual-control starter
+  rules file (never clobbers an operator-authored one).
+- **Encrypted secret store** (`secrets.enc`, Fernet + scrypt); TLS verification
+  defaults ON; central percent-encoding of every URL path segment.
+- Vendored governance harness (audit / budget / risk tiers / undo / sanitize) —
+  zero external skill-family dependencies.
+- Preview / mock-only: modelled on the public Keycloak and authentik APIs,
+  validated against mocked responses; `identity-aiops doctor` (token
+  acquisition + user-count probe) is the fastest live check.

identity_aiops-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wei <zhouwei008@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

identity_aiops-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: identity-aiops
+Version: 0.1.0
+Summary: Governed AI-ops for Keycloak + authentik identity providers: users, sessions, auth events, OAuth clients, flagship RCA analyses (login-failure, stale access, client misconfig, MFA coverage), and governed identity writes (disable/enable, session revoke, reset, redirect URIs, secret rotation) with a built-in governance harness (audit, budget, undo, risk tiers)
+Author-email: wei <zhouwei008@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: mcp[cli]<2.0,>=1.10
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: rich<16.0,>=13.0
+Requires-Dist: typer<1.0,>=0.12
+Description-Content-Type: text/markdown
+
+# Identity AIops
+
+**Governed AI-ops for self-hosted identity providers — Keycloak + authentik.**
+
+`identity-aiops` gives AI agents (and the humans supervising them) a safe,
+audited way to operate the identity plane of self-built and small/mid-size
+infrastructure: who can sign in, what failed and why, which OAuth clients are
+misconfigured, and who still has no second factor. It is built for teams
+running their own Keycloak or authentik who want agent-driven identity
+operations **with receipts** — every tool call is audited, writes carry risk
+tiers with dry-run previews and undo tokens, and high-risk actions require a
+named human approver.
+
+> **Preview**: modelled on the public Keycloak admin REST API and authentik API
+> v3 and exercised against mocked responses; not yet validated against live
+> production instances. `identity-aiops doctor` is the fastest live check.
+
+## What it does
+
+| Area | Tools |
+|------|-------|
+| Realm / system | overview, realm settings (brute-force protection, password/OTP policy), identity providers |
+| Users | list/search, detail, count, sessions, credentials (MFA surface), groups, members, lockout status |
+| Events | authentication events, admin/config-change events |
+| Clients | list, detail, per-client sessions, session stats |
+| **Flagship RCA** | `login_failure_rca` — brute-force (spray/targeted) vs misconfigured client vs expired-credential storm vs lockout storm; `stale_access_audit` — dormant users, never-logged-in accounts, service accounts used interactively, orphaned sessions; `client_misconfig_audit` — wildcard/http redirect URIs, public clients with secrets, implicit flow, missing PKCE, password grant (ranked risk); `mfa_coverage_analysis` — coverage %, gap list |
+| Governed writes | `disable_user` / `enable_user` (undo pair), `revoke_user_sessions`, `require_password_reset` (undo clears the flag), `update_client_redirect_uris` (undo replays the prior list), `rotate_client_secret` (masked priorState) |
+
+27 MCP tools: 21 reads (including the 4 analyses) + 6 governed writes. The
+same tools work on both platforms — a per-target `platform` field selects the
+API shape (auth flow + resource paths).
+
+## Supported platforms
+
+| Platform | API | Auth |
+|----------|-----|------|
+| **keycloak** | Admin REST API (`/admin/realms/{realm}/...`) | OAuth2 client-credentials grant against `/realms/{realm}/protocol/openid-connect/token`; short-lived token auto-refreshed on 401 |
+| **authentik** | API v3 (`/api/v3/...`) | Long-lived API token (Bearer) |
+
+Platform notes: `require_password_reset`, `rotate_client_secret`,
+`client_sessions`, `client_session_stats`, and `user_lockout_status` are
+Keycloak-shaped (authentik has no equivalent endpoint — the tools return a
+teaching error there). authentik contributes the global session list used by
+the stale-access audit's orphaned-session check.
+
+Missing a platform (Authelia, Zitadel, Ory...), an endpoint, or an analysis
+you need? **缺功能提 issue/PR 欢迎留言** — open an issue or PR at
+https://github.com/AIops-tools/Identity-AIops, feature requests welcome.
+
+## Quick start
+
+```bash
+uv tool install identity-aiops        # or: pipx install identity-aiops
+
+identity-aiops init      # wizard: target + realm + credential (encrypted) + policy seed
+identity-aiops doctor    # token acquisition + user-count probe per target
+identity-aiops overview  # one-shot estate summary
+```
+
+For Keycloak, create a **confidential client** with *Service accounts roles*
+enabled and grant its service account the realm-management roles you want the
+agent to have (start with `view-users`, `view-events`, `view-clients`; add
+`manage-users` / `manage-clients` only if you want the governed writes). For
+authentik, create an API token for a (least-privileged) admin user.
+
+CLI surface: `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`.
+Write commands take `--dry-run` and always double-confirm; execution is
+delegated to the governed MCP twins so CLI writes land in the audit log too.
+
+## MCP configuration
+
+```json
+{
+  "mcpServers": {
+    "identity-aiops": {
+      "command": "uvx",
+      "args": ["--from", "identity-aiops", "identity-aiops-mcp"],
+      "env": {
+        "IDENTITY_AIOPS_MASTER_PASSWORD": "<master password for secrets.enc>"
+      }
+    }
+  }
+}
+```
+
+> **env-block caveat**: MCP clients launch the server with a minimal
+> environment — variables from your shell profile are NOT inherited. Anything
+> the server needs (`IDENTITY_AIOPS_MASTER_PASSWORD`, an alternate
+> `IDENTITY_AIOPS_HOME`, `IDENTITY_AUDIT_APPROVED_BY` for high-risk writes)
+> must be set in the `env` block above.
+
+## Governance
+
+Every MCP tool runs through the vendored governance harness
+(`identity_aiops/governance/`, zero external dependencies):
+
+- **Audit** — every call (including denials and errors) lands in
+  `~/.identity-aiops/audit.db` with params, status, risk level, and approver.
+- **Budget** — per-session call/time budgets and a runaway breaker
+  (`IDENTITY_MAX_TOOL_CALLS`, `IDENTITY_MAX_TOOL_SECONDS`,
+  `IDENTITY_RUNAWAY_MAX`).
+- **Risk tiers + approval** — reads are `low`; containment/hygiene writes
+  (`disable_user`, `revoke_user_sessions`, `require_password_reset`) are
+  `medium`; access-granting or boundary-replacing writes (`enable_user`,
+  `update_client_redirect_uris`, `rotate_client_secret`) are `high`.
+  **Secure by default**: with no `rules.yaml`, high/critical writes are denied
+  unless a named approver is present (`IDENTITY_AUDIT_APPROVED_BY`, plus
+  `IDENTITY_AUDIT_RATIONALE`). `identity-aiops init` seeds this dual-control
+  rule explicitly; the file hot-reloads.
+- **Undo** — reversible writes capture the REAL prior state (fetched before
+  mutating, never guessed) and record a replayable inverse descriptor in
+  `~/.identity-aiops/undo.db`. Irreversible writes (`revoke_user_sessions`,
+  `rotate_client_secret`) record priorState only — the secret is stored
+  **masked**, never in clear.
+- **Sanitize** — every string an IdP returns is folded through an
+  injection-safe normaliser (bounded length, control characters stripped)
+  before an agent sees it.
+- **Secrets** — credentials live Fernet-encrypted (scrypt-derived key) in
+  `~/.identity-aiops/secrets.enc`, never plaintext on disk; a legacy
+  `IDENTITY_<TARGET>_SECRET` env var is honoured as fallback and
+  `identity-aiops secret migrate` moves it in. TLS verification defaults ON.
+
+## Configuration
+
+`~/.identity-aiops/config.yaml` (created by `init`):
+
+```yaml
+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
+```
+
+Set `IDENTITY_AIOPS_HOME` to relocate all state (config, secrets, audit,
+undo, policy). `IDENTITY_AIOPS_CONFIG` points the MCP server at an alternate
+config file.
+
+## Development
+
+```bash
+uv sync
+uv run pytest -q
+uv run ruff check .
+```
+
+MIT License. Part of the [AIops-tools](https://github.com/AIops-tools) line —
+governed AI-ops tooling for self-hosted infrastructure.

identity_aiops-0.1.0/README.md

@@ -0,0 +1,156 @@
+# Identity AIops
+
+**Governed AI-ops for self-hosted identity providers — Keycloak + authentik.**
+
+`identity-aiops` gives AI agents (and the humans supervising them) a safe,
+audited way to operate the identity plane of self-built and small/mid-size
+infrastructure: who can sign in, what failed and why, which OAuth clients are
+misconfigured, and who still has no second factor. It is built for teams
+running their own Keycloak or authentik who want agent-driven identity
+operations **with receipts** — every tool call is audited, writes carry risk
+tiers with dry-run previews and undo tokens, and high-risk actions require a
+named human approver.
+
+> **Preview**: modelled on the public Keycloak admin REST API and authentik API
+> v3 and exercised against mocked responses; not yet validated against live
+> production instances. `identity-aiops doctor` is the fastest live check.
+
+## What it does
+
+| Area | Tools |
+|------|-------|
+| Realm / system | overview, realm settings (brute-force protection, password/OTP policy), identity providers |
+| Users | list/search, detail, count, sessions, credentials (MFA surface), groups, members, lockout status |
+| Events | authentication events, admin/config-change events |
+| Clients | list, detail, per-client sessions, session stats |
+| **Flagship RCA** | `login_failure_rca` — brute-force (spray/targeted) vs misconfigured client vs expired-credential storm vs lockout storm; `stale_access_audit` — dormant users, never-logged-in accounts, service accounts used interactively, orphaned sessions; `client_misconfig_audit` — wildcard/http redirect URIs, public clients with secrets, implicit flow, missing PKCE, password grant (ranked risk); `mfa_coverage_analysis` — coverage %, gap list |
+| Governed writes | `disable_user` / `enable_user` (undo pair), `revoke_user_sessions`, `require_password_reset` (undo clears the flag), `update_client_redirect_uris` (undo replays the prior list), `rotate_client_secret` (masked priorState) |
+
+27 MCP tools: 21 reads (including the 4 analyses) + 6 governed writes. The
+same tools work on both platforms — a per-target `platform` field selects the
+API shape (auth flow + resource paths).
+
+## Supported platforms
+
+| Platform | API | Auth |
+|----------|-----|------|
+| **keycloak** | Admin REST API (`/admin/realms/{realm}/...`) | OAuth2 client-credentials grant against `/realms/{realm}/protocol/openid-connect/token`; short-lived token auto-refreshed on 401 |
+| **authentik** | API v3 (`/api/v3/...`) | Long-lived API token (Bearer) |
+
+Platform notes: `require_password_reset`, `rotate_client_secret`,
+`client_sessions`, `client_session_stats`, and `user_lockout_status` are
+Keycloak-shaped (authentik has no equivalent endpoint — the tools return a
+teaching error there). authentik contributes the global session list used by
+the stale-access audit's orphaned-session check.
+
+Missing a platform (Authelia, Zitadel, Ory...), an endpoint, or an analysis
+you need? **缺功能提 issue/PR 欢迎留言** — open an issue or PR at
+https://github.com/AIops-tools/Identity-AIops, feature requests welcome.
+
+## Quick start
+
+```bash
+uv tool install identity-aiops        # or: pipx install identity-aiops
+
+identity-aiops init      # wizard: target + realm + credential (encrypted) + policy seed
+identity-aiops doctor    # token acquisition + user-count probe per target
+identity-aiops overview  # one-shot estate summary
+```
+
+For Keycloak, create a **confidential client** with *Service accounts roles*
+enabled and grant its service account the realm-management roles you want the
+agent to have (start with `view-users`, `view-events`, `view-clients`; add
+`manage-users` / `manage-clients` only if you want the governed writes). For
+authentik, create an API token for a (least-privileged) admin user.
+
+CLI surface: `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`.
+Write commands take `--dry-run` and always double-confirm; execution is
+delegated to the governed MCP twins so CLI writes land in the audit log too.
+
+## MCP configuration
+
+```json
+{
+  "mcpServers": {
+    "identity-aiops": {
+      "command": "uvx",
+      "args": ["--from", "identity-aiops", "identity-aiops-mcp"],
+      "env": {
+        "IDENTITY_AIOPS_MASTER_PASSWORD": "<master password for secrets.enc>"
+      }
+    }
+  }
+}
+```
+
+> **env-block caveat**: MCP clients launch the server with a minimal
+> environment — variables from your shell profile are NOT inherited. Anything
+> the server needs (`IDENTITY_AIOPS_MASTER_PASSWORD`, an alternate
+> `IDENTITY_AIOPS_HOME`, `IDENTITY_AUDIT_APPROVED_BY` for high-risk writes)
+> must be set in the `env` block above.
+
+## Governance
+
+Every MCP tool runs through the vendored governance harness
+(`identity_aiops/governance/`, zero external dependencies):
+
+- **Audit** — every call (including denials and errors) lands in
+  `~/.identity-aiops/audit.db` with params, status, risk level, and approver.
+- **Budget** — per-session call/time budgets and a runaway breaker
+  (`IDENTITY_MAX_TOOL_CALLS`, `IDENTITY_MAX_TOOL_SECONDS`,
+  `IDENTITY_RUNAWAY_MAX`).
+- **Risk tiers + approval** — reads are `low`; containment/hygiene writes
+  (`disable_user`, `revoke_user_sessions`, `require_password_reset`) are
+  `medium`; access-granting or boundary-replacing writes (`enable_user`,
+  `update_client_redirect_uris`, `rotate_client_secret`) are `high`.
+  **Secure by default**: with no `rules.yaml`, high/critical writes are denied
+  unless a named approver is present (`IDENTITY_AUDIT_APPROVED_BY`, plus
+  `IDENTITY_AUDIT_RATIONALE`). `identity-aiops init` seeds this dual-control
+  rule explicitly; the file hot-reloads.
+- **Undo** — reversible writes capture the REAL prior state (fetched before
+  mutating, never guessed) and record a replayable inverse descriptor in
+  `~/.identity-aiops/undo.db`. Irreversible writes (`revoke_user_sessions`,
+  `rotate_client_secret`) record priorState only — the secret is stored
+  **masked**, never in clear.
+- **Sanitize** — every string an IdP returns is folded through an
+  injection-safe normaliser (bounded length, control characters stripped)
+  before an agent sees it.
+- **Secrets** — credentials live Fernet-encrypted (scrypt-derived key) in
+  `~/.identity-aiops/secrets.enc`, never plaintext on disk; a legacy
+  `IDENTITY_<TARGET>_SECRET` env var is honoured as fallback and
+  `identity-aiops secret migrate` moves it in. TLS verification defaults ON.
+
+## Configuration
+
+`~/.identity-aiops/config.yaml` (created by `init`):
+
+```yaml
+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
+```
+
+Set `IDENTITY_AIOPS_HOME` to relocate all state (config, secrets, audit,
+undo, policy). `IDENTITY_AIOPS_CONFIG` points the MCP server at an alternate
+config file.
+
+## Development
+
+```bash
+uv sync
+uv run pytest -q
+uv run ruff check .
+```
+
+MIT License. Part of the [AIops-tools](https://github.com/AIops-tools) line —
+governed AI-ops tooling for self-hosted infrastructure.

identity_aiops-0.1.0/RELEASE_NOTES.md

@@ -0,0 +1,68 @@
+# Identity AIops v0.1.0 — preview
+
+Governed AI-ops for **Keycloak** and **authentik** identity providers for AI
+agents, with a built-in governance harness (audit, policy, token/runaway
+budget, undo-token recording, graduated risk tiers) and an encrypted credential
+store. Standalone — no external skill-family dependency. One MCP server spans
+both platforms: a per-target `platform` field selects the API shape, and the
+same 27 tools work on Keycloak (admin REST `/admin/realms/{realm}/...`,
+client-credentials grant with automatic refresh-on-401) and authentik (API v3
+`/api/v3/...`, Bearer token).
+
+> **Not affiliated with, endorsed by, or sponsored by the Keycloak project,
+> Red Hat, Authentik Security Inc., or the authentik project.** Keycloak and
+> authentik are trademarks of their respective owners.
+
+> **Preview / mock-only.** All behaviour is validated against mocked
+> Keycloak/authentik JSON responses; it has **not** been run against a live
+> IdP. The concrete REST paths are modelled from each project's public API and
+> need live verification. Both platforms are free/self-hostable, so a self-hosted
+> lab is the easiest live check — `identity-aiops doctor` is the fastest.
+
+## Highlights
+
+- **27 MCP tools** (21 read, 6 write), every one wrapped with `@governed_tool`:
+  - **Realm / system** — `identity_overview`, `realm_info`,
+    `list_identity_providers`.
+  - **Users / groups** — `list_users`, `user_detail`, `user_count`,
+    `user_sessions`, `user_credentials`, `list_groups`, `group_members`,
+    `user_lockout_status`.
+  - **Events** — `login_events`, `admin_events`.
+  - **Clients** — `list_clients`, `client_detail`, `client_sessions`,
+    `client_session_stats`.
+  - **Writes** — `disable_user`, `revoke_user_sessions`,
+    `require_password_reset` (med); `enable_user`,
+    `update_client_redirect_uris`, `rotate_client_secret` (**high**).
+- **Flagship analyses** (transparent heuristics that show their numbers):
+  - `login_failure_rca` — failed-auth events windowed by user/IP/client:
+    password spray, targeted brute-force, stale stored credential,
+    misconfigured client (rotated secret still deployed), expired-credential
+    storm, lockout storm — each with cause + action.
+  - `stale_access_audit` — enabled users idle > N days, never-logged-in
+    accounts, service accounts used interactively, orphaned sessions.
+  - `client_misconfig_audit` — wildcard/plain-http redirect URIs, public
+    clients carrying secrets, implicit flow, missing PKCE, password grant —
+    ranked per-client riskScore with evidence.
+  - `mfa_coverage_analysis` — coverage %, per-group breakdown, gap list.
+- **Governed writes** — reversible writes capture the **real fetched
+  before-state** and record an undo descriptor (`disable_user` ↔
+  `enable_user`; `require_password_reset` undoes via `clear=True`;
+  `update_client_redirect_uris` replays the prior list). Irreversible writes
+  record priorState only — `rotate_client_secret` stores a **masked**
+  fingerprint, never the value. High-risk writes take a `dry_run` preview and
+  require an approver.
+- **Encrypted secret store** — the Keycloak client secret or authentik API
+  token lives encrypted in `~/.identity-aiops/secrets.enc` (Fernet + scrypt),
+  never plaintext; legacy `IDENTITY_<TARGET>_SECRET` env fallback. TLS
+  verification defaults ON.
+- **Secure by default** — with no `rules.yaml`, high-risk writes are denied
+  unless `IDENTITY_AUDIT_APPROVED_BY` names an approver; `init` seeds the
+  dual-control rule explicitly.
+
+## Install
+
+```bash
+uv tool install identity-aiops
+identity-aiops init
+identity-aiops doctor
+```

identity_aiops-0.1.0/SECURITY.md

@@ -0,0 +1,83 @@
+# Security Policy
+
+## Disclaimer
+
+Community-maintained open-source project. **Not affiliated with, endorsed by, or
+sponsored by the Keycloak project, Red Hat, Authentik Security Inc., or the
+authentik project.** Product and trademark names (Keycloak, authentik) belong to
+their owners. Source is auditable under the MIT license.
+
+## Reporting Vulnerabilities
+
+Report privately via a GitHub Security Advisory on
+[github.com/AIops-tools/Identity-AIops](https://github.com/AIops-tools/Identity-AIops/security/advisories)
+or email zhouwei008@gmail.com. Please do not open public issues for security
+reports.
+
+## Security Design
+
+### Credential Management
+- Per-target secrets — the Keycloak confidential client's **client secret** or the
+  authentik **API token** — live **encrypted** in
+  `~/.identity-aiops/secrets.enc` (Fernet/AES-128 + scrypt-derived key; chmod
+  600), never in `config.yaml` and never in source. The master password is never
+  stored — only a per-store random salt and the ciphertext are on disk.
+- A legacy plaintext env var `IDENTITY_<TARGET_NAME_UPPER>_SECRET` is still
+  honoured as a fallback with a deprecation warning (migrate with
+  `identity-aiops secret migrate`).
+- The secret is held only in memory and never logged or echoed. Keycloak's client
+  secret is exchanged at request time for a short-lived access token
+  (client-credentials grant, refreshed once on a 401); authentik's API token is
+  presented as a Bearer header. The config file holds only platform, base URL,
+  realm, client_id, and TLS settings.
+- `rotate_client_secret` never returns or records a secret in clear — old and new
+  values appear only as masked fingerprints in results and the audit log.
+
+### Governed Operations
+Every MCP tool runs through the bundled `@governed_tool` harness
+(`identity_aiops.governance`):
+- **Audit** — every call logged to a local SQLite DB under `~/.identity-aiops/`
+  (relocatable via `IDENTITY_AIOPS_HOME`), agent-attributed, secret-redacted.
+- **Token/runaway budget** — hard ceilings (`IDENTITY_MAX_TOOL_CALLS` /
+  `IDENTITY_MAX_TOOL_SECONDS`) plus an on-by-default guard that trips a tight
+  poll/retry loop, preventing unbounded API consumption.
+- **Graduated risk tiers** — `~/.identity-aiops/rules.yaml` `risk_tiers` gate
+  writes by environment/tag; the highest tiers require a recorded approver.
+- **Undo-token recording** — reversible writes capture the BEFORE state (via a
+  real GET) and record an inverse descriptor (`disable_user` ↔ `enable_user`;
+  `require_password_reset` clears via its own `clear=True` path;
+  `update_client_redirect_uris` replays the prior list) so the change can be
+  rolled back.
+
+### State-Changing Operations
+Access-granting / boundary-replacing writes — `enable_user`,
+`update_client_redirect_uris`, `rotate_client_secret` — are `risk_level=high`,
+accept a `dry_run` preview, and (under `risk_tiers`) require a recorded approver
+(`IDENTITY_AUDIT_APPROVED_BY` + `IDENTITY_AUDIT_RATIONALE`).
+`revoke_user_sessions` and `rotate_client_secret` are irreversible (priorState
+recorded, no undo). Containment/hygiene writes — `disable_user`,
+`revoke_user_sessions`, `require_password_reset` — are `risk_level=medium`.
+
+### SSL/TLS Verification
+`verify_ssl` defaults to true; disable only for self-signed lab certificates.
+
+### Prompt-Injection Protection
+All IdP-returned text (usernames, email addresses, event messages, client names,
+redirect URIs, group names) is passed through a `sanitize()` truncate +
+control-character strip before reaching the agent.
+
+### Network Scope
+No webhooks, no telemetry, no outbound calls beyond the configured Keycloak /
+authentik REST API endpoints. No post-install scripts or background services.
+
+## Static Analysis
+
+```bash
+uvx bandit -r identity_aiops/ mcp_server/
+uv run ruff check .
+```
+
+## Supported Versions
+
+The latest released version receives security fixes. This is a preview (0.x);
+pin a version in production.

identity_aiops-0.1.0/identity_aiops/__init__.py

@@ -0,0 +1,14 @@
+"""identity-aiops — governed Keycloak + authentik identity operations for AI agents.
+
+Standalone and self-contained: the governance harness (audit, token budget,
+undo-token recording, graduated risk tiers, output sanitize) is
+bundled under ``identity_aiops.governance`` — this package has no external
+skill-family dependency. Preview: not yet full-coverage.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("identity-aiops")
+except PackageNotFoundError:  # running from an uninstalled source tree
+    __version__ = "0.0.0+unknown"

identity_aiops-0.1.0/identity_aiops/cli/__init__.py

@@ -0,0 +1,9 @@
+"""CLI package for identity-aiops.
+
+Re-exports ``app`` so the pyproject entry point
+``identity-aiops = "identity_aiops.cli:app"`` works unchanged.
+"""
+
+from identity_aiops.cli._root import app
+
+__all__ = ["app"]