Example integration sq1shield

From Dreamtsoft Wiki
Jump to: navigation, search

Work In Progress: FULL Testing will be completed By August 15th


Integration Example For SQ1Shield

The general flow for inbound alerts is to create a REST endpoint, then process that endpoints payload with an IO handler, which will create or update an alert.

Once an alert is stored in the alert table, we will monitor it with a bucket trigger for status changes and send outbound REST calls back to SQ1.

Create a schema for the additional attributes

Created a Schmea on the bucket allows you to store specific data on the alert record that is only related to your integration.

Below we will create a new schema and add 2 fields to identify the SQ1 Alert ID and the source system.

Screenshot 2022-08-10 at 1.30.22 PM.png

Add two new slots to the schema

We created two new slots by dragging over the "slot" widget and then giving each slot a name and type.

The first slot is the source system slot identified as SQ1 Source (sq1_source).

The second slot is the ID from the SQ1 Sheild alert ID so we have the ability to push updates back into the source system when somethign changes on the Dreamtsoft side of the integration.

(both slot types are left as "string")

Screenshot 2022-08-10 at 1.34.11 PM.png

Visualizing the Schema from the Alert record

On the right-hand panel of an Alert, we now see the "Add Schema" button that allows us to add a schema.

Later in the integration, we will show you how to do this in a script so it is automated when we receive a new alert from SQ1 Sheild system.

For now, to test this, you can click on "Add Schema" to see the new data attributes that will show up when this schema is active on an alert record.

Screenshot 2022-08-10 at 1.34.57 PM.png

Select the Schema type

Here are the current schemas available in my test system, you can see multiple schemas for different integration types.


Screenshot 2022-08-10 at 1.35.04 PM.png

New attributes on the record

After selecting the schema manually, you will see those new attributes are editable and stored in the record for this alert.

Next, we will build the incoming integration point and show how to use this new schema through a REST transaction.

Screenshot 2022-08-10 at 1.35.14 PM.png

Building the REST endpoint for the SQ1 Alert Schema

From your ITSM bundle, select the "Bundle configuration" (gears icon) at the bottom of the left hand menu.

Screenshot 2022-08-11 at 12.43.50 PM.png

Select Integrate & Schedule from this bundle configuration menu

Screenshot 2022-08-11 at 12.46.20 PM.png

Create a new REST API endpoint

Once on the list of REST API endpoints, select the plus button on the upper right to create a new entry.

Screenshot 2022-08-11 at 12.55.27 PM.png


Populate the endpoint details before adding the processing script

Give your REST API endpoint a name and a path. The API URL will be updated automagically for you.

(this will be the endpoint you point your SQ1 System at for sending alerts)

Screenshot 2022-08-11 at 12.46.52 PM.png

Create a processing script to push the REST body of the integration to our IO tables for processing

Insert this example code into the 'Script' section of the REST API record.

This will create a new IO record with the alert data so we can process it and make any adjustments or changes.

(You can also do any normilizing, or additional lookups here in this script section before creating an IO record)


// A very generic example to push the REST BODY to a IO bucket
var SQ1Alert = ARestAPI.create({
 	// Process is always invoked on incoming transactions to this endpoint.
	process: function() {  
		
		var jsonBodyStr = this.getBody();  // The BODY of our REST POST
		
		var newAlert = new FRecord('io_in');  // Set the Input/Output bucket for further processing.
		newAlert.setValue('subject', "sq1_shield.received"); // Give our IO record a subject.

		newAlert.message = jsonBodyStr; // the message field in the IO bucket will contain the alert.
		newAlert.insert(); // Insert IO record for further processing.
		
		this.setContentType('application/json');
		this.setResponseCode(200); // Send 200 response back to SQ1

		return newAlert.number;  // return the Dreamtsoft ID
	},

	className: "SQ1Alert"
});

module.exports = SQ1Alert;
// End


Processing the IO message into an alert.

An IO handler is a way to do various things to the incoming data payload. Think of this as a temporary transaction table to execute specific data tasks like:

  1. Validate data fields.
  2. Lookup Additional data like Company records based on a hostname.
  3. Normalize the data feed

Create a new IO handler

Click on the Plus icon to create a new record and fill in the required fields.

The "Subjects handled" field is where we tell this IO handler to only process messages with the specific subject type we used when we sent our JSON transaction from the REST endpoint to the message bus.


