Skip to main content
Calico Enterprise 3.19 (latest) documentation

Security event webhook

A security event webhook (SecurityEventWebhook) is a cluster-scoped resource that represents instances of integrations with external systems through the webhook callback mechanism.

For kubectl commands, the following case-insensitive aliases can be used to specify the resource type on the CLI: securityeventwebhook.projectcalico.org, securityeventwebhooks.projectcalico.org and abbreviations such as securityeventwebhook.p and securityeventwebhooks.p.

Sample YAML​

apiVersion: projectcalico.org/v3
kind: SecurityEventWebhook
metadata:
name: jira-webhook
annotations:
webhooks.projectcalico.org/labels: 'Cluster name:Calico Enterprise'
spec:
consumer: Jira
state: Enabled
query: type=waf
config:
- name: url
value: 'https://your-jira-instance-name.atlassian.net/rest/api/2/issue/'
- name: project
value: PRJ
- name: issueType
value: Bug
- name: username
valueFrom:
secretKeyRef:
name: jira-secrets
key: username
- name: apiToken
valueFrom:
secretKeyRef:
name: jira-secrets
key: token

Security event webhook definition​

Metadata​

FieldDescriptionAccepted ValuesSchema
nameUnique name to describe this resource instance. Required.Alphanumeric string with optional ., _, or -.string

Annotations​

Security event webhooks provide an easy way to add arbitrary data to the webhook generated HTTP payload through the metadata annotation. The value of the webhooks.projectcalico.org/labels, if present, will be converted into the payload labels. The value must conform to the following rules:

  • Key and value data for a single label are separated by the : character,
  • Multiple labels are separated by the , character.

Spec​

FieldDescriptionAccepted ValuesSchemaRequired
consumerSpecifies intended consumer of the webhook.Slack, Jira, Genericstringyes
stateDefines current state of the webhook.Enabled, Disabled, Debugstringyes
queryDefines query used to retrieve security events from Calico.see Querystringyes
configWebhook configuration, required contents of this structure is determined by the value of the consumer field.see Configlist of SecurityEventWebhookConfigVaryes

SecurityEventWebhookConfigVar​

FieldDescriptionSchemaRequired
nameConfiguration variable name.stringyes
valueDirect value for the variable.stringyes if valueFrom is not specified
valueFromValue defined either in a Kubernetes ConfigMap or in a Kubernetes Secret.SecurityEventWebhookConfigVarSourceyes if value is not specified

SecurityEventWebhookConfigVarSource​

FieldDescriptionSchemaRequired
configMapKeyRefKubernetes ConfigMap reference.ConfigMapKeySelector (referenced ConfigMap key should exist in the tigera-intrusion-detection namespace)yes if secretKeyRef is not specified
secretKeyRefKubernetes Secret reference.SecretKeySelector (referenced Secret key should exist in the tigera-intrusion-detection namespace)yes if configMapKeyRef is not specified

Status​

Field status reflects the health of a webhook. It is a list of Kubernetes Conditions.

Query​

Security event webhooks use a domain-specific query language to select which records from the data set should trigger the HTTP request.

The query language is composed of any number of selectors, combined with boolean expressions (AND, OR, and NOT), set expressions (IN and NOTIN) and bracketed subexpressions. These are translated by Calico Enterprise to Elastic DSL queries that are executed on the backend.

Set expressions support wildcard operators asterisk (*) and question mark (?). The asterisk sign matches zero or more characters and the question mark matches a single character.

A selector consists of a key, comparator, and value. Keys and values may be identifiers consisting of alphanumerics and underscores (_) with the first character being alphabetic or an underscore, or may be quoted strings. Values may also be integer or floating point numbers. Comparators may be = (equal), != (not equal), < (less than), <= (less than or equal), > (greater than), or >= (greater than or equal).

Configuration​

Data required to be present in the config section of the security event webhook spec depends on the intended consumer for the HTTP requests generated by the webhook. The value in the consumer field of the spec specifies the consumer and therefore data that is required to be present. Currently Calico supports the following consumers: Slack, Jira and Generic. Payloads generated by the webhook will be different for each of the listed use cases.

Slack​

Data fields required for the Slack value present in the spec.consumer field of a webhook:

FieldDescriptionRequired
urlA valid Slack Incoming Webhook URL.yes

Generic​

Data fields required for the Generic value present in the spec.consumer field of a webhook:

FieldDescriptionRequired
urlA generic and valid URL of another HTTP(s) endpoint.yes

Jira​

Data fields required for the Jira value present in the spec.consumer field of a webhook:

FieldDescriptionRequired
urlURL of a Jira REST API v2 endpoint for the organisation.yes
projectA valid Jira project abbreviation.yes
issueTypeA valid issue type for the selected project, examples: Bug or Taskyes
usernameA valid Jira user name.yes
apiTokenA valid Jira API token for the user.yes