Webhooks Concepts: IQ Server and Slack Integration

As a company, we value test-driven development, so we’re going to go ahead and make some tests for this project. We’re going to use the Mocha JS test framework and Chai assertion library to write tests that will help us develop without having to spin everything up.

Install Mocha with npm install --save-dev mocha.

Install Chai with npm install --save-dev chai.

In your project folder, make a test folder and then create a file in it called policy-evaluation-mapper-test.js. This file will contain the test for the policy evaluation mapper that converts the policy evaluation webhook into a Slack message.

We’re going to look at the IQ Webhooks page on Sonatype Help to get an idea of what this object could look like. We’ll grab a copy of the example application evaluation payload:

const { assert } = require('chai');
const mapper = require('../src/policy-evaluation-mapper');

function getPayload(criticalComponentCount) {
  return {
    'applicationEvaluation': {
      'policyEvaluationId': 'debceb1d-9209-485d-8d07-bd5390de7ef5',
      'stage': 'build',
      'ownerId': '6a454175-f55d-4d33-ba44-90ac3af2e8b8',
      'evaluationDate': '2015-05-05T23:40:12Z',
      'affectedComponentCount': 10,
      'criticalComponentCount': criticalComponentCount,
      'severeComponentCount': 5,
      'moderateComponentCount': 3,
      'outcome': 'fail'
    }
  };
}             

We also want the message mapper to map to a payload and assert that the message is “IQ Policy Eval: 2 Critical".

describe('policy-evaluation-mapper', () => {
  it('should convert policy evaluation webhook to slack message', () => {
    const message = mapper.map(getPayload(2));

    assert.equal(message, 'IQ Policy Eval: 2 Critical Violations');
  });

  it('should convert policy evaluation webhook to slack message, no critical', () => {
    const message = mapper.map(getPayload(0));

    assert.equal(message, 'IQ Policy Eval: Free of Critical Violations');
  });
});                     

Now that we have a test written, we want to go ahead and make our mapper. In your project, make a folder called src and then create a new file called policy-evaluation-mapper.js.

The mapper will be successful if the tests don’t fail, so we’ll implement logic to create the critical violation message if there are critical violations and a congrats message if there are none.

const mapper = {};
mapper.map = (payload) => {
  const trailingMessage = payload.applicationEvaluation.criticalComponentCount
      ? `${payload.applicationEvaluation.criticalComponentCount} Critical Violations`
      : 'Free of critical violations';
  return `IQ Policy Eval: ${trailingMessage}`;
};

module.exports = mapper;

Our evaluation mapper will now take our payload and return some text. We can run the tests with ./node_modules/mocha/bin/mocha or npm test with the correct configuration. Doing so shows our first tests passing! Next, we need to verify the webhook signature and ensure that the source came from where we thought it did.

In the tests folder, make a file called webhook-signature-validator-test.js.

In here, we want to describe the webhook and what it does (validate a well-formed body with a signature). We also want to make a “fake” webhook with some headers, a body, a secret, and assert that our validator validates the request and secret. We can use OpenSSL to determine what the signature should be given to the body and our secret key:

echo -n '{"field":"value"}' | openssl sha1 -hmac "secret"

Finally, we should also check that the validator invalidates a well-formed body with an incorrect signature:

const { assert } = require('chai');
const validator = require('../src/webhook-signature-validator');

describe('webhook-signature-validator', () => {
  const request = {
    headers: {
      'x-nexus-webhook-signature': '42f0ce462b5631af387660d11c7b93a1d8ae209d'
    },
    body: {
      'field': 'value'
    }
  };

  it('should validate a well formed body with signature', () => {
    const secret = 'secret';

    assert.isTrue(validator.validate(request, secret));
  });

  it('should invalidate a well formed body with incorrect signature', () => {
    const secret = 'notsecret';

    assert.isFalse(validator.validate(request, secret));
  });
});

Now that we have tests, we can write our validator. We want to make a new file in our src folder called something like webhook-signature-validator.js.

Refer to the signature that is compared against a secret key and the body in HMAC Payloads. All requests are going to look the same from the IQ server whether it’s a policy evaluation or something else. This validator will take in the request and the secret key and ensure the request is authentic.

const crypto = require('crypto');
const validator = {};

validator.validate = (request, secretKey) => {
  const body = request.body;
  const signature = request.headers['x-nexus-webhook-signature'];
  const jsonBody = JSON.stringify(body);
  const hmacDigest = crypto.createHmac('sha1', secretKey).update(jsonBody).digest('hex');
  return signature === hmacDigest;
};

module.exports = validator;

Again, running the tests verifies that our validator is working as intended. Now that we have our validator and mapper, the next step is getting our webhook and spitting it out in Slack.

Now that we have our incoming Webhook URL from Slack, we’re going to add our validator to index.js.

We’ll set the validator request secret key as an environmental variable and call it IQ_SECRET_KEY. If the validation fails, we don’t want to do anything so we’ll just send a 401 Auth Error.

We also need our message. We wrote our mapper already, so the message will be the mapper and the payload is the body of the request. This means that we have our message and then we send it.

The Express web application framework we’re using is very lightweight and you can add modules to it. One of the modules we need to add when expecting to get JSON data is a bodyParser. Without this, the body will never exist, and we want the application to use bodyParser to take JSON data.

const serverless = require('serverless-http');
const express = require('express');
const bodyParser = require('body-parser');
const app = express();
const {IncomingWebhook} = require('@slack/client');
const validator = require('./src/webhook-signature-validator');
const mapper = require('./src/policy-evaluation-mapper');

app.use(bodyParser.json({strict: false}));

app.post('/', function(req, res) {
  if (!validator.validate(req, process.env.IQ_SECRET_KEY)) {
    res.status(401).send({error: 'Not authorized'});
    return;
  }
  const iqNotification = new IncomingWebhook(process.env.SLACK_WEBHOOK_URL);
  const message = mapper.map(req.body);
  iqNotification.send(message, (error, resp) => {
    if (error) {
      console.error(error);
      res.status(500).send({error: error});
      return;
    }
    res.send('');
  });
});

module.exports.handler = serverless(app);

We’ve already copied the incoming Slack webhook constructor into our serverless.yml file. Next, we’ll add the secret environmental variable. The Slack Developer Kit article has secrets about the environmental variables of the servers, but for this example, we’ll put them in the serverless.yml file. In a real-world scenario, we’d want to configure them on our cloud provider and not store them in source control.

service: iq-slack-integration
provider:
  name: aws
  runtime: nodejs6.10
  stage: dev
  region: us-east-1

functions:
  app:
    handler: index.handler
    events:
      - http: ANY /
      - http: 'ANY {proxy+}'
    environment:
      SLACK_WEBHOOK_URL: 'https://hooks.slack.com/services/000000000/000000000/00000000000000000000000'
      IQ_SECRET_KEY: 'secret'

plugins:
  - serverless-offline

NOTE: In general you don’t want environmental variables where people can see them! We’re just doing this for development, but you should use the correct process.