gen-ai: add security guardian (apply_guardrail) span + finding event

[nagkumar91]

Motivation

GenAI semantic conventions cover model, agent, and tool operations, but they don't provide a vendor-neutral way to observe security guardian/guardrail evaluations (allow/deny/modify decisions) and the specific security findings produced during those evaluations. This limits auditability, incident investigation, and cross-provider correlation for systems using guardrails across different vendors and frameworks.

What this PR adds

• Adds apply_guardrail to the gen_ai.operation.name enum for guardrail/guardian evaluations.
• Adds new attributes under gen_ai.guardian.* and gen_ai.security.* to describe:
  • Guardian identity (gen_ai.guardian.*)
  • Decision outcomes (gen_ai.security.decision.*)
  • Target being evaluated (gen_ai.security.target.*)
  • Findings and policy context (gen_ai.security.risk.*, gen_ai.security.policy.*)
  • Opt-in content capture (gen_ai.security.content.*)
• Note: gen_ai.security.risk.category is a free-form string with suggested values aligned with OWASP LLM Top 10 2025.
• Adds a new span: span.gen_ai.apply_guardrail.internal (guardian evaluation).
• Adds a new event: gen_ai.security.finding (individual findings under a guardian evaluation).
• Adds documentation: docs/gen-ai/gen-ai-security.md (linked from docs/gen-ai/README.md).

References

• OTel GenAI semantic conventions: https://opentelemetry.io/docs/specs/semconv/gen-ai/
• OWASP Agent Observability Standard (decision events / allow-deny-modify model): https://aos.owasp.org/spec/trace/events/
• OWASP Agent Observability Standard (mapping guidance to OpenTelemetry): https://aos.owasp.org/spec/trace/extend_opentelemetry/
• OWASP LLM Top 10 (2025): https://genai.owasp.org/llm-top-10/

Prototypes / Instrumentation Links

The prototype demonstrates all proposed conventions with runnable story scenarios:

Quick Start

cd prototype
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements-appinsights.txt
python -m stories.story_runner --all --exporters console

Key Files

File	Purpose
prototype/README.md	Full documentation and quickstart
prototype/otel_guardian_utils.py	Core span/event emission utilities
prototype/stories/	Runnable story scenarios
prototype/frameworks/	Framework adapters (LangChain, MCP)

Story Scenarios

Story	Scenario	Key Conventions
4	Enterprise RAG Access Control	knowledge_query, knowledge_result, memory_* targets
5	Multi-Tenant SaaS	llm_input, llm_output, modify decision, tenant.id
7	Multi-Agent Orchestrator	tool_definition, tool_call, gen_ai.agent.id nesting
10	Progressive Jailbreak	gen_ai.conversation.id correlation, cumulative risk
11	Guardian Error Handling	error.type attribute, fail-open/fail-closed

Semantic Convention Coverage

• Decision Types: allow, deny, modify, warn, audit
• Target Types: llm_input, llm_output, tool_call, tool_definition, message, memory_store, memory_retrieve, knowledge_query, knowledge_result
• Risk Categories: OWASP LLM Top 10 2025 aligned (prompt_injection, sensitive_info_disclosure, excessive_agency, etc.)

Tests

• make table-generation registry-generation
• make markdown-toc
• make SED=sed check-policies (macOS note: the repo defaults to gsed)

Changelog

