docs: add security ADRs 003-007 and link from operational docs - #940
Merged
Conversation
Closes pugsley76#874 Introduce integration/rpc_failure_journey_test.go — a deterministic, hermetically isolated journey that exercises every documented RPC failure mode and asserts coherent behavior across debug, compare, dry-run, and watch workflows. Failure classes covered (27 test functions): - Connection refused / unreachable endpoint → exit 3 - HTTP 500 Internal Server Error (non-retryable) → exit 3 - HTTP 503 Service Unavailable — retries exhausted → exit 3 - HTTP 503 → success on third attempt (retry recovery) → exit 0/2 - HTTP 429 Rate Limit, integer Retry-After → exit 3, ≥900ms elapsed - HTTP 429 Rate Limit, RFC 1123 date Retry-After → exit 3, ≥800ms elapsed - HTTP 429 Rate Limit, Retry-After: 0 (fast path) → exit 3 - HTTP 413 Response Too Large (non-retryable, ≤2 hits) → exit 3 - Malformed JSON body → exit ≠ 0 - JSON-RPC auth failure → exit ≠ 0 - JSON-RPC transaction not found (hint asserted) → exit ≠ 0 - JSON-RPC ledger not found / ledger archived → exit ≠ 0 - All-nodes-failed (two 503 servers) → exit 3 - Cancellation during retry backoff (60s Retry-After, → exit ≠ 0 killed by 3s test timeout) - compare command: missing --wasm PreRunE guard → exit ≠ 0 - compare command: RPC down with valid WASM → exit ≠ 0 - dry-run subcommand RPC failure → exit ≠ 0 - debug --dry-run: zero RPC calls made → hits == 0 - watch mode timeout (--watch-timeout 2, PENDING srv) → exit ≠ 0, ≥1.5s - Session absence on every RPC failure variant → no "Session created:" - Retry count ≤ MaxRetries+1 for 429/503/504 → hits ≤ 4 - Exit-code stability across all RPC failure classes → always 3 - Error output placement (stderr, not stdout) - Partial artifact safety (no trace file on RPC failure) - Invalid network flag: PreRunE fires, zero RPC contact → hits == 0 - JSON output mode: stdout empty or valid JSON on failure Test infrastructure: - rpcHermeticEnv: strips all ambient config, injects GLASSBOX_NO_UPDATE_CHECK=1, NO_COLOR=1, GLASSBOX_SIM_PATH= - rpcFixedHandler / rpcCounting / rpcSequence: composable fake-server primitives for scripting deterministic response sequences - rpcRunEnv: context-aware child-process runner (default 20 s timeout) - Retry-After: 1 on every retryable handler so worst-case backoff stays well within the 20 s runner - Atomic hit counters on all retry-count assertions for race safety Bugs fixed during review (in the same squash): - Removed t.Errorf call from httptest goroutine (would panic after test completion during deferred srv.Close) - Fixed silent false-pass in 503-then-success assertion - Added Retry-After: 1 to ten 503/504 handlers that were missing it - Removed three unused constants (rpcExitUser/Config/Interrupt)
Add five Architecture Decision Records covering the trust model and security properties of Glassbox: - ADR-003: Trust Boundaries and Component Trust Levels — five-tier model (CLI host, simulator subprocess, plugin subprocess, signing providers, external services, browser bindings) with controls at each boundary. - ADR-004: Data Classification and Cross-Boundary Data Flows — taxonomy (SECRET / INTERNAL / PUBLIC / UNTRUSTED INPUT), boundary catalogue A-G, redaction rules, and explicit not-claimed properties. - ADR-005: Canonicalization Ownership — Go CLI as canonical form authority, JCS-inspired invariants, cross-language equivalence testing strategy. - ADR-006: Provider Isolation — Signer interface contract, provider lifecycle, software / PKCS#11 / KMS isolation properties and limitations. - ADR-007: Offline Guarantees — offline-capable operations table, air-gapped signing pipeline (3-stage envelope), snapshot replay determinism, KMS network requirement. Each ADR includes consequences, migration impact, and an Implementation table that maps every security claim to the source file or doc that verifies it. No ADR claims a property absent from tests or implementation. Back-links added to: docs/adr/README.md, audit-signing.md, audit-kms-signing.md, audit-canonicalization.md, audit-verify-command.md, sandboxed-replay.md, snapshot-deduplication.md, security-warnings.md, bindings-environments.md. Closes pugsley76#876
|
@Mansa147 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits. You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀 |
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
3 participants
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.
Closes #876
Add five Architecture Decision Records covering the trust model and
security properties of Glassbox:
(CLI host, simulator subprocess, plugin subprocess, signing providers,
external services, browser bindings) with controls at each boundary.
(SECRET / INTERNAL / PUBLIC / UNTRUSTED INPUT), boundary catalogue A-G,
redaction rules, and explicit not-claimed properties.
JCS-inspired invariants, cross-language equivalence testing strategy.
software / PKCS#11 / KMS isolation properties and limitations.
signing pipeline (3-stage envelope), snapshot replay determinism, KMS
network requirement.
Each ADR includes consequences, migration impact, and an Implementation table
that maps every security claim to the source file or doc that verifies it.
No ADR claims a property absent from tests or implementation.
Back-links added to: docs/adr/README.md, audit-signing.md,
audit-kms-signing.md, audit-canonicalization.md, audit-verify-command.md,
sandboxed-replay.md, snapshot-deduplication.md, security-warnings.md,
bindings-environments.md.