feat: evidence source provenance (EvidenceMapping) support - #840
Open
marcusburghardt wants to merge 4 commits into
Open
feat: evidence source provenance (EvidenceMapping) support#840marcusburghardt wants to merge 4 commits into
marcusburghardt wants to merge 4 commits into
Conversation
jpower432
reviewed
Sep 5, 2026
Add OpenSpec change artifacts for plumbing the Gemara EvidenceMapping (source field) through complyctl's evidence pipeline. This enables providers to report evidence provenance -- which artifact, location, and content digest each evidence entry was collected from. Artifacts: - proposal.md: motivation and scope - specs/evidence-source/spec.md: behavioral requirements - design.md: technical decisions and approach - tasks.md: implementation checklist Assisted-by: OpenCode (claude-opus-4-6) Signed-off-by: Marcus Burghardt <maburgha@redhat.com>
Refine Non-Goals to acknowledge go-gemara#127 tracks evidence-to-OSCAL and evidence-to-SARIF conversion upstream. SARIF already delegates to gemaraconv.ToSARIF() and will benefit automatically. Local OSCAL formatter migration tracked in a separate complyctl issue. Assisted-by: OpenCode (claude-opus-4-6) Signed-off-by: Marcus Burghardt <maburgha@redhat.com>
Apply auto-fixes for findings from 6 Divisor spec reviewers: - Normalize SHALL to MUST per AGENTS.md spec convention - Add scenario for partial source fields (common real-world case) - Add scenario for coordinate/entry_id passthrough (Gemara mutual exclusivity documented but not enforced by complyctl) - Qualify YAML omission scenario with JSON serialization edge case (encoding/json does not omit zero-value structs) - Add D5 design decision for passthrough model + digest format note - Expand D3 with gemara value-type serialization note - Task 1.1: add buf breaking check for backward-compat verification - Task 2.2: acknowledge missing internalEvidenceToProto test coverage - Task 3.2: add JSON serialization and YAML omission assertions - Task 5.2: add schema validation and specific E2E assertions - Add documentation tasks (CHANGELOG.md, AGENTS.md Recent Changes) Assisted-by: OpenCode (claude-opus-4-6) Signed-off-by: Marcus Burghardt <maburgha@redhat.com>
Add EvidenceMapping message to proto API and plumb the source field through the entire evidence pipeline, enabling providers to report where evidence was collected from. Changes: - Proto: add EvidenceMapping message with reference_id, coordinate, entry_id, digest, remarks fields; add source field (field 6) to Evidence message; remove stale ADR 0023 comment - SDK: add EvidenceSource struct and Source *EvidenceSource field to provider.Evidence in pkg/provider/client.go - Mapping: add internalEvidenceSourceToProto() in server.go and protoEvidenceMappingToInternal() in client.go for gRPC boundary - Evaluator: map provider.EvidenceSource to gemara.EvidenceMapping when constructing evaluation log entries - Markdown: render source provenance as 'source: <ref> @ <coord>' in formatEvidenceMeta() - Test provider: emit evidence with Source for E2E coverage - Tests: comprehensive coverage for both proto mapping directions, evaluator serialization (YAML + JSON), and markdown rendering Backward-compatible: providers without source are unaffected. Assisted-by: OpenCode (claude-opus-4-6) Signed-off-by: Marcus Burghardt <maburgha@redhat.com>
marcusburghardt
force-pushed
the
opsx/evidence-source
branch
from
September 11, 2026 08:37
ee3915f to
ddb1674
Compare
marcusburghardt
marked this pull request as ready for review
September 11, 2026 08:48
gxmiranda
approved these changes
Sep 11, 2026
gxmiranda
left a comment
gxmiranda
left a comment
Contributor
There was a problem hiding this comment.
Clean, well-specified feature implementation that plumbs the Gemara EvidenceMapping through complyctl's entire evidence pipeline -- from proto definition through gRPC mapping, evaluator, and Markdown rendering. Comprehensive test coverage (both mapping directions, nil/partial/full cases, YAML/JSON serialization), backward-compatible design, and proper spec-first workflow with OpenSpec artifacts. All CI checks pass.
This review was generated by /review-pr (AI-assisted).
jpower432
reviewed
Sep 11, 2026
|
|
||
| // Precise location within the referenced artifact (e.g. file path, | ||
| // API path, JSON path). Upstream Gemara schema documents this as | ||
| // mutually exclusive with entry_id; complyctl passes through without |
Member
There was a problem hiding this comment.
This was a documentation bug. Not mutally exclusive. Fixed in the next release.
jpower432
reviewed
Sep 11, 2026
| // evidence was collected. Mirrors go-gemara EvidenceMapping. | ||
| message EvidenceMapping { | ||
| // Ties this evidence to a mapping-reference in the artifact's metadata | ||
| string reference_id = 1; |
Member
There was a problem hiding this comment.
Do plugins have awareness of a mapping reference? Would we prefer that they send us a list of their sources too?
jpower432
requested changes
Sep 11, 2026
jpower432
left a comment
jpower432
left a comment
Member
There was a problem hiding this comment.
Implementation looks good, but I see an issue with regard to reference-id. There doesn't seem to be a way to collect this actual reference from plugins and I don't think the host would have that information either.
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
4 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.
Summary
Plumb the Gemara
#EvidenceMapping(sourcefield) through complyctl'sentire evidence pipeline, enabling providers to report where evidence
was collected from.
Fixes #841
Context
The Gemara CUE schema (
evaluationlog.cueline 73,auditlog.cuelines 78-97) defines
#Evidencewith asourcefield of type#EvidenceMappingthat records evidence provenance -- which artifact,which location within it, and a content digest. The go-gemara SDK already
exposes this as
Evidence.Source. complyctl's proto API currently defersthis field with a comment referencing an unwritten "ADR 0023".
Changes
EvidenceMappingmessage (reference_id,coordinate,entry_id,digest,remarks) andsourcefield(field 6) on
Evidence. Remove stale ADR 0023 comment.EvidenceSourcestruct andSource *EvidenceSourcefield onEvidenceinpkg/provider/.internalEvidenceSourceToProto()inserver.goand
protoEvidenceMappingToInternal()inclient.go.provider.EvidenceSourcetogemara.EvidenceMappingwhen constructing evaluation log entries.source: <ref> @ <coord>in
formatEvidenceMeta().Sourcefor E2E coverage.evaluator serialization (YAML + JSON), and markdown rendering.
Backward-compatible: providers that don't send
sourceare unaffected.OpenSpec Artifacts
openspec/changes/evidence-source/proposal.mdopenspec/changes/evidence-source/specs/evidence-source/spec.mdopenspec/changes/evidence-source/design.mdopenspec/changes/evidence-source/tasks.mdRelated