|
|
|
|
@@ -0,0 +1,363 @@
|
|
|
|
|
# NetKingdom Security Infrastructure Boundary
|
|
|
|
|
|
|
|
|
|
## Purpose
|
|
|
|
|
|
|
|
|
|
This document defines how `secrets-engine` participates in the NetKingdom
|
|
|
|
|
security infrastructure. It is the first place agents and operators should read
|
|
|
|
|
when they need to understand responsibility boundaries, system interactions,
|
|
|
|
|
secret organization, and stage-specific policy concepts.
|
|
|
|
|
|
|
|
|
|
`secrets-engine` is the workflow and interaction layer for approved secret work.
|
|
|
|
|
OpenBao remains the custody, policy, lease, and audit backend.
|
|
|
|
|
|
|
|
|
|
## Core Responsibility
|
|
|
|
|
|
|
|
|
|
`secrets-engine` turns an approved secret request into a safe, reviewable,
|
|
|
|
|
auditable sequence of actions:
|
|
|
|
|
|
|
|
|
|
1. Resolve the catalog entry and stage.
|
|
|
|
|
2. Verify the decision or approval state.
|
|
|
|
|
3. Render a plan for OpenBao metadata, value provisioning, verification, and
|
|
|
|
|
delivery.
|
|
|
|
|
4. Apply only allowed OpenBao changes through the minimal stage role.
|
|
|
|
|
5. Provision or confirm the value without exposing it in coordination systems.
|
|
|
|
|
6. Deliver the secret to a workload or command without printing it.
|
|
|
|
|
7. Record non-secret evidence for audit, troubleshooting, and readiness.
|
|
|
|
|
8. Rotate, revoke, deactivate, or mark compromised secrets through the same
|
|
|
|
|
catalog and decision model.
|
|
|
|
|
|
|
|
|
|
## Boundary Map
|
|
|
|
|
|
|
|
|
|
| System | Owns | secrets-engine interaction | Must not do |
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
| OpenBao | Secret custody, ACL policy enforcement, leases, response wrapping, audit logs | Use OpenBao through constrained build, test, and production roles; write policies, auth roles, metadata, and values only through validated plans | Treat OpenBao UI/CLI as the routine operator interface; bypass decision checks; store raw values outside OpenBao |
|
|
|
|
|
| flex-auth | Authorization decisions and policy reasoning | Ask whether an actor may establish, access, rotate, or deactivate a cataloged secret for a purpose | Store or deliver secret values; become the vault |
|
|
|
|
|
| user-engine / key-cape | Human and service identity, user lifecycle, claims, groups, MFA/OIDC context | Consume stable identity claims and service identities for OpenBao auth bindings and decision checks | Own secret lifecycle policy; mint provider tokens |
|
|
|
|
|
| ops-warden | SSH certificate issuance and credential routing front door | Route non-SSH credential requests to secrets-engine; show catalog readiness and safe next commands | Vend API keys, provider tokens, database passwords, or OpenBao tokens |
|
|
|
|
|
| ops-bridge | Remote execution, tunnels, transport, and operator connectivity | Consume secrets through `secrets-engine exec` or scoped delivery when a remote operation needs credentials | Persist secrets in tunnel configs, logs, or reusable shell state |
|
|
|
|
|
| info-tech-canon | Canonical terminology, governance patterns, stage taxonomy, naming conventions, documentation profiles | Reuse canon terms for stage, catalog, approval, delivery, evidence, rotation, and deactivation concepts | Act as runtime authority or store secret values |
|
|
|
|
|
| State Hub | Non-secret workstreams, decisions, progress, review comments, and evidence pointers | Read decisions and write non-secret progress/evidence | Store raw secret values, tokens, wrapped tokens, passwords, or private keys |
|
|
|
|
|
| llm-connect / agents | Reasoning and task execution | Receive non-secret plans and use exec-time delivery only when needed | Place secrets in prompts, chat, model context, or logs |
|
|
|
|
|
|
|
|
|
|
## System-of-Systems Position
|
|
|
|
|
|
|
|
|
|
`secrets-engine` sits between request/decision systems and OpenBao operations.
|
|
|
|
|
It is not the source of identity, authorization, or custody. It is the place
|
|
|
|
|
where those systems are composed into an operator- and agent-usable workflow.
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
request / ops-warden route
|
|
|
|
|
|
|
|
|
|
|
v
|
|
|
|
|
State Hub decision <---- flex-auth authorization
|
|
|
|
|
|
|
|
|
|
|
v
|
|
|
|
|
secrets-engine catalog + plan + policy guard
|
|
|
|
|
|
|
|
|
|
|
v
|
|
|
|
|
OpenBao role/policy/value operations
|
|
|
|
|
|
|
|
|
|
|
v
|
|
|
|
|
verification + evidence + safe delivery
|
|
|
|
|
|
|
|
|
|
|
v
|
|
|
|
|
workload, CI job, operator command, or ops-bridge task
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Core Concepts
|
|
|
|
|
|
|
|
|
|
### Secret Lane
|
|
|
|
|
|
|
|
|
|
A secret lane is the governed path for one secret use case. It joins a catalog
|
|
|
|
|
id, owner, stage, OpenBao location, fields, consumer binding, approval model,
|
|
|
|
|
delivery modes, verification checks, and revocation behavior.
|
|
|
|
|
|
|
|
|
|
Example catalog id:
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
whynot-design-npm-publish
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Catalog Entry
|
|
|
|
|
|
|
|
|
|
A catalog entry is non-secret metadata. It is the primary object agents and
|
|
|
|
|
operators should reference. It must never contain raw secret values.
|
|
|
|
|
|
|
|
|
|
Required concepts:
|
|
|
|
|
|
|
|
|
|
- catalog id;
|
|
|
|
|
- stage;
|
|
|
|
|
- owner domain, repo, workload, or service;
|
|
|
|
|
- OpenBao backend mount/path and fields;
|
|
|
|
|
- allowed consumers and identity claims;
|
|
|
|
|
- allowed delivery modes;
|
|
|
|
|
- approval/decision requirement;
|
|
|
|
|
- verification requirements;
|
|
|
|
|
- rotation, revocation, and compromised/deactivated behavior;
|
|
|
|
|
- evidence expectations.
|
|
|
|
|
|
|
|
|
|
### Stage
|
|
|
|
|
|
|
|
|
|
A stage is a security boundary. The initial stages are:
|
|
|
|
|
|
|
|
|
|
- `build`;
|
|
|
|
|
- `test`;
|
|
|
|
|
- `production`.
|
|
|
|
|
|
|
|
|
|
Short aliases such as `prod` may exist in CLI flags, but catalog and policy
|
|
|
|
|
documents should normalize to the canonical names above.
|
|
|
|
|
|
|
|
|
|
### Decision
|
|
|
|
|
|
|
|
|
|
A decision is the non-secret approval state that allows a secret lane to be
|
|
|
|
|
created, changed, delivered, rotated, or deactivated. Decisions live outside the
|
|
|
|
|
vault, usually in State Hub and/or flex-auth. A production action must fail
|
|
|
|
|
closed without an approved decision, except for explicit break-glass flows.
|
|
|
|
|
|
|
|
|
|
### Delivery Mode
|
|
|
|
|
|
|
|
|
|
A delivery mode defines how a secret reaches a consumer without becoming visible
|
|
|
|
|
in normal coordination surfaces.
|
|
|
|
|
|
|
|
|
|
Initial allowed modes:
|
|
|
|
|
|
|
|
|
|
- exec-time environment injection;
|
|
|
|
|
- exec-time temporary config file;
|
|
|
|
|
- response-wrapped handoff;
|
|
|
|
|
- local bootstrap file import for setup only;
|
|
|
|
|
- non-production generated test value.
|
|
|
|
|
|
|
|
|
|
Denied modes:
|
|
|
|
|
|
|
|
|
|
- chat;
|
|
|
|
|
- prompts or model context;
|
|
|
|
|
- Git;
|
|
|
|
|
- State Hub message body;
|
|
|
|
|
- command-line argument containing the raw value;
|
|
|
|
|
- normal logs;
|
|
|
|
|
- long-lived untracked local files.
|
|
|
|
|
|
|
|
|
|
### Evidence
|
|
|
|
|
|
|
|
|
|
Evidence is non-secret proof that an action happened and what its result was.
|
|
|
|
|
Evidence may include catalog id, actor, stage, decision id, OpenBao path, field
|
|
|
|
|
names, lease accessor, timestamps, audit request ids, and pass/fail status. It
|
|
|
|
|
must not include raw secret values.
|
|
|
|
|
|
|
|
|
|
## Stage Policy Model
|
|
|
|
|
|
|
|
|
|
### Build
|
|
|
|
|
|
|
|
|
|
Purpose:
|
|
|
|
|
|
|
|
|
|
- local development;
|
|
|
|
|
- disposable integration experiments;
|
|
|
|
|
- generated or synthetic values;
|
|
|
|
|
- quick iteration before stronger policy is justified.
|
|
|
|
|
|
|
|
|
|
Allowed direction:
|
|
|
|
|
|
|
|
|
|
- manage build-stage metadata and values under build prefixes;
|
|
|
|
|
- generate fake or low-impact values;
|
|
|
|
|
- use lightweight decisions or repo-owner approval;
|
|
|
|
|
- support fast `exec` flows for development commands.
|
|
|
|
|
|
|
|
|
|
Restrictions:
|
|
|
|
|
|
|
|
|
|
- no production mounts or paths;
|
|
|
|
|
- no broad OpenBao sys/auth administration;
|
|
|
|
|
- no reuse of build values in test or production;
|
|
|
|
|
- short TTLs by default.
|
|
|
|
|
|
|
|
|
|
### Test
|
|
|
|
|
|
|
|
|
|
Purpose:
|
|
|
|
|
|
|
|
|
|
- staging and integration verification;
|
|
|
|
|
- proving delivery, rotation, and negative checks;
|
|
|
|
|
- rehearsing production policy with lower impact.
|
|
|
|
|
|
|
|
|
|
Allowed direction:
|
|
|
|
|
|
|
|
|
|
- manage approved test-stage metadata and values;
|
|
|
|
|
- run positive and negative access verification;
|
|
|
|
|
- use provider tokens or service credentials with test-only scope;
|
|
|
|
|
- record evidence before a similar production lane is considered ready.
|
|
|
|
|
|
|
|
|
|
Restrictions:
|
|
|
|
|
|
|
|
|
|
- no production values;
|
|
|
|
|
- no production auth roles;
|
|
|
|
|
- stricter identity binding than build;
|
|
|
|
|
- explicit denial checks for unrelated consumers.
|
|
|
|
|
|
|
|
|
|
### Production
|
|
|
|
|
|
|
|
|
|
Purpose:
|
|
|
|
|
|
|
|
|
|
- real workload secrets;
|
|
|
|
|
- real provider tokens;
|
|
|
|
|
- auditable delivery to production-capable consumers.
|
|
|
|
|
|
|
|
|
|
Allowed direction:
|
|
|
|
|
|
|
|
|
|
- apply approved production metadata such as ACL policies and auth roles;
|
|
|
|
|
- provision values only through approved custody modes;
|
|
|
|
|
- deliver values through exec-time or workload-scoped mechanisms;
|
|
|
|
|
- record evidence and readiness state.
|
|
|
|
|
|
|
|
|
|
Restrictions:
|
|
|
|
|
|
|
|
|
|
- no action without approved decision, except explicit break-glass;
|
|
|
|
|
- no broad `platform-root`, `platform-admin`, or wildcard admin semantics;
|
|
|
|
|
- no raw value printing;
|
|
|
|
|
- no default raw reads by agents;
|
|
|
|
|
- rotation, revocation, and compromised/deactivated states must be expressible.
|
|
|
|
|
|
|
|
|
|
## OpenBao Role Layers
|
|
|
|
|
|
|
|
|
|
The initial OpenBao-facing roles are:
|
|
|
|
|
|
|
|
|
|
| Role | Stage | Main capability |
|
|
|
|
|
| --- | --- | --- |
|
|
|
|
|
| `secrets-engine-build` | build | Manage approved build-stage metadata and values under build prefixes. |
|
|
|
|
|
| `secrets-engine-test` | test | Manage approved test-stage metadata and values and run verification. |
|
|
|
|
|
| `secrets-engine-prod` | production | Apply approved production metadata and perform constrained delivery/provisioning actions. |
|
|
|
|
|
|
|
|
|
|
A temporary bootstrap credential may be used to create these roles and policies.
|
|
|
|
|
Bootstrap credentials must be local-only, outside repositories, mode 0600,
|
|
|
|
|
revocable, and tracked as temporary setup material.
|
|
|
|
|
|
|
|
|
|
## Secret Organization
|
|
|
|
|
|
|
|
|
|
The catalog is the stable interface. Physical OpenBao paths may evolve, but
|
|
|
|
|
catalog entries must keep enough structure to enforce stage and ownership.
|
|
|
|
|
|
|
|
|
|
Recommended logical dimensions:
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
stage / tenant-or-org / workload-or-service / bundle / field
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Recommended OpenBao path shape when a shared mount is used:
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
<mount>/workloads/<stage>/<tenant-or-org>/<workload-or-service>/<bundle>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
If a mount is already stage-specific, the stage may be represented by the mount
|
|
|
|
|
instead:
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
<stage-mount>/workloads/<tenant-or-org>/<workload-or-service>/<bundle>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The catalog must make the resolved stage explicit in either case. Existing
|
|
|
|
|
legacy paths should be represented by catalog metadata before being normalized.
|
|
|
|
|
|
|
|
|
|
## Policy Families
|
|
|
|
|
|
|
|
|
|
The engine should distinguish policy families rather than treating every
|
|
|
|
|
OpenBao policy as a free-form string:
|
|
|
|
|
|
|
|
|
|
| Family | Purpose |
|
|
|
|
|
| --- | --- |
|
|
|
|
|
| catalog-read | Read non-secret catalog metadata and readiness. |
|
|
|
|
|
| stage-applier | Apply metadata inside one stage boundary. |
|
|
|
|
|
| value-provisioner | Write or import secret values under approved custody. |
|
|
|
|
|
| delivery-runner | Fetch and inject a value only into a child process or workload-specific config. |
|
|
|
|
|
| verifier | Run positive/negative checks without printing values. |
|
|
|
|
|
| revoker | Revoke leases, deactivate lanes, or mark compromised state. |
|
|
|
|
|
| auditor | Produce non-secret reports and evidence summaries. |
|
|
|
|
|
|
|
|
|
|
Production policy families should be split so that metadata apply, value
|
|
|
|
|
provisioning, and value delivery do not automatically imply each other.
|
|
|
|
|
|
|
|
|
|
## Main Interaction Flows
|
|
|
|
|
|
|
|
|
|
### Establish a Secret Lane
|
|
|
|
|
|
|
|
|
|
1. Actor requests a cataloged secret lane.
|
|
|
|
|
2. flex-auth and/or State Hub records an approval decision.
|
|
|
|
|
3. secrets-engine renders the OpenBao policy/auth/value plan.
|
|
|
|
|
4. Operator or agent reviews the plan.
|
|
|
|
|
5. secrets-engine applies allowed metadata through the minimal stage role.
|
|
|
|
|
6. Secret value is provisioned by approved custody mode.
|
|
|
|
|
7. Positive and negative verification run.
|
|
|
|
|
8. Catalog readiness becomes resolvable for ops-warden and consumers.
|
|
|
|
|
|
|
|
|
|
### Use a Secret
|
|
|
|
|
|
|
|
|
|
1. Consumer asks ops-warden or secrets-engine for a catalog id.
|
|
|
|
|
2. secrets-engine checks catalog, stage, readiness, identity, and decision state.
|
|
|
|
|
3. secrets-engine fetches the value through OpenBao using a delivery role.
|
|
|
|
|
4. The value is injected only into the child process or temporary config.
|
|
|
|
|
5. Temporary material is removed.
|
|
|
|
|
6. Non-secret evidence is recorded.
|
|
|
|
|
|
|
|
|
|
Target shape:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
secrets-engine exec --catalog whynot-design-npm-publish -- npm publish
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Rotate a Secret
|
|
|
|
|
|
|
|
|
|
1. Rotation request is linked to the existing catalog entry.
|
|
|
|
|
2. New value is provisioned under approved custody.
|
|
|
|
|
3. Consumers are switched or verified.
|
|
|
|
|
4. Old value is revoked or deactivated.
|
|
|
|
|
5. Evidence records old/new version identifiers without raw values.
|
|
|
|
|
|
|
|
|
|
### Mark Compromised or Deactivated
|
|
|
|
|
|
|
|
|
|
1. Actor marks the lane compromised or requests deactivation.
|
|
|
|
|
2. secrets-engine blocks delivery immediately where possible.
|
|
|
|
|
3. OpenBao leases/tokens are revoked.
|
|
|
|
|
4. Related policies or auth roles are disabled if required.
|
|
|
|
|
5. ops-warden readiness becomes not resolvable.
|
|
|
|
|
6. Evidence and follow-up tasks are recorded.
|
|
|
|
|
|
|
|
|
|
## Explicit Non-responsibilities
|
|
|
|
|
|
|
|
|
|
secrets-engine must not:
|
|
|
|
|
|
|
|
|
|
- replace OpenBao;
|
|
|
|
|
- make identity or authorization decisions by itself;
|
|
|
|
|
- issue SSH certificates;
|
|
|
|
|
- establish network tunnels;
|
|
|
|
|
- persist raw secret values outside OpenBao as normal operation;
|
|
|
|
|
- put secrets into prompts, chat, State Hub, Git, or logs;
|
|
|
|
|
- make production changes without an approved decision;
|
|
|
|
|
- normalize insecure bootstrap shortcuts into permanent operations.
|
|
|
|
|
|
|
|
|
|
## First Pilot
|
|
|
|
|
|
|
|
|
|
The first pilot lane is:
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
catalog id: whynot-design-npm-publish
|
|
|
|
|
field: NPM_AUTH_TOKEN
|
|
|
|
|
consumer: whynot-design npm publish workflow
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The pilot should prove:
|
|
|
|
|
|
|
|
|
|
- a catalog entry can describe the lane without a raw value;
|
|
|
|
|
- an approved decision can drive OpenBao policy and auth role creation;
|
|
|
|
|
- provisioning can happen without secret disclosure;
|
|
|
|
|
- positive and negative verification can be recorded;
|
|
|
|
|
- `secrets-engine exec` can deliver the token to `npm publish` safely;
|
|
|
|
|
- ops-warden can route to secrets-engine and report readiness.
|
|
|
|
|
|
|
|
|
|
## Canonicalization Tasks
|
|
|
|
|
|
|
|
|
|
These concepts should be aligned with info-tech-canon as the implementation
|
|
|
|
|
hardens:
|
|
|
|
|
|
|
|
|
|
- stage names and aliases;
|
|
|
|
|
- catalog entry schema terms;
|
|
|
|
|
- decision states and evidence vocabulary;
|
|
|
|
|
- delivery mode names;
|
|
|
|
|
- compromised, deactivated, rotated, ready, and resolvable states;
|
|
|
|
|
- standard OpenBao path and policy naming patterns.
|
