stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
108d1c64b323808d6085fca05818fc581c6b003a
git.stella-ops.org/docs/modules/findings-ledger/workflow-inference.md
master 536f6249a6
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Add SBOM, symbols, traces, and VEX files for CVE-2022-21661 SQLi case 
- Created CycloneDX and SPDX SBOM files for both reachable and unreachable images.
- Added symbols.json detailing function entry and sink points in the WordPress code.
- Included runtime traces for function calls in both reachable and unreachable scenarios.
- Developed OpenVEX files indicating vulnerability status and justification for both cases.
- Updated README for evaluator harness to guide integration with scanner output.
2025-11-08 20:53:45 +02:00

3.1 KiB
Raw Blame History

Findings Ledger — Workflow Inference Notes

Audience: Findings Ledger Guild, Vuln Explorer API, Console Guild
Scope: How workflow mutations (assign/comment/accept-risk/etc.) derive canonical ledger inputs when the caller omits low-level fields.

1. Chain + sequencing

  • Chain derivation. When a request does not provide chainId, we deterministically derive it from tenantId :: policyVersion (Guid from SHA-256 first 16 bytes). This keeps per-policy ordering stable and avoids callers leaking raw GUID logic.
  • Sequence number. We fetch the current chain head and expect head.sequence + 1. If the chain has no entries, the expected sequence is 1. The append path still enforces optimistic concurrency and rejects mismatches.
  • Previous hash. We reuse the head’s event_hash (defaulting to the all-zero hash for genesis events) so writers don’t need to manage hash pointers.

2. Event identifiers + timestamps

  • Event IDs. If the caller omits eventId, we mint a V7 GUID to keep chronological ordering while remaining globally unique.
  • Occurred / recorded timestamps. occurredAt defaults to “now” in UTC (based on TimeProvider). recordedAt always comes from the service’s TimeProvider to avoid caller-provided drift.

3. Status & severity fallbacks

  • The reducer already maps event types to canonical statuses. Workflow service only writes status when the mutation explicitly changes it (e.g., accept-risk → accepted_risk, target-fix → in_progress, verify-fix → verified, reopen → affected). Otherwise we leave status null and let the reducer infer it.
  • Severity is never inferred inside workflow handlers—they rely on policy evaluation or reducer logic.

4. Attachments metadata

  • Attachments now include security context: every entry captures an AES-256-GCM envelope (algorithm, ciphertext, nonce, tag, expiresAt) derived from attachments.encryptionKey.
  • Signed URLs are generated with HMAC-SHA256 using attachments.signedUrlSecret and inherit attachments.signedUrlLifetime (default 15 minutes). URLs plus envelopes share the same expiry window.
  • Metadata is normalized (trimmed keys, deterministic ordering) before encryption so ledger hashes remain stable; duplicate IDs are deduplicated.
  • Actual binary blobs stay in Evidence Locker/S3; the envelope is what downstream services use to decrypt the blob once downloaded.

5. Validation surface

  • All handlers enforce tenant/policy/finding/artifact/vuln IDs, actor identity, and supported actor types.
  • Mutation-specific requirements (e.g., assignment requires assignee, accept-risk needs justification) are validated before any ledger append occurs.
  • Attachments are validated for ID/file name/MIME type/positive size and 64-char SHA-256 digests before encryption, preventing malformed payloads from burning hashes or emitting invalid URLs.

These rules let upstream APIs/clients send high-level workflow intents without micromanaging ledger sequencing or hashing, while preserving deterministic ledger entries. LEDGER-29-005 implements the service described here; LEDGER-29-006 builds on it for secure attachment handling.