Repository navigation
Promote integration to main - #350
Merged
Merged
Conversation
Align §3’s envelope description with the existing request and response schemas and the common envelope example in `hooks.md`. Closes #194 Signed-off-by: aaronormerod <137795541+aaronormerod@users.noreply.github.com> Reviewed-by: Lrd0036 <lrd0036@auburn.edu>
Part of #252 Signed-off-by: Evgeny Kokuykin <artmaro@gmail.com> Signed-off-by: rocklambros <rock@rockcyber.com>
Closes #37 Signed-off-by: Bar Kaduri <bar@capsule.security> Signed-off-by: rocklambros <rock@rockcyber.com>
Closes #93 Signed-off-by: Mayur Agnihotri <mayur.agnihotri0021@gmail.com> Signed-off-by: rocklambros <rock@rockcyber.com>
…oes (#323) The ACS-Trace section, the Trace events page, and handshake.json all require Trace events under at least one of OTel or OCSF for every supported step. The quick-reference row was the one place that said both, since the v0.1.0 integration in f46d260. The row now matches the profile and names its other two requirements, decisions as events and provenance carried forward. Signed-off-by: rocklambros <rock@rockcyber.com>
…never under its claimed ids (#309) ## What changed PR #273 adds a rule to Trace Events: a Guardian MUST NOT emit `acs.decision` or `acs.decision.failure` under the pair of a request it rejects before trusting it. Our reference Guardian broke that rule. An envelope that failed the schema, carrying a forged `request_id`, got an `acs.decision` span under that `request_id`. This fixes the reference Guardian, following @bar-capsule's ruling on issue #283: keep the rejected request visible, under separate names, never under the genuine request's ids. - **Rejected requests get their own span.** A request the Guardian can't vouch for becomes a `guardian.rejected_request` span. It carries no `acs.session.id`, `acs.request_id`, step attribute, or `acs.decision` event. The ids it claimed go under `guardian.rejected.claimed_session_id` and `guardian.rejected.claimed_request_id`, with `guardian.rejected.reason` and the error code. - **What counts as rejected:** an envelope that fails validation, a request the Guardian couldn't check at all (`guardian_fault`, which still records its `guardian_error`), and a step answered with `SIGNATURE_INVALID`, `REPLAY_DETECTED` or `TIMESTAMP_OUT_OF_WINDOW`. - **The pair is added last.** A trusted step's pair and step attributes go on only when its span ends. `dispatch` now returns its trust verdict next to the response. So a check that runs after the span opens can't leak a rejected request's ids onto a step span, whether it answers with an error or with a deny. That's where PR #229's checks will run. - **Sample trace:** it now includes a forged request that reuses the allowed call's ids. A test checks that the allowed call keeps the only span under its pair. - **Docs:** the READMEs and `extend_opentelemetry.md` say what a rejected span carries. The known limits say plainly that this Guardian checks nothing but the schema yet, so a well-formed forgery or replay is still recorded as a step until PR #229 lands. @sabasiddique1, this implements item 6 of issue #283, so you can skip that item. Items 1 to 5 and 7 are still yours. **Merge order:** this is safe to merge before PR #273. Before that rule exists, the only effect is that a rejected request moves off the step spans. Please don't promote it to `main` without PR #273, or the other way round. ## Which issue does this implement Part of #283 Refs #37 - [ ] This is an editorial correction (typo, grammar, link, formatting) with no change in meaning, so it needs no issue ## Base branch - [x] `integration`, because this touches the specification, schemas, a reference implementation, an adapter, tests, or CI - [ ] `main`, because every changed path is on the documentation lane allowlist in CONTRIBUTING.md ## Type of change - [ ] Specification change (schema, hooks, events, AgBOM) - [x] Reference implementation or adapter - [x] Documentation - [ ] Tooling or CI - [ ] Governance (licensing, security policy, contributor docs) ## Specification changes No normative text changes. `docs/spec/trace/extend_opentelemetry.md` changes only where it describes what the reference Guardian exports. **Breaking for implementers?** No ACS change. Anyone reading the reference Guardian's trace sees a schema-invalid envelope as a `guardian.rejected_request` span. Before, it was a `gen_ai.tool.call` with an `envelope_invalid` deny. ## I tested this - [x] I synced my branch with the base branch before opening this - [x] `uv run pytest -v` passes on my machine - [x] `uv run mkdocs build --strict` passes on my machine From `reference-implementations/agt/`, `bun run typecheck` is clean and `bun test` passes (1245). I checked the new tests by breaking each behavior on purpose. With trust always true, a late rejection ignored, the pair attached early, `dispatch`'s verdict dropped, the fault event removed, or the arrival time ignored, the matching tests fail. Before writing this I ran a six-perspective premortem and a code review, and their findings are fixed here. ## Checklist - [x] Commits are signed off with `git commit -s` (required by the DCO) - [x] Prose follows [STYLE.md](../STYLE.md) - [x] No secrets, tokens, or internal URLs in the diff ## Security - [ ] This change has no security impact Without this, anyone who can reach the Guardian's port could write a decision into the trace under a live session's ids by sending a malformed envelope with those ids. A reader joining the Guardian's and the host's streams by pair would then see a step that never happened. A well-formed forgery or replay still gets through until PR #229 adds signature, replay and timestamp checks. The README says so. Signed-off-by: rocklambros <rock@rockcyber.com>
bar-capsule
requested review from
GangGreenTemperTatum,
Lrd0036,
afogel,
almogbhl,
artmaro,
fewdisc,
mamicidal,
rocklambros,
sclintonowasp and
stefanoamorelli
as code owners
October 28, 2026 11:54
Open
acs-board-reconciler
Bot
moved this from Needs triage
to In progress
in ACS Project Tracker
rocklambros
approved these changes
Oct 29, 2026
rocklambros
left a comment
rocklambros
left a comment
Collaborator
There was a problem hiding this comment.
Seven commits match the body, checks are green, version stays 0.1.4. Merging with a merge commit.
github-project-automation
Bot
moved this from In progress
to Done
in ACS Project Tracker
This branch was successfully deployed
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
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.
7 commit(s) ahead. Merging publishes the site and every schema $id URI. Merge with a merge commit, not a squash: squashing flattens the specification history that makes a schema change reviewable later.
What this ships
This is not a release.
version.txtstays 0.1.4, so no tag is created. Schema changes publish in place at the/schema/v0.1.0/URIs.key_idas a configured label with no default, and a record for an unresolvedrequest_id_ref(PR Fix the HMAC key derivation, define key_id, and record an unresolved request_id_ref #272, issue [Proposal] Clarify request_id_ref semantics and ACS-Core HKDF parameters #118);sessionEnd.summary.decision_failures, and no event under the pair of a request rejected before it is trusted (PR Record every decision failure and count them at session end #273, issue [Bug] §6.4's mandatory fail-open audit event has no conformant shape, so the decision-failure rate is unmeasurable #37);acs_versionlocation in §3 (PR Fix acs_version location in section 3 #254, issue [Bug] §3 says acs_version is top-level; the request envelope schema and hooks.md put it in params #194);reference-implementations/README.md(PR Align expectations for Guardian reference implementations (#252) #256);#273 and #309 go out together, as #309 asks.
For implementers
session-end.jsongains one optional field, so the schema change is additive. Two rules tighten:key_idcomes from configuration, and a verifier rejects one it does not know (Fix the HMAC key derivation, define key_id, and record an unresolved request_id_ref #272).Roadmap
Merging delivers #37, #93, #118 and #194, which the health issue (#209) lists as not on main.