feat: agent remote configuration (overlay, apply modes, safeguards)

[ccf-lisa]

Summary

The API side of agent remote configuration. Each agent gets an API-stored overlay over its file config (RFC 7396 JSON Merge Patch). Each instance applies the overlay according to its own remote_config.mode and reports back what it runs.

Scope: config overlay plus safeguards. An overlay can set verbosity, agent_evidence and plugins.<p>.{enabled, protocol_version, schedule, source, policies, config, labels, policy_data, policy_behavior}. Plugin policies entries are vendor OCI sources or local paths; authoring policy modules or bundles through the overlay is out of scope (policy_bundles is rejected as an unknown field).

Ship order: this PR first, then compliance-framework/agent#95, then compliance-framework/ui#318. The agent pins this branch's pseudo-version.

What's in it

pkg/agentconfig: the shared config contract (also imported by the agent)

• Model and merge:
  • the declared Config types;
  • Merge / MergePatch / StripLocked, using RFC 7396 merge patch;
  • the locked keys api, daemon and remote_config can never be overlaid;
  • DiffJSON, and RFC 6901 pointers.
• Validation:
  • ValidateOverlay strictly checks an overlay alone, with rules O1–O10 and exact pointers and codes;
  • Validate / ValidateEditable check a merged config;
  • 5-field cron schedules.
• Safety:
  • RemoteConfig.Normalize: an agent with credentials and no remote_config.mode runs in report (it reports but never applies); without credentials the mode is forced to off. Remote apply is opt-in via apply_safe or apply_all;
  • Classify / WillApply decide what each mode (report, apply_safe, apply_all) applies, using trusted_sources, overridable_config_flags and allow_local_sources. Re-enabling a plugin disabled in the base is unsafe unless its source is trusted (reenables-plugin); policy_data, policy_behavior, labels, schedule and removing a plugin are safe by design.
• Integrity:
  • Redact / WithMaskedPointers mask values as exactly •••• (always the whole value, never part of it), under plugins.*.config and plugins.*.policy_data, plus api.url when it holds a secret. Digest and the server-side RedactDocument apply the same rules:
    • by key name, split into words at separators and camelCase: the stems password, passwd, passphrase, secret, token, credential, apikey, privatekey, accesskey, connectionstring/connstring/connstr, sessionid, authorization and authheader match anywhere. key(s), pass, pwd, auth, dsn and cookie(s) match as the last word or its suffix (sshkey, dbpass, basicauth), ignoring trailing format words (_pem, _b64, _hex, …). Ordinary words such as monkey and bypass are excluded. So keyword, key_id, pass_rate and auth_method are not masked, while tokens_per_minute is (a deliberate false positive);
    • by content, whatever the key: URLs with a password in their userinfo (also inside DSNs and longer strings), PEM private keys, password=… assignments, and high-confidence token formats adapted from gitleaks' MIT rules (AWS key IDs, GitHub, GitLab, Slack, Google API keys, Stripe, JWTs, SendGrid, npm, PyPI, OpenAI, Anthropic, Hugging Face, DigitalOcean, Shopify, Terraform Cloud, Vault, Azure AD client secrets, age). No entropy heuristics;
    • ${env:…} placeholders: a value is kept verbatim only if nothing but whitespace and :;,|/@=& is left once its placeholders are removed. Literal text mixed with a placeholder is masked under a secret-like key, and otherwise checked by content. Booleans are never masked by key;
  • Digest;
  • opaque agent ETags, and admin If-Match parsing;
  • ${env:NAME} references, resolved by the agent only in plugins.*.config.
• Wire types:
  • OverlayDocument;
  • Report, carrying plugins[] with lib-version;
  • the status and reason vocabularies.

Storage, authz and pruning

• Tables:
  • ccf_agent_config_revisions: append-only, unique (agent_id, revision), revert creates a new revision; deleting an agent deletes its revisions;
  • ccf_agent_instances: one row per reporting instance, capped per agent (non-prunable rows); when full, the oldest stale instance is replaced, and a 409 only happens when every counted instance is fresh.
• Authz:
  • new actions agent:configure (overlay writes) and agent:sync (the agent fetching its overlay and reporting);
  • with the builtin driver, only admins can use the agent resource;
  • GET /admin/agents[/:id] now needs agent:read; writes and keys still need admin:manage.
