Ticket Sync (Jira / GitHub Issues)¶

Ticket Sync automatically creates an external ticket (Jira issue or GitHub issue) when a new finding appears, keeps that ticket's content and priority in sync as the finding changes, closes it when the finding is resolved, and escalates it if the finding breaches its SLA. It runs as a per-schedule notification channel - there is currently no dedicated Settings UI page for it; it's configured through a schedule's ticket_sync config block plus service-level credentials.

How a finding becomes a ticket¶

Ticket Sync listens for three event types on the same event stream every other notification channel (Slack, email, webhook) consumes:

Before doing anything, the plugin checks:

1. ticket_sync.enabled is true in the schedule's config. This flag alone turns ticket sync on for a schedule. The deployment's TICKET_SYNC_ENABLED (chart notification.ticketSync.enabled) neither turns it on nor off (see the environment variables).
2. The configured provider has its required target set - project_key for Jira, repo for GitHub Issues. If the target is missing, the event is skipped before any HTTP call is made.
3. If the schedule brings no credential of its own, its target is on the deployment's allowlist (see the environment variables). Otherwise the event fails before any HTTP call.
4. The finding's severity meets or exceeds severity_threshold (default medium).

A failure anywhere in this path never blocks delivery to other notification channels (Slack/email) for the same event. Each outcome is recorded in the run's notification delivery log (the run Overview, and Admin > Operations > Deliveries):

The providers' update and close calls still log an HTTP failure and return, so those two are recorded as sent (platform#475).

Provider configuration¶

Jira¶

Issues are created with summary prefixed [SEVERITY], an ADF-formatted description (finding description + finding ID + resource ID), issue type Bug, priority mapped from severity (critical→Highest, high→High, medium→Medium, low→Low, info→Lowest), and labels vsutra, security.

GitHub Issues¶

Issues are created with title [SEVERITY] <finding title>, a Markdown body (finding ID, severity, resource, check ID, scanner, description), and labels security, vsutra. Severity escalation is expressed as a single priority:* label (GitHub Issues has no native priority field) - any existing priority:* label is removed before the new one is added, so an issue never carries two contradictory priority labels.

Choosing/overriding the provider¶

ticket_sync.provider ("jira" or "github_issues") selects the provider; it falls back to the service-level TICKET_SYNC_PROVIDER env var if unset on the schedule. ticket_sync.severity_threshold falls back to TICKET_SYNC_SEVERITY_THRESHOLD (service default: medium).

Closing and reopening - the GitHub side¶

GitHub Issues sync is bidirectional: closing or reopening the linked GitHub issue updates the finding's status back in VirtualSutra, via POST /webhooks/github/issues.

• Issue reopened → the linked finding's status is set to open.
• Issue closed → the linked finding's status is set to resolved.

Requirements and safeguards:

• The webhook is authenticated via HMAC-SHA256 using the GITHUB_WEBHOOK_SECRET environment variable (configured as the shared secret on the GitHub webhook itself). This is a separate secret from the per-installation webhook_secret used by the PR-check integration under Settings > Integrations.
• If GITHUB_WEBHOOK_SECRET is unset, the endpoint runs in a permissive dev-mode for reopened events only (an ERROR is logged to surface the misconfiguration) - but a closed event is refused outright when the secret isn't configured, since re-resolving a finding suppresses its visibility and that direction must never run unauthenticated.
• The finding to update is looked up by its stored external_issue_url, which must match the repository.full_name + issue.number carried in the same signed payload - this stops a payload from naming one repo while pointing at an issue URL belonging to a different one.
• Jira has no equivalent inbound webhook in this build - closing/reopening a Jira issue does not currently sync back to the finding's status.

SLA-breach escalation¶

Independent of any new scan, an hourly scheduled job (SLA_BREACH_CHECK_ENABLED, default on; interval via SLA_BREACH_CHECK_INTERVAL_HOURS, default 1 hour) scans every org for open, unmuted findings older than that org's SLA threshold for their severity, and emits an escalated_finding event (escalation_reason: "sla_breach") for each one - which Ticket Sync picks up the same way as a diff-driven escalation.

Default thresholds (hours), overridable per-org:

Setting an override to 0 or a non-positive number disables SLA tracking for that severity. Each org's breach check is isolated - a failure processing one org doesn't stop the hourly cycle from checking the rest. Each finding/severity breach is deduplicated via a Redis key so the same breach doesn't re-fire every hour within the same threshold window.

Environment variables reference¶

Per-schedule ticket_sync config values (set in the schedule's config JSON) always take precedence over these service-level values. The credential env vars exist as fallbacks so you don't have to repeat credentials on every schedule, but the deployment's credential is only sent to a target on its allowlist. Self-hosted, that is any project on JIRA_DOMAIN, the repos in TICKET_SYNC_REPO / GITHUB_ISSUES_REPO, and TICKET_SYNC_ALLOWED_TARGETS. Under SaaS, it is only the projects in TICKET_SYNC_PROJECT_KEY / JIRA_PROJECT_KEY on JIRA_DOMAIN, plus those repos. A schedule that names any other target must carry its own credential (platform#472); under SaaS, such a schedule is refused when it is saved.