Agentic Telemetry Contract

What this adds. SecurityRecipes now treats telemetry as part of the secure context layer. Agent and MCP traces are useful only when they are complete enough to reconstruct a run and safe enough not to become a new secret, prompt, or tenant-data sink.

Rechecked source anchors against the public MCP specification 2026-07-28 on October 9, 2026. Rechecked the same day against MCP Security Best Practices State Handle Hijacking and OpenTelemetry MCP semantic conventions: MCP 2026-07-28 is stateless and has no protocol-level sessions. OpenTelemetry recommends mcp.session.id only when a request is part of a session. This pack now allows telemetry_ready for 2026-07-28 tool spans that carry jsonrpc.request.id, mcp.method.name, and mcp.protocol.version without mcp.session.id. A 2025-11-25 span still requires mcp.session.id so stored receipts stay evaluable. A present traceparent that is not valid W3C Trace Context is held. A present session id is host-session correlation, not authentication. Unspecified protocol-version evidence stays on the prior required-session path. This change does not claim human review of the pack; lastmod and the source last_reviewed date record this editorial pass.

Agentic AI security is moving from “did the model answer correctly?” to “can we prove what context, tool, identity, policy, approval, egress decision, verifier, and incident signal shaped the run?” The Agentic Telemetry Contract turns that into a generated artifact that a platform team can hand to observability, SIEM, MCP gateway, GRC, and trust review diligence reviewers.

Generated artifact

  • Profile: data/assurance/agentic-telemetry-contract-profile.json
  • Generator: scripts/generate_agentic_telemetry_contract.py
  • Runtime evaluator: scripts/evaluate_agentic_telemetry_event.py
  • Evidence pack: data/evidence/agentic-telemetry-contract.json
  • MCP tools: recipes_agentic_telemetry_contract, paired with recipes_playbook_plan using playbook id agentic-telemetry-contract.

Regenerate and validate:

python3 scripts/generate_agentic_telemetry_contract.py
python3 scripts/generate_agentic_telemetry_contract.py --check

Evaluate one telemetry event:

python3 scripts/evaluate_agentic_telemetry_event.py \
  --workflow-id vulnerable-dependency-remediation \
  --event-class mcp.tools.call \
  --attribute service.name=security-recipes-mcp \
  --attribute deployment.environment=production \
  --attribute trace_id=trace-ci \
  --attribute span_id=span-ci \
  --attribute workflow_id=vulnerable-dependency-remediation \
  --attribute run_id=run-ci \
  --attribute agent_id=sr-agent::vulnerable-dependency-remediation::codex \
  --attribute identity_id=sr-agent::vulnerable-dependency-remediation::codex \
  --attribute correlation_id=ci-correlation \
  --attribute receipt_id=sr-run-receipt::vulnerable-dependency-remediation \
  --attribute telemetry.redaction_state=metadata_only \
  --attribute gen_ai.operation.name=execute_tool \
  --attribute gen_ai.tool.name=repo.contents.patch \
  --attribute mcp.protocol.version=2026-07-28 \
  --attribute mcp.method.name=tools/call \
  --attribute jsonrpc.request.id=req-ci \
  --attribute network.transport=tcp \
  --attribute policy.decision=allow \
  --attribute authorization.decision=allow_authorized_mcp_request \
  --expect-decision telemetry_ready

Workflow at a glance

Agentic Telemetry Contract workflow

Define privacy-preserving event schemas, correlation, retention, and delivery requirements for agent decisions and side effects.

agent-assurance

  1. Signal

    Identify required signals

    Select identity, context, policy, approval, tool, action, handoff, memory, egress, request identity, review, and outcome events. For MCP 2026-07-28, request identity is jsonrpc.request.id, mcp.method.name, and mcp.protocol.version rather than a protocol session id.

  2. Scope

    Define the event contract

    Specify fields, types, reason codes, timestamps, correlation IDs, tenant boundaries, severity, and source evidence.

  3. Decision

    Apply data minimization

    Remove raw prompts, secrets, source code, customer content, and unnecessary arguments; define redaction and retention. Do not mint mcp.session.id for MCP 2026-07-28 spans. Treat a present session id as host-session correlation, not authentication, and hold a present traceparent that is not valid W3C Trace Context.

  4. Action

    Validate event delivery

    Check schema, ordering, duplication, clocks, transport, failure handling, access, storage, and downstream compatibility.

  5. Proof

    Prove operational use

    Connect validated events to receipts, SOC detections, metrics, incident response, audits, and customer proof.

Decision gate

Is the event valid, correlated, privacy-safe, attributable, and deliverable to its approved consumers?

