Repository navigation
docs: HMAC v2 promote runbook, status pairing detector, PIV pin honesty - #31
Draft
cursor[bot] wants to merge 2 commits into
Draft
cursor[bot] wants to merge 2 commits into
cursor[bot] wants to merge 2 commits into
Conversation
Operators still had no mint/promote curl path for v2 tokens after #25/#27. ARCHITECTURE still listed 7 CI suites, and #27's title is easy to over-read as a hardware signer plus SSH/NETCONF/Batfish. Adds the pairing-hole detector on GET /api/status, a local config/inventory digest recompute for v2 deny debug, connector HTTP codes, and the two CI commands the README table listed but the copy-paste omitted. Supersedes draft #29 and #30. Verified against serve.py, core/promote/{tokens,gate,promote,connectors}.py, core/seal/{pins,signing}.py, evidence/{oscal,cab}.py, and test.yml. Co-authored-by: georgy75 <georgy75@gmail.com>
Reviewer's GuideDocumentation-only PR that promotes the HMAC v2 operator runbook, exposes the current HMAC/API-key pairing hole through the status contract, specifies OSCAL/CAB evidence limitations, accurately scopes PIV work to compiled-in pins, and synchronizes CI and feature references across the documentation set. Sequence diagram for HMAC v2 mint and dry-run promotesequenceDiagram
actor Operator
participant Server as serve.py
participant Tokens as core/promote/tokens.py
participant Gate as core/promote/gate.py
participant Connector as core/promote/connectors.py
Operator->>Server: POST /api/approve/mint
Server->>Tokens: mint_token_for_bundle()
Tokens-->>Server: v2 token with config_digest and inventory_digest
Server-->>Operator: token
Operator->>Server: POST /api/preflight/promote
Server->>Gate: evaluate()
Gate->>Tokens: verify_approval()
Tokens-->>Gate: v2 approval result
Gate-->>Server: GateDecision
Server->>Connector: push()
Connector-->>Server: dry-run result
Server-->>Operator: promotion record
State diagram for HMAC and API-key pairing statusstateDiagram-v2
[*] --> OpenUnverified: AEGIS_APPROVE_KEY unset
[*] --> Paired: Both keys set
[*] --> PairingHole: AEGIS_APPROVE_KEY set, AEGIS_API_KEY unset
OpenUnverified: api_auth=open or required
OpenUnverified: approve_hmac=asserted-unverified
Paired: api_auth=required
Paired: approve_hmac=required
PairingHole: api_auth=open
PairingHole: approve_hmac=required
OpenUnverified --> [*]
Paired --> [*]
PairingHole --> [*]
Flow diagram for v1 and v2 approval token mintingflowchart TD
Request["POST /api/approve/mint"] --> HasBundle{Bundle supplied?}
HasBundle -->|Yes| V2["mint_token_for_bundle() → v2\napprover + bundle hash + config digest + inventory digest + expiry"]
HasBundle -->|No| Hashes{Config and inventory hashes supplied?}
Hashes -->|Yes| V2Hash["v2 token\nconfig_sha256 + inventory_sha256"]
Hashes -->|No| V1["mint_token() → v1\napprover + bundle hash + expiry"]
V2 --> Promote["POST /api/preflight/promote"]
V2Hash --> Promote
V1 --> Promote
Promote --> Drift{v2 digests still match?}
Drift -->|No| Deny["Deny"]
Drift -->|Yes or v1| DryRun["DryRunConnector"]
File-Level Changes
Possibly linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
promote() catches DisabledLiveConnector.push per device, so connector=live after G4 is HTTP 200 status=partial, not 500. G4 without the env stays 403. Lock the contract in api_test. Co-authored-by: georgy75 <georgy75@gmail.com>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
#25 (HMAC v2) and the pins-only slice of #27 landed on
mainafter the 2026-08-31 docs pass. Draft #29 still describes v1-only tokens. Draft #30 (2026-09-07) had the v2 runbook but never merged, somainstill listed 7 CI suites and had no operator mint/promote path. #27's title is easy to over-read as a hardware signer plus SSH/NETCONF/Batfish.This is documentation only. Behavior is verified against
serve.py,core/promote/{tokens,gate,promote,connectors}.py,core/seal/{pins,signing}.py,evidence/{oscal,cab}.py, and.github/workflows/test.yml.Supersedes draft #29 and draft #30.
Docs added/updated
docs/DEVELOPER.md— §4 v1+v2 token contract; §5GET /api/statusfield table; §7 HMAC approval + promote runbook (curl, TTL, pairing table, status detector, digest recompute, live inventory override, connector HTTP codes); §8 PIV pins (step 0 only).docs/EVIDENCE.md— OSCAL/CAB field contract, filenames,intents_that_holdrule,to_oscal/to_cabdo not verify.docs/ARCHITECTURE.md— component map + §6 gate notes; new §11 exports, §12 HMAC v2 + status detector, §13 PIV pins; tech-stack CI count 9.docs/PIV_HARDWARE_SIGNER_PLAN.md— step 0 pins landed; ECDSA helpers /PivSigner/C_Signdid not.docs/index.html— Pages honesty for HMAC v2, pairing hole, inertliveconnector, OSCAL/CAB limits,pins.py; quickstart lists all nine CI suites.docs/GO_LIVE.md,docs/PHASES.md,README.md,CHANGELOG.md— pointers, triage rows, pairing-hole note, complete CI command list.Codepaths covered
GET /api/status(api_auth,approve_hmac,seal,egress)POST /api/approve/mint(bundle → v2, hash-only → v1),POST /api/preflight/promote(inventory_sha256override)core/promote/tokens.pyv1 + v2 (cconfig digest,invinventory fingerprint)core/promote/gate.pyG1–G5 (G1 isbundler.verify, notverify_seal)core/promote/connectors.py(dry_rundefault;liveisDisabledLiveConnector→ HTTP 500)core/seal/pins.pycompiled-in Yubico root fingerprint onlyPOST /api/preflight/evidence/{oscal,cab}via_verified_bundleKnowledge gaps addressed
:8088GET /api/statusreturnsapi_auth=open+approve_hmac=requiredconfig_digest/inventory_digestwhen a v2 token dies on driftinventory_sha256overrideAEGIS_APPROVE_KEYwithoutAEGIS_API_KEYis still an unauthenticated mint onmain(do not treat draft fix: refuse HMAC mint when API auth is unset #28 as shipped)PivSigner, ECDSA raw→DER helpers, SSH/NETCONF, or a Batfish sidecarconnector=liveis HTTP 500; unknown connector names are 400; CI is 9 suites (README now liststwin_test+api_test)Out of scope
Unmerged draft #28 (startup refuse HMAC-without-API-key). Did not invent SSH/NETCONF or Batfish sidecar docs from the #27 PR title.
Summary by Sourcery
Bring the project documentation in line with the shipped HMAC v2, promotion, evidence-export, CI, and PIV step-0 behavior while clearly documenting current security and implementation limitations.
Enhancements:
Documentation:
Tests: