docs: adds initial spec and plan for export functionality by gvauter · Pull Request #431 · complytime/complyctl

gvauter · 2026-03-23T23:30:32Z

Summary

Adds feature specification and implementation plan for a new complyctl export command that ships scan results to a ComplyBeacon OTEL collector
Proposes extending the plugin gRPC contract with an Export RPC so scanning providers can emit evidence directly via ProofWatch

The export command orchestrates evidence delivery without touching evidence data itself. Plugins that opt in (via a new supports_export capability on Describe) use ProofWatch to emit GemaraEvidence as OTLP log records directly to the collector. Enrichment is handled downstream by TruthBeam in the Beacon collector pipeline.

Key decisions documented in the spec:

Standalone command — complyctl export --policy-id <ID> runs after scan, keeping the two as composable steps
Plugins export directly — complyctl passes collector config via gRPC; plugins own OTLP emission
Zero new deps in complyctl core — ProofWatch/OTEL SDK only in plugins that implement Export
Collector config in complytime.yaml — new optional collector: section with endpoint and auth

The implementation plan breaks work into four areas: proto contract changes, plugin SDK extension, CLI command, and config/doctor additions.

Files

specs/003-complybeacon-export/spec.md — feature specification with clarifications, user stories, acceptance scenarios, functional requirements, and success criteria
specs/003-complybeacon-export/plan.md — implementation plan with project structure, proto schema, config schema, data flow, and test architecture

Review Hints

This PR is spec and plan only — no code changes. Looking for feedback on:

The decision to have plugins export directly vs. complyctl exporting centrally
The Export RPC contract and CollectorConfig shape
Whether the supports_export capability discovery approach is sufficient
Any missing edge cases or requirements

huiwangredhat

@gvauter Thanks for your PR. The core logic LGTM. It's a solid implementation of the proposed plan. I’ve tagged a few minor nits and my questions.

huiwangredhat · 2026-03-24T06:47:06Z

specs/003-complybeacon-export/spec.md

+  backends (Loki, S3) and reporting tools (Hyperproof).
+
+- **ProofWatch**: A Go instrumentation library
+  (`github.com/complytime/complybeacon/proofwatch`) that


Nit: This library link is outdated.

huiwangredhat · 2026-03-24T06:47:22Z

specs/003-complybeacon-export/spec.md

+An auditor needs to verify that compliance evidence in the
+downstream reporting system traces back to the original
+scan. The evidence exported by complyctl via ProofWatch
+carries integrity attributes (assessment IDs, timestamps,


I am not sure that Assessment IDs, timestamps, and Evaluator Identity could provide a sufficient Chain of Custody. To satisfy a rigorous audit, we should ensure the evidence is immutable and verifiable. Do we need to include a cryptographic hash in the results?

Hey Sophia - this is a good question, perhaps we can table it for now and discuss more with @jpower432 to understand the chain of custody in more detail.

huiwangredhat · 2026-03-24T06:47:24Z

specs/003-complybeacon-export/spec.md

+reports back the number of records exported and any errors.
+
+**Why this priority**: At least one plugin must implement
+export for the feature to be usable. The OpenSCAP and AMPEL


Just a question: are both OpenSCAP and AMPEL being developed in parallel, or will AMPEL be the first plugin to support export?

I'm not sure which would be first, but perhaps AMPEL would be easiest to start with here?

huiwangredhat · 2026-03-24T06:47:27Z

specs/003-complybeacon-export/spec.md

+
+- Q: Where does collector endpoint and authentication
+  configuration live? → A: `complytime.yaml` top-level
+  `collector` section with `endpoint` and `auth` fields.


The authtoken could be generated by the client ID and client secret dynamically, so do we need to add the two input fields?

This is a good callout @huiwangredhat. I would think the token would generated dynamically with the client_id, client_secret, and token_endpoint, right? Then complyctl does the handshake and passes the temporary access token to the plugin which they include in the request headers along with some plugin specific identifier.

@jpower432, Oh, yes, that's right. We also need the token_endpoint.

Ok thank you, I've updated this in the spec.

huiwangredhat · 2026-03-24T06:47:33Z

specs/003-complybeacon-export/plan.md

+6. Display terminal summary:
+   PROVIDER        EXPORTED  FAILED  STATUS
+   openscap        47        0       ✅
+   ampel           5         0       ✅


Does it show the friendly error message if the status is FAILED?

updated FR-008 to require that the plugin's error message is displayed below the summary table when failures occur

jpower432 · 2026-03-24T17:49:25Z

specs/003-complybeacon-export/plan.md

+
+## Summary
+
+Add a `complyctl export` command that orchestrates evidence


Should we make this a required feature of every plugin? Seems like it would be lightweight if it were optional. Could this be an optional "output" of complyctl scan instead?

@jpower432 I have no strong opinions on making it mandatory. I can't think of a plugin where we wouldn't want the evidence exported. Are you thinking we should drop the export command and instead have scan handle the export? I guess this depends how coupled we want those workflows to be? A few possible thoughts

initial users may not have the collector components running, so exporting isn't something they would want to happen by default (making them use --skip-export or similar flag) on every scan

a user may want to inspect the results before exporting? e.g. dont export failures, fix the issue, run a clean scan, then export

I agree. I was thinking it would be something controls by a flag on scan. Right now we have --format oscal, pretty, sarif. Could we tweak that? To me, this seems like just another way to aggregate and report the information.

It could be

--export oscal,sarif,pretty,otel

Signed-off-by: George Vauter <gvauter@redhat.com>

gvauter requested a review from jpower432 March 23, 2026 23:30

gvauter requested a review from a team as a code owner March 23, 2026 23:30

huiwangredhat reviewed Mar 24, 2026

View reviewed changes

jpower432 reviewed Mar 24, 2026

View reviewed changes

docs: adds initial spec and plan

8be651d

Signed-off-by: George Vauter <gvauter@redhat.com>

gvauter force-pushed the 003-complybeacon-export branch from 2ea5229 to 8be651d Compare March 25, 2026 18:10


		## Summary

		Add a `complyctl export` command that orchestrates evidence

Conversation

gvauter commented Mar 23, 2026

Summary

Files

Review Hints

Uh oh!

huiwangredhat left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gvauter Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gvauter Mar 25, 2026 •

edited

Loading