Proceed

Accept and route the minimized event under retention policy.

Hold or stop

Reject or quarantine malformed, uncorrelated, sensitive, cross-tenant, or untrusted events.

Evidence to retain

  • versioned telemetry schema
  • redaction/retention policy
  • delivery and consumer validation

Expected outputs

  • telemetry contract
  • validated event record
  • instrumentation gap list

Hold a 2025-11-25 tool span that omits mcp.session.id:

python3 scripts/evaluate_agentic_telemetry_event.py \
  --workflow-id vulnerable-dependency-remediation \
  --event-class mcp.tools.call \
  --attribute service.name=security-recipes-mcp \
  --attribute deployment.environment=production \
  --attribute trace_id=trace-ci \
  --attribute span_id=span-ci \
  --attribute workflow_id=vulnerable-dependency-remediation \
  --attribute run_id=run-legacy \
  --attribute agent_id=sr-agent::vulnerable-dependency-remediation::codex \
  --attribute identity_id=sr-agent::vulnerable-dependency-remediation::codex \
  --attribute correlation_id=ci-correlation \
  --attribute receipt_id=sr-run-receipt::vulnerable-dependency-remediation \
  --attribute telemetry.redaction_state=metadata_only \
  --attribute gen_ai.operation.name=execute_tool \
  --attribute gen_ai.tool.name=repo.contents.patch \
  --attribute mcp.protocol.version=2025-11-25 \
  --attribute mcp.method.name=tools/call \
  --attribute jsonrpc.request.id=req-legacy \
  --attribute network.transport=tcp \
  --attribute policy.decision=allow \
  --attribute authorization.decision=allow_authorized_mcp_request \
  --expect-decision hold_for_trace_completion

Hold a current-spec span whose traceparent is not valid W3C Trace Context:

python3 scripts/evaluate_agentic_telemetry_event.py \
  --workflow-id vulnerable-dependency-remediation \
  --event-class mcp.tools.call \
  --attribute service.name=security-recipes-mcp \
  --attribute deployment.environment=production \
  --attribute trace_id=trace-ci \
  --attribute span_id=span-ci \
  --attribute workflow_id=vulnerable-dependency-remediation \
  --attribute run_id=run-traceparent \
  --attribute agent_id=sr-agent::vulnerable-dependency-remediation::codex \
  --attribute identity_id=sr-agent::vulnerable-dependency-remediation::codex \
  --attribute correlation_id=ci-correlation \
  --attribute receipt_id=sr-run-receipt::vulnerable-dependency-remediation \
  --attribute telemetry.redaction_state=metadata_only \
  --attribute gen_ai.operation.name=execute_tool \
  --attribute gen_ai.tool.name=repo.contents.patch \
  --attribute mcp.protocol.version=2026-07-28 \
  --attribute mcp.method.name=tools/call \
  --attribute jsonrpc.request.id=req-traceparent \
  --attribute network.transport=tcp \
  --attribute policy.decision=allow \
  --attribute authorization.decision=allow_authorized_mcp_request \
  --attribute traceparent=not-a-traceparent \
  --expect-decision hold_for_trace_completion

Signal classes

Signal What must be reconstructable
Agent session Workflow, run, agent, identity, tenant, correlation, and receipt linkage.
Model call Provider/model operation and redaction state without raw prompt capture by default.
MCP tool call JSON-RPC request id, method, protocol, transport, tool, policy, and authorization evidence. Session id is required for 2025-11-25 receipts and optional host-session correlation on 2026-07-28.
Context retrieval Source ids, source hashes, package hash, poisoning scan state, and retrieval decision.
Policy decision Policy pack hash, rule, gate phase, MCP namespace, access mode, and decision.
Egress decision Destination class, data class, policy hash, tenant, and allow/hold/deny/kill result.
Human approval Approval system, actor, decision, expiry, and risk acceptance linkage.
Verifier result Test, eval, scanner, or red-team result linked to receipt and artifact hash.
Incident signal Incident class, severity, containment, replay case, and correlation evidence.

Enterprise default

The default state is untrusted_until_required_trace_fields_present. Raw prompt text, model outputs, tool arguments, tool results, MCP resource URIs, and HTTP bodies are opt-in only. Credentials, bearer tokens, private keys, seed phrases, unredacted PII, customer secrets, and cross-tenant context force a kill_session_on_secret_telemetry decision.

This makes AI easier for enterprises because platform teams do not have to choose between blind agents and unsafe logging. They get a small contract: emit metadata, hashes, policy decisions, and receipt links by default; capture content only with explicit redaction and retention controls.

Source anchors

See also