Skip to main content

Notification Hook

Deployment

Installing the Notification hook will add a ReadOnly Hook to your namespace.

helm upgrade --install nwh ./hooks/notification-hook/ --values /path/to/your/values"

The values.yaml you need depends on the notification type you want to use. Please take a look at the documentation for each type (e.g. for slack see Configuration of a Slack Notification)

Available Notifier

Configuration of a Notification

The general configuration of a notification looks something like this

notificationChannels:
  - name: slack
    type: slack
    template: slack-messageCard
    rules:
      - matches:
          anyOf:
            - category: "Open Port"
    endPoint: "SOME_ENV"

env:
  - name: SOME_ENV
    valueFrom:
      secretRefKey:
       secret: some-secret
       key: some-key

The Notification Hook enables you to define multiple so called notificationChannels. A notificationChannel defines the Notification to a specific platform (e.g. Slack or Teams).

The name is used to for debugging failing notifications. it can be a string of you choice.

The type specifies the type of the notification (in this example slack). Currently slack is the only available type, but we are working on others (e.g. MS Teams or email) as well.

The template field defines the name of a Nunjucks template to send to your notification channel. These templates are usually tied to their notification channel (slack templates will not work for teams). The template slack-messageCard is provided by default. Notice that for the name of the template we chose to omit the file type. The template slack-messageCard will point to slack-messageCard.njk in the filesystem of the hook.

The endPoint specifies where the notification has to go to. To protect the actual endPoint (e.g. a webhook url) this should point to an env name defined under env For slack this would be your webhook URL to slack.

To define conditions when a notification should be created you can use rules. If no rules are specified, this hook will assume that you always want to be notified.

Under env you have to define additional information needed for your templates such as the actual endpoint. env will be mapped to the env implementation of Kubernetes. This means that you can define key-value pairs as well as providing envs via secrets (See Define Environment Variables for a Container | Kubernetes).

Rule Configuration

The rules can be defined in the values of the Chart. The syntax and semantic for these rules are quite similar to CascadingRules (See: secureCodeBox | CascadingRules) To define Rules you will have to provide the rules field with one or more matches elements. Each machtes defines one Rule. For example:

rules:
  - matches:
      anyOf:
        - category: "Open Port"
          attributes:
            port: 23
            state: open

This Rule will match all Findings with an open port on 23.

matches

Within the matches you will have to provide anyOf anyOf contains one or more conditions to be met by the finding to match the rule. Notice that only one of these elements needs to match the finding for the rule to match.

Configuration of a Slack Notification

To configure a Slack notification set the type to slack and the endPoint to point to your env containing your Webhook URL to slack. You can use one of the following default templates:

  • slack-messageCard

Configuration Of An Email Notification

To configure an email notification set the type to email and the endPoint to point to your env containing your target email address. You can use one of the following default templates:

  • email

Additional to this configuration you will have to provide a special smtp configuration URL. This config reflects the transporter configuration of nodemailer (See nodemailer | SMTP Transport). This configuration needs to be specified under env in the values yaml. The identifier for this config has to be SMTP_CONFIG. A basic configuration could look like this:

...
env:
  - name: SMTP_CONFIG
    value: "smtp://user@domain.tld:pass@smtp.domain.tld/"

To provide a custom from field for your email you can specify EMAIL_FROM under env. For example:

env:
  - name: SMTP_CONFIG
    value: "smtp://user@domain.tld:pass@smtp.domain.tld/"
  - name: EMAIL_FROM
    value: secureCodeBox

Custom Message Templates

CAUTION: Nunjucks templates allow code to be injected! Use templates from trusted sources only!

The Notification Hook enables you to write your own message templates if the templates provided by default are not sufficient. Templates for this hook are written using the Nunjucks templating engine.

To fill your template with data we provide the following objects.

objectDetails
findingsAn array of the findings matching your rules (See [Finding
scanAn Object containing information about the scan that triggered the notification (See [Scan
argscontains process.env (See: [process.env

Chart Configuration

KeyTypeDefaultDescription
customTemplateMap.existsboolfalse
customTemplateMap.namestring"config-map-name"
env[0].namestring"SOME_ENV_KEY"
env[0].valueFrom.secretKeyRef.keystring"some-key"
env[0].valueFrom.secretKeyRef.namestring"some-secret"
env[1].namestring"SMTP_CONFIG"
env[1].valueFrom.secretKeyRef.keystring"smtp-config-key"
env[1].valueFrom.secretKeyRef.namestring"some-secret"
hookJob.ttlSecondsAfterFinishedstringnilseconds after which the kubernetes job for the hook will be deleted. Requires the Kubernetes TTLAfterFinished controller: https://kubernetes.io/docs/concepts/workloads/controllers/ttlafterfinished/
image.pullPolicystring"Always"
image.repositorystring"docker.io/securecodebox/notification-hook"Hook image repository
image.tagstringdefaults to the charts versionImage tag
notificationChannels[0].endPointstring"SOME_ENV_KEY"
notificationChannels[0].namestring"slack"
notificationChannels[0].rules[0].matches.anyOf[0].categorystring"Open Port"
notificationChannels[0].templatestring"slack-messageCard"
notificationChannels[0].typestring"slack"