Metadata-Version: 2.4
Name: keycloak-mcp
Version: 1.4.0
Summary: MCP server for KeyCloak Admin REST API via Service Account
Author: AIKAWA Shigechika
License-Expression: MIT
Project-URL: Homepage, https://github.com/shigechika/keycloak-mcp
Project-URL: Repository, https://github.com/shigechika/keycloak-mcp
Project-URL: Issues, https://github.com/shigechika/keycloak-mcp/issues
Keywords: keycloak,mcp,model-context-protocol,sso,authentication
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<3,>=2
Requires-Dist: httpx
Requires-Dist: tzdata; sys_platform == "win32"
Dynamic: license-file

<!-- mcp-name: io.github.shigechika/keycloak-mcp -->

# keycloak-mcp

English | [日本語](README.ja.md)

An MCP (Model Context Protocol) server for the [KeyCloak](https://www.keycloak.org/) Admin REST API.

Documentation: <https://shigechika.github.io/keycloak-mcp/>

Authenticates via a Service Account (**Client Credentials Grant**), so no human password or TOTP is involved. Also Infinispan-safe — it never creates user sessions and never hits the userinfo endpoint.

## Features

### Users

| Tool | Description |
|------|-------------|
| `count_users` | Total user count in the realm |
| `search_users` | Partial-match search (username / email / name) |
| `get_user` | Full detail for an exact username |
| `reset_password` | Reset one user's password |
| `reset_passwords_batch` | Bulk reset from CSV (`username,password` per line; blank password is generated) |
| `get_user_sessions` | Active sessions for one user, timestamps in local time |
| `logout_user` | Kill all active sessions for one user |
| `set_user_enabled` | Enable or disable one user; disabling blocks all logins (custom attributes preserved) |

### MFA / Credentials

| Tool | Description |
|------|-------------|
| `get_user_credentials` | Credential types configured for one user; an `otp` entry means TOTP/HOTP is set up |
| `get_totp_users` | Realm-wide TOTP adoption: how many users have an `otp` credential, with percentage and (optionally) the user list. Enumerates users and reads each one's credentials (N+1; bound with `max_users`) |

### Groups

| Tool | Description |
|------|-------------|
| `list_user_groups` | Which groups a user belongs to |
| `list_users_by_group` | Members of a group |

### Security

| Tool | Description |
|------|-------------|
| `get_brute_force_status` | Whether a user is currently locked by brute-force detection |
| `get_realm_security_defenses` | Realm-level security policy: whether brute-force detection is enabled and its thresholds, the password policy, and browser security headers |
| `get_config_changes` | What changed in the realm configuration since a stored daily snapshot (see *Configuration snapshots*). Read-only; `baseline_date` picks an older snapshot. |
| `get_login_failures_by_ip` | Failure breakdown by source IP (site-labeled when `KEYCLOAK_SITES_INI` is set) |
| `get_ip_activity` | Exhaustive investigation of one source IP: success/failure counts, affected users/clients, timeline. Returns structured JSON. |
| `spray_check` | Password-spray detection with the breach list built in: every external IP with ≥ 10 distinct users and < 20 % login success is a spray source, and its successful logins (evidence tuple `time / ip / username / user_id / client_id`) are the breach candidates. Each row carries a `confidence`: `high` is a breach verdict; `low` means the volume rule fired on a shared egress (school NAT, home line, VDI) — signalled by `user_success_rate` (distinct users that logged in ÷ distinct users, ≥ 0.2), `failure_concentration` (share of failures on one username, ≥ 0.5) or a `KEYCLOAK_KNOWN_EGRESS` match — and the logins are to be verified with the owner, not published. `top_failed_users` and `not_found_domains` show who kept failing and which mistyped domains produced `user_not_found`. Fixed-shape JSON, `complete: false` when the window was truncated. |
| `detect_login_loops` | Flag users who logged in too many times in a short window (redirect loops) |

### Events

| Tool | Description |
|------|-------------|
| `get_events` | Filter by type, username, client, IP, and date range. Username is resolved to user ID internally. Failure events include KeyCloak's `error` field (e.g. `invalid_user_credentials`). |
| `get_login_stats` | Login success/failure totals, paginated across all results |
| `get_login_stats_by_hour` | Logins bucketed by hour of day (local time) |
| `get_login_stats_by_client` | Logins bucketed by client / SP |
| `get_password_update_events` | `UPDATE_PASSWORD` history |

### Admin Events

`get_events` only sees *user* events. Actions driven by an admin — or by a service account writing custom attributes — don't show up there. The admin-event endpoint fills that gap.

| Tool | Description |
|------|-------------|
| `get_admin_events` | Filter by operation (CREATE / UPDATE / DELETE / ACTION), resource type (USER / CLIENT / ROLE / GROUP / …), resource path, and date range |
| `get_user_attribute_history` | UPDATE/ACTION events scoped to one user — handy for tracking when a custom attribute (e.g. `provisioning_flag`) was written by an automated pipeline |

Both tools accept `max_repr` to control the representation payload: positive = truncate to N chars (default 500), `0` = omit, negative = include in full.

### Sessions & Clients

| Tool | Description |
|------|-------------|
| `get_session_stats` | Active session count per client |
| `get_client_sessions` | Active sessions for one client (SP) |
| `list_clients` | SAML and OIDC clients in the realm |
| `get_client` | One client's configuration, including its authentication flow overrides (the per-SP MFA switch). Omits `attributes` and `protocolMappers`, so no client secret or SAML signing material reaches tool output. |
| `get_realm_roles` | Realm-level roles |

### Morning Patrol

| Tool | Description |
|------|-------------|
| `health_check` | Report the running server version and verify the KeyCloak backend is reachable and the service account can authenticate. Lightweight (one token request; no user/event/session scans). Returns a fixed-shape dict with `status`, `auth`, and the configured URL/realm. The tool's own description enumerates the values those fields can take, and is the one place that does. |
| `daily_brief` | One-shot morning health check: login stats, brute-force IPs, spray check (same rule as `spray_check`, with breached accounts and evidence), active sessions, password updates, admin events, and configuration changes (admin events on roles, role mappings, flows, client scopes, protocol mappers, components and the realm, plus the snapshot comparison when `KEYCLOAK_STATE_DIR` is set; both are flagged `[CONFIG]`) in a single Markdown summary. IPs exceeding `ip_failure_threshold` failures (default 50) and spray sources are flagged **WARNING**; API errors surface as **CRITICAL**. `since_hours` controls the look-back window (default 18 h). |

## Setup

```bash
# uv
uv pip install keycloak-mcp

# pip
pip install keycloak-mcp
```

From source:

```bash
git clone https://github.com/shigechika/keycloak-mcp.git
cd keycloak-mcp

# uv
uv sync

# pip
pip install -e .
```

## Configuration

| Variable | Description | Default |
|---|---|---|
| `KEYCLOAK_URL` | Base URL, e.g. `https://keycloak.example.com` | *required* |
| `KEYCLOAK_REALM` | Realm name | `master` |
| `KEYCLOAK_CLIENT_ID` | Service Account client ID | *required* |
| `KEYCLOAK_CLIENT_SECRET` | Client secret | *required* |
| `KEYCLOAK_SITES_INI` | INI file for IP-to-site labeling (see below) | *unset* |
| `KEYCLOAK_KNOWN_EGRESS` | Comma-separated CIDRs of known shared egress points (VDI, VPN concentrators, partner proxies). `spray_check` labels matching IPs `known_egress: true` and marks them `confidence: low`; they are never excluded | *unset* |
| `KEYCLOAK_DEFAULT_DATE_FROM_HOURS` | Default look-back window for event tools when `date_from` is omitted. Set to `0` to scan full history (can hang on large realms). | `24` |
| `KEYCLOAK_DEADLINE` | Per-call wall-clock budget (seconds) for the heavy event/TOTP tools. When a wide window / large realm would exceed it, the tool stops and returns a **disclosed partial** (⚠️ warning) instead of running past the client's ~60s gateway timeout and hammering KeyCloak. Each request's timeout is also capped at the time left, and nothing is retried past the deadline, so one slow page cannot run a call past it. `0` or negative disables. | `45` |
| `KEYCLOAK_MAX_EVENTS` | Per-pagination cap on events fetched by the event tools (also bounds how deep the slow high-offset pagination goes). Over the cap the result is a disclosed partial. `0` or negative disables. | `200000` |
| `KEYCLOAK_MAX_USERS` | Default cap on users scanned by `get_totp_users` when its `max_users` argument is `0` (each user costs one credential call). `0` or negative disables (whole realm, bounded only by `KEYCLOAK_DEADLINE`). | `5000` |
| `KEYCLOAK_USER_ATTRIBUTE_WHITELIST` | Comma-separated custom user-attribute keys that `get_user` is allowed to surface. Unset by default: `get_user` only ever returns username/name/email/enabled/created, since the search endpoint it resolves the username through returns a brief representation with no `attributes` at all. Opting a key in makes `get_user` do one extra by-ID lookup and append that attribute's value when present. Everything else stays out of tool output. As a safety net, a whitelisted key whose name looks credential-shaped (contains `password`, `secret`, `token`, etc.) is reported as blocked rather than shown — not a guarantee, since a credential attribute named outside that pattern list still gets through. | *unset* |
| `KEYCLOAK_GROUP_WRITE_ROOT` | Enables the opt-in group-change tools (`plan_group_changes`, `apply_group_changes`) and confines them to groups below this absolute path (e.g. `/Staff`). Unset, empty or malformed: the two tools are not registered at all. Set it only on a deployment that puts a human approval step in front of the server. | *unset* |
| `KEYCLOAK_PROTECTED_GROUPS` | `;`-separated full group paths that the group-change tools refuse to add to or remove from (descendants included). A malformed entry disables the group-change tools rather than silently dropping the protection. | *unset* |
| `KEYCLOAK_GROUP_BATCH_MAX` | Maximum rows per group-change call. | `30` |
| `KEYCLOAK_GROUP_MODE` | `multi` (KeyCloak's default: a user can be in many groups) or `single` for a deployment where adding a group replaces every other membership (for example an event listener that keeps one group per user). Any other value disables the group tools. See *Group changes*. | `multi` |
| `KEYCLOAK_STATE_DIR` | Directory for the daily configuration snapshots (`<dir>/config-snapshots`, created 0700, files 0600). Unset: no snapshots; `daily_brief` still reports configuration admin events. See *Configuration snapshots*. | *unset* |
| `KEYCLOAK_GROUP_DEADLINE` | Time budget (seconds) for the group-change tools. A batch of 30 users needs more than the default 45 s; raise it where nothing with a ~60 s timeout sits in front of the server (for example a client that spawns it directly). Unset: `KEYCLOAK_DEADLINE`. | *unset* |

### KeyCloak client setup

1. Create a new client in the KeyCloak admin console.
2. Turn on **Client authentication** and **Service account roles**.
3. Give it `view-users`, `view-events`, `view-clients`, and — only if you need password reset — `manage-users`.

### Write operations

Four tools change state by default. Everything else only reads. With group changes
enabled (below), `apply_group_changes` is a fifth.

| Tool | Admin API call |
|---|---|
| `reset_password` | `PUT /users/{id}/reset-password` |
| `reset_passwords_batch` | the same call, once per CSV row |
| `set_user_enabled` | `PUT /users/{id}` with `enabled` toggled |
| `logout_user` | `POST /users/{id}/logout` |

All four need `manage-users` on the Service Account. **Leave that role off and the
server is read-only**: those four tools fail with `403` and every other tool keeps
working, so a realm can be handed to Claude for investigation without granting any
ability to modify it. Grant `manage-users` only when account recovery or
containment is part of the job.

### Group changes (opt-in)

`plan_group_changes` and `apply_group_changes` move users between groups (for example
staff transfers). They exist only when `KEYCLOAK_GROUP_WRITE_ROOT` is set, so a
deployment that shares the binary without an approval step never exposes them.

| Tool | Admin API call |
|---|---|
| `plan_group_changes` | read-only: `GET /users?username=...&exact=true`, `GET /group-by-path/...`, `GET /groups/{id}/role-mappings`, `GET /roles-by-id/{id}/composites`, `GET /clients/{id}`, `GET /users/{id}/groups` |
| `apply_group_changes` | `PUT /users/{id}/groups/{groupId}` then `DELETE /users/{id}/groups/{groupId}` |

- `plan_group_changes` resolves every user and group by exact name/path and returns, per
  row, the current direct groups, the operations that would run and a status. Its
  `digest` covers the resolved IDs, each user's current groups and the policy.
- `apply_group_changes` re-plans and changes nothing unless every row is still executable
  and the digest equals the approved one, so a membership changed by anyone since the
  plan aborts the whole batch. It adds before it removes, vets the destination again
  right before adding, re-reads memberships before each write and reads them back after it, and stops at the first
  mismatch, error or exhausted time budget (`KEYCLOAK_GROUP_DEADLINE`). It does not start a
  user whose operations cannot all finish in the time left, so a stop does not split an add
  from its remove. `applied` is `yes`,
  `no`, `partial` or `unknown` (a write that could not be read back).
- With `KEYCLOAK_GROUP_MODE=single` a move is one add: the server drops the old group
  itself, so no DELETE is sent and the read-back must show the destination alone. A row
  must name the group to add (a remove-only row would leave the user in no group). An
  omitted `remove` is filled in with the user's current group so the approver sees what
  is left, and that group is vetted like a `remove` at plan time and again right before
  the add. A user in more than one group breaks the server's rule and is refused (fix them
  by hand). Users whose previous state a plan cannot restore (they had no group, or the
  server turned out not to replace) are listed in `manual_restore` instead of `reverse`.
  Set it when your KeyCloak behaves this way; in `multi` mode such a server makes every
  move stop as a concurrent change, and in `single` mode a server that keeps the old group
  makes the move stop with a message that the mode does not match.
- Refused targets: anything outside the root, the root itself, and protected groups and
  their descendants.
- A group that carries roles is not refused: moving someone into a department's admin
  group is an ordinary transfer when the approver can do the same in the admin console.
  Each plan row lists `gained_roles` and `lost_roles`: the difference the move makes to the
  roles the user holds through all their group memberships (a role kept through a shared
  ancestor or another group is neither; roles mapped to the user directly are not read).
  `add_roles` and `remove_roles` are the roles membership in each named group carries.
  Realm roles appear by name and client roles as `client:role`; roles inherited from
  ancestor groups and the contents of composite roles (any depth) are included. Show the
  gains and losses to the person approving. They are part of the `digest`, and the
  destination's roles are read again before each add (at most once every 5 seconds per
  group within one call), so a role attached (or added to a composite) after the approval
  stops the run. A row whose role change cannot be
  shown (a current group that does not resolve by path, such as one with `/` in its name)
  is refused.
  Changed in 1.3.0: earlier versions refused any group with role mappings. If you relied on
  that, list those groups in `KEYCLOAK_PROTECTED_GROUPS` before upgrading.
