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 § 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)
• 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