onDetails

Run second order queries when a user expands your integration in the Overlay Window

Summary

optional function onDetails(lookupObject, options, callback)

Parameters	Description
lookupObject	An object containing the lookup object for which the onDetails request is made
options	An options object with key value pairs representing the requesting user's options and their value
callback	A Node.js style callback which should return the updated data property of the lookupObject

If implemented, the onDetails method is used to add additional details and summary tag information to a lookup result. This method is called anytime a user clicks on a summary block to expand it and view details. The onDetails hook is used to make integrations more efficient by only querying for an expanded set of details information when a user clicks to view the details. It should be used anytime the details information requires an "expensive" lookup.

The onDetails method should return a new data object made up of a details object and a summary tag array via the callback.

Parameters

The following is an explanation of the onDetails parameters.

lookupObject

function onDetails(lookupObject, options, callback)

The lookupObject parameter is an object containing the previously returned lookup result for this entity. The object contains the entity, and data properties of the previous object. The lookupObject has the following structure:

lookupObject

{
    entity: {object}
    displayValue: {string},
    isVolatile: {boolean},
    isCached: {boolean},
    data: {
        summary: {Array},
        details: {Object}
    }
 }

entity

The entity object provides information about the entity for which details are being requested. Note that this entity object is the same entity object passed into the doLookup method as part of that methods entities array.

displayValue

A string value that is used to display the given entity. Note that by default this is equal to the entity.value property.

isVolatile

A boolean value indicating whether the lookupObject should be cached or not. If true, the lookup result will not be cached (even when the cached is enabled). If false, the lookup result will be cached. Note that this value defaults to false when not specified.

isCached

A boolean value indicating whether or not the lookupObject was served out of the cache.

data.details

The details object for this lookupObject.

data.summary

An array of strings that represent tags to be rendered in the summary block.

// Example lookup object
{
    entity: {
        value: '56.2.3.2'
        type: 'IP',
        types: ['IP', 'IPv4'],
        isIPv4: true
        ...//additional entity object properties
    },
    displayValue: '56.2.3.2',
    isVolatile: false,
    isCached: false,
    data: {
        details: {
           severity: 90,
           confidence: 'high',
           source: 'Internet'
        }
        summary: ['malicious']
    }
 }

options

function onDetails(lookupObject, options, callback)

The second parameter to the onDetails method is the options object which contains the values for the integration options as set in the integration config.js. Note that for per-user settings the value in the options object will reflect the value of the user requesting the lookup.

The key in the options object is the same value of the key property set in the integration config.js file.

Options Object

{
    "apiKey": "lkasjdioajsdoij12lk3j1lk23j12",
    "lookupHashes": true,
    "throttleLookups": false
}

callback(error, results)

function onDetails(lookupObject, options, callback)

The callback must be called before execution of the onDetails method completes. The callback accepts two parameters.

The first parameter is an error which can either be a string literal or an error object. In the case of a string literal the returned string is displayed as an error in the notification window as well as tracked as an error in the integration.

If you have no error to return you should return null for the error parameter.

The second parameter is the data parameter. The data parameter is the new data object for this lookupResult. The data parameter is an object that contains a details object and summary array.

//callback parameters
callback(error, data);

Examples

The following is a snippet of example code that shows how you can add additional summary tags to the lookupObject as well as set details to be returned to the overlay window.

Note that in this example, we are replacing any existing data in the lookupObject.data.details object. In addition, we are preserving the existing summary tags by pushing the new tags onto the existing summary array. If we replaced the summary array entirely then we would lose any existing tags for the entity.

function onDetails(lookupObject, options, cb) {
    // Add additional summary tags
    lookupObject.data.summary.push("New Tag 1");
    lookupObject.data.summary.push("New Tag 2");

    // Add a new details object
    lookupObject.data.details = {
        // set your new details here
    };

    // Return the modified data object
    cb(null, lookupObject.data);
}

In cases where you don't want to replace the existing details information you can simply add a new property to the existing details and return that information. Note that in this example we are not modifying the summary tags and simply passing back the existing tags.

function onDetails(lookupObject, options, cb) {
    // Add new information to the details without overriding any existing information
    lookupObject.data.details.newData = {
        newKey: "this is some new data"
    };

    // Return the modified data object
    cb(null, lookupObject.data);
}