JavaScript® SDK

About This Document

This section explains the process of coding JavaScript applications, and the implementation of the JavaScript SDK, using the ThreatConnect API. The JavaScript SDK offers coverage of all features of the ThreatConnect API, including the ability to write data to ThreatConnect.

The goal of this JavaScript SDK library is to provide a programmatic abstraction layer around the ThreatConnect API without losing functional coverage over the available API resources. This abstraction layer enables developers to focus on writing enterprise functionality without worrying about low-level RESTful calls and authentication management.

This document is not a replacement for the ThreatConnect API User Guide but serves as a companion to the official documentation for the REST API. Read the official documentation to gain a further understanding of the functional aspects of using the ThreatConnect API.

How to Use This Document

This document explains how to create Groups, Indicators, Associations, Tags, Security Labels, and Victims. Along with creating data elements, a developer will learn how to create, update, delete, and request data from the API using JavaScript. This document assumes the reader knows the JavaScript programming language.

All code examples will be noted in a separate box with a monospaced font and line numbers to facilitate explanation of code functionality.

Getting Started

An example of using configuration to read API configuration values is the following:

var apiSettings,
    tcSpaceElementId = getParameterByName('tcSpaceElementId');

if ( tcSpaceElementId ) {
    apiSettings = {
        apiToken: getParameterByName('tcToken'),
        apiUrl: getParameterByName('tcApiPath')
    };
} else {
    apiSettings = {
        apiId: '12345678900987654321',
        apiSec: 'aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz!@#$%^&*()-=',
        apiUrl: 'https://api.threatconnect.com'
    };
}

Note

If you are working with the ThreatConnect sandbox, the second apiSettings.apiUrl (the one in the else branch) should be: https://sandbox.threatconnect.com/api/ instead of https://api.threatconnect.com.

<!-- JQuery -->
<script src="./libs/jquery-2.1.4.min.js" type="test/javascript"></script>

<!-- HMAC -->
<script src="./libs/core.js" type="text/javascript"></script>
<script src="./libs/sha256.js" type="text/javascript"></script>
<script src="./libs/hmac.js" type="text/javascript"></script>
<script src="./libs/enc-base64.js" type="text/javascript"></script>

<!-- ThreatConnect -->
<script src="./libs/threatconnect.js" type="text/javascript"></script>

The JavaScript SDK is written to support ECMAScript®-5 and should work in most modern browsers.

To use the RESTful API for ThreatConnect, an API user must be provisioned. See the ThreatConnect API User Guide for details on how to create an API user as it is out of scope for this document.

The JavaScript SDK can be configured to use an Access ID and Secret Key or a Token. Token support is only available when working with a Spaces application.

Once the configuration has been set up, the developer should be able to run the examples in this document as long as the JavaScript SDK has been installed.

The following example illustrates a typical initialization of the ThreatConnect Object:

var tc = new ThreatConnect(apiSettings);

Third-Party Dependencies

Name	Version	Link
jquery	2.1.4	https://jquery.com/
Crypto-JS	3.1	https://code.google.com/p/crypto-js/

Technical Design

The JavaScript SDK for ThreatConnect was designed with a focus on abstracting the API REST calls while enabling the developer to use an enterprise-level programming language.

Supported Resource Types

The JavaScript SDK supports the Resource Types listed below. There is also a mechanism to do manual API requests to cover any API calls that are not provided with the core functionality.

Object	Description
db()	Data Store container object
groups()	Group container object
indicators()	Indicator container object
indicatorsBatch()	Batch Indicator container object
owners()	Owner container object
securityLabel()	Security Label container object
tasks()	Task container object
tags()	Tag container object
victims()	Victim container object
whoami()	WhoAmI container object

Example JavaScript App

The example below illustrates how to write a program using the JavaScript SDK for the ThreatConnect API:

var apiSettings;

// retrieve Space Element ID (only supported for Spaces applications running in ThreatConnect)
var tcSpaceElementId = getParameterByName('tcSpaceElementId');

// if the Space Element ID exists, pull the token and api from the spaces environment
if ( tcSpaceElementId ) {
    apiSettings = {
        apiToken: getParameterByName('tcToken'),
        apiUrl: getParameterByName('tcApiPath')
    };
}
// otherwise, use the API settings defined below
else {
    apiSettings = {
        apiId: '12345678900987654321',
        apiSec: 'aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz!@#$%^&*()-=',
        apiUrl: 'https://demo.threatconnect.com/api'
    };
}

// create ThreatConnect object
var tc = new ThreatConnect(apiSettings);

// create Owners object
tc.owners()
    // if the call finishes successfully, the "done" callback will be run
    .done(function(response) {
        console.log('owner response', response);
    })
    // if the call does NOT finish successfully, the "error" callback will be run
    .error(function(response) {
        console.error('owner response error', response.error);
    })
    // retrieve Owners
    .retrieve();

This example illustrates how to write a program using the JavaScript SDK for the ThreatConnect API. An Owner’s object will be created in order to pull a collection of all Owners to which the API account being used has access. Once retrieved, the Owners objects will be printed to the console.

Summary

This section explained how to:

• Connect to the ThreatConnect API

• Get a list of Owners

Developing a JavaScript App

This section provides an overview of the JavaScript app-development process as it pertains to the Spaces feature within ThreatConnect. This section will also review how to package an app for deployment to the ThreatConnect platform.

Deployment Configuration

Apps use a deployment configuration file to define variables and execution environment. You can read more about the deployment configuration file here.

Query Parameters

For the install configuration example above, here is a sample query String passed to the app:

tcSpaceElementId=467&tcToken=ABC123&tcApiPath=https://api.threatconnect.com:8443&tcType=Host&tcSelectedItem=greystoneexpress.com&tcSelectedItemOwner=TestOrg&add_tags=OpenDNS Scan&add_confidence=25&add_rating=1&opendns_api_token=abc-123&logging=info

All Spaces apps will have standard ‘tc’ prefixed parameters passed that may be used by the app.

The above query string can be parsed with the following JavaScript code:

$(document).ready(function () {

    var type = getParameterByName("tcType");
    var selectedItem = getParameterByName("tcSelectedItem");

    // startApp(type, selectedItem);
});

All visible parameters defined in the configuration file will be passed to the Spaces app via a query String. The Spaces app is responsible for retrieving parameter values via the SDK’s convenience function getParameterByName.

All Spaces apps will have standard ‘tc’ prefixed parameters passed that may be used by the app.

Optional Properties

There are some optional flags that may be used by the app to

• handle Boolean flags that turn features on/off and;

• encrypt parameters, like API Keys

Parsing Argument Flags

Apps can also use Boolean flags to designate whether to turn on a specific feature.

The configuration file must have the following flag present for a Boolean parameter:

param.<param-name>.flag

This property will direct the ThreatConnect application to show a checkbox to the Spaces configuration. The flag will be passed to the Spaces app with a true or false parameter value.

Encrypted Parameters

This property is used to encrypt private passwords that are used by the app (e.g., API keys). This added level of security will allow the application to persist the password in encrypted form when at rest. The input field during job creation will be “password” text, and the key will not be visible when typed.

The configuration property is defined for the encrypted parameter using the following flag:

param.<param-name>.encrypted

At runtime, ThreatConnect will call the Spaces app with the decrypted key. At no point is the password persisted in decrypted form.

