Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,12 @@ schemas and the `paramify` CLI — not the internal code.

### Added

- **`keycloak` category and `keycloak_realm_security` fetcher.** Reads a Keycloak realm through the Admin REST API with a
read-only service-account client: session and token lifetimes, brute-force lockout, password policy, the browser
and reset-credentials flows with each step's effective requirement (so a phishing-resistant authenticator counts
only when every sign-in must pass it), required actions such as terms and conditions, identity providers, user
federation, and login and admin event logging. Client secrets and bind credentials are never written to the
evidence, and an unreadable section leaves its fields null rather than empty.
- `paramify upload --no-waf-check` turns off the check that drops a file holding `../`, `/etc/passwd`, `/bin/sh`,
`/bin/bash` or `<script` before the upload. Those strings were confirmed blocked on one host's WAF, but some hosts
exempt the upload routes, so CVE text in a findings file was dropped though the WAF would accept it. With the flag
Expand Down
41 changes: 41 additions & 0 deletions fetchers/_categories/keycloak.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
display_name: Keycloak
description: >-
Keycloak identity provider, read through the Keycloak Admin REST API. Realm sign-in, session, lockout,
password and event settings, authentication flows, required actions, and federation. One service-account
client per Keycloak instance.

requires:
python_packages:
- requests
- python-dotenv

# Shared by every keycloak fetcher. The runner injects these env vars for any fetcher with category: keycloak.
config_schema:
base_url:
type: string
required: true
env: KEYCLOAK_BASE_URL
description: >-
Keycloak base URL, such as https://keycloak.admin.example.com. Include the /auth path for Keycloak
versions that still serve it.
realm:
type: string
default: uds
env: KEYCLOAK_REALM
description: The realm to read (uds is the default realm in UDS Core).
auth_realm:
type: string
env: KEYCLOAK_AUTH_REALM
description: >-
The realm that holds the service-account client, when it is not the realm being read (for example master).
Defaults to realm.

secrets:
- name: client_id
env: KEYCLOAK_CLIENT_ID
description: >-
Client ID of a confidential client with service accounts enabled. Its service account needs the realm-management
client roles view-realm, view-identity-providers and view-events, and nothing else.
- name: client_secret
env: KEYCLOAK_CLIENT_SECRET
description: Client secret of that client.
22 changes: 22 additions & 0 deletions fetchers/keycloak/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# Keycloak fetchers

Read-only evidence from the Keycloak Admin REST API. Every fetcher in this category signs in with the OAuth2
client-credentials grant as a dedicated service-account client, then issues only GET requests under
`/admin/realms/{realm}`. The shared client is `_shared/keycloak_client.py`.

## Setup

1. In the realm to read (or in `master`, then set `auth_realm`), create a confidential OpenID Connect client with
**Client authentication** and **Service accounts roles** on, and every other flow off.
2. Give its service account the `realm-management` client roles `view-realm`, `view-identity-providers` and
`view-events`. No manage-* role is needed.
3. Set `KEYCLOAK_BASE_URL`, `KEYCLOAK_REALM` (default `uds`), optionally `KEYCLOAK_AUTH_REALM`, and the
`KEYCLOAK_CLIENT_ID` and `KEYCLOAK_CLIENT_SECRET` secrets. The fetcher must run from a network that can reach the
Keycloak admin endpoint.

| Fetcher | Evidence set | Shows |
| --- | --- | --- |
| `realm_security` | `EVD-KEYCLOAK-REALM-SECURITY` | Sessions, lockout, password policy, browser and recovery flows, required actions, federation, event logging |

Client secrets in identity provider configs and bind credentials in user federation configs are never written to
the evidence.
98 changes: 98 additions & 0 deletions fetchers/keycloak/_shared/keycloak_client.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
#!/usr/bin/env python3
"""Read-only Keycloak Admin REST API client shared by the keycloak fetchers.

Authenticates with the OAuth2 client-credentials grant against the auth realm's token endpoint, then issues GETs
under /admin/realms/{realm}. Only GET is exposed: the fetchers read configuration and never change it.

Collection-failure convention (docs/authoring_fetcher_guide.md, step 3): a failed GET is recorded in `api_failures`
and returns None, so one bad endpoint does not lose the rest of the evidence; the fetcher exits non-zero when
`api_failures` is non-empty. A failed token request raises, since nothing can be read without a token.
"""

