Audit Administration and Event Selection

Kamiwaza separates audit administration from platform administration. Only the Information System Security Manager (ISSM), or people the ISSM appoints, decide which events are audited. The platform administrator role cannot change audit event selection or turn auditing off through the Kamiwaza API.

This page covers DISA Application Server SRG rule V-204718 ("The application server must allow only the ISSM (or individuals or roles appointed by the ISSM) to select which loggable events are to be logged"). It gives wording you can use in a System Security Plan (SSP) and the Customer Responsibility Matrix (CRM).

Where audit selection is made

Kamiwaza has no API that changes audit event selection. Audit selection is set when Kamiwaza is deployed, through Helm values and the Keycloak realm configuration:

Setting	Where	Effect on auditing
`scheduler.logging.logLevel` (core chart)	Helm values	Sets `KAMIWAZA_LOG_LEVEL`. Most Kamiwaza audit events are written at `INFO`. A level of `WARNING` or higher can drop them from the log export. Keep it at `INFO` or `DEBUG`.
`opensearch.retention.audit` (observability chart)	Helm values	How long audit records are kept in OpenSearch (default `90d`).
Keycloak realm `eventsEnabled`, `enabledEventTypes`, `adminEventsEnabled`	Realm import in the auth chart	Which login, logout and admin events Keycloak records.
OpenTelemetry collector pipelines (observability chart)	Helm values	Where audit records are forwarded, such as a customer SIEM.

Because these are deployment settings, the people who can change them are the people who can change the Helm release or the Git repository it is deployed from. Restrict both to ISSM-appointed operators.

Threat model

The protections below defend against a Kamiwaza platform administrator acting through the Kamiwaza API. Keycloak realm administrators hold the realm-management administration roles or the master realm. The ISSM appoints them, and they are outside this boundary by design: they can assign any realm role, audit-admin included. Do not give platform administrators those Keycloak roles.

Every Kamiwaza write that touches users, identity providers or role assignments goes through one check. In every profile, that check refuses to grant or map:

audit-admin;
a Kamiwaza-reserved identity-provider marker role;
a realm-management administration role, meaning any role other than view-* and query-*.

Under the stig profile, it also refuses to adopt, change, re-enable, re-password or delete an account that holds audit-admin or a realm-management administration role.

The check follows composites and client roles. Role names are compared without surrounding spaces and without regard to case. Kamiwaza reads the live Keycloak state during the request, and answers 503 when it cannot read it. Kamiwaza honors audit-admin only as the realm role. A client role with the same name never grants it.

Identity-provider marker roles (kamiwaza-brokered, kamiwaza-idp-access.*) record how an account signed in. They are not appointments. Kamiwaza refuses to grant them, but holding one does not by itself protect an account. An account that also holds audit-admin or a realm-management administration role keeps the protections above.

Reserved attribute names

Each attribute declared through the attribute schema API (PUT /api/cluster/attribute-schema/{name}) becomes a token claim of the same name. A platform administrator could otherwise use an attribute to place roles or identity in tokens. Kamiwaza therefore refuses these names with 400 and the reason attribute_name_reserved:

any name that contains . or \ (Keycloak reads these as nested claim paths, for example realm_access.roles);
standard and authorization claims: iss, sub, aud, exp, nbf, iat, jti, azp, typ, sid, nonce, session_state, auth_time, acr, amr, at_hash, c_hash, scope, cnf, client_id, realm_access, resource_access, roles, groups, allowed-origins, preferred_username, email, email_verified, name, given_name, family_name;
Kamiwaza identity and authority claims: tenant_id, tenant, realm, uid, token_type, workroom_id, workroom_role, auth_source, upn, subject_namespace, browser_session_id, browser_origin, marking_assertion, runtime_target_kind, runtime_target_id, saml_attributes, audit_token_type;
Keycloak's built-in profile fields: username, firstName, lastName.

Names are compared without surrounding spaces and without regard to case. marking_level remains declarable by design.

Some attributes may have been declared with one of these names before an upgrade. At startup, and whenever such an attribute reappears, Kamiwaza withdraws it. It removes the attribute's token-claim mapper (kamiwaza-attr-<name> on the kamiwaza-claims client scope) and its user-profile entry. If Keycloak refuses, Core logs an ERROR that names the mapper and the attribute; remove both in the Keycloak admin console. Until the withdrawal succeeds, audit-admin endpoints answer 503, because a remaining mapper could still place roles in tokens. After removing them in Keycloak, restart every Core API pod; each one checks again at startup.