Encrypted apps require that the Keychain feature be turned on, or apps with .encrypted parameters will not run properly.

ThreatConnect Parameters

ThreatConnect passes standard parameters to all jobs within its standard sandbox container. There should be no assumptions made on the naming or existence of paths passed in these variables outside of the lifetime of the job execution.

Since all Spaces apps are managed within ThreatConnect, app developers should never hard-code ThreatConnect Parameters

ThreatConnect Parameter	Description
tcSpaceElementId	The unique Space-element instance ID for users that added this app to their Space. This numeric ID can be used by the app to store state for the user.
tcToken	Session token to be used by the app to access the API. The JavaScript SDK has configuration options for this parameter.
tcApiPath	The path to the API defined in System Settings for all apps.
tcType	Only relevant for context-aware apps. This field corresponds to the runtime.context Attribute defined in the install configuration file.
tcSelectedItem	Only relevant for context-aware apps. This is the actual context-item identifier used within ThreatConnect. For instance, a Host identifier might be: g00gle.com
tcSelectedItemOwner	Only relevant for context-aware apps. This is the Owner of the context item.

JavaScript Examples

• SDK Sample index.html

Authentication

The example below demonstrates how to authenticate and add an Indicator via the ThreatConnect API, using the JavaScript programming language.

Dependencies

File	URL
enc-base-64.js	https://code.google.com/p/crypto-js/downloads
hmac-sha256.js	https://code.google.com/p/crypto-js/downloads
sha256.js	https://code.google.com/p/crypto-js/downloads

Dependencies Installation (Linux)

Run these commands to install dependencies:

mkdir lib
unzip CryptoJS\ v3.1.2.zip
cp CyrptoJS\ v3.1.2/enc-base-64.js lib/
cp CyrptoJS\ v3.1.2/hmac-sha256.js lib/
cp CyrptoJS\ v3.1.2/sha256.js lib/

tc.js code sample:

var CryptoJS = require('./lib/hmac-sha256.js'),
    Base64 = require('./lib/enc-base-64.js'),
    https = require('https'),
    querystring = require('querystring'),
    url = require('url');

// https.globalAgent.maxSockets = 20;

var request_time = 0;
CryptoJS = CryptoJS.CryptoJS;

var SETTINGS = {
    api_secret_key: '<ENTER API SECRET KEY HERE>',
    api_access_id: '<ENTER API ACCESS ID HERE>',
    api_base_url: '<ENTER API BASE URL HERE>',
    api_port: '443',
    verify_ssl: false
};

function getUTC() {
    var date = new Date().getTime();
    return Math.floor(date / 1000);
}

function api_request_headers(request_method, api_uri) {
    var timestamp = getUTC(),
        signature = api_uri + ":" + request_method + ":" + timestamp,
        hmac_signature = CryptoJS.HmacSHA256(signature, SETTINGS.api_secret_key),
        authorization = "TC " + SETTINGS.api_access_id + ":" + CryptoJS.enc.Base64.stringify(hmac_signature);

    return { "Timestamp": timestamp, "Authorization": authorization };
}

function apiRequest(request_uri, request_payload, http_method, body, activity_log, content_type) {
    /*
     * Default Values
     */
    activity_log = (activity_log === undefined) ? "false" : activity_log;
    // console.log('activity_log: %s', activity_log);
    body = (body === undefined) ? null : body;
    // console.log('body: %s', body);
    content_type = (content_type === undefined) ? "application/json" : content_type;
    // console.log('content_type: %s', content_type);
    http_method = (http_method === undefined) ? "GET" : http_method.toUpperCase();
    // console.log('http_method: %s', http_method);
    request_payload = (request_payload === undefined) ? {} : request_payload;
    request_payload["createActivityLog"] = activity_log;
    // console.log('request_payload: %s', request_payload);

    request_start = getUTC();

    if (SETTINGS.verify_ssl == false) {
        process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
    }

    /*
     * Prepare Request
     */
    api_url = request_uri + "?" + querystring.stringify(request_payload);
    // console.log('api_url: %s', api_url);
    path_url = url.parse(api_url).path;
    // console.log('path_url: %s', path_url);
    api_headers = api_request_headers(http_method, path_url)


    /*
     * POST
     */
    if (http_method.toUpperCase() == "POST") {
        api_headers["Content-Type"] = content_type;
        api_headers["Content-Length"] = body.length;
    }
    // console.log(JSON.stringify(api_headers, null, 4));

    /*
     * Options
     */
    var options = {
        host: SETTINGS.api_base_url,
        port: SETTINGS.api_port,
        method: http_method,
        path: api_url,
        headers: api_headers,
        keepAlive: 1,
        agent: false
    };
    // console.log(JSON.stringify(options, null, 4));

    /*
     * API call
     */
    // options.agent = new https.Agent(options);
    var api_request = https.request(options, function(res) {
        // console.log('STATUS: ' + res.statusCode);
        // console.log('HEADERS: ' + JSON.stringify(res.headers, null, 4));
        /*
        res.setEncoding('utf8');
        res.on('data', function (chunk) {
            console.log('BODY: ' + chunk);
        });
        */
    });

    api_request.write(body);
    api_request.end();

    request_time += (getUTC() - request_start);
}

function quick_add_ip(ip, rating, confidence, owner) {
    rating = (rating === undefined) ? null : rating;
    confidence = (confidence === undefined) ? null : confidence;
    owner = (owner === undefined) ? null : owner;

    request_uri = '/api/v2/indicators/addresses';

    /* body */
    var body = {"ip": ip};
    if (rating != null) {
        body["rating"] = rating;
    }
    if (confidence != null) {
        body["confidence"] = confidence;
    }

    /*
     * owner
     */
    if (owner != null) {
        var request_payload = {"owner":owner};
    } else {
        var request_payload = {}
    }
    // console.log("%s %j %j", request_uri, request_payload, body)
    apiRequest(request_uri, request_payload, 'POST', JSON.stringify(body), "false", "application/json")
}

var owner = "Example Community";
quick_add_ip('4.3.2.1', '2.5', '75', owner);

In the directory in which the script will be installed, run the commands in the right column. Once completed, place the example contents in tc.js.

Indicator Retrieve

This section explains how to work with ThreatConnect Indicator Resources.

Supported Indicator Types

Indicator Name	Indicator Constant
Address	TYPE.ADDRESS
Email Address	TYPE.EMAIL_ADDRESS
File	TYPE.FILE
Host	TYPE.HOST
URL	TYPE.URL

Retrieve Indicator

Example of Retrieving Indicators:

var indicators = tc.indicators();

indicators.owner('Example Community')
    // .type(TYPE.ADDRESS)
    .resultLimit(500)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieve(function() {
        if (indicators.hasNext()) {
            indicators.next()
        }
    });

This example will demonstrate how to retrieve Indicators. The result set returned from this example will contain the first 500 Indicators in the “Example Community” Owner.

Retrieve Next

Example of retrieve.next method:

if (indicators.hasNext()) {
    indicators.next();
}

Example Results of the retrieve.next method:

{
  "data": [
    {
      "id": 97262,
      "indicator": "badguys.org",
      "dateAdded": "2015-12-14T02:16:38Z",
      "lastModified": "2015-12-14T02:16:38Z",
      "ownerName": "Example Community",
      "type": "Host",
      "webLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=badguys.org&owner=Example+Community"
    },
    {
      "id": 94977,
      "indicator": "74.121.142.111",
      "dateAdded": "2015-12-12T01:24:28Z",
      "lastModified": "2015-12-13T23:22:28Z",
      "ownerName": "Example Community",
      "rating": 4,
      "confidence": 75,
      "type": "Address",
      "webLink": "https://app.threatconnect.com/auth/indicators/details/address.xhtml?address=74.121.142.111&owner=Example+Community"
    },
    {
      "id": 94980,
      "indicator": "74.121.139.80",
      "dateAdded": "2015-12-12T01:24:28Z",
      "lastModified": "2015-12-12T01:24:28Z",
      "ownerName": "Example Community",
      "rating": 4,
      "confidence": 50,
      "type": "Address",
      "webLink": "https://app.threatconnect.com/auth/indicators/details/address.xhtml?address=74.121.139.80&owner=Example+Community"
    }
  ],
  "remaining": 35,
  "url": "https://app.threatconnect.com/v2/indicators?owner=Example+Community&resultLimit=5",
  "apiCalls": 1,
  "resultCount": 40,
  "status": "Success"
}

The JavaScript SDK provide the hasNext() method for checking if more entries are available. To retrieve the next set of entries, the next() method is available.

Note

Before the next() method can be called, the first API must have completed. This should not be an issue if a user click triggers the next call; however, if the next() method is being called programmatically, then it should be passed in a function to the retrieve() method.

Note

The next() method will return the same number of results defined in the resultsLimit() or the number of results remaining. The same ‘done’ and ‘error’ callbacks are also used for the next set of results.

Single Indicator

This example will demonstrate how to retrieve a Single Indicator:

var indicators = tc.indicators();

indicators.owner('Example Community')
    .type(TYPE.ADDRESS)
    .indicator('10.20.30.40')
    .includeAdditional(true)     // OPTIONAL: include observationCount and faslePositiveCount
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieve()

Single Indicator retrieve Example Results:

{
    "data": [
        {
            "id": 97934,
            "indicator": "10.20.30.40",
            "dateAdded": "2015-12-14T23:23:00Z",
            "lastModified": "2016-01-14T23:47:53Z",
            "ownerName": "Example Community",
            "rating": 3,
            "confidence": 0,
            "observationCount": 1,
            "falsePositiveCount": 0,
            "type": "Address",
            "webLink": "https://app.threatconnect.com/auth/indicators/details/address.xhtml?address=10.20.30.40&owner=Example+Community"
        }
    ],
    "remaining": 0,
    "url": "https://api.threatconnect.com/v2/indicators/addresses/10.20.30.40?owner=Example+Community&includeAdditional=true",
    "apiCalls": 1,
    "resultCount": 0,
    "status": "Success"
}

Filters

The following is an example of how to retrieve Indicators that start with ‘bad’ and have a dateAdded value greater than ‘2015-12-13’ using an API filter:

var filter = new Filter(FILTER.AND);
filter.on('summary', FILTER.SW, 'bad');
filter.on('dateAdded', FILTER.GT, '2015-12-13');

var indicators = tc.indicators();

indicators.owner('Example Community')
    .resultLimit(500)
    .filter(filter)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieve();

Starting with ThreatConnect version 4.0 the API supports filtering using query string parameters. For more information on which parameters support which operators, see the ThreatConnect API Users Guide.

Filter Options

Filter	Filter Constant
And	FILTER.AND
Or	FILTER.OR
Equal (=)	FILTER.EQ
Greater Than (>)	FILTER.GT
Greater Than or Equal (>=)	FILTER.GE
Less Than (<)	FILTER.LT
Less Than or Equal (<=)	FILTER.LE
Starts With (^)	FILTER.SW

Note that multiple filters can be added to one API call.

Batch/Bulk Retrieve

Example of Batch/Bulk Retrieve:

var indicators = tc.indicatorsBatch();

indicators.owner('Example Community')
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieve('json');

Filters are not supported on Batch/Bulk downloads.

Associations

var indicators = tc.indicators();

indicators.owner('Example Community')
    .indicator('74.121.142.111')
    .type(TYPE.ADDRESS)
    .resultLimit(5)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieveAssociations({
        type: TYPE.INCIDENT
    });

The JavaScript SDK provides the retrieveAssociations() method to retrieve both Indicator and Indicator Associations. The type() and indicator() methods are required to retrieve the associations. The retrieveAssociations() method requires that a parameter object containing the Association type be provided. Optionally, an association id can be provided to pull a specific association.

Attributes

Example of retrieveAttributes() method:

var indicators = tc.indicators();