- Membership can grant access without any role (a SAML/OIDC group mapper that a service
  provider checks, an authorization-services group policy). List the groups that must
  never be written by these tools, whatever their roles, in `KEYCLOAK_PROTECTED_GROUPS`.
  Every protected path must exist in KeyCloak: if one does not resolve (renamed, moved,
  different case), every plan is refused until the configuration is fixed.
- The `digest` shows that nothing changed since the plan. It does not prove that a person
  approved the plan: any caller of `plan_group_changes` gets a valid digest. Put the
  approval in front of `apply_group_changes`, for example a client that keeps the digest
  itself and asks a person before each call. Treat each approval as single-use: if the
  memberships return to the planned state (for example after `reverse`), the old digest
  matches again.
- The result includes `reverse`, the changes that would undo what took effect. It is a
  proposal for a new plan and approval, never applied automatically. Restoring a
  membership does not undo access that happened while it was wrong.

Writes need `manage-users`. Depending on the KeyCloak version, reading groups and their
role mappings may also need `query-groups`. Expanding composite roles reads realm roles
(`view-realm`) and naming client roles reads clients (`view-clients`). Run
`plan_group_changes` once to confirm.

### Configuration snapshots (optional)

With `KEYCLOAK_STATE_DIR` set, the first `daily_brief` of each day stores a snapshot of the
realm configuration, and every `daily_brief` compares the current configuration with the
latest snapshot from an earlier day. Changes are a `[CONFIG]` warning with the changed
fields; `get_config_changes` lists all of them.