• Pruning: an hourly agent_instance_prune job, driven by the CCF_AGENT_* settings.

Routes

• Agent:
  • GET /api/agent/config: opaque ETag, 304, X-CCF-Remote-Config: 1;
  • PUT /api/agent/instances/:instanceId/config-report: validated, size-capped and re-redacted (base, effective, and free text: error, warnings, plugin sources, remote-config), NUL rejected, 409 at the instance cap;
  • the heartbeat now carries config_revision / config_digest.
• Admin:
  • GET|PUT /admin/agents/:id/config: If-Match required (428 without it, 409 when stale);
  • POST …/config/preview (needs agent:configure): a dry run, with overlay errors and a per-instance diff, change classification and will-apply result; an invalid overlay returns only its errors;
  • GET …/config/revisions[/:rev] and POST …/config/revisions/:rev/revert;
  • GET …/instances[/:instanceId].
  • PUT, preview and revert bodies are capped at 1 MiB (4 × MaxOverlayBytes), so an oversized overlay gets a 422 with the size error rather than a 413.
• SDK: client.AgentConfig.Get/Report, with the remote-config errors and header plumbing.
• Swagger: regenerated for the new routes only.

Notable decisions

• Overlays are redacted for readers. GET …/config and GET …/config/revisions/:rev return the overlay verbatim only to callers with agent:configure (editors); everyone else gets it masked (supersedes R57). Secrets still belong in ${env:NAME} placeholders.
• Masking is conservative. A masked base value hides its ${env:…} references from the API, so a preview against an instance whose base has a mixed value such as postgres://u:${env:PG_PASS}@h under dsn reports a reused reference as new-env-reference (unsafe). The agent classifies against its unredacted base, so what it applies is unaffected.
• Removed during review:
  • inline policy bundles (authoring, overriding and removing policy modules through the overlay), with everything that only served them: the Rego checks, the static and evaluated policy contract check, policy-error reporting, and the narrower agent:configure-policy permission and policy-author role;
  • the automatic continuity design (R82), the optional authored policy ID (R74) and bundle age (bundles-first-seen);
  • after the security review: the artifact file routes (GET /api/artifacts/{digest}/files[/{path}]) and the report's policy-bundle inventory (policy-bundles, BundleTreeDigest, the policy_bundles instance column). Nothing read them. Reports that still send policy-bundles are accepted and the field is ignored. Evaluation-time bundle uploads and GET /api/artifacts/{digest} are unchanged from main.
• Dependency pin: github.com/moby/go-archive is pinned to v0.1.0, because the go-containerregistry bump otherwise breaks testcontainers builds.

Testing

• go build, go vet (with and without the integration tag), make test and golangci-lint are clean. make swag leaves no diff, and go mod tidy is a no-op.
• Integration suites run on Postgres testcontainers (go test -tags integration -p 1 ./...): TestAgentCfgServiceIntegration, TestAgentConfigSyncAPI, TestAgentConfigAdminAPI (every admin route, plus builtin and Cedar authz matrices), the prune worker.
• Redaction has table tests for key names (including negatives), URL credentials, PEM keys, each token format, placeholder rules, idempotency, RedactDocument parity and digest stability.

Release notes

• Remote apply is now opt-in. Agents being upgraded no longer apply remote config unless remote_config.mode is set to apply_safe or apply_all. With credentials and no mode set, an agent only reports (report).
• Builtin authz: agent service accounts may only register, ingest and sync on the agent resource (parity with Cedar).
• Digests change for configs whose keys end in name, url, file, id and similar (no longer masked by key name; values are still content-checked), and for sources/policy entries holding credentials (now masked).
• Config reports and previews mask more values: secrets are now detected by content as well as by key name, and literal text mixed with an ${env:…} placeholder under a secret-like key is masked.

Follow-ups

• Purging one revision: deleting an agent removes its revisions; redacting a single revision in place is not implemented yet.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 08cd0854-8865-4ca2-bf7c-ab52648e6e1a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[gusfcarvalho]

Approving at 52e315b. I found no blocking issues. The four inline threads are non-blocking, and two of them ask for an owner decision.

What I checked:

• Against design §12 (R1–R56) and the API LLD:
  • locked keys: stripped in Merge and rejected by ValidateOverlay;
  • classification: Classify/WillApply, including R23 and R24;
  • builtin PDP gate on agent (R39);
  • agent routes: agent JWT only, with cross-agent isolation from the JWT;
  • D18 and the R22 swap;
  • opaque ETag and 304 (R7);
  • If-Match handling: 428, 409 and 200 for no-op saves;
  • the 422 body shape (R6), and R48 validated;
  • redaction and the digest stored as sent (R55);
  • the instance cap (R37), heartbeat R11/R45, and pagination (R49).
• Local runs: go build, go vet, go test ./... and go mod verify are clean. -tags integration passes for handler, agentcfg, authz and worker on testcontainers Postgres.
• gofmt: it only flags internal/authz/cedar_test.go, which is already on main and not touched here.

GitHub Actions has not run on this PR (only CodeRabbit, which skipped it). The bot-authored run probably needs approval before merge.

[gusfcarvalho]

Blocking: R58 (extends bypass) and R59 (file-origin errors block saves); see threads

[ccf-lisa]

Review pass (aa005f7) addressed R58, R59, R57 and the D18 audit. API change for the UI LLD (R59): preview instances[].warnings (always []) and 422 errors.instances[].warnings now carry validation errors that already exist in the instance's own file (Merge(base, {})). They are non-blocking. instances[].errors now holds only errors the overlay introduces, and only those force invalid-config. R58: a configure-policy-only save gets 403 when it adds or changes policy_bundles.*.extends to a source the validation bases don't already use, unless the change is the R22 swap at the same index. The UI's client-side policy-only check should mirror this rule.

[gusfcarvalho]

Re-reviewed 52e315b..aa005f7. R58 and R59 are implemented correctly, so this approval supersedes my CHANGES_REQUESTED review.

• R58: extendsChangeAllowed runs for every base, including diffs that touch only /policy_bundles. A new or changed extends must be in usedSources(base) or be the source replaced by an accepted R22 swap at the same index; removing or keeping extends is still allowed, and with no bases only the swap can add one. The unit tests cover each of these cases, and the Cedar policy-author tests check that an unknown extends gets 403 and an already-used source gets 201.
• R59: splitIntroduced compares errors against Merge(base, {}) on (Path, Code, Message). Only errors the overlay introduces block a save or force invalid-config; file-origin errors are returned as warnings, never null. The integration test confirms a base with a bad cron still accepts {"verbosity":1} with 201, and preview shows the warning with will-apply: true.
• R57 docs and swagger, the D18 denial audit record, and the policy-author revert test all look good.
• Local verification: build, vet and unit tests are green. With -tags integration, the handler, agentcfg, authz and worker suites pass. gofmt flags only internal/authz/cedar_test.go, which is already like that on main.

GitHub Actions still hasn't run on this bot-authored PR, so the workflow needs approval before merge.

[ccf-lisa]

PR approved. Marking ready for e2e.

[gusfcarvalho]