indicators.owner('Example Community')
    .indicator('74.121.142.111')
    .type(TYPE.ADDRESS)
    .resultLimit(5)
    .done(function(response) {
        console.log('response', response);
        $('#response-content').append(JSON.stringify(response, null, 4));
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieveAttributes();

The JavaScript SDK provides the retrieveAttributes() method to retrieve Attributes. Both the type() method and indicator() are required to retrieve the Attributes. An id can be passed to the retrieveAttributes() method to retrieve a specific aAttribute.

Retrieve Observations

var indicators = tc.indicators();

indicators.owner('Example Community')
    .indicator('74.121.142.111')
    .type(TYPE.ADDRESS)
    .resultLimit(5)
    .done(function(response) {
        console.log('response', response);
        $('#response-content').append(JSON.stringify(response, null, 4));
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieveObservations();

The JavaScript SDK provides the retrieveObservations() method to retrieve Observations. Both the type() and indicator() methods are required to retrieve the Observations.

Retrieve Observation Count

var indicators = tc.indicators();

indicators.owner('Example Community')
    .indicator('74.121.142.111')
    .type(TYPE.ADDRESS)
    .done(function(response) {
        console.log('response', response);
        $('#response-content').append(JSON.stringify(response, null, 4));
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieveObservationCount();

The JavaScript SDK provides the retrieveObservationCount() method to retrieve the Observation Count for an Indicator. Both the type() and indicator() methods are required to retrieve the Observation Count.

Note

The Observation Count can also be retrieved with the “Single Indicator” method described above, using the includeAdditional parameter.

Retrieve Security Labels Method

Example of retrieveSecurityLabel() method:

var indicators = tc.indicators();

indicators.owner('Example Community')
    .indicator('74.121.142.111')
    .type(TYPE.ADDRESS)
    .resultLimit(5)
    .done(function(response) {
        console.log('response', response);
        $('#response-content').append(JSON.stringify(response, null, 4));
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieveSecurityLabel();

Retrieve Tags Method

Example of retrieveTags() method:

var indicators = tc.indicators();

indicators.owner('Example Community')
    .indicator('74.121.142.111')
    .type(TYPE.ADDRESS)
    .resultLimit(5)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieveTags();

The JavaScript SDK provides the retrieveTags() method to retrieve tags. Both the type() and indicator() methods are required to retrieve the tags.

Tags Retrieve

Example of how to retrieve Tags:

tc.tags()
    .owner('Example Community')
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieve();

Example of retrieve Tags results:

{
  "data": [
    {
      "name": "APT",
      "webLink": "https://app.threatconnect.com/auth/tags/tag.xhtml?tag=APT&owner=Example+Community"
    },
    {
      "name": "BadGuy",
      "webLink": "https://app.threatconnect.com/auth/tags/tag.xhtml?tag=BadGuy&owner=Example+Community"
    },
    {
      "name": "blah",
      "webLink": "https://app.threatconnect.com/auth/tags/tag.xhtml?tag=blah&owner=Example+Community"
    },
    {
      "name": "threat_tag",
      "webLink": "https://app.threatconnect.com/auth/tags/tag.xhtml?tag=threat_tag&owner=Example+Community"
    }
  ],
  "remaining": 0,
  "url": "https://api.threatconnect.com/v2/tags",
  "apiCalls": 1,
  "resultCount": 11,
  "status": "Success"
}

This section explains how to work with ThreatConnect Tags Resources.

This example will demonstrate how to retrieve Tags. The result set returned from this example will contain all Tags to which the API credential being used has access. Optionally, the name() method can be used to pass a specific Tag name.

Owners Retrieve

Retrieve Owners Example:

tc.owners()
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieve();

Example Owners Results:

{
  "data": [
    {
      "id": 2,
      "name": "SumX",
      "type": "Organization"
    },
    {
      "id": 3,
      "name": "Local Common Community",
      "type": "Source"
    },
    {
      "id": 4,
      "name": "Blocklist.de Source",
      "type": "Source"
    },
    {
      "id": 10,
      "name": "Example Community",
      "type": "Community"
    }
  ],
  "remaining": 0,
  "url": "https://demo.threatconnect.com/api/v2/owners",
  "apiCalls": 1,
  "resultCount": 9,
  "status": "Success"
}

This section explains how to work with ThreatConnect Owners Resources.

Metrics

Retrieving Owner Metrics:

tc.owners()
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieveMetrics();

Starting with ThreatConnect platform version 4.0 retrieving Owner metrics is supported. Owner metrics provides the summed data for the last 15 days. Optionally the id() method can be used to pass a specific Owner ID.

Example Metrics Results:

{
    "data":
    {
        "ownerMetric": [
        {
            "metricDate": "2016-08-20",
            "totalIndicator": 140,
            "totalHost": 140,
            "totalAddress": 0,
            "totalEmailAddress": 0,
            "totalFile": 0,
            "totalUrl": 0,
            "totalGroup": 0,
            "totalThreat": 0,
            "totalIncident": 0,
            "totalEmail": 0,
            "totalCampaign": 0,
            "totalAdversary": 0,
            "totalSignature": 0,
            "totalTask": 0,
            "totalDocument": 0,
            "totalTag": 0,
            "totalTrack": 0,
            "totalResult": 0,
            "totalIndicatorAttribute": 140,
            "totalGroupAttribute": 0,
            "averageIndicatorRating": 3.61,
            "averageIndicatorConfidence": 27,
            "totalEnrichedIndicator": 140,
            "totalGroupIndicator": 0,
            "totalObservationDaily": 0,
            "totalObservationIndicator": 5,
            "totalObservationAddress": 0,
            "totalObservationEmailAddress": 0,
            "totalObservationFile": 0,
            "totalObservationHost": 5,
            "totalObservationUrl": 0,
            "totalFalsePositiveDaily": 0,
            "totalFalsePositive": 0
        },
        {
            "metricDate": "2016-08-20",
            "totalIndicator": 53876,
            "totalHost": 0,
            "totalAddress": 53876,
            "totalEmailAddress": 0,
            "totalFile": 0,
            "totalUrl": 0,
            "totalGroup": 0,
            "totalThreat": 0,
            "totalIncident": 0,
            "totalEmail": 0,
            "totalCampaign": 0,
            "totalAdversary": 0,
            "totalSignature": 0,
            "totalTask": 0,
            "totalDocument": 0,
            "totalTag": 0,
            "totalTrack": 0,
            "totalResult": 0,
            "totalIndicatorAttribute": 107752,
            "totalGroupAttribute": 0,
            "averageIndicatorRating": 3,
            "averageIndicatorConfidence": 53,
            "totalEnrichedIndicator": 53876,
            "totalGroupIndicator": 0,
            "totalObservationDaily": 6,
            "totalObservationIndicator": 8763,
            "totalObservationAddress": 8763,
            "totalObservationEmailAddress": 0,
            "totalObservationFile": 0,
            "totalObservationHost": 0,
            "totalObservationUrl": 0,
            "totalFalsePositiveDaily": 0,
            "totalFalsePositive": 5
        },
        ...
        {
            "metricDate": "2016-09-03",
            "totalIndicator": 74,
            "totalHost": 20,
            "totalAddress": 38,
            "totalEmailAddress": 3,
            "totalFile": 7,
            "totalUrl": 6,
            "totalGroup": 6,
            "totalThreat": 0,
            "totalIncident": 4,
            "totalEmail": 2,
            "totalCampaign": 0,
            "totalAdversary": 0,
            "totalSignature": 0,
            "totalTask": 0,
            "totalDocument": 0,
            "totalTag": 6,
            "totalTrack": 0,
            "totalResult": 0,
            "totalIndicatorAttribute": 159,
            "totalGroupAttribute": 4,
            "averageIndicatorRating": 4.93,
            "averageIndicatorConfidence": 94,
            "totalEnrichedIndicator": 56,
            "totalGroupIndicator": 5,
            "totalObservationDaily": 0,
            "totalObservationIndicator": 14,
            "totalObservationAddress": 14,
            "totalObservationEmailAddress": 0,
            "totalObservationFile": 0,
            "totalObservationHost": 0,
            "totalObservationUrl": 0,
            "totalFalsePositiveDaily": 0,
            "totalFalsePositive": 0
        }]
    },
    "remaining": 0,
    "url": "https://api.threatconnect.com/v2/owners/metrics?resultLimit=500",
    "apiCalls": 1,
    "resultCount": 0,
    "status": "Success"
}

Group Retrieve

This section explains how to work with ThreatConnect Group Resources.

Supported Group Types

Group Name	Group Constant
Adversary	TYPE.ADVERSARY
Document	TYPE.DOCUMENT
Email	TYPE.EMAIL
Incident	TYPE.INCIDENT
Signature	TYPE.SIGNATURE
Threat	TYPE.THREAT

Retrieve Group

The following is an example of how to retrieve Adversaries:

groups = tc.groups();

groups.owner('Example Community')
    .type(TYPE.ADVERSARY)
    .resultLimit(500)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieve();

This example will demonstrate how to retrieve Adversaries. The result set returned from this example will contain the first 500 Adversaries in the “Example Community” Owner.

Retrieve Next

Example of hasNext() method:

while (groups.hasNext()) {
    groups.next();
}

Example of Results:

{
  "data": [
    {
      "id": 81,
      "name": "adver-000",
      "ownerName": "Example Community",
      "dateAdded": "2015-10-30T05:46:21Z",
      "webLink": "https://api.threatconnect.com/auth/adversary/adversary.xhtml?adversary=81"
    },
    {
      "id": 189,
      "name": "adver-001",
      "ownerName": "Example Community",
      "dateAdded": "2015-11-02T13:55:45Z",
      "webLink": "https://api.threatconnect.com/auth/adversary/adversary.xhtml?adversary=189"
    },
    {
      "id": 1,
      "name": "adver-015",
      "ownerName": "Example Community",
      "dateAdded": "2015-10-23T21:10:14Z",
      "webLink": "https://api.threatconnect.com/auth/adversary/adversary.xhtml?adversary=200"
    }
  ],
  "remaining": 0,
  "url": "https://api.threatconnect.com/v2/groups/adversaries/?createActivityLog=false&resultLimit=500&resultStart=0&owner=Example+Community",
  "apiCalls": 1,
  "resultCount": 3,
  "status": "Success"
}

The JavaScript SDK provide the hasNext() method for checking if more entries are available. To retrieve the next set of entries the next() method is available.

Note

Before the next() method can be called, the first API must have completed. This should not be an issue if a user click triggers the next call; however, if the next() method is being called programmatically, then it should be passed in a function to the retrieve() method.

Note

The next() method will return the same number of results defined in the resultsLimit() or the number of results remaining. The same ‘done’ and ‘error’ callbacks are also used for the next set of results.

Security Labels Retrieve

The following is an example of how to retrieve all Security Labels belonging to the given Owner:

tc.securityLabel()
    .owner('Example Community')
    .done(function(response) {
        console.log('response', response);
        $('#response-content').append(JSON.stringify(response, null, 4));
    })
    .error(function(response) {
        console.error('error response', response);
        $('#response-content').append(JSON.stringify(response, null, 4));
    })
    .retrieve();

The following is an example of retrieve Tags results:

{
    "data": [
    {
        "name": "TLP:AMBER",
        "description": "Recipients may only share TLP:AMBER information with members of their own organization who need to know, and only as widely as necessary to act on that information.",
        "dateAdded": "2013-09-24T15:34:51Z",
        "color": "ffbf00"
    },
    {
        "name": "TLP:GREEN",
        "description": "Recipients may share TLP:GREEN information with peers and partner organizations within their sector or community, but not via publicly accessible channels.",
        "dateAdded": "2013-09-24T15:34:37Z",
        "color": "33ff00"
    },
    {
        "name": "TLP:RED",
        "description": "Recipients may not share TLP:RED information with any parties outside of the specific exchange, meeting, or conversation in which it is originally disclosed.",
        "dateAdded": "2013-09-24T15:35:27Z",
        "color": "ff0033"
    },
    {
        "name": "TLP:WHITE",
        "description": "TLP:WHITE information may be distributed without restriction, subject to copyright controls.",
        "dateAdded": "2013-09-24T15:34:12Z",
        "color": "ffffff"
    }],
    "remaining": 0,
    "url": "https://api.threatconnect.com/v2/securityLabels?resultLimit=500&owner=Example+Community",
    "apiCalls": 1,
    "resultCount": 4,
    "status": "Success"
}

Optionally the name() method can be used to pass a specific Security Label name.

Retrieve Associations

The following is an example of group retrieveAssociations() method:

tc.groups()
    .owner('Example Community')
    .type(TYPE.INCIDENT)
    .id(123)
    .done(function(response) {
        var associatedIndicators = response['data'];

        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieveAssociations({
        type: TYPE.INDICATOR
        /*
        type: TYPE.ADVERSARY,
        id: 253
        */
    });

The JavaScript SDK provides the retrieveAssociations() method to retrieve both Indicator and Group Associations. The type() and id() methods are required to retrieve the Associations. The retrieveAssociations() method requires that a parameter object containing the Association type be provided. Optionally, an id can be provided to pull a specific associated Group.

Retrieve Attributes

The following is an example of retrieveAttributes() method:

tc.groups()
    .owner('Example Community')
    .type(TYPE.INCIDENT)
    .id(173)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieveAttributes();

The JavaScript SDK provides the retrieveAttributes() method to retrieve Attributes. Both the type() method and id() are required to retrieve the Attributes. Optionally, an id can be passed to the retrieveAttributes() method to retrieve a specific Attribute.

Retrieve Tags

The following is an example of retrieveTags() method:

tc.groups()
    .owner('Example Community')
    .type(TYPE.INCIDENT)
    .id(173)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieveTags();

The JavaScript SDK provides the retrieveTags() method to retrieve Tags. Both the type() method and id() are required to retrieve the Tags.

Retrieve Security Labels

The following is an example of retrieveSecurityLabel() method:

tc.groups()
    .owner('Example Community')
    .type(TYPE.INCIDENT)
    .id(256)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieveSecurityLabel();

The JavaScript SDK provides the retrieveSecurityLabel() method to retrieve Security Labels. Both the type() method and id() are required to retrieve the Security Label.

Retrieve Tasks

This example will demonstrate how to retrieve Tasks. The result set returned from this example will contain all Tasks to which the API credential being used have access. Optionally, the id() method can be used to pass a specific Task id to retrieve.

Example

tc.tasks()
    .owner('Example Community')
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieve();

Example Results

{
  "data": [{
    "id": 571,
    "name": "Test Task",
    "ownerName": "Example Community",
    "dateAdded": "2016-03-11T20:15:52Z",
    "webLink": "https://app.threatconnect.com/auth/workflow/task.xhtml?task=571",
    "status": "In Progress",
    "escalated": false,
    "reminded": false,
    "overdue": true,
    "dueDate": "2016-03-11T00:00:00Z",
    "reminderDate": "2016-03-14T20:14:00Z",
    "escalationDate": "2016-03-22T20:14:00Z"
  }],
  "remaining": 0,
  "url": "https://api.threatconnect.com/v2/tasks?resultLimit=500&owner=Example+Community",
  "apiCalls": 1,
  "resultCount": 1,
  "status": "Success"
}

Retrieve Victims

This example will demonstrate how to retrieve Victims. The result set returned from this example will contain all Victims to which the API credential being used have access. Optionally the id() method can be used to pass a specific Victim id to retrieve.

Example

tc.victims()
    .owner('Example Community')
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .retrieve();

Example Results

{
    "data": [{
        "id": 20,
        "name": "Robin Scherbatsky",
        "org": "Fox News",
        "suborg": "Anchor",
        "workLocation": "New York City, New York",
        "nationality": "Canadian",
        "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=20"
    }, {
        "id": 4,
        "name": "Bob Steal",
        "org": "Fox News",
        "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=4"
    }, {
        "id": 3,
        "name": "Rodney Pear",
        "org": "Fox News",
        "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=3"
    }],
    "remaining": 0,
    "url": "https://api.threatconnect.com/api/v2/victims?resultLimit=500&owner=Example+Community",
    "apiCalls": 1,
    "resultCount": 3,
    "status": "Success"
}

Indicator Commit

This section explains how to work with ThreatConnect Indicator Resources.

Supported Indicator Types

Indicator Name	Indicator Constant
Address	TYPE.ADDRESS
Email Address	TYPE.EMAIL_ADDRESS
File	TYPE.FILE
Host	TYPE.HOST
URL	TYPE.URL

Commit Indicator

The following is an example of how to add an Address Indicator to the “Example Community” Owner:

var indicators = tc.indicators();

indicators.owner('Example Community')
    .indicator('10.20.30.40')
    .type(TYPE.ADDRESS)
    .rating(3)
    .confidence(75)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commit();

Example Results:

{
  "data": [
    {
      "id": 97932,
      "indicator": "10.20.30.40",
      "dateAdded": "2015-12-14T22:41:39Z",
      "lastModified": "2015-12-14T22:41:39Z",
      "ownerName": "Example Community",
      "rating": 3,
      "confidence": 55,
      "type": "Address",
      "webLink": "https://app.threatconnect.com/auth/indicators/details/address.xhtml?address=10.20.30.40&owner=Example+Community"
    }
  ],
  "remaining": 0,
  "url": "https://api.threatconnect.com/v2/indicators/addresses?owner=Example+Community",
  "apiCalls": 1,
  "body": "{\"ip\":\"10.20.30.40\",\"rating\":3,\"confidence\":55}",
  "resultCount": 0,
  "status": "Success"
}

This example will demonstrate how to add an Address indicator to the “Example Community” Owner. For indicator specific parameters refer to the ThreatConnect API User Guide.

Batch/Bulk Commit

Example of Batch/Bulk Commit:

var indicators = tc.indicatorsBatch();

indicators.owner('Example Community')
    .action('Create')
    .attributeWriteType('Append')
    .haltOnError(false)
    .done(function(response) {
        c.log('response', response);
    })
    .error(function(response) {
        c.log('error response', response);
    });


for (i = 1; i <= 5; i++) {
    indicators.indicator('10.10.10.' + i)
        .type(TYPE.ADDRESS)
        .rating(3)
        .confidence(42)
        .attributes([
            {
                type: 'Description',
                value: 'Example Description'
            }
        ])
        .tags([
            'Example',
            'JS_SDK'
        ])
        .add()
}

indicators.commit();

Filters are not supported on Batch/Bulk downloads.

Commit Association

The JavaScript SDK provides the commitAssociation() method to add Group Associations. Both type(), and indicator() methods are required to commit the Associations. The value passed to the commitAssociation() method must be the specific Group Type (e.g., TYPE.ADVERSARY, TYPE.HOST) and id.

Example of commitAssociations() method:

tc.indicators()
    .owner('Example Community')
    .type(TYPE.ADDRESS)
    .indicator('10.20.30.40')
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitAssociation({
        type: TYPE.ADVERSARY,
        id: '253'
    });

Commit Attribute

The following is an example of commitAttributes() method:

tc.indicators()
    .type(TYPE.ADDRESS)
    .indicator('10.20.30.40')
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitAttribute({
        type: 'Description',
        value: 'This is a description.'
    });

The JavaScript SDK provides the commitAttribute() method to add Attributes. Both type() and indicator() are required to add Attributes. The Attribute object should be passed to commitAttribute() method with a type and value parameter.

Commit Tags

Example of commitTags() method:

tc.indicators()
    .owner('Example Community')
    .type(TYPE.ADDRESS)
    .indicator('10.20.30.40')
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitTags('Example Tag');

The JavaScript SDK provides the commitTags() method to add Tags. Both the .type() and either the .id() or .indicator() methods are required to add the Tags. The Tag value should be passed to the commitTags() method.

Commit Security Labels

Example of commitSecurityLabel() method:

tc.indicators()
    .type(TYPE.ADDRESS)
    .indicator('10.20.30.40')
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitSecurityLabel('TLP Red');

The JavaScript SDK provides the commitSecurityLabel() method to add Security Labels. Both the type() and indicator() methods are required to add the Security Labels. The Security Label value should be passed to the commitSecurityLabel() method.

Putting It All Together

The following is an example of how to add an Adversary with a name of ‘adver-999’ to the “Example Community” Owner

indicators.owner('Example Community')
    .indicator('10.20.30.40')
    .type(TYPE.ADDRESS)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commit(function() {
        indicators.commitAssociation({
            type: TYPE.INCIDENT,
            id: 256
        });
        indicators.commitAttribute({
            type: 'Description',
            value: 'Example Description.'
        });
        indicators.commitObservation({
            count: 1,
            dateObserved: '2008-12-12T14:26:45-06:00'
        });
        indicators.commitTag('Example');
        indicators.commitSecurityLabel('TLP Red');
    });

This example will demonstrate how to add an Adversary with a name of ‘adver-999’ to the “Example Community” Owner. It passes a callback to the commit() method that will add a Group and Indicator Association, Attribute, Tag, and SecurityLabel. Any number of Associations, Attributes, or Tags can be added in the callback.

Note

To ensure that commits for the metadata happen after the commit of the Indicator, pass a callback to the Indicator Commit method.

Group Commit

This section explains how to work with ThreatConnect Group Resources.

Supported Group Types

Group Name	Group Constant
Adversary	TYPE.ADVERSARY
Document	TYPE.DOCUMENT
Email	TYPE.EMAIL
Incident	TYPE.INCIDENT
Signature	TYPE.SIGNATURE
Threat	TYPE.THREAT

Commit Group

The following is an example of how to add an Adversary with a name of ‘adver-001’ to the “Example Community” Owner:

groups = tc.groups();

groups.owner('Example Community')
    .name('adver-001')
    .type(TYPE.ADVERSARY)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commit();

Example Results:

{
  "data": [
    {
      "id": 265,
      "name": "adver-001",
      "dateAdded": "2015-12-13T15:50:08Z",
      "webLink": "https://api.threatconnect.com/auth/adversary/adversary.xhtml?adversary=265",
      "ownerName": "Example Community"
    }
  ],
  "remaining": 0,
  "url": "https://api.threatconnect.com/v2/groups/adversaries/?createActivityLog=false&owner=Example+Community",
  "apiCalls": 1,
  "body": "{\"name\":\"adver-001\"}",
  "resultCount": 0,
  "status": "Success"
}

This example will demonstrate how to add an Adversary with a name of ‘adver-001’ to the “Example Community” Owner. For Group-specific parameters, refer to the ThreatConnect API User Guide.

Commit Associations

The following is an example of commitAssociations() method:

tc.groups()
    .owner('Example Community')
    .type(TYPE.INCIDENT)
    .id(256)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitAssociation({
        type: TYPE.ADDRESS,
        id: '74.121.142.111'
    });

The JavaScript SDK provides the commitAssociations() method to add both Indicator and Group Associations. The type(), id(), associationType(), and associationId() methods are required to commit the Associations. The value passed to the associationType() method must be the specific Group or Indicator Type (e.g., TYPE.ADVERSARY, TYPE.HOST).

Commit Attributes

Example of commitAttributes() method:

tc.groups()
    .type(TYPE.INCIDENT)
    .id(256)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitAttribute({
        type: 'Description',
        value: 'This is a description.'
    });

The JavaScript SDK provides the commitAttributes() method to add Attributes. The type() and id() are required to add Attributes. The Attribute object should be passed to the commitAttribute() method with a type and value parameter.

Commit False Positive

tc.indicators
    .owner('Example Community')
    .indicator('10.20.30.40')
    .type(TYPE.ADDRESS)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitFalsePositive();

The JavaScript SDK provides the commitFalsePositive() method to add a False Positive mark on an Indicator. Both .type() and id() are required to add a False Positive mark.

Commit Observation Method

tc.indicators
    .owner('Example Community')
    .indicator('10.20.30.40')
    .type(TYPE.ADDRESS)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitObservation({
        count: 1,
        dateObserved: '2008-12-12T14:26:45-06:00'
    });

The JavaScript SDK provides the commitObservation() method to add an Indicator Observation. Both type() and id() are required to add an Observation. The Observation Count and dateObserved values should be passed to the commitObservation() method.

Commit Tag Method

Example of commitTag() method:

tc.groups()
    .type(TYPE.INCIDENT)
    .id(256)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitTag('Example Tag');

The JavaScript SDK provides the commitTag() method to add Tags. Both the type() and id() methods are required to add the Tags. The Tag value should be passed to the commitTag() method.

Commit Security Label

The following is an example of commitSecurityLabel() method:

tc.groups()
    .type(TYPE.ADDRESS)
    .indicator('10.20.30.40')
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitSecurityLabel('TLP Red');

Putting It All Together

Example of how to add an Adversary with a name of ‘adver-999’ to the “Example Community” Owner

groups = tc.groups();

groups.owner('Example Community')
    .name('adver-999')
    .type(TYPE.ADVERSARY)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commit(function() {
        groups.commitAssociation({
            type: TYPE.ADDRESS,
            id: '74.121.142.111'
        });
        groups.commitAssociation({
            type: TYPE.INCIDENT,
            id: 256
        });
        groups.commitAttribute({
            type: 'Description',
            value: 'Example Description.'
        });
        groups.commitTag('Example');
        groups.commitSecurityLabel('TLP Red');
    });

This example will demonstrate how to add an Adversary with a name of ‘adver-999’ to the Example Community Owner. It passes a callback to the commit() method that will add a Group and Indicators Association, Attribute, Tag, and Security Label. Any number of Associations, Attributes, or Tags can be added in the callback.

Note

To ensure that commits for the metadata happen after the commit of the Group, pass a callback to the Group Commit method.

Task Commit

This example will demonstrate how to add a Task with a name of ‘task-001’ to the “Example Community” Owner.

Example

tc.tasks()
    .owner('Example Community')
    // required
    .name('Test Task')
    // optional
    .assignee([{'userName': '[email protected]'}])
    .escalatee([{'userName': 'juser'}])
    .dueDate('2017-01-13T03:04:05Z')
    .escalationDate('2017-01-18T03:04:05Z')
    .reminderDate('2017-01-16T03:04:05Z')
    .escalated(false)
    .reminded(false)
    .overdue(false)
    .status('In Progress')
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commit();

Example Results

{
    "data": {
        "id": 600,
        "name": "Test Task",
        "owner": {
            "id": 2,
            "name": "SumX",
            "type": "Organization"
        },
        "dateAdded": "2016-03-17T17:13:30Z",
        "webLink": "https://demo.threatconnect.com/auth/workflow/task.xhtml?task=600",
        "status": "In Progress",
        "escalated": false,
        "reminded": false,
        "overdue": false,
        "dueDate": "2017-01-13T03:04:05Z",
        "reminderDate": "2017-01-16T03:04:05Z",
        "escalationDate": "2017-01-18T03:04:05Z",
        "assignee": [{
            "userName": "[email protected]",
            "firstName": "Joe",
            "lastName": "User"
        }],
        "escalatee": [{
            "userName": "[email protected]",
            "firstName": "Joe",
            "lastName": "Admin"
        }]
    },
    "remaining": 0,
    "url": "https://demo.threatconnect.com/api/v2/tasks/?resultLimit=500&owner=SumX",
    "apiCalls": 1,
    "body": "{\"name\":\"Test Task\",\"assignee\":[{\"userName\":\"[email protected]\"}],\"escalatee\":[{\"userName\":\"juser\"}],\"dueDate\":\"2017-01-13T03:04:05Z\",\"escalationDate\":\"2017-01-18T03:04:05Z\",\"reminderDate\":\"2017-01-16T03:04:05Z\",\"escalated\":false,\"reminded\":false,\"overdue\":false,\"status\":\"In Progress\"}",
    "resultCount": 0,
    "status": "Success"
}

Associations

The JavaScript SDK provides the commitAssociations() method to add both Indicator and Group Associations. The type(), id(), associationType(), and associationId() methods are required to commit the Associations. The value passed to the associationType() method must be the specific Group or Indicator Type (e.g. TYPE.ADVERSARY, TYPE.HOST).

tc.tasks()
    .owner('Example Community')
    .id(571)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitAssociation({
        type: TYPE.ADDRESS,
        id: '74.121.142.111'
    });

tc.tasks()
    .owner('Example Community')
    .id(571)
    .done(function(response) {
        console.log('response', response);
        $('#response-content').append(JSON.stringify(response, null, 4));
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitAssociation({
        type: TYPE.INCIDENT,
        id: 569
    });

Attributes

The JavaScript SDK provides the commitAttributes() method to add Attributes. The id() method is required to add Attributes. The Attribute object should be passed to commitAttribute() method with a type and value parameter.

tc.tasks()
    .id(571)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitAttribute({
        type: 'Description',
        value: 'This is a description.'
    });

Tags

The JavaScript SDK provides the commitTags() method to add Tags. The id() method is required to retrieve the Task. The Tag value should be passed to the commitTags() method.

tc.tasks()
    .id(256)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitTags('Example Tag');

Security Labels

tc.tasks()
    .id(256)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitSecurityLabel('TLP Red');

Putting It All Together

This example will demonstrate how to add a Task with a name of ‘task-999’ to the “Example Community” Owner. It passes a callback to the commit() method that will add a Group and Indicator Association, Attribute, Tag, and Security Label. Any number of Associations, Attributes, or Tags can be added in the callback.

tasks = tc.tasks();

tasks.owner('Example Community')
    .name('task-999')
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commit(function() {
        tasks.commitAssociation({
            type: TYPE.ADDRESS,
            id: '74.121.142.111'
        });
        tasks.commitAssociation({
            type: TYPE.INCIDENT,
            id: 256
        });
        tasks.commitAttribute({
            type: 'Description',
            value: 'Example Description.'
        });
        tasks.commitTag('Example');
        tasks.commitSecurityLabel('TLP Red');
    });

Note

To ensure the commits for the metadata happen after the commit of the Task, pass a callback to the group commit method.

Victim Commit

This example will demonstrate how to add a Victim with a name of ‘task-001’ to the “Example Community” Owner.

Example

victim.owner('Example Community')
    .name('Robin Scherbatsky')
    .org('Fox News')
    .suborg('Anchor')
    .workLocation('New York City, New York')
    .nationality('Canadian')
    .done(function(response) {
        console.log('response', response);
        $('#response-content').append(JSON.stringify(response, null, 4));
    })
    .error(function(response) {
        console.log('error response', response);
        $('#response-content').append(JSON.stringify(response, null, 4));
    })
    .commit();

Example Results

{
    "data": {
        "id": 22,
        "name": "Robin Scherbatsky",
        "org": "Fox News",
        "suborg": "Anchor",
        "workLocation": "New York City, New York",
        "nationality": "Canadian",
        "webLink": "https://demo.threatconnect.com/auth/victim/victim.xhtml?victim=22"
    },
    "remaining": 0,
    "url": "https://demo.threatconnect.com/api/v2/victims?resultLimit=500&owner=Example+Community",
    "apiCalls": 1,
    "body": "{\"name\":\"Robin Scherbatsky\",\"org\":\"Fox News\",\"suborg\":\"Anchor\",\"workLocation\":\"New York City, New York\",\"nationality\":\"Canadian\"}",
    "resultCount": 0,
    "status": "Success"
}

Associations

The JavaScript SDK provides the commitAssociations() method to add both Indicator and Group Associations. The type(), id(), associationType(), and associationId() methods are required to commit the Associations. The value passed to the associationType() method must be the specific Group or Indicator Type (e.g. TYPE.ADVERSARY, TYPE.HOST).

tc.victims()
    .owner('Example Community')
    .id(571)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitAssociation({
        type: TYPE.ADDRESS,
        id: '74.121.142.111'
    });

tc.victims()
    .owner('Example Community')
    .id(571)
    .done(function(response) {
        console.log('response', response);
        $('#response-content').append(JSON.stringify(response, null, 4));
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitAssociation({
        type: TYPE.INCIDENT,
        id: 569
    });

Attributes

The JavaScript SDK provides the commitAttributes() method to add Attributes. The id() method is required to add Attributes. The Attribute object should be passed to commitAttribute() method with a type and value parameter.

tc.victims()
    .id(571)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitAttribute({
        type: 'Description',
        value: 'This is a description.'
    });

Tags

The JavaScript SDK provides the commitTags() method to add Tags. The id() method is required to retrieve the Victim. The Tag value should be passed to the commitTags() method.

tc.victims()
    .id(256)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitTags('Example Tag');

Security Labels

tc.victims()
    .id(256)
    .done(function(response) {
        console.log('response', response);
    })
    .error(function(response) {
        console.log('error response', response);
    })
    .commitSecurityLabel('TLP Red');

Putting It All Together

This example will demonstrate how to add a Victim with a name of ‘task-999’ to the “Example Community” owner. It passes a callback to the commit() method that will add a Group and Indicators Association, Attribute, Tag, and Security Label. Any number of Associations, Attributes, or Tags can be added in the callback.

victim = tc.victims();

victim.owner('Example Community')
    .name('Robin Scherbatsky')
    .org('Fox News')
    .suborg('Anchor')
    .workLocation('New York City, New York')
    .nationality('Canadian')
    .done(function(response) {
        console.log('response', response);
        $('#response-content').append(JSON.stringify(response, null, 4));
    })
    .error(function(response) {
        console.log('error response', response);
        $('#response-content').append(JSON.stringify(response, null, 4));
    })
    .commit(function() {
        // add email address asset
        victim.address('[email protected]')
            .addressType('Work')
            .commitAsset(TYPE.VICTIM_ASSET_EMAIL_ADDRESSES);

        // add network account asset
        victim.account('robin')
            .network('LDAP')
            .commitAsset(TYPE.VICTIM_ASSET_NETWORK_ACCOUNTS);

        // add phone number asset
        victim.phoneType('222-222-2222')
            .commitAsset(TYPE.VICTIM_ASSET_PHONE_NUMBERS);

        // add social network asset
        victim.account('RobinSparkles')
            .network('FaceBook')
            .commitAsset(TYPE.VICTIM_ASSET_SOCIAL_NETWORKS);

        // add webSite
        victim.webSite('https://www.robinsparkles.com')
            .commitAsset(TYPE.VICTIM_ASSET_WEBSITES);

        // add indicator associations
        victim.commitAssociation({
            type: TYPE.ADDRESS,
            id: '74.121.142.111'
        });

        // add group association
        victim.commitAssociation({
            type: TYPE.INCIDENT,
            id: 256
        });

        // add attribute association
        victim.commitAttribute({
            type: 'Description',
            value: 'Example Description.'
        });

        // add tag
        victim.commitTag('Example');

        // add securityLabel
        victim.commitSecurityLabel('TLP Red');
    });

Note

To ensure the commits for the metadata happen after the commit of the Task, pass a callback to the group commit method.

Manual API Calls

The example below accesses the API by allowing the creation of a requestObject():

tc.requestObject()
ro.apiRequest(ro);

The JavaScript SDK supports a manual way to access the API by allowing the creation of a requestObject() and submitting these objects to the apiRequest() method. The returned result will contain an API response.

Retrieving Indicators

The example below displays how to create a RequestObject that will retrieve all Indicators from a specified Owner:

var ro = tc.requestObject();

ro.owner('Example Community')
    .createActivityLog(false)
    .requestUri('v2/indicators')
    .requestMethod('GET')
    .resultLimit(250)
    .resultStart(0)
    .done(function(response) {
        c.log('response', response);
    })
    .error(function(response) {
        c.log('error response', response);
    })
    .apiRequest('manual');

This example displays how to create a RequestObject that will retrieve all Indicators from a specified Owner.

Downloading Document Contents

The example below displays how to create a RequestObject that will retrieve the contents of a document stored in a Document Resource:

var ro = tc.requestObject();

ro.owner('Example Community')
    .createActivityLog(false)
    .requestUri('v2/groups/documents/261/download')
    .requestMethod('GET')
    .done(function(response) {
        c.log('response', response);
    })
    .error(function(response) {
        c.log('error response', response);
    })
    .apiRequest('manual');

This example displays how to create a RequestObject that will retrieve the contents of a document stored in a Document Resource.

Creating and Uploading Documents

The example below displays how to create a RequestObject that will create a Document Resource in ThreatConnect and upload a file to this Resource.

var ro = tc.requestObject();

ro.owner('Example Community')
    .createActivityLog(false)
    .requestUri('v2/groups/documents/263/upload')
    .requestMethod('POST')
    .body('Content of file.')
    .contentType('application/octet-stream')
    .done(function(response) {
        c.log('response', response);
        $('#response-content').append(JSON.stringify(response, null, 4));
    })
    .error(function(response) {
        c.log('error response', response);
        $('#response-content').append(JSON.stringify(response, null, 4));
    })
    .apiRequest('manual');

This example displays how to create a RequestObject that will create a Document Resource in ThreatConnect and upload a file to this Resource.

Query String Parameters

This example shows how to add filters to a manual request using the payload() option.

var ro = tc.requestObject();

ro.owner('Example Community')
    .payload('filters', 'summary="1.2.3.4",rating>3')

The JavaScript SDK requestObject provides the payload() method to add any additional query string parameters. This example shows how to add filters to a manual request using the payload() option.

Query String Parameter	Helper Method
owner	owner()
createActivityLog	createActivityLog()
resultLimit	resultLimit()
resultStart	resultStart()
filters	manually via payload()
orParams	manually via payload()

For a full list of query string parameters supported by the ThreatConnect API, reference the ThreatConnect API documentation:.

Helper Functions

groupHelper

The groupHelper function makes it easy to retrieve the TYPE object for a given Group type (provided as a string). For example, when retrieving Groups, you can find the full type (TYPE.<GROUP_TYPE>) for each Group using the groupHelper as demonstrated below.

groups = tc.groups();

groups.owner('Example Community')
    .resultLimit(500)
    .done(function(response) {
        for (var i = response.data.length - 1; i >= 0; i--) {
            # return the complete TYPE of the group
            console.log(groupHelper(response.data[i].type))
        }
    })
    .error(function(response) {
        console.error('error response', response);
    })
    .retrieve();

indicatorHelper

The indicatorHelper function makes it easy to retrieve the TYPE object for a given Indicator type (provided as a string). For example, when retrieving Indicators, you can find the full type (TYPE.<INDICATOR_TYPE>) for each Indicator using the indicatorHelper as demonstrated below.

var indicators = tc.indicators();

indicators.owner('Example Community')
    .resultLimit(500)
    .done(function(response) {
        for (var i = response.data.length - 1; i >= 0; i--) {
            # return the complete TYPE of the indicator
            console.log(indicatorHelper(response.data[i].type))
        }
    })
    .error(function(response) {
        console.error('error response', response);
    })
    .retrieve(function() {
        if (indicators.hasNext()) {
            indicators.next()
        }
    });

JavaScript® is a registered trademark of the Oracle Corporation.