- Covered: realm settings (brute-force detection, password and OTP policies, session and
  token lifespans, flow bindings), event settings, realm roles and what each composite role
  contains, authentication flows and their executions, required actions, clients (redirect
  URIs, allowed flows, flow overrides, attributes, protocol mappers), client scopes,
  default client scopes, components, and identity providers when the service account may
  read them. Group role mappings and client roles are not in the snapshot; their admin
  events are reported instead.
- Secrets are not stored: string values under keys containing `secret`, `password`,
  `privateKey`, `apiKey`, `credential`, `token` and similar (the markers `get_user` also
  uses) are replaced with `<redacted>`, so a changed secret does not show as a change.
  `true`/`false` and numbers under such keys are settings and stay visible, except under
  a field that is itself a secret (`...password`, `...secret`). This is a safety net for
  the common names, not a guarantee. Long values (certificates, public keys) are stored
  as a hash.
- Only a complete read is stored. When the time budget runs out, the brief says the
  comparison was skipped and the previous baseline stays.
- Snapshots are written only by `daily_brief`, and only the first one of a day, so a change
  made during the day is reported again the next morning. The last 30 are kept.
- Reading the configuration needs `view-realm` and `view-clients`; identity providers
  also need `view-identity-providers`. Without it that section is left out of the
  comparison and the brief says so.

