[READ] RCA over the failed-auth feed: separates brute-force (spray or targeted) from a misconfigured client from an expired-credential storm and a lockout storm — each finding carries its numbers, cause, and action.

Args: window_minutes: Trailing analysis window (default 60). max_events: Failed-login events to pull (default 500). target: IdP target name from config; omit for the default.

Returns "feedTruncated": true when the event feed hit max_events — every count is then a lower bound; re-run with a higher max_events before concluding a threshold was not reached.

[READ] Dormant-access audit: enabled users idle > N days, accounts that never signed in, service accounts with interactive logins, and sessions orphaned by disabled/unknown users.

Args: stale_days: Idle threshold in days (default 90). max_users: Users to pull (default 500). target: IdP target name from config; omit for the default.

Returns "inputsTruncated" per input feed and "truncated" when a finding list was capped at maxRows; the *Count fields are always the full totals.

[READ] Ranked OAuth/OIDC client risk: wildcard/http redirect URIs, public clients with secrets, implicit flow, missing PKCE, password grant — per-client riskScore with evidence and actions.

Args: max_clients: Clients to pull (default 200). target: IdP target name from config; omit for the default.

Returns "inputsTruncated": true when the client list hit max_clients — a clean result over a clipped list is not evidence of a clean estate.

[READ] Second-factor coverage: overall %, the users without MFA, and the factor types counted. Pulls one credential list per user (bounded).

Args: max_users: Users to sample (default 200 — one API call each). target: IdP target name from config; omit for the default.

Returns "inputsTruncated": true when the realm is larger than max_users — coveragePct then describes the sample, not the realm.

[READ] OAuth/OIDC clients in the realm, normalized (redirect URIs, public/confidential, grant flags, PKCE method).

Args: max_results: Page bound (default 200). target: IdP target name from config; omit for the default.

Returns {"clients": [...], "returned": N, "limit": L, "truncated": bool}, with truncated measured rather than guessed. Fields the IdP did not return are null — a null pkceMethod means no PKCE method is pinned.

[READ] One client's normalized detail by internal id.

Args: client_id: Internal id (Keycloak UUID / authentik provider pk), from list_clients. target: IdP target name from config; omit for the default.

[READ] Active user sessions on one client (Keycloak).

KEYCLOAK ONLY. authentik has no per-provider session listing, so on an authentik target this returns {"error": "Resource 'client_sessions' is not mapped for platform 'authentik'..."}. That is a platform-capability answer, not a fault: switch approach (user_sessions per user) rather than retrying or reporting the tool as broken.

Args: client_id: Internal id, from list_clients. max_results: Page bound (default 200). target: IdP target name from config; omit for the default.

Returns {"sessions": [...], "returned": N, "limit": L, "truncated": bool}, with truncated measured rather than guessed.

[READ] Active-session counts per client, busiest first (Keycloak).

KEYCLOAK ONLY. authentik has no per-client session rollup, so on an authentik target this returns {"error": "Resource 'client_session_stats' is not mapped for platform 'authentik'..."}. A platform-capability answer, not a fault — do not retry.

Args: target: IdP target name from config; omit for the default.

Returns {"clients": [...], "returned": N, "truncated": false} — the rollup is unbounded, so this listing is always complete.

[READ] Recent authentication events, normalized (time/type/user/ip/client/error).

Args: event_type: Platform vocabulary — Keycloak LOGIN / LOGIN_ERROR, authentik login / login_failed (case-insensitive). user: Optional username / user-id filter. max_results: Page bound (default 200, max 500). target: IdP target name from config; omit for the default.

Returns {"events": [...], "returned": N, "limit": L, "truncated": bool}. truncated is measured (one extra event is fetched), not guessed — when it is true, more events exist; re-run with a higher max_results rather than treating the partial feed as the whole picture. Optional fields an event did not carry are null, never "".

[READ] Recent admin/config-change events (who changed what, from where).

Args: max_results: Page bound (default 200, max 500). target: IdP target name from config; omit for the default.

Returns {"events": [...], "returned": N, "limit": L, "truncated": bool}, with truncated measured rather than guessed. On authentik the single event feed is post-filtered to admin actions, so truncated also reports feed rows that were never examined.

[READ] One-shot summary: platform/realm, user/client/IdP counts, and the size of the recent failed-login feed. Lead with this.

Args: target: IdP target name from config; omit for the default.

[READ] Realm / instance settings relevant to identity hygiene (brute-force protection, password policy, OTP policy, registration).

Args: target: IdP target name from config; omit for the default.

[READ] Federated identity providers / sources configured on the IdP.

Args: target: IdP target name from config; omit for the default.

Returns {"identityProviders": [...], "returned": N, "truncated": false} — the IdP returns the complete set, so this listing is never clipped.

[READ] List recorded, not-yet-applied undo tokens (most recent first).

Each entry names the original tool, the inverse tool that undo_apply would run, and a human note. Use the undoId with undo_apply.

Returns {"undos": [...], "returned": N, "limit": L, "truncated": bool}. truncated is measured (one extra row is fetched), not guessed from a length coincidence: when it is true there are MORE tokens than shown, so re-run with a higher limit rather than reporting the list as complete.

Each entry carries effectVerified. False means the original write lost its response, so the change it reverses is PROBABLE, not confirmed — check the live state before applying, and do not report the result as a restore of a state that may never have been reached.

Args: limit: Max rows to return (default 50, capped at 500). target: Unused (undo state is host-local); accepted for CLI uniformity.

