gitea-admin/gh-christianlouis-dmarq
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add ticketing chatops templates

Browse Source
This commit is contained in:
Christian Krakau-Louis
2026-05-23 18:41:10 +02:00
parent 7f648e01a6
commit 453a9b7e2a
8 changed files with 612 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/app/api/api_v1/endpoints/integrations.py
+7
View File
@@ -4,6 +4,7 @@ from fastapi import APIRouter, Depends
from app.core.security import require_admin_auth
from app.services.siem_templates import get_siem_templates
from app.services.ticketing_chatops_templates import get_ticketing_chatops_templates
router = APIRouter()
@@ -12,3 +13,9 @@ router = APIRouter()
async def siem_templates(_auth: dict = Depends(require_admin_auth)):
"""Return versioned schemas and examples for SIEM ingestion."""
return get_siem_templates()
@router.get("/ticketing-chatops/templates")
async def ticketing_chatops_templates(_auth: dict = Depends(require_admin_auth)):
"""Return ticketing and chatops workflow templates."""
return get_ticketing_chatops_templates()
backend/app/services/ticketing_chatops_templates.py
+313
View File
@@ -0,0 +1,313 @@
"""Ticketing and chatops integration templates."""
from __future__ import annotations
import copy
from typing import Any, Dict, List
from app.services.webhook_events import (
EVENT_ALERT_CREATED,
EVENT_ALERT_RESOLVED,
EVENT_COMPLIANCE_DROP,
EVENT_REPORTS_MISSING,
EVENT_SENDER_NEW,
)
TICKETING_CHATOPS_TEMPLATE_VERSION = "2026-05-23"
TICKETING_CHATOPS_SCHEMA_VERSION = "dmarq.workflow.template.v1"
WORKFLOW_EVENT_TYPES = [
EVENT_SENDER_NEW,
EVENT_COMPLIANCE_DROP,
EVENT_REPORTS_MISSING,
EVENT_ALERT_CREATED,
EVENT_ALERT_RESOLVED,
]
EVENT_WORKFLOW_MAPPINGS: Dict[str, Dict[str, Any]] = {
EVENT_SENDER_NEW: {
"severity": "medium",
"owner": "email-security",
"ticket_action": "create_or_update",
"chat_action": "notify_channel",
"dedupe_key_template": "dmarq:{event_type}:{domain}:{sender_ip}",
"summary_template": "Review new DMARC sending source for {domain}",
"noise_control": "Open one ticket per domain and sender IP. Suppress repeats for 7 days after acknowledgement.",
},
EVENT_COMPLIANCE_DROP: {
"severity": "high",
"owner": "email-security",
"ticket_action": "create_or_update",
"chat_action": "notify_channel_and_thread",
"dedupe_key_template": "dmarq:{event_type}:{domain}",
"summary_template": "Investigate DMARC compliance drop for {domain}",
"noise_control": "Escalate only when drop_points meets the configured alert threshold. Update the same ticket while active.",
},
EVENT_REPORTS_MISSING: {
"severity": "medium",
"owner": "mail-operations",
"ticket_action": "create_or_update",
"chat_action": "notify_channel",
"dedupe_key_template": "dmarq:{event_type}:{domain}",
"summary_template": "Restore missing DMARC aggregate reports for {domain}",
"noise_control": "Create one ticket per domain and keep reminders to one chat update per day.",
},
EVENT_ALERT_CREATED: {
"severity": "medium",
"owner": "email-security",
"ticket_action": "create_or_update",
"chat_action": "notify_channel",
"dedupe_key_template": "dmarq:{event_type}:{domain}:{alert_rule}",
"summary_template": "DMARQ alert: {title}",
"noise_control": "Route by alert_rule and reuse open tickets while the alert remains active.",
},
EVENT_ALERT_RESOLVED: {
"severity": "info",
"owner": "email-security",
"ticket_action": "resolve_or_comment",
"chat_action": "notify_thread",
"dedupe_key_template": "dmarq:{event_type}:{domain}:{alert_rule}",
"summary_template": "DMARQ alert resolved: {title}",
"noise_control": "Resolve the linked ticket when all active signals for the dedupe key are clear.",
},
}
SAMPLE_CONTEXT: Dict[str, Any] = {
"event_type": EVENT_COMPLIANCE_DROP,
"event_id": "dmarq-compliance-drop-20260523-example-com",
"domain": "example.com",
"severity": "high",
"title": "DMARC compliance dropped for example.com",
"detail": "Compliance fell by 23.39 percentage points in the current window.",
"alert_rule": "compliance_drop",
"sender_ip": None,
"message_count": 1280,
"failed_count": 366,
"compliance_rate": 71.41,
"previous_compliance_rate": 94.8,
"drop_points": 23.39,
"domain_url": "https://dmarq.example/domains/example.com",
"report_url": "https://dmarq.example/domains/example.com/reports",
"dedupe_key": "dmarq:dmarq.compliance.drop:example.com",
}
JIRA_ISSUE_TEMPLATE: Dict[str, Any] = {
"operation": "create_or_update_issue",
"lookup": {
"jql": 'project = EMAILSEC AND labels = "dmarq" AND "Dedupe Key" ~ "{dedupe_key}" AND statusCategory != Done'
},
"create": {
"fields": {
"project": {"key": "EMAILSEC"},
"issuetype": {"name": "Task"},
"summary": "[DMARQ][{severity}] {title}",
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "{detail}",
}
],
},
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Domain: {domain} | Compliance: {compliance_rate}% | Previous: {previous_compliance_rate}% | Drop: {drop_points} points",
}
],
},
],
},
"labels": ["dmarq", "email-security", "{alert_rule}"],
"priority": {"name": "High"},
"customfield_dedupe_key": "{dedupe_key}",
}
},
"update": {
"comment": "{event_time}: {detail}",
"fields": {"priority": {"name": "High"}},
},
"resolve": {
"transition": "Done",
"comment": "DMARQ reports this alert is resolved. Event: {event_id}",
},
}
GITHUB_ISSUE_TEMPLATE: Dict[str, Any] = {
"operation": "create_or_update_issue",
"repository": "security-operations/email-auth",
"lookup": {
"state": "open",
"labels": ["dmarq", "{alert_rule}", "dedupe:{dedupe_key}"],
},
"create": {
"title": "[DMARQ][{severity}] {title}",
"body": "\n".join(
[
"## Signal",
"{detail}",
"",
"## Evidence",
"- Domain: `{domain}`",
"- Compliance rate: `{compliance_rate}%`",
"- Previous compliance rate: `{previous_compliance_rate}%`",
"- Drop: `{drop_points}` points",
"- Failed messages: `{failed_count}` of `{message_count}`",
"",
"## Links",
"- Domain: {domain_url}",
"- Reports: {report_url}",
"",
"Dedupe key: `{dedupe_key}`",
]
),
"labels": ["dmarq", "email-security", "{alert_rule}", "dedupe:{dedupe_key}"],
},
"update": {"comment": "{event_time}: {detail}\n\nDedupe key: `{dedupe_key}`"},
"resolve": {"state": "closed", "comment": "Resolved by DMARQ event `{event_id}`."},
}
SLACK_MESSAGE_TEMPLATE: Dict[str, Any] = {
"channel": "#email-security",
"thread_key": "{dedupe_key}",
"text": "[DMARQ][{severity}] {title}",
"blocks": [
{
"type": "header",
"text": {"type": "plain_text", "text": "DMARQ: {title}"},
},
{
"type": "section",
"text": {"type": "mrkdwn", "text": "{detail}"},
},
{
"type": "section",
"fields": [
{"type": "mrkdwn", "text": "*Domain*\n{domain}"},
{"type": "mrkdwn", "text": "*Severity*\n{severity}"},
{"type": "mrkdwn", "text": "*Compliance*\n{compliance_rate}%"},
{"type": "mrkdwn", "text": "*Drop*\n{drop_points} points"},
],
},
{
"type": "actions",
"elements": [
{
"type": "button",
"text": {"type": "plain_text", "text": "Open domain"},
"url": "{domain_url}",
},
{
"type": "button",
"text": {"type": "plain_text", "text": "Open reports"},
"url": "{report_url}",
},
],
},
],
}
TEAMS_MESSAGE_TEMPLATE: Dict[str, Any] = {
"type": "message",
"attachments": [
{
"contentType": "application/vnd.microsoft.card.adaptive",
"content": {
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.5",
"body": [
{
"type": "TextBlock",
"size": "Medium",
"weight": "Bolder",
"text": "DMARQ: {title}",
},
{"type": "TextBlock", "wrap": True, "text": "{detail}"},
{
"type": "FactSet",
"facts": [
{"title": "Domain", "value": "{domain}"},
{"title": "Severity", "value": "{severity}"},
{"title": "Compliance", "value": "{compliance_rate}%"},
{"title": "Drop", "value": "{drop_points} points"},
],
},
],
"actions": [
{
"type": "Action.OpenUrl",
"title": "Open domain",
"url": "{domain_url}",
},
{
"type": "Action.OpenUrl",
"title": "Open reports",
"url": "{report_url}",
},
],
},
}
],
}
OPERATING_MODEL = [
"Use DMARQ webhook idempotency keys or the documented dedupe_key_template as the ticket correlation key.",
"Route ownership by event type: email-security for sender/compliance/alert signals, mail-operations for missing reports.",
"Create or update one ticket per active signal, and close or comment when a resolved event arrives.",
"Send chat notifications to a stable channel, then keep follow-up updates in the same thread whenever the destination supports threading.",
"Use severity and configured thresholds to suppress low-value repeats. Do not page on every aggregate report import.",
"Store Jira, GitHub, Slack, and Teams credentials in the receiving automation platform or secret manager, not in DMARQ payloads.",
]
def get_ticketing_chatops_templates() -> Dict[str, Any]:
"""Return a copy of the ticketing and chatops template bundle."""
return copy.deepcopy(
{
"template_version": TICKETING_CHATOPS_TEMPLATE_VERSION,
"schema_version": TICKETING_CHATOPS_SCHEMA_VERSION,
"event_types": WORKFLOW_EVENT_TYPES,
"event_workflow_mappings": EVENT_WORKFLOW_MAPPINGS,
"sample_context": SAMPLE_CONTEXT,
"payload_templates": {
"jira": JIRA_ISSUE_TEMPLATE,
"github": GITHUB_ISSUE_TEMPLATE,
"slack": SLACK_MESSAGE_TEMPLATE,
"microsoft_teams": TEAMS_MESSAGE_TEMPLATE,
},
"operating_model": OPERATING_MODEL,
}
)
def validate_workflow_template_bundle(bundle: Dict[str, Any]) -> List[str]:
"""Validate bundled templates without pulling in a schema dependency."""
errors: List[str] = []
if bundle.get("schema_version") != TICKETING_CHATOPS_SCHEMA_VERSION:
errors.append("schema_version must be dmarq.workflow.template.v1")
if sorted(bundle.get("event_types", [])) != sorted(WORKFLOW_EVENT_TYPES):
errors.append("event_types must match supported workflow events")
mappings = bundle.get("event_workflow_mappings") or {}
for event_type in WORKFLOW_EVENT_TYPES:
mapping = mappings.get(event_type) or {}
if not mapping.get("dedupe_key_template"):
errors.append(f"{event_type} is missing a dedupe key template")
if not mapping.get("owner"):
errors.append(f"{event_type} is missing an owner")
if not mapping.get("ticket_action"):
errors.append(f"{event_type} is missing a ticket action")
templates = bundle.get("payload_templates") or {}
for destination in ["jira", "github", "slack", "microsoft_teams"]:
if destination not in templates:
errors.append(f"missing payload template: {destination}")
return errors
backend/app/tests/test_ticketing_chatops_templates.py
+101
View File
@@ -0,0 +1,101 @@
import json
from fastapi.testclient import TestClient
from app.services.ticketing_chatops_templates import (
TICKETING_CHATOPS_SCHEMA_VERSION,
WORKFLOW_EVENT_TYPES,
get_ticketing_chatops_templates,
validate_workflow_template_bundle,
)
from app.services.webhook_events import EVENT_ALERT_RESOLVED, EVENT_COMPLIANCE_DROP
def _string_values(value):
if isinstance(value, dict):
for item in value.values():
yield from _string_values(item)
elif isinstance(value, list):
for item in value:
yield from _string_values(item)
elif isinstance(value, str):
yield value
def test_ticketing_chatops_bundle_is_versioned_and_complete():
"""Workflow templates cover every ticketing/chatops event type."""
bundle = get_ticketing_chatops_templates()
assert bundle["schema_version"] == TICKETING_CHATOPS_SCHEMA_VERSION
assert sorted(bundle["event_types"]) == sorted(WORKFLOW_EVENT_TYPES)
assert validate_workflow_template_bundle(bundle) == []
assert bundle["event_workflow_mappings"][EVENT_COMPLIANCE_DROP]["severity"] == "high"
assert (
bundle["event_workflow_mappings"][EVENT_ALERT_RESOLVED]["ticket_action"]
== "resolve_or_comment"
)
def test_ticketing_chatops_templates_have_no_embedded_credentials():
"""Examples must be safe to publish without leaking destination credentials."""
bundle = get_ticketing_chatops_templates()
encoded_values = json.dumps(list(_string_values(bundle))).lower()
for forbidden in ["xoxb-", "ghp_", "jira_pat", "incoming_webhook", "bearer "]:
assert forbidden not in encoded_values
def test_ticketing_chatops_validation_reports_template_drift():
"""Validator explains missing required workflow and destination fields."""
bundle = get_ticketing_chatops_templates()
bundle["schema_version"] = "unexpected"
bundle["event_types"] = [EVENT_COMPLIANCE_DROP]
bundle["event_workflow_mappings"][EVENT_COMPLIANCE_DROP].pop("dedupe_key_template")
bundle["event_workflow_mappings"][EVENT_COMPLIANCE_DROP].pop("owner")
bundle["event_workflow_mappings"][EVENT_COMPLIANCE_DROP].pop("ticket_action")
bundle["payload_templates"].pop("slack")
errors = validate_workflow_template_bundle(bundle)
assert "schema_version must be dmarq.workflow.template.v1" in errors
assert "event_types must match supported workflow events" in errors
assert f"{EVENT_COMPLIANCE_DROP} is missing a dedupe key template" in errors
assert f"{EVENT_COMPLIANCE_DROP} is missing an owner" in errors
assert f"{EVENT_COMPLIANCE_DROP} is missing a ticket action" in errors
assert "missing payload template: slack" in errors
def test_ticketing_chatops_templates_return_independent_copies():
"""Mutating one returned bundle does not alter future callers."""
bundle = get_ticketing_chatops_templates()
bundle["payload_templates"]["jira"]["operation"] = "mutated"
fresh_bundle = get_ticketing_chatops_templates()
assert fresh_bundle["payload_templates"]["jira"]["operation"] == "create_or_update_issue"
def test_ticketing_chatops_endpoint_returns_workflow_templates(
authed_client: TestClient,
):
"""Administrators can fetch issue and chat message templates."""
response = authed_client.get("/api/v1/integrations/ticketing-chatops/templates")
assert response.status_code == 200
body = response.json()
assert body["schema_version"] == TICKETING_CHATOPS_SCHEMA_VERSION
assert set(body["payload_templates"]) == {
"jira",
"github",
"slack",
"microsoft_teams",
}
assert body["payload_templates"]["jira"]["operation"] == "create_or_update_issue"
assert body["payload_templates"]["slack"]["thread_key"] == "{dedupe_key}"
def test_ticketing_chatops_endpoint_requires_admin_auth(client: TestClient):
"""Workflow templates use the same admin boundary as integration settings."""
response = client.get("/api/v1/integrations/ticketing-chatops/templates")
assert response.status_code == 401