This is user-facing (new conventions). Add a .chloggen/*.yaml entry with component: gen-ai, or apply the "Skip Changelog" label if maintainers agree it's not required for this proposal stage.

[adityamehra]

@nagkumar91 We have a similar use-case and when a security incident happens for a chat span we create a new span as a chat span and add an attributed called gen_ai.security.event_id. The value for this attribute can either be in the response body of the inspection call, which is separate from the actual LLM call, or can be in the response header when inspection happens along with the LLM call. Is it possible to add support for this attribute in here? Thanks!

Here's the sample of how we add it as of now - https://github.com/signalfx/splunk-otel-python-contrib/tree/main/instrumentation-genai/opentelemetry-instrumentation-aidefense#trace-integration

[adityamehra]

Also, it will be great if we can have another entry in the otel-genai-util for this new span type like we have for chat span - https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/util/opentelemetry-util-genai/src/opentelemetry/util/genai/types.py#L96. Or probably this new type can extend the LLMInvocation type

[adityamehra]

Can we add an attribute called gen_ai.security.event_id?

[nagkumar91]

The event being proposed would be a gen_ai.security.finding

Apply guardrail span will have these for IDs:

• gen_ai.guardian.id
• gen_ai.security.target.id
• gen_ai.security.policy.id

Would any of those fit your need?

[adityamehra]

Would this be better as an event (security finding event as proposed in this span)? Wondering why its a chat span?

Currently, the domain team is using event_id and it's as per their requirement. Also, in our case the event is generated elsewhere and not instrumentation side. We used chat span to use existing types in the genai-utils for now and manage span life cycle using it.

[nagkumar91]

@nagkumar91 We have a similar use-case and when a security incident happens for a chat span we create a new span as a chat span and add an attributed called gen_ai.security.event_id. The value for this attribute can either be in the response body of the inspection call, which is separate from the actual LLM call, or can be in the response header when inspection happens along with the LLM call. Is it possible to add support for this attribute in here? Thanks!

Here's the sample of how we add it as of now - https://github.com/signalfx/splunk-otel-python-contrib/tree/main/instrumentation-genai/opentelemetry-instrumentation-aidefense#trace-integration

Would this be better as an event (security finding event as proposed in this span)? Wondering why its a chat span?

[habibam]

One nit, the draft currently mixes guardian (evaluator/service) vs guardrail (policy/config) identity (e.g., mapping provider guardrail IDs into gen_ai.guardian.id). I suggest keeping gen_ai.guardian.* for the evaluating component, and mapping guardrail/config identifiers (like aws.bedrock.guardrail.id) to gen_ai.security.policy.id (and/or on gen_ai.security.finding when policy-triggered). Otherwise it becomes hard/impossible to differentiate a guardian from a guardrail in traces, and we end up with confusing cardinality/semantics. This keeps cross provider correlation clean.

[nagkumar91]

Thanks @habibam! I've addressed this in the commit (88c269b):

• Updated gen_ai.guardian.* attribute documentation to clarify these identify the evaluating service/component, not the policy
• Added explicit mapping guidance:
  • Guardian = service doing evaluation (e.g., "Azure Content Safety", "Bedrock Guardrails")
  • Policy = configuration being applied (use gen_ai.security.policy.id for ARNs, blocklist IDs, etc.)
• Updated examples to be clearer

This should make cross-provider correlation cleaner by keeping guardian and guardrail/policy semantics distinct. Let me know if the updated documentation captures your concern!

[habibam]

We should add in an example of generating a span from the response of elicitation

[nagkumar91]

Added in commit 88c269b!

New elicitation guard methods:

• guard_elicitation_request() - Guards outbound requests to user (prevents info leakage, excessive elicitation)
• guard_elicitation_response() - Guards user's response (detects PII, injection attempts)

Both map to target_type=message since they're user-facing interactions.

See the updated module docstring and main examples (tests 6-9) for usage patterns.

[nagkumar91]

Thanks for the feedback @adityamehra!

Regarding the otel-genai-util entry - this is tracked separately since it lives in opentelemetry-python-contrib. Once this semconv PR is approved and merged, I'll open a follow-up PR to add the corresponding types for apply_guardrail spans to the util package.

In the meantime, I've addressed your other feedback:

• Added gen_ai.security.external_event_id attribute for correlation with external security systems (SIEM, incident management). This should help with the use case you described where the event ID comes from an external inspection service response.

Let me know if the new attribute meets your needs or if you'd like any adjustments!

[nagkumar91]

Non-normative implementation guide (PR branch):
https://github.com/nagkumar91/semantic-conventions/blob/gen-ai-security-guardian/docs/gen-ai/non-normative/security_implementation_gen_ai_spec.md

Note on scope:

• All files under prototype/ are included for reference and to help understand/simulate the spans (stories, adapters, viewer).
• These prototype/ files are intended to be removed before merge.