tegwick
63e3bb6f7d
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a0e77d-47a4-7771-8e34-7339c7fac0e4
229 lines
11 KiB
Markdown
229 lines
11 KiB
Markdown
# SCOPE
|
|
|
|
> This file describes the repository's current capability and authority.
|
|
> `INTENT.md` remains the aspirational direction; the difference is assessed in
|
|
> `history/2026-08-23-scope-intent-gap-assessment.md`.
|
|
|
|
---
|
|
|
|
## One-liner
|
|
|
|
Canonical security architecture and bootstrap/reference implementation for
|
|
NetKingdom: defines identity, tenancy, workload-zone, credential, and
|
|
orchestration contracts; supplies conformance and bootstrap tooling; and
|
|
coordinates their realization across KeyCape, flex-auth, OpenBao, and
|
|
Railiance.
|
|
|
|
---
|
|
|
|
## Core Idea
|
|
|
|
This repository is NetKingdom's security canon and integration hub. It defines
|
|
provider-neutral contracts and responsibility boundaries, provides executable
|
|
validators and bootstrap/reference tooling, and records how independently owned
|
|
services compose into a security control plane.
|
|
|
|
It does not own every runtime that realizes those contracts. Service
|
|
implementations, Kubernetes infrastructure, platform data services, and managed
|
|
deployment packages remain in their respective repositories. The dynamic,
|
|
self-optimizing platform in `INTENT.md` is the direction of travel, not a claim
|
|
about the current implementation.
|
|
|
|
---
|
|
|
|
## In Scope
|
|
|
|
### Canon and architecture
|
|
|
|
- NetKingdom IAM Profile v0.3: the accepted provider-neutral OIDC/PKCE,
|
|
principal, tenant, workload-identity, assurance, and flex-auth input contract.
|
|
- Accepted user-engine and tenant-engine boundary contracts.
|
|
- Credential Management Standard v0.2 and the platform-root/OpenBao custody
|
|
model.
|
|
- Playbook Capability Contract v0.1 for the boundary between NetKingdom
|
|
selection/parameterization and Railiance execution.
|
|
- Security Scenario Composition v0.1 for deterministic provider selection,
|
|
trust ordering, responsibility mapping, and non-executing owner handoff.
|
|
- Posture Feedback v0.1 for deterministic, proposal-only routing of posture
|
|
review, evidence-freshness, implementation, and declared-gap findings.
|
|
- Tenancy Posture v0.1 and Security Zones v0.1 proposed standards, their schemas,
|
|
validators, evidence rules, and publication stewardship. Zone semantics are
|
|
owned by `zone-engine`; NetKingdom owns their canon publication.
|
|
- Architecture decisions and the cross-repository responsibility map for
|
|
identity, authorization, credentials, tenancy, and bootstrap trust.
|
|
|
|
### Executable reference and verification surfaces
|
|
|
|
- `local-identity/`: minimal file-backed OIDC identity for bootstrap,
|
|
development, test, and sandbox use.
|
|
- IAM Profile, playbook-capability, tenancy-posture, posture-feedback, custody,
|
|
evidence, and bootstrap-policy validators.
|
|
- `tools/security-scenario-composer/`: fail-closed, plan-only composition of
|
|
declared capabilities, parameters, trust transitions, responsibilities, and
|
|
readiness obligations.
|
|
- `tools/posture-feedback/`: deterministic, time-explicit remediation proposals
|
|
with authoritative owner resolution and no external or policy writes.
|
|
- `tools/security-bootstrap-console/`: guarded platform-root and OpenBao
|
|
bootstrap workflow, including refusal of unsafe live initialization.
|
|
- SOPS/age bootstrap integration, credential-generation and rotation helpers,
|
|
and documented attended, automated-lab, and auto-unseal custody paths.
|
|
- Reference and migration-stage manifests/runbooks for the current lightweight
|
|
identity stack: KeyCape, Authelia, LLDAP, and privacyIDEA.
|
|
|
|
### Integration and meta-orchestration contracts
|
|
|
|
- Capability selection, safe parameterization, trust-state requirements, and
|
|
responsibility assignment across Railiance playbooks.
|
|
- User/tenant onboarding boundaries, issuer/client registration patterns,
|
|
caller identity, workload identity, authorization inputs, and audit evidence.
|
|
- Cross-repository workplans and decision records needed to converge security
|
|
providers without absorbing their implementations into this repository.
|
|
|
|
---
|
|
|
|
## Authority Boundaries
|
|
|
|
This repository owns security semantics and composition rules. It does not own:
|
|
|
|
- KeyCape's implementation (`key-cape`)
|
|
- authorization service implementation or policy evaluation (`flex-auth` and
|
|
its PDP adapters)
|
|
- runtime secret-service deployment (`railiance-platform` / OpenBao)
|
|
- Kubernetes and host infrastructure (`railiance-cluster`,
|
|
`railiance-infra`)
|
|
- SSH certificate issuance or tunnels (`ops-warden`, `ops-bridge`)
|
|
- user or tenant service implementation (`user-engine`, `tenant-engine`)
|
|
- managed application packages (`rapp-*` repositories)
|
|
- generic platform data services such as PostgreSQL and storage
|
|
(`railiance-platform`)
|
|
|
|
The material under `sso-mfa/k8s/` includes live-proven integration history and
|
|
migration inputs. It is not blanket authority for managed runtime deployment.
|
|
ADR-0015 moves package/application ownership to the relevant `rapp-*`
|
|
repositories while NetKingdom retains the contracts and reference evidence.
|
|
|
|
---
|
|
|
|
## Current Capability
|
|
|
|
| Tier | Current repository/estate capability | Delivery state |
|
|
| --- | --- | --- |
|
|
| C0 — Bootstrap identity | Local OIDC identity, SOPS/age bootstrap, guarded credential workflow, greenfield OpenBao init/unseal proof, and deterministic plan-only C0 composition | Implemented as reference/bootstrap tooling |
|
|
| C1 — Lightweight SSO | IAM-profile-based KeyCape composition using Authelia and LLDAP | Live-proven integration; implementation externally owned |
|
|
| C2 — MFA/token authority | Authelia factors and privacyIDEA integration | Live-proven integration; implementation externally owned |
|
|
| C3 — Runtime secrets | OpenBao custody, bootstrap, policy, delivery, and recovery contracts | Integrated with an externally deployed runtime; production evidence remains gated |
|
|
| C4 — Fine-grained authorization | flex-auth caller identity and boundary integration | Partially delivered; full estate/PDP readiness is not established here |
|
|
| C5 — Enterprise federation | Keycloak/SAML/enterprise-IdP design | Backlog; not a current provided runtime capability |
|
|
| C6 — Self-optimizing security | Declarations, validators, evidence freshness, and deterministic owner-routed remediation proposals | First proposal-only feedback loop delivered; no autonomous policy mutation or closed loop |
|
|
|
|
The [2026-09-28 infrastructure review](history/2026-09-28-open-workplan-infrastructure-review.md)
|
|
records the current evidence baseline: one Railiance node, ready lightweight
|
|
identity services, six flex-auth consumers enforcing caller authentication,
|
|
and private OpenBao access. Readiness and replica counts do not establish HA,
|
|
user acceptance, or complete recovery. Keycloak remains backlog.
|
|
|
|
OpenBao callback/login admission (NK-WP-0032) is complete from the platform's
|
|
September receipts. Operators use the named `openbao-ui-railiance01` tunnel;
|
|
`bao.coulomb.social` is retired. Scoped optional-enrollment policy and
|
|
privileged MFA guards are delivered for the portal and Vergabe demo clients;
|
|
NK-WP-0042 still needs a workload pilot agreement and accepted step-up/recovery
|
|
journey. IAM v0.4 and Playbook Capability v0.2 remain proposed amendments.
|
|
|
|
The current owner/evidence gates are:
|
|
|
|
- NK-WP-0022: final identity-resource retirement needs recovery evidence and
|
|
explicit deletion approval; its August 29 retention minimum has elapsed.
|
|
- NK-WP-0027: reef provider carrier/ceiling agreement and the authoritative
|
|
public-classification maturity mapping remain external dependencies.
|
|
- NK-WP-0031: the implemented proposal-only evaluator still needs Audit Core's
|
|
machine-readable authoritative ownership and E2 freshness metadata.
|
|
- NK-WP-0035: corrected candidate contract pins do not resolve source migration,
|
|
local-identity's missing heartbeat, or the absent source/observer proof.
|
|
- NK-WP-0039: obsolete flex-auth reference objects have been removed; remaining
|
|
tenant-engine references and repository-rename pointers await their owners.
|
|
- NK-WP-0040: execution-attribution receipt emission, custody and schema require
|
|
owner agreement before an end-to-end implementation claim.
|
|
- NK-WP-0042: reuse delivered enrollment/policy components for the agreed pilot;
|
|
generic workload step-up is not established by those two scoped clients.
|
|
|
|
Tutorials (NK-WP-0009) and enterprise federation (NK-WP-0011) remain backlog.
|
|
NK-WP-0030's deterministic composition and NK-WP-0031's local feedback tooling
|
|
are implemented; neither autonomously changes policy. Use the workplan files
|
|
and generated `WORK-RECORDS.md` for changing task state, rather than treating
|
|
this dated operating baseline as a live health report.
|
|
|
|
---
|
|
|
|
## Relevant When
|
|
|
|
- Defining or reviewing identity, tenancy, workload-zone, credential, and
|
|
security-composition canon.
|
|
- Bootstrapping identity and trust before the normal platform is available.
|
|
- Validating an IAM issuer, posture declaration, posture feedback report, or
|
|
Railiance capability declaration against NetKingdom contracts.
|
|
- Integrating KeyCape, flex-auth, OpenBao, user-engine, tenant-engine, or a
|
|
Railiance package across an explicit security boundary.
|
|
- Deciding which repository owns a security semantic, runtime, deployment, or
|
|
evidence obligation.
|
|
|
|
## Not Relevant When
|
|
|
|
- Implementing a provider's internal service behavior: work in that service's
|
|
repository.
|
|
- Provisioning hosts or Kubernetes: use `railiance-infra` and
|
|
`railiance-cluster`.
|
|
- Operating generic platform services: use `railiance-platform`.
|
|
- Shipping a managed application package: use its `rapp-*` repository.
|
|
- Treating the proposed Keycloak expanded mode or autonomous adaptation as an
|
|
already delivered feature.
|
|
|
|
---
|
|
|
|
## Provided Capabilities
|
|
|
|
```capability
|
|
type: governance
|
|
title: NetKingdom security canon
|
|
description: Provider-neutral IAM v0.3, user/tenant boundaries, credential, playbook and scenario composition, tenancy-posture, posture-feedback, and workload-zone standards with explicit ownership and conformance rules.
|
|
keywords: [iam, oidc, tenancy, workload-identity, security-zones, credentials, canon]
|
|
```
|
|
|
|
```capability
|
|
type: validation
|
|
title: Security contract conformance
|
|
description: Executable validation for IAM Profile issuers, playbook capability declarations, tenancy posture, deterministic proposal-only feedback, bootstrap custody, and non-secret evidence records.
|
|
keywords: [validation, conformance, iam, posture, feedback, evidence, playbooks]
|
|
```
|
|
|
|
```capability
|
|
type: tooling
|
|
title: Guarded security bootstrap
|
|
description: Local bootstrap identity plus SOPS/age and OpenBao custody workflows that establish trust while refusing unsafe or unevidenced live initialization.
|
|
keywords: [bootstrap, local-identity, openbao, sops, age, custody, recovery]
|
|
```
|
|
|
|
```capability
|
|
type: governance
|
|
title: Security meta-orchestration boundary
|
|
description: Contracts and responsibility maps for selecting and parameterizing externally executed Railiance security capabilities without reimplementing their deployment mechanics.
|
|
keywords: [meta-orchestration, railiance, responsibility, capability, trust-state]
|
|
```
|
|
|
|
---
|
|
|
|
## Getting Oriented
|
|
|
|
- Direction: `INTENT.md`
|
|
- Current-vs-intended assessment:
|
|
`history/2026-08-23-scope-intent-gap-assessment.md`
|
|
- Canon: `canon/standards/`, `canon/schemas/`, and `docs/adr/`
|
|
- Architecture and ownership: `docs/platform-identity-security-architecture.md`
|
|
and `docs/responsibility-map.md`
|
|
- Bootstrap/custody: `docs/platform-root-custody.md`,
|
|
`docs/security-bootstrap-use-cases.md`,
|
|
`docs/openbao-unseal-custody-models.md`, and
|
|
`tools/security-bootstrap-console/`
|
|
- Executable surfaces: `local-identity/`, `tools/iam-profile-conformance/`,
|
|
`tools/playbook-capability-contract/`, `tools/security-scenario-composer/`,
|
|
`tools/tenancy-posture/`, and `tools/posture-feedback/`
|
|
- Work state: `.custodian-brief.md` and `workplans/`
|