The `audit-admin` role

Kamiwaza defines one role for audit administration: the audit-admin Keycloak realm role.

GET /api/security/audit/config reports Core's own audit logging state in the running API. It returns:
- the effective level of the audit logger;
- whether INFO audit events pass that level;
- whether Core also writes audit events to a durable file;
- confirmation that no API can change the selection.
Only audit-admin can call it. It does not inspect Keycloak event settings, collector routing or OpenSearch retention. Verify those where they are configured (see the table above).
The platform admin role is refused, at the gateway and in the API. Holding admin never substitutes for audit-admin.
An account that holds both admin and audit-admin is handled according to the security profile. The profile is the KAMIWAZA_SECURITY_PROFILE environment variable on the Kamiwaza Core API. It must be absent (default) or exactly default or stig. Core API refuses to start with any other value, including an empty one. The Helm value that sets it is being added to the Kamiwaza charts. Until it ships, set the variable on the Core API deployment directly. A direct edit to a Helm- or GitOps-managed deployment is reverted by the next upgrade or sync, so re-apply it after each one. After each deployment change, wait for the rollout and check the value each running Core API process sees:
```
kubectl -n <namespace> rollout status deployment/core-api --timeout=180s
for pod in $(kubectl -n <namespace> get pods -o name | grep '^pod/core-api-'); do
  if env_out=$(kubectl -n <namespace> exec "$pod" -c core-api -- printenv); then
    if line=$(printf '%s\n' "$env_out" | grep -m1 '^KAMIWAZA_SECURITY_PROFILE='); then
      echo "$pod: '${line#KAMIWAZA_SECURITY_PROFILE=}'"
    else
      echo "$pod: (not set: the default profile)"
    fi
  else
    echo "$pod: CHECK FAILED (could not read the pod's environment)"
  fi
done
# Expect every pod to print: 'stig'
# "(not set ...)" and 'default' mean the default profile: an account holding
# both admin and audit-admin is NOT refused. Any other value (including '') is
# invalid, and Core API does not start with it. "CHECK FAILED" proves nothing either way; fix
# access to the pod or the pod itself and run the check again. A failed
# rollout can mean an invalid value: Core API does not start with one.
```
- KAMIWAZA_SECURITY_PROFILE=stig: the account is refused, so one person cannot hold both duties through a single account. The refusal is audited with the reason audit_admin_separation.
- Default profile: small installations where one person runs everything may hold both roles. Each use is allowed, logged at WARNING, and audited as an authorization.decision event with the reason audit_admin_combined_with_admin_default_profile.
The platform admin cannot appoint audit administrators through Kamiwaza:
- The Kamiwaza user API refuses any change to an account's audit-admin membership in Kamiwaza's local role list. These refusals are recorded as failed user_management.change events with the reason audit_admin_role_reserved_grant or audit_admin_role_reserved_revoke.
- The user API never changes roles assigned directly in Keycloak, so it can neither grant nor remove a Keycloak-assigned audit-admin.
- Creating a Kamiwaza user with a role that is a Keycloak composite containing audit-admin, or a Keycloak administration role of the realm-management client (any role other than view-* and query-*, which could assign audit-admin), is refused with 403, and the reason audit_admin_role_reserved is recorded on the request's denial event. Composites are followed through client roles too.
- Identity provider role mappings cannot target audit-admin, or a composite role that contains it or a Keycloak administration role, and grant realm roles only: a mapping whose role name Keycloak would read as a client role (for example realm-management.realm-admin) is refused. A save that would keep an existing mapping of any of these kinds is refused with 403. These refusals are recorded as failed identity-provider save events.
- Roles asserted by a customer-controlled identity provider, such as SAML attributes mapped in Keycloak, are outside Kamiwaza's control. Restrict them the same way as Keycloak realm administration.
Under the stig profile, the platform admin cannot set the password of an account that holds audit-admin or a Keycloak administration role of realm-management (which could assign audit-admin), because that would let the admin sign in as that account. An ISSM-appointed Keycloak realm administrator resets it in Keycloak instead. This applies to:
- the user password reset;
- a subject upsert that carries a password;
- creating a Kamiwaza user whose username matches an existing Keycloak account.
- Kamiwaza checks the account's live Keycloak roles, including roles granted through groups.
- The account is checked before it is touched, so a refused request does not re-enable a disabled appointee.
- The refusal is audited with the reason audit_admin_password_reset_reserved.
- If Keycloak cannot be reached for the check, the change is refused with 503 and audited as audit_admin_check_unavailable. If the account no longer exists, the reset returns 409 instead.
Under the stig profile, the subjects API (PUT and DELETE /api/authz/subjects/...) also refuses any other change to, or deletion of, an account that holds audit-admin or a realm-management administration role, with the reason audit_admin_role_reserved.
Under the default profile, the platform admin can still disable or delete an account that holds audit-admin or a realm-management administration role through the Kamiwaza user API. Those actions are audited user_management.change events for the ISSM to review. Under the stig profile, the user API refuses them with 403 (audit_admin_role_reserved); an ISSM-appointed Keycloak realm administrator makes the change in Keycloak.
Any future API that changes audit selection will require audit-admin and record an audit event for the change.