import logging
import os
import time
from typing import Any, Dict, List, Optional
from urllib.parse import quote

import requests

RETRY_STATUS = frozenset({429, 500, 502, 503, 504})
MAX_RETRIES = 3
TIMEOUT = 30
CODES = {401: "auth_failed", 403: "not_authorized", 429: "rate_limited"}

logger = logging.getLogger("keycloak_client")


class KeycloakAuthError(RuntimeError):
def __init__(self, message: str, code: str):
super().__init__(message)
self.code = code


def settings_from_env() -> Dict[str, str]:
"""base_url, realm and auth_realm from the category config; client credentials from the declared secrets."""
missing = [n for n in ("KEYCLOAK_BASE_URL", "KEYCLOAK_CLIENT_ID", "KEYCLOAK_CLIENT_SECRET") if not os.environ.get(n)]
if missing:
raise KeycloakAuthError(f"Missing required setting: {', '.join(missing)}", "bad_config")
realm = os.environ.get("KEYCLOAK_REALM") or "uds"
return {"base_url": os.environ["KEYCLOAK_BASE_URL"].rstrip("/"), "realm": realm,
"auth_realm": os.environ.get("KEYCLOAK_AUTH_REALM") or realm}


class KeycloakClient:
def __init__(self, base_url: str, realm: str, auth_realm: str, client_id: str, client_secret: str, session: Any = None):
self.base_url, self.realm, self.auth_realm = base_url.rstrip("/"), realm, auth_realm
self._client_id, self._client_secret = client_id, client_secret
self.session = session or requests.Session()
self.api_failures: List[Dict[str, Any]] = []
self.failure_codes: List[str] = []
self._token: Optional[str] = None
self._expires = 0.0

def _authenticate(self) -> str:
if self._token and time.time() < self._expires - 30:
return self._token
url = f"{self.base_url}/realms/{quote(self.auth_realm, safe='')}/protocol/openid-connect/token"
try:
response = self.session.post(url, data={"grant_type": "client_credentials", "client_id": self._client_id,
"client_secret": self._client_secret}, timeout=TIMEOUT)
except requests.RequestException as exc:
raise KeycloakAuthError(f"Keycloak token request failed: {type(exc).__name__}", "target_unreachable") from exc
if response.status_code != 200:
raise KeycloakAuthError(f"Keycloak token request answered {response.status_code}", CODES.get(response.status_code, "auth_failed"))
body = response.json()
self._token, self._expires = body["access_token"], time.time() + float(body.get("expires_in") or 60)
return self._token

def get(self, operation: str, path: str, params: Optional[Dict[str, str]] = None) -> Any:
"""GET /admin/realms/{realm}{path}; None (and a recorded failure) when it cannot be read."""
url = f"{self.base_url}/admin/realms/{quote(self.realm, safe='')}{path}"
response = None
for attempt in range(MAX_RETRIES + 1):
try:
response = self.session.get(url, params=params, timeout=TIMEOUT, allow_redirects=False,
headers={"Authorization": f"Bearer {self._authenticate()}", "Accept": "application/json"})
except requests.RequestException as exc:
if attempt == MAX_RETRIES:
return self._fail(operation, type(exc).__name__, str(exc), "target_unreachable")
time.sleep(min(2 ** attempt, 30))
continue
if response.status_code in RETRY_STATUS and attempt < MAX_RETRIES:
time.sleep(min(2 ** attempt, 30))
continue
break
if response.status_code != 200:
return self._fail(operation, f"HTTP {response.status_code}", (response.text or "")[:300],
CODES.get(response.status_code, "partial_failure"))
return response.json()

def flow_executions(self, alias: str) -> Optional[List[Dict[str, Any]]]:
return self.get(f"authentication flow executions ({alias})", f"/authentication/flows/{quote(alias, safe='')}/executions")

def _fail(self, operation: str, kind: str, message: str, code: str) -> None:
self.api_failures.append({"operation": operation, "type": kind, "message": message})
self.failure_codes.append(code)
logger.error("%s failed: %s", operation, kind)
return None
Loading
Loading