Postee

Table of Contents

• Abstract
• Features
• Installation
• Configure the Aqua Server with Webhook Integration
• Set up the Configuration File

Abstract

Postee is a simple application that receives JSON messages from one hand, and delivers them (after reformatting) to different collaboration systems, like: JIRA, Email, Slack, Microsoft Teams, Generic WebHook, Splunk and ServiceNow.

Postee is exteremly useful for sending vulnerability scan results, reported by Aqua Security product, to collaboration systems. It has some special logic that can prevent sending same message twice! For example - in case vulnerability for certain image was already reported, Postee can suppress new messages for same image vulnerabilities and only send messages with new vulnerabilities. To setup Postee with Aqua Security vulnerability scanning follow this.

Features

Some features that Postee provides:

1. Image rescans: When an image is rescanned, the integration will not send a message if the scan results are same as the previous scan results. If the scan results are different then a message with the diff between the results will be sent.

2. Scan policy: You can create a policy that sends a message based on image scan criteria. The criteria can be based on the image name, registry name and scan results (e.g. only if there are high severity vulnerabilities). For more information see "Policy-Min-Vulnerability", "Policy-Registry", "Policy-Image-Name", "Policy-Only-Fix-Available", "Policy-Non-Compliant" tokens in the cfg.yaml file.

3. Ignore policy: You can create a policy that ignores specific registries/images. For more information see "Ignore-Registry" and "Ignore-Image-Name" tokens in the cfg.yaml file.

4. Aggregation policy: You can aggregate multiple scan results in a single ticket/message. This is useful if you would like to get a digest on daily/weekly basis. For more information see "Aggregate-Issues-Number" and "Aggregate-Issues-Timeout" tokens in the cfg.yaml file.

Installation

From Source

Clone this project:

git clone [email protected]:aquasecurity/postee.git
make all
./bin/webhooksrv

Docker

Build the postee Docker image:

docker build -t aquasec/postee:latest .

Run the Aqua Postee container with the configuration file:

docker run -d --name=postee -v /<path to configuration file>/cfg.yaml:/config/cfg.yaml \
    -e AQUAALERT_CFG=/config/cfg.yaml -e AQUAALERT_URL=0.0.0.0:8084 -e AQUAALERT_TLS=0.0.0.0:8444 \ 
    -p 8444:8444 -p 8084:8084 aquasec/postee:latest

Kubernetes

Helm

Configure the Aqua Server with Webhook Integration

Configure the Aqua Server to send a Webhook notification when a new vulnerability is found

Validate that a ticket has been opened, or email was sent (depending on your configuration file).

You can configure the Aqua Server to send a Webhook notification whenever a new vulnerability is found. Navigate to the Settings page in the System section, menu, under the "Image Scan Results Webhook" section.

Click "Enable sending image scan results to Postee server", and specify the URL of the Aqua Webhook server.

The URL is in the following formats: HTTPS: https://:8444 or HTTP: http://:8084

Validate the Integration

To validate that the integration is working, you can scan a new image for security vulnerabilities from the Aqua Server UI (Images > Add Image > Specify Image Name > Add).

When vulnerabilities are found in an image, you will see that a JIRA ticket is created/ Email is received/ Slack message is posted to the channel.

To troubleshoot the integration, you can look at both the Aqua Postee container logs and the Aqua Server logs. Use the "docker logs " command to view these logs.

Set up the Configuration File

To set up the integration, you will need to create a cfg.yaml file, which contains the connection settings. Edit the configuration file (cfg.yaml) with the connection details of your JIRA, Slack, etc.

The below example is to setup a JIRA integration:

---
- name: my-jira
  type: jira
  enable: true
  url: https://myname.atlassian.net
  user: [email protected]
  password: XXXXXXXXXXX
  project_key: #Provide here the JIRA project key, e.g., VUL
  board: #Optional JIRA board key, e.g., SLK
  priority: #Optional ticket priority, e.g., High
  assignee: $Optional assignee, e.g., John
  issuetype: $Optional issue type, e.g., Bug
  labels: #Optional comma separated list of labels that will be assigned to ticket, e.g., ["label1", "label2"]
  sprint: #Optional Sprint name, e.g., "3.5 Sprint 8"
  unknowns: #optional custom fields. Replace the "custom-field" text with the field name in JIRA
     custom-field: #text value, e.g. "hello world"
     custom-field-numeric-field: #numeric value, e.g. 337
     custom-field-multiple-value: #multi value, e.g., 1,2,3 (must be separated by commas)
     custom-field-multiple-line-text-field: #multi line text value, e.g. "text \n moretext" (quotes are mandatory for this field)
     custom-field-date-time-picker: #date and time value, e.g. 2014-04-11T12:14:26.880+0400
     custom-field-url: #URL value, e.g., https://tour.golang.org/moretypes/7

