dt-sec-semantic-mapping

$npx mdskill add Dynatrace/dynatrace-for-ai/dt-sec-semantic-mapping

Suggest and validate semantic dictionary mappings for security integrations.

  • Maps vendor API output to Dynatrace security.events fields.
  • Depends on semantic dictionary, vendor samples, and live tenant data.
  • Validates against local references and live Grail tables.
  • Returns mapping suggestions, discrepancies, and actionable improvements.

SKILL.md

.github/skills/dt-sec-semantic-mappingView on GitHub ↗
---
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-dictionary.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-output.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/data-model-notes.md` — field taxonomy, event types, provider taxonomy, entity scoping
- `references/known-discrepancies.md` — documented acceptable deviations between SD and observed samples
- `references/object-type-expectations.md` — `object.type` namespace expectations
- `references/semantic-dictionary.md` — SD reference and live-verification patterns

## 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-rules.md](references/validation-rules.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-output.md` and the report templates in `references/report-format.md`. Validation rules (event-type coverage, required fields, scan references, namespace requirements, value/type checks, vendor-namespace duplication) live in `references/validation-rules.md`.

## Acceptable Discrepancy Policy

See `references/known-discrepancies.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-dictionary.md`) must be questioned per `references/validation-rules.md § Known SD Discrepancies and Unknown Fields`.

## 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-dictionary.md` — SD reference: local sources, live (queryable) sources, DQL patterns, when-to-query decision matrix, authority rule
- 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/data-model-notes.md` — field dictionary and event-type taxonomy
- `references/known-discrepancies.md` — acceptable SD deviations
- `references/object-type-expectations.md` — `object.type` namespace expectations
- `references/intake-and-output.md` — intake checklist and output contract
- `references/mapping-workflow.md` — how to build and refine a mapping candidate
- `references/openpipeline-constraints.md` — OpenPipeline processor chain architecture (generic → per-subcategory → cleanup), restricted DQL subset, `jsonPath()` unavailable, `ip()` cast for IP fields
- `references/validation-rules.md` — full validation rule set
- [references/report-format.md](references/report-format.md) — discrepancy report templates
- `references/runtime-validation.md` — optional real-environment query validation pack

More from Dynatrace/dynatrace-for-ai

SkillDescription
dt-alertingEnd-to-end Dynatrace alerting lifecycle — anomaly detector setup and model selection (static threshold, adaptive baseline, seasonal baseline), alert event storage in Grail, problem grouping and denoising by root cause analysis, and workflow-based notification routing (email, Slack, ServiceNow, webhook). Use when configuring alerting, choosing between detector types, querying alert event history, understanding why alerts merged into a problem, or setting up problem-triggered notifications.
dt-app-dashboardsWork with Dynatrace dashboards - create, modify, query, and analyze dashboard JSON including tiles, layouts, DQL queries, variables, and visualizations.
dt-app-notebooksWork with Dynatrace notebooks - create, modify, query, and analyze notebook JSON including sections, DQL queries, and visualizations.
dt-dql-essentialsCore DQL syntax, pitfalls, query patterns, and query optimization. Load to write, build, fix, or OPTIMIZE a DQL query — prevents syntax errors and makes queries faster, more efficient, and cheaper (less data scanned = lower query consumption/cost per run). Covers fetch commands, data models, field namespaces, time alignment, entity/smartscape patterns, metric discovery, and performance/cost optimization (filter early, bucket filters, short time ranges, field selection, sampling, cardinality). Trigger: \"write/build/fix a DQL query\", \"DQL syntax\", \"query logs/spans/metrics\", \"create a timeseries\", \"optimize my DQL\", \"make my query faster/cheaper\", \"reduce DQL cost/consumption/scanned data\", \"keep DQL cost under control\". Do NOT use to explain an existing query or answer product questions. For MONITORING a tenant's ACTUAL query consumption/billing (how much queries cost, who scanned most, cost trends) use dt-platform-costs — this tunes the query text, not billing data.
dt-js-runtimeDynatrace server-side JS runtime — function contract, runtime limits, Web APIs, Node.js modules, fetch with credential vault, and the @dynatrace-sdk/* catalog.
dt-migrationMigrate Dynatrace classic and Gen2 entity-based DQL to Smartscape equivalents. Covers three scenarios. (1) mass data queries filtered by classic entity conditions — migrate to direct dimension filters first, Smartscape only as fallback; (2) mass data queries using entity subqueries for filtering — same dimension-first strategy; (3) pure entity list queries — migrate fetch dt.entity.* to smartscapeNodes. Also handles entityName, entityAttr, classicEntitySelector, and classic relationship patterns.
dt-obs-androidInstruments an existing Android project (Kotlin or Java) with the Dynatrace Mobile Agent for basic monitoring. Covers zero-to-first-event setup only: Gradle plugin, agent config, and user privacy opt-in. Do not use for advanced Dynatrace configuration beyond initial instrumentation.
dt-obs-aws>-
dt-obs-azureAzure cloud resources including VMs, VMSS, SQL Database, Storage, AKS, App Service, Functions, VNet networking, load balancers, Event Hubs, Container Apps, and Key Vault. Monitor Azure infrastructure, analyze resource usage, audit security posture, and manage organizational hierarchy across subscriptions and resource groups.
dt-obs-flutter>-