Security¶
Reporting a vulnerability¶
Use GitHub's private vulnerability reporting on the rosschiu/kiban repository ("Security"
tab, "Report a vulnerability"). Do not post details in a public issue. If the button is not
available, open an issue that says only that you need a private channel; a maintainer will
arrange one.
Include the affected version or commit (kiban_build_info{version,commit} on every service), a
reproduction, and the impact you believe it has.
What the platform guarantees¶
Authorization¶
Authorization fails closed: any error while evaluating a decision is a refusal. Every object
check is bound to the request's company: companies and company modules by id, positions and
groups through their company, module objects through the anchor tuple their module writes at
creation. An object from another company is denied, and so is a subject: a position, group or
member named in a tuple resolves only inside its own company, and a grant that names another
company's position, group or member is refused (422). An object carries exactly one anchor: a
grant that would anchor an already-anchored object to another company is refused (422), and
a unique index on the tuple table holds that rule for every write path; re-anchoring is a
revoke followed by a grant.
A grant names the company and may only write tuples on object types the caller owns: an
app's backend, identified by the verified azp of its service-client token matching the app's
registered service client id, on the app's own types in any company where the app is enabled;
a superadmin, or a caller who passes the module's company-scope decision (membership of the
company, the module enabled), on any other enabled module's or app's types, which includes
another app's backend whose service account is a member of that company (see limitations); module-tier tuples additionally need the company-module administrator relation. Every
object must carry its company anchor. Base-model tuples cannot be written through the grants
route, with one exception: a superadmin may grant or revoke company:<id>#admin for a user to
appoint a company administrator. A registered app's checks are limited to the feature keys its manifest declares.
The superadmin role is a single authorization tuple. Grant and revoke are immediate and audited, and the last superadmin cannot be revoked.
The authorization engine is compared against OpenFGA in make test (65 vectors, two mutation
proofs, a cycle proof, 5000 generated checks). The limitations page says what that does not
cover.
Identity and audit¶
The actor of every request is the verified bearer token; client-supplied identity headers are rejected.
A decision reads the user's state from two places: Kiban's own lifecycle column, and Keycloak's
enabled flag. The flag is read from Keycloak's database directly when it is on the same
Postgres server (the shipped shape, KEYCLOAK_DB_NAME), so a disable in Keycloak is refused on
the very next check; when identity has to ask the admin REST API instead, the answer is cached
for KIBAN_USER_STATE_CACHE_SECONDS and a disable is refused within that window. Any failure to
read the flag is an unknown state and the decision is refused, never allowed. See
Operating.
Every mutation is audited in the same transaction, with the actor taken from the verified token
(never from the request body) and the request's correlation id. A definite denial on an
administrative route is audited with its reason. Foundation audit tables refuse updates, deletes
and TRUNCATE at the database level, and the service roles have no privilege to bypass that.
Authenticator-app (otp) or passkey MFA policy is set globally or per user by the superadmin
through /api/platform/admin/mfa-policy/* and pushed to Keycloak with the sync route (see
Operating); a per-user override can only raise the
requirement. A new realm requires no second factor. Passkey enrolment works; the login challenge
for a passkey policy does not yet (see limitations).
Bootstrap enforces brute-force protection (temporary lockout after ten failures) and the
password policy length(12) and notUsername and notEmail. The realm binds one browser flow
(kiban browser): password form, conditional one-time code, then Kiban's MFA-setup
authenticator as a required step, so every interactive login passes through it. By default no
client issues a Kiban token outside the browser flow: there is no direct-grant client, and the
only client-credentials clients are the confidential service clients an operator names in
KIBAN_SERVICE_CLIENTS.
Deployment¶
Every service connects to the database with its own role, limited to its own schema. kiban is
the non-superuser owner of the application database and runs migrations and bootstrap;
keycloak owns Keycloak's database; the superuser (POSTGRES_USER, default postgres) is used
only at initialisation.
The superadmin's initial password, the identity client secret and the Keycloak admin password
reach Kiban's services as mounted files (_FILE variables), never as process environment. Each
service's own database role password is an environment variable, and in the image quickstart's
compose file so is the Keycloak admin password on the bootstrap job. See the limitations page
for Keycloak's own container.
Gateway responses carry X-Content-Type-Options, X-Frame-Options, Referrer-Policy and (over
TLS) Strict-Transport-Security; the shell is served with an enforced Content-Security-Policy.
Over-limit bodies are refused. The Keycloak admin console and the master realm are not reachable
through the gateway.
Application containers run as uid 65532 with a read-only root filesystem, all capabilities dropped and no privilege escalation, in Compose and in the Kubernetes template.
There is no runtime dependency on any third-party service. TLS is either operator certificates on the gateway or your own TLS-terminating reverse proxy in front of it; the gateway never contacts a certificate authority.
Secret scanning, dependency licence scanning and vulnerability checks run in make check.
Known gaps¶
See known limitations. Items there that touch security are listed first.