### Verify your setup

After setting the environment variables, run `--check` to confirm authentication works before wiring it into an MCP client:

```bash
export KEYCLOAK_URL=https://keycloak.example.com
export KEYCLOAK_REALM=my-realm
export KEYCLOAK_CLIENT_ID=keycloak-mcp
export KEYCLOAK_CLIENT_SECRET=your-secret
keycloak-mcp --check
# HTTP Request: POST https://keycloak.example.com/realms/my-realm/protocol/openid-connect/token "HTTP/1.1 200 OK"
# OK: authenticated to https://keycloak.example.com/admin/realms/my-realm
```

Exit codes: `0` success, `1` configuration error (missing variable), `2` authentication error.

### IP-to-site labeling (optional)

Point `KEYCLOAK_SITES_INI` at an INI file if you want IP addresses in tool output to be tagged with your site names. Tools like `get_user_sessions`, `get_events`, and `get_login_failures_by_ip` pick it up automatically; anything outside your declared ranges is labeled `external`. Leave the variable unset and IPs are shown as-is.

See [`sites.ini.example`](sites.ini.example). A minimal file:

```ini
[hq]
name = HQ (Tokyo)
ipv4 = 192.0.2.0/24, 198.51.100.0/24
ipv6 = 2001:db8:1::/48

[vpn]
name = VPN
ipv4 = 10.0.0.0/8, 172.16.0.0/12
```