Screenshot 2022-08-12 at 11.36.57 AM.png

Configure the Script to map fields

We will add an IO script to the flow so we can map fields and create or update alerts from SQ1

Screenshot 2022-08-12 at 11.38.18 AM.png

Name the IO block and connect it to start before adding the javascript.

Screenshot 2022-08-16 at 4.04.50 PM.png

Add the javascript to the script block

var sq1_payload = $record.getValue('message');

var alert = new FRecord('alert');

alert.addSchemaId('sq1_shield'); // adds the schmea ID for the schema we created.
alert.addSearch('sq1_alert_id', sq1_payload.sq1_alert_id);
alert.search(); // lookup existing alerts with sq1 ID

if (alert.next()) {
	alert.status = sq1_payload.alert_status;
	alert.update();
	$flow.result_message = 'Updated Alert SQ1 ID :' + sq1_payload.sq1_alert_id;

} else {  // No alert found, it must be new, create a new alert
	alert.status = sq1_payload.alert_status;
	alert.sq1_id = sq1_payload.sq1_alert_id;
	alert.insert();
	$flow.result_message = 'Created new Alert for SQ1 ID :' + sq1_payload.sq1_alert_id;
}

$action.success = true;


This concludes the inbound processing of an alert, at this point you should have alerts in the alert table with the SQ1 additional metadata in the form of a schema tag.

Moving on to the outbound processing of alerts in the next section, which will update the SQ1 system with status changes from the Dreamtsoft side.


Creating a bucket action to trigger outbound REST calls to SQ1 Shield

A bucket action can do many things. In this specific use case, we want an action that will be "triggered" when a status change on an alert takes place. Once the status change conditions are met, a Script will be executed, and this will send an outbound REST call to another system to update the alert at its origin (SQ1 Sheild)

Create the trigger action

Set the action to run "Before" the "Update" happens, we will not need it to run on Insert as there would be no use case where we would send a stats back when the alert is inserted into Dreamtsoft alert bucket.

The conditions are status is "being changed" (from open), to the status of "Closed",and the alert sq1_id field cannot be blank.

When the conditions are met and an alert changes from open to close in the Dreamtsoft bucket, this trigger will execute the flow defined below.

Make sure your action is active, and also, in some cases you might want to adjust the "order" of operations of all triggers. If another integration needed to be updated first, we could set this "order" field to 100.

This would allow any other actions on the alert bucket to run first, assuming that they have a lower order number than 100.


Screenshot 2022-08-16 at 2.10.29 PM.png

Define the scriptable flow

You will need to click on the "+ Add" button to add a "Run script and connect it to the Start "Always" block.

The title we created for the run script is "Send API call" and is defined in the next section.

Screenshot 2022-08-16 at 1.05.37 PM.png

Define the Script box

Open the "Send API call" script block and paste the following code into the code editor. You will need to add basic authentication or a key in the header for non-public API calls. The request_body is defined using the $record object, which points to the current alert that has changed.

// API call

var HTTPScriptable = require('core/HTTPScriptable'); // Include HTTP methods
var URL = 'https://sandbox.centrexit.sq1shield.com/api/vulnerability-api-status-update';
http = new HTTPScriptable();
var username = ;
var password = ;
var auth_key = ;

var request_body = {};
request_body.status = $record.status; // current status
request_body.sq1_alert_id = $record.sq1_id;  // This is from the schema tag

// if using basic auth, uncomment and populate username and password vars
// http.setBasicAuthentication(username, password);

// If using tokens/keys, use the header below
// http.setHeader('Example-Key', auth_key);

// Misc headers
http.setHeader('accept', 'application/json');
// Set the URL
http.setUrl(URL);
// Set the JSON body
http.setRequestBody(request_body, 'json'); 


var response = http.post();
var responseCode = response.getResponseCode();
var responseBody = JSON.parse(response.getResponseBody());

if (responseCode == 200) {
	return true;
}  else {
	console.log('WARN', 'update alert: Failed - code: ' + responseCode);
	return false;
}

Connect the blocks

Click on 'Always' from the start box, and drag the line over the to blue "Send API call" box to have the script inside that box process.

Screenshot 2022-08-16 at 1.08.06 PM.png


Test your integration

If an Alert exists in the system and contains the schema tag information for an SQ1 alert then these actions will be reviewed when stats changes.