[WRITE][risk=medium] Apply a recorded undo by dispatching its inverse tool.

The inverse runs through its own governed tool, so it is audited and carries its own risk tier there. Pass dry_run=True to preview the inverse call without executing it. A token can only be applied once.

Args: undo_id: The undoId from undo_list (or an _undo_id in a write result). dry_run: If True, preview the inverse tool + params without running it. target: Passed through to the inverse tool when it accepts a target.

[READ] Users in the realm, normalized across Keycloak/authentik.

Args: search: Optional username/email search string. max_results: Page bound (default 200). target: IdP target name from config; omit for the default.

Returns {"users": [...], "returned": N, "limit": L, "truncated": bool}. truncated is measured (one extra user is fetched); when true, more users exist — re-run with a higher max_results before drawing a realm-wide conclusion. Fields the IdP did not return are null, never "".

[READ] One user's full detail (enabled state, required actions, attributes).

Args: user_id: User id (Keycloak UUID / authentik pk), from list_users. target: IdP target name from config; omit for the default.

[READ] Total user count in the realm (the cheap health probe).

Args: target: IdP target name from config; omit for the default.

[READ] A user's active sessions (id, IP, start/last access, clients).

Args: user_id: User id, from list_users. target: IdP target name from config; omit for the default.

Returns {"sessions": [...], "returned": N, "truncated": false} — the IdP returns the user's whole session set, so this listing is always complete.

[READ] A user's configured credentials/authenticators — the MFA surface.

Args: user_id: User id, from list_users. target: IdP target name from config; omit for the default.

Returns {"credentials": [...], "returned": N, "truncated": false, "secondFactors": N} — always the user's complete credential set.

[READ] Groups in the realm.

Args: max_results: Page bound (default 200). target: IdP target name from config; omit for the default.

Returns {"groups": [...], "returned": N, "limit": L, "truncated": bool}, with truncated measured rather than guessed.

[READ] Members of one group, normalized user rows.

Args: group_id: Group id, from list_groups. max_results: Page bound (default 200). target: IdP target name from config; omit for the default.

Returns {"members": [...], "returned": N, "limit": L, "truncated": bool}, with truncated measured rather than guessed.

[READ] Brute-force lockout status for one user (Keycloak attack-detection).

KEYCLOAK ONLY. authentik keeps no per-user lockout register, so on an authentik target this returns {"error": "Resource 'user_lockout' is not mapped for platform 'authentik'..."}. That is a definitive answer about the platform, not a fault: do not retry it and do not report the tool as broken — use login_failure_rca on the failed-auth feed instead.

Args: user_id: User id, from list_users. target: IdP target name from config; omit for the default.

[WRITE][risk=medium] Disable a user (blocks sign-in); reversible.

The containment move for a compromised/stale account. Reads the user first so the harness records an undo that restores the prior enabled state. Live sessions survive — pair with revoke_user_sessions. Pass dry_run=True to preview.

Refuses to disable the account this tool authenticates as — including under dry_run, which must report a refusal rather than preview a call that will be refused.

Args: user_id: User id (Keycloak UUID / authentik pk), from list_users. dry_run: If True, preview without changing. target: IdP target name from config; omit for the default.

[WRITE][risk=high] Re-enable a user (restores sign-in); reversible.

Re-granting access reverses a containment action, so it is tagged risk=high on the audit row (a descriptive label, not a gate). Whether it should run is the agent's judgement or the connecting account's permissions, not the tool's. Pass dry_run=True to preview.

Args: user_id: User id, from list_users. dry_run: If True, preview without changing. target: IdP target name from config; omit for the default.

[WRITE][risk=medium] Revoke ALL of a user's sessions. IRREVERSIBLE — no undo; the prior session count is recorded (audit shows the blast radius).

Args: user_id: User id whose sessions to revoke, from list_users. dry_run: If True, preview without revoking. target: IdP target name from config; omit for the default.

[WRITE][risk=medium] Require a password reset at next sign-in (Keycloak required actions); reversible — the undo clears the flag only if this call set it. Pass clear=True to remove a pending requirement instead.

Args: user_id: User id, from list_users. clear: If True, REMOVE the pending reset requirement (the undo path). dry_run: If True, preview without changing. target: IdP target name from config; omit for the default.

[WRITE][risk=high] REPLACE a client's redirect-URI list; reversible — the prior list is captured and the undo replays it.

Redirect URIs are the OAuth flow's security boundary, so this is tagged risk=high on the audit row (a descriptive label, not a gate). Pass the FULL desired list (this replaces, not appends) and dry_run=True to preview.

Args: client_id: Client internal id, from list_clients. redirect_uris: The complete new redirect-URI list. dry_run: If True, preview without changing. target: IdP target name from config; omit for the default.

[WRITE][risk=high] Rotate a client's secret. IRREVERSIBLE — the old secret is invalidated; only masked fingerprints are recorded/returned, never the value.

Refuses to rotate the client this tool authenticates as: that would revoke its own credential with no undo to fall back on — including under dry_run, which must report a refusal rather than preview a call that will be refused. Rotate that one from the admin console and re-store it with 'identity-aiops secret set'.

Every deployment using this client must be updated with the new secret (fetch it from the admin console over a trusted channel). Pass dry_run=True to preview.

Args: client_id: Client internal id, from list_clients. dry_run: If True, preview without rotating. target: IdP target name from config; omit for the default.