Skip to content

Latest commit

 

History

History
2654 lines (2166 loc) · 83.7 KB

javascript_sdk.rst

File metadata and controls

2654 lines (2166 loc) · 83.7 KB

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

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