dt-sec-semantic-mapping

---
name: dt-sec-semantic-mapping
description: "Suggest and validate semantic dictionary (SD) mappings for new security integrations using vendor API samples or live events. Use when: mapping a new security vendor data to Dynatrace SD; checking required fields; validating namespaces; highlighting discrepancies vs the semantic dictionary; proposing mapping improvements; running runtime validation against live tenant data."
license: Apache-2.0
---

# dt-sec-semantic-mapping

Build and validate semantic-dictionary-aligned mappings for new security integrations.

## Purpose

Use this skill when a user wants to:

- **Suggest** a mapping from vendor API output to Dynatrace `security.events` fields (Workflow A).
- **Validate** an existing mapping for completeness and quality against:
  - Local baseline samples and semantic dictionary (Workflow B1 — static, offline validation), or
  - Live tenant data via live tenant access (Workflow B2 — runtime validation)
- Highlight discrepancies vs. the Semantic Dictionary and local references.
- Get actionable mapping improvements.

## Semantic Dictionary

The Semantic Dictionary (SD) defines the canonical field set for `security.events`. See `references/semantic-reference.md` for the canonical reference: local-vs-live sources, queryable Grail tables, when-to-query decision matrix, and the authority rule (live SD wins on disagreement).

## Required Inputs

Always run the intake checklist in `references/intake-and-constraints.md` before generating or validating a mapping. If inputs are incomplete, continue with a partial draft but explicitly list missing evidence and confidence limits.

## Baseline Sources (self-contained)

All baseline material lives inside this skill:

- `samples/` — real integration payloads covering all finding types and providers. Consulted as a fallback when primary references (SD, data-model-notes, known-discrepancies, validation-rules, object-type-expectations) leave a specific question unresolved — not as a routine step on every workflow run.
- `references/semantic-reference.md` — SD reference, field taxonomy, event types, provider taxonomy, and entity scoping
- `references/validation-policy-and-reporting.md` — validation rules, acceptable discrepancies, and report templates
- `references/intake-and-constraints.md` — intake checklist, output contract, `object.type` expectations, and OpenPipeline constraints

## Event-Type Coverage Requirements

The mapping MUST address the correct set of `event.type` values per finding class. Detection integrations are push-based and do not use scan cycles — never require scan events for detection.

See [validation-policy-and-reporting.md](references/validation-policy-and-reporting.md#validation-rules) § Event-Type Coverage for the full table, severity rules, and the alternative-classification path when a detection-class mapping incorrectly emits `*_SCAN` events.

## Workflows

This skill operates in three modes. Detect the mode from context:

| Mode | Input | Procedural source |
|---|---|---|
| **Workflow A** — Suggest a new mapping | Raw vendor API payloads only | `references/mapping-workflow.md § Workflow A` (Phase 1 mapping table → user approval → Phase 2 sample JSON) |
| **Workflow B1** — Static validation | Existing mapping + vendor API samples | `references/mapping-workflow.md § Workflow B` — classify input mode (final ingested / theoretical), apply rules, produce diff-highlighted table |
| **Workflow B2** — Runtime validation | Existing mapping + live tenant access | `references/runtime-validation.md` — load the security (AppSec) events supporting skill first (REQUIRED Step 0), then run the query pack, produce a Validation Summary table |

All workflows follow the output contracts in `references/intake-and-constraints.md` and the report templates in `references/validation-policy-and-reporting.md`. Validation rules (event-type coverage, required fields, scan references, namespace requirements, value/type checks, vendor-namespace duplication) live in `references/validation-policy-and-reporting.md`.

## Acceptable Discrepancy Policy

See `references/validation-policy-and-reporting.md` for the canonical list of acceptable SD deviations and vendor-namespace patterns. Do NOT raise critical/major issues for fields on that list. Genuinely unknown fields (not in local refs AND not in the live SD — see `references/semantic-reference.md`) must be questioned per `references/validation-policy-and-reporting.md`.

## Scope

This skill covers:

- Mapping suggestion and refinement (Workflow A).
- Static validation against local baseline examples and semantic dictionary (Workflow B1).
- Runtime validation via live tenant access against live tenant data (Workflow B2).
- Semantic-dictionary conformance checks.
- Gap analysis and improvement recommendations.

This skill does not cover:

- Live ingestion pipeline deployment.
- Runtime DQL performance benchmarking.
- Tenant-side ingestion troubleshooting.

## References

- `references/semantic-reference.md` — SD reference plus data-model notes: local sources, live (queryable) sources, DQL patterns, when-to-query decision matrix, authority rule, field taxonomy
- A skill covering full SD access patterns and Grail-table documentation — for DQL query patterns against `security.events` and Grail tables
- [Semantic Dictionary (public docs)](https://docs.dynatrace.com/docs/semantic-dictionary/model/security-events)
- `references/intake-and-constraints.md` — intake checklist, output contract, OpenPipeline constraints, and `object.type` namespace expectations
- `references/mapping-workflow.md` — how to build and refine a mapping candidate
- `references/validation-policy-and-reporting.md` — full validation rule set, known discrepancies, and discrepancy report templates
- `references/runtime-validation.md` — optional real-environment query validation pack

More agent context in Dynatrace/dynatrace-for-ai

35 other files this repository gives its agents.