One site per `[section]`. `name` is the display label (falls back to the section name). `ipv4` / `ipv6` take comma-separated CIDRs; a single host is `/32` or `/128`. Matching is first-match in file order — put specific ranges before broad ones.

## Usage

### Claude Code (plugin)

This repository doubles as a single-plugin marketplace, so Claude Code can install
the server for you:

```
/plugin marketplace add shigechika/keycloak-mcp
/plugin install keycloak-mcp@keycloak-mcp
```

The plugin launches `uvx keycloak-mcp` and reads the same environment variables
described in [Configuration](#configuration); export them before starting Claude
Code. `KEYCLOAK_REALM` falls back to `master` and `KEYCLOAK_SITES_INI` may stay
unset.

`uvx` must be on the `PATH` of the process that runs Claude Code — a login
shell usually has it, but a GUI-launched app may not; install
[uv](https://docs.astral.sh/uv/) system-wide if the plugin fails to start.

### Claude Code (manual)

In `.mcp.json`:

```json
{
  "mcpServers": {
    "keycloak-mcp": {
      "type": "stdio",
      "command": "keycloak-mcp",
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_REALM": "my-realm",
        "KEYCLOAK_CLIENT_ID": "keycloak-mcp",
        "KEYCLOAK_CLIENT_SECRET": ""
      }
    }
  }
}
```

### Claude Desktop

In `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "keycloak-mcp": {
      "command": "keycloak-mcp",
      "env": {
        "KEYCLOAK_URL": "https://keycloak.example.com",
        "KEYCLOAK_REALM": "my-realm",
        "KEYCLOAK_CLIENT_ID": "keycloak-mcp",
        "KEYCLOAK_CLIENT_SECRET": ""
      }
    }
  }
}
```

### From a shell

```bash
export KEYCLOAK_URL=https://keycloak.example.com
export KEYCLOAK_REALM=my-realm
export KEYCLOAK_CLIENT_ID=keycloak-mcp
export KEYCLOAK_CLIENT_SECRET=your-secret
keycloak-mcp
```

### CLI

```bash
keycloak-mcp --version   # Print version and exit
keycloak-mcp --help      # Show usage and required environment variables
keycloak-mcp --check     # Verify env vars and authentication, then exit
keycloak-mcp             # Run the MCP STDIO server (default)
```

No-argument mode is the normal one — that's how MCP clients launch it.

### Daily spray report (batch)

`spray_check` looks at a rolling window ending now, which is right for a patrol but cannot be archived day by day. For that, run the same analysis over one calendar day from a scheduled job:

```bash
keycloak-mcp spray-report --date 2026-09-17 --tz Asia/Tokyo > 2026-09-17.json
```

- The window is `[DATE 00:00, DATE+1 00:00)` in `--tz` (default: the host's zone). Use the zone the KeyCloak server logs in, because `dateFrom` / `dateTo` are interpreted there. Events are cut to the window by timestamp on both ends.
- One JSON document goes to stdout; errors go to stderr with a non-zero exit (2 = configuration, 1 = fetch/auth), and nothing is written to stdout in that case.
- The output is the `spray_check` shape with every external IP that has at least one event carrying a username in `external_ips` (`min_report_users=1`), plus `external_totals`, which counts LOGIN / LOGIN_ERROR for **every** external IP — including IPs whose failures carry no username at all and therefore have no row, `fetch_complete`, `resolve_complete`, `coverage` (`first_event`, `last_event`, `head_gap_seconds`, `tail_gap_seconds`), `schema`, `keycloak_mcp_version` and `sites_ini_sha256`. Treat a day as final only when both `*_complete` flags are true and neither gap is large; a gap at one end usually means `--tz` differs from the KeyCloak server's zone.
- It refuses to run when `KEYCLOAK_SITES_INI` yields no ranges (every IP would count as external) unless `--allow-no-sites` is given, and when `KEYCLOAK_KNOWN_EGRESS` has an entry that is not a CIDR.
- Its own limits apply (`--deadline 900`, `--max-events 1000000`, `--max-resolves 2000`), not `KEYCLOAK_DEADLINE` / `KEYCLOAK_MAX_EVENTS`, which are sized for a tool call behind an HTTP gateway.
- The output contains source IPs and usernames. Keep it out of anything published.

## Development

```bash
git clone https://github.com/shigechika/keycloak-mcp.git
cd keycloak-mcp

# uv
uv sync --dev
uv run pytest -v
uv run ruff check .

# pip
python3 -m venv .venv
.venv/bin/pip install -e . && .venv/bin/pip install pytest pytest-cov respx ruff
.venv/bin/pytest -v
.venv/bin/ruff check .
```

### Live smoke test

`pytest` checks logic against fixtures; it cannot tell you that a tool has
stopped returning real data. `scripts/smoke_test.py` runs **every registered
tool** against the configured realm and fails on empty, malformed or error
answers:

```bash
# needs KEYCLOAK_URL / KEYCLOAK_CLIENT_ID / KEYCLOAK_CLIENT_SECRET
uv run python scripts/smoke_test.py
uv run python scripts/smoke_test.py --only login_stats --traceback
```

- **Read-only.** Every state-changing tool (`reset_password`, `logout_user`,
  `set_user_enabled`, `reset_passwords_batch`) is skipped by name, and a test
  enforces that. The report prints tool names and statuses only — never
  payloads, and server-authored error text is redacted too (KeyCloak quotes the
  username it was asked about); `--traceback` still shows the full text on the
  operator's own terminal.
- Arguments that would identify real users, groups or IPs are **discovered at
  run time**, never written into `scripts/smoke_probes.py`.
- CI enforces the cheap half: a tool registered without a probe spec fails the
  build (`tests/test_smoke_probes.py`), so adding a tool forces the question
  "how would we know it works?".
- `scripts/smoke_harness.py` is the engine and holds no KeyCloak knowledge:
  it is kept identical across the servers that share it, so fix engine bugs
  once and sync the file rather than patching this copy.

## License

MIT
