Skip to content

Commit a968a6e

Browse files
Degrade inferred OpenAPI action_id collisions instead of crashing the scan (#226)
A valid third-party OpenAPI spec (block/goose) crashed `agents-shipgate scan` with `exit 2 / Config error: Duplicate action_surface action_id`. The OpenAPI action_id is derived from METHOD + normalized path only — the operationId is dropped — so two distinct operations whose paths normalize identically (goose ships `GET /sessions/{session_id}` plus a trailing-slash variant, each with its own operationId) collapse to one action_id and hard-fail the duplicate-id guard. Make this fail-soft, matching the symlink-loop (#212) and MCP-as-tools (#214) precedent: a third-party spec must never crash a scan. - build_action_surface_facts takes an optional `warnings` sink. On the live scan path, collisions between purely INFERRED ids (e.g. OpenAPI method+path normalization) are disambiguated deterministically (first operation by tool_name keeps the bare id, the rest gain a `#<operationId>` suffix, ordinal fallback on ties), the identity_hash is refreshed, and one warning is recorded per collision. - A collision that touches a manifest-authored action identity stays a hard ConfigError on both paths — a declared id is a contract, never silently rewritten. "Manifest-authored" means any action_surface declaration that sets an explicit action_id component: `id`, `provider`, or `operation` (all three feed build_action / _provider / _operation). Without a sink the legacy ConfigError is preserved for all collisions, so the redaction path's public-only ordinal disambiguator is untouched. - Thread the warnings from Phase 5 into report.source_warnings (appended last, so byte-stable for the common no-collision case). A source_warning routes the release to review_required rather than crashing. - Add network-free regression tests: inferred OpenAPI collisions degrade; explicit collisions via `id` and via `provider`/`operation` still raise on both the no-sink and warnings-sink paths; plus a full run_scan integration test on the goose-shaped fixture.
1 parent 8f68737 commit a968a6e

6 files changed

Lines changed: 333 additions & 3 deletions

File tree

‎src/agents_shipgate/cli/scan/decision.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,10 +58,12 @@ def _run_checks_and_decide(
5858
derived from sanitized tools. Mutating ``reason`` here would leak
5959
``path:line`` into ``Finding.evidence``, churning fingerprints.
6060
"""
61+
action_surface_warnings: list[str] = []
6162
action_surface_facts = build_action_surface_facts(
6263
manifest,
6364
agent_id=tools_and_agent.agent.id,
6465
tools=tools_and_agent.tools,
66+
warnings=action_surface_warnings,
6567
)
6668
capability_facts, capability_policy_subjects = build_capability_policy_subjects(
6769
manifest,
@@ -167,6 +169,7 @@ def _run_checks_and_decide(
167169
return _ChecksDecision(
168170
action_surface_facts=action_surface_facts,
169171
action_surface_diff=action_surface_diff,
172+
action_surface_warnings=action_surface_warnings,
170173
findings=findings,
171174
legacy_fingerprints=legacy_fingerprints,
172175
override_resolution=override_resolution,

‎src/agents_shipgate/cli/scan/models.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,11 @@ class _ChecksDecision:
103103

104104
action_surface_facts: ActionSurfaceFacts
105105
action_surface_diff: Any # ActionSurfaceDiff (internal/semantic)
106+
# Fail-soft warnings raised while building the action surface (e.g.
107+
# duplicate action_id collisions from OpenAPI specs whose paths
108+
# normalize identically). Merged into ``report.source_warnings`` so a
109+
# third-party spec degrades to review_required instead of crashing.
110+
action_surface_warnings: list[str]
106111
findings: list[Any] # list[Finding]
107112
legacy_fingerprints: list[str]
108113
override_resolution: Any # SeverityOverrideResolution

‎src/agents_shipgate/cli/scan/sanitization.py‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,17 @@ def _sanitize_for_output(
162162
stats=privacy_stats,
163163
path="source_warnings[]",
164164
)
165+
# Fail-soft action-surface warnings (e.g. OpenAPI action_id collisions)
166+
# are raised in Phase 5, after the Phase 3 source-warning list is
167+
# assembled. Append them last so byte-stable output is preserved for
168+
# the common (no-collision) case where this list is empty.
169+
public_source_warnings.extend(
170+
redact_data(
171+
decision.action_surface_warnings,
172+
stats=privacy_stats,
173+
path="source_warnings[]",
174+
)
175+
)
165176
public_api_surface = redact_data(
166177
public_api_artifacts.surface_summary() if public_api_artifacts else None,
167178
stats=privacy_stats,

‎src/agents_shipgate/core/lenses/action_surface.py‎

Lines changed: 111 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,23 @@ def build_action_surface_facts(
9292
*,
9393
agent_id: str,
9494
tools: list[Tool],
95+
warnings: list[str] | None = None,
9596
) -> ActionSurfaceFacts:
97+
"""Build the typed action surface from ``tools`` + manifest declarations.
98+
99+
Two distinct operations can derive the same ``action_id`` — most
100+
commonly two OpenAPI operations whose paths normalize identically
101+
(e.g. a trailing-slash variant of ``/sessions/{session_id}``), because
102+
the OpenAPI ``operation`` token is ``METHOD path`` only and drops the
103+
``operationId``. A third-party spec must never crash a scan, so when a
104+
``warnings`` sink is provided the colliding ids are disambiguated
105+
fail-soft and one ``source_warning`` is recorded per collision (same
106+
fail-soft principle as the symlink-loop and MCP-as-tools fixes).
107+
108+
Callers that cannot tolerate a fail-soft snapshot (the redaction path,
109+
which has its own public-only ordinal disambiguator) pass no sink and
110+
keep the legacy hard :class:`ConfigError`.
111+
"""
96112
declarations = {entry.tool: entry for entry in manifest.action_surface.actions}
97113
actions = [
98114
_action_from_tool(
@@ -103,7 +119,26 @@ def build_action_surface_facts(
103119
)
104120
for tool in sorted(tools, key=lambda item: item.name)
105121
]
106-
_validate_unique_action_ids(actions)
122+
if warnings is None:
123+
_validate_unique_action_ids(actions)
124+
else:
125+
# Tools whose action_id carries a manifest-authored component. A
126+
# collision touching one of these stays a hard ConfigError even on
127+
# the fail-soft path — only inferred-vs-inferred collisions degrade.
128+
# `id`, `provider`, and `operation` all override action_id
129+
# components (see `build_action` / `_provider` / `_operation`), so a
130+
# declaration setting any of them is an explicit identity the engine
131+
# must never silently rewrite.
132+
explicit_tool_names = {
133+
entry.tool
134+
for entry in manifest.action_surface.actions
135+
if entry.id or entry.provider or entry.operation
136+
}
137+
warnings.extend(
138+
_disambiguate_duplicate_action_ids(
139+
actions, explicit_tool_names=explicit_tool_names
140+
)
141+
)
107142
return ActionSurfaceFacts(actions=sorted(actions, key=lambda item: item.action_id))
108143

109144

@@ -547,8 +582,11 @@ def _validate_unique_action_ids(actions: list[ActionFact]) -> None:
547582
for action_id, tool_names in by_id.items()
548583
if len(tool_names) > 1
549584
}
550-
if not duplicates:
551-
return
585+
if duplicates:
586+
_raise_duplicate_action_ids(duplicates)
587+
588+
589+
def _raise_duplicate_action_ids(duplicates: dict[str, list[str]]) -> None:
552590
details = "; ".join(
553591
f"{action_id!r} used by {', '.join(tool_names)}"
554592
for action_id, tool_names in sorted(duplicates.items())
@@ -560,6 +598,76 @@ def _validate_unique_action_ids(actions: list[ActionFact]) -> None:
560598
)
561599

562600

601+
def _disambiguate_duplicate_action_ids(
602+
actions: list[ActionFact],
603+
*,
604+
explicit_tool_names: set[str],
605+
) -> list[str]:
606+
"""Fail-soft replacement for :func:`_validate_unique_action_ids`,
607+
scoped to *inferred* collisions only.
608+
609+
A manifest-authored action identity — any ``action_surface.actions[]``
610+
declaration setting ``id``, ``provider``, or ``operation`` — is a
611+
contract: a collision that involves one (explicit-vs-explicit or
612+
explicit-vs-inferred) is a config mistake to fix, so it stays a hard
613+
:class:`ConfigError` (identical to the no-sink path).
614+
``explicit_tool_names`` names the tools carrying such a declaration.
615+
616+
Only collisions between purely *inferred* ids degrade — most commonly
617+
two OpenAPI operations whose paths normalize identically. Those are
618+
mutated in place so each ``action_id`` is unique, returning one
619+
human-readable warning per resolved collision. The first member of each
620+
colliding group (in ``tool_name`` order) keeps the bare id; the rest
621+
gain a ``#<operationId>`` suffix so distinct operations stay distinct in
622+
the diff. An ordinal fallback covers the pathological case where two
623+
colliding actions also share a ``tool_name``. Renamed actions get a
624+
refreshed ``identity_hash`` so downstream identity-hash consumers stay
625+
consistent.
626+
"""
627+
by_id: dict[str, list[ActionFact]] = {}
628+
for action in actions:
629+
by_id.setdefault(action.action_id, []).append(action)
630+
colliding = {
631+
action_id: group for action_id, group in by_id.items() if len(group) > 1
632+
}
633+
634+
# Hard-fail any collision that touches an explicitly declared id. These
635+
# are not third-party quirks the engine should silently rewrite.
636+
explicit_collisions = {
637+
action_id: sorted(item.tool_name for item in group)
638+
for action_id, group in colliding.items()
639+
if any(item.tool_name in explicit_tool_names for item in group)
640+
}
641+
if explicit_collisions:
642+
_raise_duplicate_action_ids(explicit_collisions)
643+
644+
warnings: list[str] = []
645+
for action_id, group in sorted(colliding.items()):
646+
ordered = sorted(group, key=lambda item: item.tool_name)
647+
warnings.append(
648+
"Duplicate action_surface action_id "
649+
f"{action_id!r} derived from operations "
650+
f"{', '.join(repr(item.tool_name) for item in ordered)}; "
651+
"disambiguated with per-operation suffixes so distinct "
652+
"operations are not collapsed."
653+
)
654+
used_suffixes: dict[str, int] = {}
655+
for index, action in enumerate(ordered):
656+
if index == 0:
657+
continue
658+
suffix = action.tool_name or str(index)
659+
seen = used_suffixes.get(suffix, 0) + 1
660+
used_suffixes[suffix] = seen
661+
if seen > 1:
662+
suffix = f"{suffix}#{seen}"
663+
new_id = f"{action_id}#{suffix}"
664+
action.action_id = new_id
665+
action.hashes = action.hashes.model_copy(
666+
update={"identity_hash": _stable_hash(new_id)}
667+
)
668+
return warnings
669+
670+
563671
def _provider(tool: Tool, declaration: ActionDeclarationConfig | None) -> str:
564672
if declaration and declaration.provider:
565673
return _normalize_token(declaration.provider)

‎tests/test_action_surface_diff.py‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
from agents_shipgate.core.findings import assign_finding_ids
1414
from agents_shipgate.core.lenses.action_surface import (
1515
_dedupe_findings,
16+
_stable_hash,
1617
build_action_surface_facts,
1718
compute_action_surface_diff,
1819
enrich_action_surface_diff_with_source,
@@ -209,6 +210,11 @@ def test_action_surface_rejects_duplicate_tool_declarations():
209210

210211

211212
def test_action_surface_rejects_action_id_collisions():
213+
"""An explicit ``actions[].id`` colliding with another action's inferred
214+
id is a manifest config error and must stay a hard ConfigError — even on
215+
the fail-soft (warnings-sink) path the live scan uses. Only purely
216+
inferred collisions degrade; a user-declared id is never silently
217+
rewritten."""
212218
manifest = _manifest(
213219
{
214220
"action_surface": {
@@ -244,6 +250,109 @@ def test_action_surface_rejects_action_id_collisions():
244250
agent_id="agent:action-test/agent",
245251
tools=tools,
246252
)
253+
# The live scan path always passes a warnings sink; an explicit-vs-inferred
254+
# collision must NOT be silently disambiguated into review_required.
255+
with pytest.raises(ConfigError, match="Duplicate action_surface action_id"):
256+
build_action_surface_facts(
257+
manifest,
258+
agent_id="agent:action-test/agent",
259+
tools=tools,
260+
warnings=[],
261+
)
262+
263+
264+
def test_action_surface_rejects_collision_from_explicit_provider_operation():
265+
"""``provider``/``operation`` declarations override action_id components
266+
just like ``id`` does. A collision between two such manifest-authored
267+
identities must stay a hard ConfigError even on the warnings-sink path —
268+
not be silently rewritten to ``...:shared#beta``."""
269+
manifest = _manifest(
270+
{
271+
"action_surface": {
272+
"actions": [
273+
{"tool": "alpha", "provider": "tools", "operation": "shared"},
274+
{"tool": "beta", "provider": "tools", "operation": "shared"},
275+
]
276+
}
277+
}
278+
)
279+
tools = [
280+
Tool(
281+
id="tool:alpha",
282+
name="alpha",
283+
source_type="mcp",
284+
source_id="tools",
285+
extraction_confidence="high",
286+
),
287+
Tool(
288+
id="tool:beta",
289+
name="beta",
290+
source_type="mcp",
291+
source_id="tools",
292+
extraction_confidence="high",
293+
),
294+
]
295+
296+
for sink in (None, []):
297+
with pytest.raises(ConfigError, match="Duplicate action_surface action_id"):
298+
build_action_surface_facts(
299+
manifest,
300+
agent_id="agent:action-test/agent",
301+
tools=tools,
302+
warnings=sink,
303+
)
304+
305+
306+
def test_action_surface_disambiguates_openapi_action_id_collisions_fail_soft():
307+
"""Two OpenAPI operations whose paths normalize identically (a
308+
trailing-slash variant) collapse to one ``action_id``. With a warnings
309+
sink the scan degrades instead of raising: ids stay distinct and one
310+
warning is recorded. Real-world repro: block/goose's spec."""
311+
manifest = _manifest()
312+
tools = [
313+
Tool(
314+
id="tool:get_session",
315+
name="get_session",
316+
source_type="openapi",
317+
source_id="goose-api",
318+
annotations={"httpMethod": "get", "path": "/sessions/{session_id}"},
319+
extraction_confidence="high",
320+
),
321+
Tool(
322+
id="tool:get_session_detail",
323+
name="get_session_detail",
324+
source_type="openapi",
325+
source_id="goose-api",
326+
# Trailing slash normalizes to the same path as get_session.
327+
annotations={"httpMethod": "get", "path": "/sessions/{session_id}/"},
328+
extraction_confidence="high",
329+
),
330+
]
331+
332+
warnings: list[str] = []
333+
facts = build_action_surface_facts(
334+
manifest,
335+
agent_id="agent:action-test/agent",
336+
tools=tools,
337+
warnings=warnings,
338+
)
339+
340+
action_ids = [action.action_id for action in facts.actions]
341+
base_id = "agent:action-test/agent:openapi:goose-api:GET /sessions/{session_id}"
342+
# Both operations are retained as distinct actions; the first (in
343+
# tool-name order) keeps the bare id, the second is suffixed.
344+
assert action_ids == sorted([base_id, f"{base_id}#get_session_detail"])
345+
assert len(set(action_ids)) == 2
346+
assert {action.tool_name for action in facts.actions} == {
347+
"get_session",
348+
"get_session_detail",
349+
}
350+
# identity_hash tracks the renamed action_id.
351+
suffixed = next(a for a in facts.actions if a.action_id.endswith("#get_session_detail"))
352+
assert suffixed.hashes.identity_hash == _stable_hash(suffixed.action_id)
353+
assert len(warnings) == 1
354+
assert "Duplicate action_surface action_id" in warnings[0]
355+
assert "get_session" in warnings[0] and "get_session_detail" in warnings[0]
247356

248357

249358
def test_action_surface_policy_requires_typed_expected_values():

0 commit comments

Comments
 (0)