Appointing an audit administrator

Make sure the audit-admin realm role exists in the Kamiwaza Keycloak realm. If your realm import does not create it, create it once in the Keycloak admin console (Realm roles > Create role, name audit-admin).
In Keycloak, assign audit-admin to each account the ISSM appoints. Also give these accounts viewer, so they can sign in to the Kamiwaza UI. Under the stig profile, do not assign audit-admin to an account that holds admin; such an account is refused.
Limit Keycloak realm administration (the realm-admin, manage-users and manage-events client roles of realm-management) to ISSM-appointed administrators. Anyone with these roles can assign audit-admin or change Keycloak event settings.
Have the appointed audit administrator call GET /api/security/audit/config and confirm that info_audit_events_recorded is true.

SSP and CRM wording

The following text can be adapted for the SSP control implementation statement (AU-12, CCI-000171) and the CRM.

Implementation statement. Kamiwaza restricts selection of audited events to the ISSM and ISSM-appointed audit administrators. Audit event selection is not configurable through the Kamiwaza application interface: it is defined in deployment configuration (Helm values for the Kamiwaza charts and the Keycloak realm import) and applied through the organization's change-controlled deployment process. Within the application, audit configuration is visible only to the audit-admin role, which is separate from the platform administrator role. Under the stig security profile, an account holding both roles is refused. The platform administrator role cannot view or change audit configuration and cannot grant itself or anyone else the audit-admin role through Kamiwaza. Attempts to do so are refused and audited.

Responsibility split.

Responsibility	Provided by Kamiwaza	Customer responsibility
No application API that changes audit selection or disables auditing	Yes	—
Separate `audit-admin` role, refused to platform administrators (and to accounts holding both roles under `KAMIWAZA_SECURITY_PROFILE=stig`)	Yes	Set the `stig` security profile. Assign the role only to ISSM appointees, never to accounts holding `admin`.
Platform admin cannot assign `audit-admin` through Kamiwaza	Yes	Restrict Keycloak `realm-management` roles to ISSM appointees.
Audit selection in Helm values and the Keycloak realm import	Configurable	Restrict who can modify the Helm release, its values files and the GitOps repository to ISSM-appointed operators, through Kubernetes RBAC and repository permissions.
Change control for audit selection	—	Approve every change to the settings above through the organization's change control board, with the ISSM as approver.
Verification	`GET /api/security/audit/config` reports Core's audit logging state	The audit administrator reviews it after each deployment change. The ISSM-authorized deployment operator confirms `KAMIWAZA_SECURITY_PROFILE=stig` (see above) and reports the result to the ISSM. The ISSM-appointed Keycloak administrator verifies the Keycloak event settings, and the deployment operator verifies the collector and retention settings, where they are configured.

Kubernetes RBAC. Grant write access (create, update, patch, delete) to the Kamiwaza namespaces' ConfigMaps, Secrets, Deployments and Helm release Secrets only to the service account or group that the ISSM authorizes to deploy Kamiwaza. Platform administrators who operate Kamiwaza through its UI or API do not need these permissions and should not hold them.

Where audit selection is made​

Threat model​

Reserved attribute names​

The audit-admin role​

Appointing an audit administrator​