Re-approving at 9a512a6, the merge of main (#464, evaluation artifacts). The conflict resolutions are correct, and CI is green.

• Conflicts (.env.example, cmd/root.go, internal/config/config.go, api.go imports): both sides were kept.
• sdk/client.go: both clients are kept, with our stricter header loop. It still drops a caller's Authorization and canonicalizes via Del/Add; Artifact.Upload's Content-Type override still works.
• Swagger: regenerated. It adds exactly #464's artifact paths and definitions.
• Non-conflicted files from main are byte-identical to 181097e.
• Semantics:
  • the manifest adds artifact alongside policy-author and agent sync;
  • the builtin PDP's agent-resource special case doesn't touch artifact;
  • migrator Up/Down ordering is consistent;
  • the new Cedar cases check that policy-author can read artifacts but not ingest them.
• Local: build, vet and unit tests are green. With -tags integration, handler, agentcfg, authz and worker pass.
• CI: check-diff, lint, unit-tests and integration-tests all pass.

[ccf-lisa]

Round 2: e2e feedback (design §13: R62, R63, R72)

New commits on top of 9a512a6 (main has not moved, so no merge was needed):

Commit	What
bc4f6db	refactor: share risk template rules in pkg/risktemplate
4b799b7	feat: policy contract checker (R63)
29d926e	feat: policy bundle file routes and report artifact digests (R62)
e8d1883	docs: artifact file routes, report artifact digests and artifact:read scope (R72)
491f415, b6609f7, 6c801a3	self-review passes 1 to 3

R62: vendor sources through the artifact store

• agentconfig.PolicyBundleReport and PolicyExtendsReport gain artifact-digest (omitempty). PUT /api/agent/instances/{id}/config-report checks only its format (artifact.ValidDigest) and returns 400 if it is malformed. It does not check that the artifact exists. Agents keep the field when they drop files to fit the report.
• GET /api/artifacts/{digest}/files returns {digest, treeDigest, files[{path, sha256, size, package?}]}.
  • treeDigest is agentconfig.BundleTreeDigest over the files, so a config report's digest for the same tree matches it.
  • sha256 is plain hex, the same as PolicyFileReport.
  • package comes from the OPA AST: Rego v1 is tried first, then v0.
• GET /api/artifacts/{digest}/files/{path} returns {path, package?, sha256, source}. Files over 1 MiB, or that are not UTF-8, get 422. A / in the path may be escaped as %2F.
• Both routes are on the existing artifact read group (same middleware and artifact:read guard). They return:
  • 400 for a malformed digest;
  • 404 for an unknown digest or path;
  • 415 for a non-bundle media type.
• Responses are immutable: Cache-Control: private, max-age=31536000, immutable. The ETag is the digest of the response body, and If-None-Match gets 304.
• internal/artifact gains WalkBundleTar / ReadBundleFiles (next to ReadBundleTar) and ModulePackage.

R63: policy contract checker (pkg/policyeval/contract.go)

• CheckContract(map[string]*ast.Module) []Issue is the static layer.
  • Errors:
    • a missing title;
    • a contract key defined as a function or with contains;
    • a literal type mismatch in title, description, remarks, skip_reason, labels or risk_templates;
    • violation[k] := v, or a complete violation that is not a collection;
    • a literal violation that is not an object, or that has a non-string id, title, description or remarks;
    • a risk template the API would reject: required name, title and statement, hint enums, threat refs, dedupe_label_keys ⊆ label_schema, template label keys, duplicate names.
  • Warnings:
    • an empty or conditional-only title;
    • no violation rule;
    • a violation without an id;
    • violation_ids that no literal violation produces (matched trimmed and case-insensitively, like the API);
    • more than one non-test module per package.
• ValidateResult(Result) []Issue is the dynamic layer. Execute stores its result in the new Result.Issues field, and its error semantics are unchanged.
• Issue is {file, row, col, package, severity, code, message}.
• regocheck runs the static layer on the authored overlay modules.
  • Type and shape problems are errors and block the save (R54).
  • A missing title is a warning, not an error, when vendor or file modules could complete the package. That covers a bundle that extends a source, a patch of a bundle that a validation base's file defines (regocheck.WithPartialBundles), or a bundle with a module that does not parse.
  • PolicyError gains code (omitempty).
• Playback returns the static issues as top-level issues and the dynamic ones as results[].issues. Neither fails the request.
• The risk template service's limits, hint vocabulary and template label-key rule moved to the dependency-free pkg/risktemplate, which the service now uses. A parity test pins the hint rule to the service's own check.

R72: docs

• docs/artifacts.md covers:
  • the new routes;
  • config reports that reference artifacts;
  • who can read artifacts: artifact:read is held by every role, including ssp-subscriber, so inline Rego is readable beyond agent:read. This is documented, not narrowed.
• The same note is in the manifest roles comment next to R40/R57 and in docs/authz-oss-cedar.md.
• The stale evidence-v3 G1.1 comment in pkg/agentconfig/digest.go is fixed.

Deviations (also in the lisa-design git note)

• The listing field is treeDigest (design §13 and the artifact API's camelCase), not tree-digest.
• No violation rule is a warning everywhere, as in the R63 table. Only a missing title becomes an error, and only for self-contained authored bundles.
• risk_templates as a set, or defined with contains, is an error (R63), even though OPA would return it as an array.

Verification

• go build, go vet (with and without -tags integration) and go test ./... pass.
• go test -tags integration ./internal/api/handler/... ./pkg/... ./internal/artifact/... passes.
• golangci-lint reports 0 issues; make swag and go mod tidy leave no diff.

For agent#95 and ui#318

regocheck.ValidatePolicyBundles now includes the contract layer. Agents that bump the pin get the static R63 check in prepareInline without calling CheckContract again on the same modules.

[gusfcarvalho]

Approving the §13 round, 9a512a6..6c801a3. I found nothing blocking.

• File routes (R62):
  • {path} is only compared, by exact equality, against the stored canonical tar's entry names; nothing touches the filesystem. So .. and %2F can't escape, and an unescaped path that doesn't match gets 404.
  • The routes use the existing artifact:read guard, and the digest is format-checked.
  • A single file over 1 MiB, or one that isn't valid UTF-8, gets 422. Listings carry no file contents, and the whole artifact is already capped by CCF_ARTIFACT_MAX_BYTES.
  • ETags are immutable. The broader artifact:read scope is documented as R72.
• Contract checker (R63):
  • It mirrors Execute's package selection (compliance_framework.*, non-test modules).
  • Computed values are left to the dynamic check, and it handles v0 violation[x] {} as well as v1 contains/[x] if.
  • I ran a v0/v1 vendor-style probe: sprintf/concat values, comprehension-built ids, a default+conditional title, and a ccf_libs helper. It produced no false issues.
  • Severities follow §13. missing-title is downgraded to a warning for extends bundles, patched file bundles, and bundles with a module that doesn't parse.
  • ValidateResult only fills Result.Issues, so Execute's errors are unchanged.
• pkg/risktemplate: a behaviour-preserving extraction. The limits, hint rule and template label-key walk are the same, and a parity test pins the hint rule.
• Recorded deviations, all fine:
  • (a) treeDigest is the name R62 itself specifies;
  • (b) and (c) match the R63 table;
  • (d) is conservative, because standalone mode can't know which bundles the agent's file defines;
  • (e) no SDK consumer needs the file routes.
• Verification:
  • Locally with GOWORK=off: build, vet and unit tests are green. With -tags integration, internal/api/handler/..., pkg/... and internal/artifact/... pass.
  • CI on 6c801a3: check-diff, lint, unit-tests and integration-tests all pass.

[ccf-lisa]

This PR is now split into a GitHub stack (stack #484) of 15 PRs, each at most ~1000 changed lines (without docs/go.sum). The top layer's tree is identical to this branch at 6b970f0, including the fixes for Ian's findings.

1. feat(agentconfig): config model and RFC 7396 overlay merge (1/15) #469 agentconfig: config model and overlay merge (852)
2. feat(agentconfig): JSON diff, env references, plugin sources and ETags (2/15) #470 agentconfig: diff, env refs, sources, ETags (862)
3. feat(agentconfig): change-safety classification and wire types (3/15) #471 agentconfig: change classification (934)
4. feat(agentconfig): secret detection, redaction and digests (4/15) #472 agentconfig: secret detection and redaction (1100, size-exception)
5. feat(agentconfig): overlay validation (5/15) #473 agentconfig: overlay validation (921)
6. feat(sdk): agent config client (6/15) #474 sdk: agent config client (557)
7. feat(agentcfg): append-only agent config revision store (7/15) #475 agentcfg: revision store (772)
8. feat(agentcfg): agent instance store (8/15) #476 agentcfg: instance store (986)
9. feat(agentcfg): validation bases, instance pruning and agent deletion (9/15) #477 agentcfg: validation bases, pruning, agent deletion (649)
10. feat(authz): agent configure/sync actions and per-route agent guards (10/15) #478 authz: configure/sync actions, agent route guards (279)
11. feat(api): agent-facing config overlay route and heartbeat instance registration (11/15) #479 api: agent GET config + heartbeat registration (490)
12. feat(api): agent instance config reports (12/15) #480 api: agent config reports (1089, size-exception)
13. feat(api): admin agent config read and save (13/15) #481 api: admin config read/save (1180, size-exception)
14. feat(api): admin agent config preview, revision history and revert (14/15) #482 api: admin preview, revisions, revert (655)
15. feat(api): admin agent instances, CORS and authz coverage (15/15) #483 api: admin instances, CORS, authz coverage (468)

I'm leaving this PR open for its review history; close it once the stack is reviewed.