See the bottom of this page for other integration types and their parameters.

*To prevent providing clear text passwords in text file you can pass an environment variable, e.g. $MY_PASSWORD.

You will need to make sure this environment variable value is passed to the container.

Run the Aqua Postee Container

Build and run the Aqua Webhook Server container on the same host where the JIRA configuration file is located, as follows:

docker build -t postee:latest .

docker run -d --name=aqua-postee -v /<path to configuration file>/cfg.yaml:/config/cfg.yaml \
    -e AQUAALERT_CFG=/config/cfg.yaml -e AQUAALERT_URL=0.0.0.0:8084 -e AQUAALERT_TLS=0.0.0.0:8444 \
    -p 8444:8444 -p 8084:8084 postee:latest

There is a volume mount that mounts the configuration file from the host to the container. There is also an environment variable, AQUAALERT_CFG, that specifies the location of the JIRA configuration file inside the container.

Getting the JIRA connection details

Follow these steps to set up JIRA integration:

Login to Jira. Go to the user profile API tokens (JIRA Cloud users can find it here: https://id.atlassian.com/manage-profile/security/api-tokens). Click on the Create API Token. A new API token for the user is created. Keep the token value, together with the JIRA URL and user name, for the next step.

Getting the Slack connection details: Slack Custom App

1. Visit api.slack.com
2. Press "Create custom app"
3. Fill app name and select slack workspace
4. Open "Incoming webhooks" tab
5. Enable "Incoming webhooks"
6. Add webhook to workspace
7. On next screen pick slack channel and click allow
8. Copy webhook url to the Postee config

Getting the MS Teams connection details

Open your Microsoft Teams client. Click on the "..." near the channel you would like to send notifications to. Choose "Connectors". The connectors window will open. Look for the "Incoming Webhook" connector (it is under the "All" category). Click "Add" near the Incoming Webhook connector. Click "Add" again. Provide a name and click "Create". You will be provided with a URL address. Copy this URL and put it in the cfg.yaml.

Configure the Splunk Integration

You will need to craate an HTTP Event Collector in Splunk Enterprise or Splunk Cloud. This can usually be found in the Splunk console under "Settings -> Data Inputs -> HTTP Event Collector -> Add New". Once you create an HTTP Event Collector you will receive a token. You should provide this token, together with the Splunk HTTP Collector URL, as part of the cfg.yaml settings.

Integration Settings

You can setup integrations through the cfg.yaml file. Note that one yaml file can contain multiple integrations (e.g. multiple email integrations, where each integration is handling different container image registry).

The following are the global cfg.yaml parameters that apply for all integrations:

The following are the cfg.yaml parameters that you can include in every integration section:

A sample of a REGO policy file:

package postee

default allow = false

allow {
    contains(input.image, "alpine")
}

ServiceNow integration parameters

Jira integration parameters

For Jira you can also specify custom fields that will be populated with values. Use the "unknowns" parameter in cfg.yaml for custom fields. Under the "unknowns" parameter, specify the list of fields names to provide value for. You can add "-numeric-field", "-multiple-value", "multiple-line-text-field", "-date-time-picker" and "-field-url" as suffix to the custom field name, to specify what is the field type.

For example:

unknowns:
     mycustom: "this is a text custom field"
     mycustom-numeric-field: 123
     mycustom-multiple-value: 1,2,3 
     mycustom-multiple-line-text-field: "text \n moretext" 
     mycustom-date-time-picker: 2014-04-11T12:14:26.880+0400
     mycustom-url: https://tour.golang.org/moretypes/7

Email integration parameters

Slack integration parameters

MS Teams integration parameters

Splunk integration parameters

Generic Webhook integration parameters

Data Persistency

The Postee container uses BoltDB to store information about previously scanned images. This is used to prevent resending messages that were already sent before. The size of the database can grow over time. Every image that is saved in the database uses 20K of storage.

If you would like to persist the database file between restarts of the Postee container, then you should use a persistent storage option to mount the "/server/database" directory of the container. The "Kubernetes" directory in this project contains an example deployment that includes a basic Host Persistency.