Ticketing & custom templates

Suricatavel features a Ticketing Subsystem that integrates with external issue tracking platforms and messaging systems. This allows you to automatically dispatch detailed tickets or alerts when security policies trigger.

---

Supported integrations

Suricatavel supports two core ticketing adapter channels:

1. Jira

Creates issues directly in your Jira Cloud or Jira Server instance.

• Connection properties: Jira URL, Authentication email/username, and API token/Password.
• Defaults: Default Project Key (e.g., SEC) and Default Issue Type (e.g., Task, Bug).
• Priority mapping: Maps alert severity numbers (1 to 3) to Jira priority IDs or labels.

2. Custom webhooks

Sends HTTP POST payloads to messaging tools (Slack, Microsoft Teams, Discord) or API gateways.

• Connection properties: Destination Webhook URL and HTTP Method.
• Custom payload builder: Optional custom JSON template to override the default JSON structure with tailored request schemas.

---

Configuring integrations

To set up a ticketing channel:

1. Go to Administration > Settings > Ticketing.
2. Click Add integration and select either Jira or Webhook.
3. Fill out the connection details and credential tokens.
4. Click Test connection to verify connection reachability.
5. Save the configuration.

---

Creating ticket templates

Templates define the title and body layout of generated tickets. They are managed under the Administration > Templates menu and use Twig templating syntax.

Available template variables

When a policy triggers, the following context variables are injected into your Twig templates:

Common variables (all triggers)

• {{ trigger_type }}: Trigger event (alert_created or ioc_score_updated).
• {{ trigger_label }}: Human-readable trigger label (Alert Created or IOC Score Updated).
• {{ timestamp }}: ISO 8601 trigger timestamp.
• {{ app_url }}: Base URL of your Suricatavel panel.
• {{ app_name }}: The application name.
• {{ summary }}: Concise event summary.
• {{ policy_name }}: Triggering policy name.
• {{ policy_id }}: Triggering policy ID.

Alert context (available if alert is true)

• {{ alert }}: Evaluates to true when triggered by a Suricata alert.
• {{ source_ip }}: Source IP address.
• {{ dest_ip }}: Destination IP address.
• {{ severity }}: Alert severity (1, 2, or 3).
• {{ signature }}: Suricata rule signature message.
• {{ category }}: Alert classification category.
• {{ hostname }}: Host node that logged the alert.
• {{ source_port }}: Source port.
• {{ dest_port }}: Destination port.
• {{ protocol }}: IP protocol (TCP, UDP, ICMP, etc.).

IOC context (available if ioc is true)

• {{ ioc }}: Evaluates to true when triggered by an IOC score change.
• {{ ioc_value }}: Value of the indicator (e.g., IP, domain).
• {{ ioc_type }}: Type of indicator (e.g., ipv4, domain).
• {{ ioc_score }}: Updated threat score (0–100).
• {{ ioc_observations }}: Number of times observed in network events.

---

Twig template examples

Ticket title template

[{{ app_name }}] {{ trigger_label }} — {{ summary }}

Ticket body template (markdown)

## Automated security ticket

**Triggered by policy:** {{ policy_name | default('N/A') }}
**Trigger:** {{ trigger_label }}
**Timestamp:** {{ timestamp }}

{% if alert is defined and alert %}
### Alert details
| Field | Value |
|---|---|
| Signature | {{ signature }} |
| Severity | {{ severity }} |
| Source IP | {{ source_ip }} |
| Destination IP | {{ dest_ip }} |
| Category | {{ category | default('N/A') }} |
| Hostname | {{ hostname | default('N/A') }} |
| Protocol | {{ protocol | default('N/A') }} |
{% endif %}

{% if ioc is defined and ioc %}
### IOC Details
| Field | Value |
|---|---|
| Value | {{ ioc_value }} |
| Type | {{ ioc_type }} |
| Reputation Score | {{ ioc_score }} |
| Observations | {{ ioc_observations }} |
{% endif %}

---
*This ticket was created automatically by [Suricatavel]({{ app_url }}).*

---

Attaching actions to policies

Once integrations and templates are created, you can automate ticket generation:

1. Edit or create an automation rule in the Administration > Policies section.
2. In the Actions layout, select Notification / Ticket.
3. Choose the Integration channel and the Template to use.
4. Set optional override fields (such as Jira labels, custom projects, assignees, or Webhook JSON payloads).
5. Save the policy.

---

Queue management & retries

To prevent API loss, Suricatavel processes ticket actions asynchronously in the background.

• Rate-Limiting & Jitter: If an external provider returns a rate limit (HTTP 429), the ticketing engine automatically reschedules the job. It respects the provider’s Retry-After header (configurable) and applies a randomized delay jitter to prevent server hammering.
• Failures & Notifications: If a ticket action fails after exhausting the configured retry attempts, administrators are notified via configured alert channels (e.g., Email, Slack, Telegram).