/audit API

Creates a new history audit log

Parameters:

Param Type Description
audit Audit The history entry to create

Returns:

Name Type Description
  Promise The promise that either resolves or rejects in error

/audits API

GET - /api/audits

Returns list of audit logs that the requesting user is allowed to view.

Parameters:

Param Type Description
searchTerm string an optional query parameter to filter on indicator, iType, and tags
startMs string an optional query parameter to specify the start of results (milliseconds since Unix EPOCH)
stopMs string an optional query parameter to specify the end of results (milliseconds since Unix EPOCH)
seeAll string an optional query parameter to request viewing all history (only works for admin users)
sortBy string an optional query parameter to specify the field to sort by
sortOrder string an optional query parameter to specify the order to sort by
itemsPerPage string an optional query parameter to specify the number of results to return
page string an optional query parameter to specify the page number (1-indexed)

Returns:

Name Type Description
audits Array.<Audit> A sorted array of audit logs that the logged
success boolean True if the request was successful, false otherwise

/audit/:id API

DELETE - /api/audit/:id

Delete a log from history. Users can delete their own logs. Admins can delete any log.

Returns:

Name Type Description
success boolean Whether the delete history log operation was successful.
text string The success/error message to (optionally) display.

/settings API

GET - /api/settings

Returns all the settings relevant for the cont3xt settings page

Returns:

Name Type Description
success boolean True if the request was successful, false otherwise
settings object General cont3xt settings
linkGroups Array.<LinkGroup> An array of link groups that the logged in user can view/edit
selectedOverviews object A mapping of the selected overview per iType, of shape {[iType]: overviewId}

/settings API

PUT - /api/settings

Updates the general cont3xt settings

Parameters:

Param Type Description
settings object General cont3xt settings for the logged in user

Returns:

Name Type Description
success boolean True if the request was successful, false otherwise
text string The success/error message to (optionally) display to the user

/integration API

GET - /api/integration

List out all the integrations. Integrations without any itypes are skipped.

Returns:

Name Type Description
integrations Object.<string, Integration> A map of integrations that the logged in user has configured
success boolean True if the request was successful, false otherwise

/integration/search API

POST - /api/integration/search

Fetches integration data

Parameters:

Param Type Description
query string The string to query integrations
doIntegrations Array.<string> A list of integration names to query
skipCache boolean Ignore any cached data and query all integrations again
skipChildren boolean Don’t query integrations for sub-indicators
tags Array.<string> Tags applied at the time of search
viewId string | undefined The ID of the view at the time of search (if any)

Returns:

Name Type Description
results Array.<IntegrationChunk> An array of data chunks with the data

/integration/:itype/:integration/search API

POST - /api/integration/:itype/:integration/search

Fetches integration data about a single itype/integration

Parameters:

Param Type Description
query string The string to query the integration

Returns:

Name Type Description
  IntegrationChunk The chunk with either: purpose:data, purpose:fail, or purpose:error

/integration/settings API

GET - /api/integration/settings

Return all the integration settings and current values that a user can set

Returns:

Name Type Description
success boolean True if the request was successful, false otherwise
settings Array.<IntegrationSetting> The settings for each integration for the logged in user

/integration/settings API

PUT - /api/integration/settings

Updates the integration settings

Returns:

Name Type Description
success boolean True if the request was successful, false otherwise
settings Array.<IntegrationSetting> The integration settings to update for the logged in user

/integration/stats API

GET - /api/integration/stats

Fetches stats about integrations

Returns:

Name Type Description
success boolean True if the request was successful, false otherwise
startTime number The start time of the cont3xt server (the start of the stats data)
stats Array.<Stat> The integration stat data
itypeStats Array.<Stat> The itype stat data

/linkGroup API

GET - /api/linkGroup

Returns link groups that the requesting user is allowed to view.

Returns:

Name Type Description
linkGroups Array.<LinkGroup> An array of link groups that the logged in user can view
success boolean True if the request was successful, false otherwise

/linkGroup API

PUT - /api/linkGroup

Creates a new link group

Parameters:

Param Type Description
linkGroup LinkGroup The link group to create

Returns:

Name Type Description
success boolean True if the request was successful, false otherwise
text string The success/error message to (optionally) display to the user

/linkGroup/:id API

PUT - /api/linkGroup/:id

Updates a link group

Parameters:

Param Type Description
linkGroup LinkGroup The link group to update

Returns:

Name Type Description
success boolean True if the request was successful, false otherwise
text string The success/error message to (optionally) display to the user

/linkGroup/:id API

DELETE - /api/linkGroup/:id

Deletes a link group

Returns:

Name Type Description
success boolean True if the request was successful, false otherwise
text string The success/error message to (optionally) display to the user

/overview API

PUT - /api/overview

Creates a new overview

Parameters:

Param Type Description
req.body Cont3xtOverview The overview to create

Returns:

Name Type Description
success boolean True if the request was successful, false otherwise
text string The success/error message to (optionally) display to the user

/overview/:id API

PUT - /api/overview/:id

Updates an overview

Parameters:

Param Type Description
req.params.id string The id of the overview to update
req.body Cont3xtOverview The new value of the overview to update

Returns:

Name Type Description
success boolean True if the request was successful, false otherwise
text string The success/error message to (optionally) display to the user

/overviews API

GET - /api/overview

Returns overviews that the requesting user is allowed to view.

Returns:

Name Type Description
overviews Array.<Cont3xtOverview> An array of overviews that the logged in user can view
success boolean True if the request was successful, false otherwise

/overview/:id API

DELETE - /api/overview/:id

Deletes an overview

Returns:

Name Type Description
success boolean True if the request was successful, false otherwise
text string The success/error message to (optionally) display to the user

/views API

GET - /api/views

Returns views that the requesting user is allowed to view.

Returns:

Name Type Description
views Array.<Cont3xtView> An array of views that the logged in user can view
success boolean True if the request was successful, false otherwise

/view API

POST - /api/view

Creates a new view

Parameters:

Param Type Description
view Cont3xtView The view to create

Returns:

Name Type Description
success boolean True if the request was successful, false otherwise
text string The success/error message to (optionally) display to the user

/view/:id API

PUT - /api/view/:id

Updates a view

Parameters:

Param Type Description
view Cont3xtView The view to update

Returns:

Name Type Description
success boolean True if the request was successful, false otherwise
text string The success/error message to (optionally) display to the user

/view/:id API

DELETE - /api/view/:id

Deletes a view

Parameters:

Param Type Description
view Cont3xtView The view to delete

Returns:

Name Type Description
success boolean True if the request was successful, false otherwise
text string The success/error message to (optionally) display to the user

IntegrationFieldDef Type

An Integration field definition object

The specifics on how to display a field

Parameters:

Param Type Default Description
label string   The field label to display to a user
path string   The path (it can have dots) to the data for field, if not set the field is the same as name. For table type this will be the path to the array.
fields Array.<IntegrationField>   Used with table data types, the list of fields to display in the table
defang boolean   When true defang the string, change http to hXXp and change . to [.]
pivot boolean   When set this field should be added to action menu for table entry that you can replace query with
join string   Used with array data types, display with value as the separator on one line (example single: ‘, ‘)
defaultSortField string   Used with table data types, sorts the table by this field initially
defaultSortDirection string "\"desc\"" Used with table data types if defaultSortField is also set, sorts the table in this direction (‘asc’ or ‘desc’)

IntegrationFieldType Type

An Integration field type string

The data type of the field data

Parameters:

Param Type Default Description
type string "\"string\"" The type of data displayed in the field string - obvious url - a url that should be made clickable table - there will be a fields element array - the field var will point to an array, display 1 per line unless join set date - a date value ms - a ms time value seconds - a second time value json - just display raw json, call in JSON.stringify(blah, false, 2)

IntegrationTidbitContainer Type

An Integration tidbits object

Information for creating and ordering tidbits

Parameters:

Param Type Description
order number | undefined a default order to apply to all contained tidbits
fields Array.<IntegrationTidbit> the objects that define individual tidbit displays

IntegrationTidbit Type

An Integration tidbit object

Information about how to display a field from an Integration’s data to the primary indicator-tree display.

Parameters:

Param Type Description
label string | undefined The name of the field. If given, tidbit is displayed as key-value pair at bottom
type IntegrationFieldType The type of data displayed in the field, default ‘string’
field IntegrationFieldDef path to data
fieldRoot IntegrationFieldDef | undefined path to element data from data root
display string how to display value in UI, default ‘badge’
template string | undefined pseudo template-string applied to value before postProcess
postProcess Array.<string> | string | undefined named filter(s) to pass value into
tooltip string | undefined value used as tooltip
tooltipTemplate string | undefined pseudo template-string filled with value & data for use in tooltip
order number number by which tidbits are sorted (ascending order), default 0
precedence number | undefined the higher, the more preferred among those with the same purpose
purpose string | undefined when multiple valid tidbits have the same purpose, only the one with the highest precedence will be kept

IntegrationField Type

An Integration field object

Information about how to display a field within an Integration’s data.

Parameters:

Param Type Description
name string The name of the field
type IntegrationFieldType The type of data displayed in the field
field IntegrationFieldDef If not “name” and “type” it’s an object describing the data

IntegrationCard Type

An Integration card object

Information about how to display the integration’s data.

Parameters:

Param Type Description
title string The title of the card to display in the UI
fields Array.<IntegrationField> An array of field objects to outline how to display data for each field within the integration’s data

Integration Type

An Integration object

Integrations are the configured data sources for Cont3xt.

Parameters:

Param Type Description
cachePolicy string Who can access the cached results of this integration’s data (“shared”)
cacheTimeout number | string How long results will be cached, as a time string (e.g. ‘1h’, ‘1w’) or a number of seconds, -1 not cached
doable boolean Whether the user has access to execute this integration
icon string The relative url to the integrations icon
order number The order in which this integration displays in the UI
card IntegrationCard Information on how to display the integration’s data
tidbits IntegrationTidbitContainer Information on how to pull specialized fields into indicator-tree UI

Integration.initialize() (function)

Initialize the Integrations subsystem

Parameters:

Param Type Default Description
options.cache object   The ArkimeCache implementation
options.getConfig function   function used to get configuration items
options.integrationsPath string "__dirname/integrations/" Where to find the integrations

Integration.register() (function)

Register an integration implementation

Parameters:

Param Type Default Description
integration.name string   The name of the integration
integration.itypes object   An object of itypes to functions to call
integration.cacheable boolean true Should results be cached
integration.noStats boolean false Should we not save stats
integration.order number 10000 What order should this integration be shown

Itype Type

The classification of the search string

Parameters:

Param Type Default Description
itype string "\"text\"" The type of the search ip, domain, url, email, phone, hash, or text

DataChunkPurpose Type

The classification of the data chunk

IntegrationChunk Type

Integration Data Chunk object

A chunk of data returned from searching integrations

Parameters:

Param Type Description
purpose DataChunkPurpose String discriminator to indicate the use of this data chunk
text string The message describing the error (on purpose: ‘error’)
indicators Array.<Cont3xtIndicator> The deduped, top-level indicators searched, given in search-order (purpose: ‘init’)
indicator Cont3xtIndicator The itype and query that correspond to this chunk of data (all purposes except: ‘init’, ‘finish’, and ‘error’)
total number The total number of integrations to query
sent number The number of integration results that have completed and been sent to the client
name string The name of the integration result within the chunk (purpose: ‘data’)
data object The data from the integration query (purpose: ‘data’). This varies based upon the integration. The IntegrationCard describes how to present this data to the user.
parentIndicator Cont3xtIndicator The indicator that caused this integration/query to be run (purpose: ‘link’)
enhanceInfo object Curated data contributed from an integration to an indicator of a separate query (purpose: ‘enhance’)

IntegrationSetting Type

Integration Settings object

The settings for an integration for the logged in user

Parameters:

Param Type Description
globalConfiged boolean Whether integration is configured globally across cont3xt users or by this user (if a user has changed the settings for an integration, this is false)
locked boolean Whether integration is locked. Locked integrations use the globally configured settings. Users cannot update locked integrations. Any previously configured settings for locked integrations will be ignored in favor of the global configuration.
homePage string The link to the home page for this integration so a user can learn more
settings object The setting field definitions for this integration
values object The values that map to the setting fields for this integration (empty object if not set)

Stat Type

Integration Stat object

The statistic data for an integration

Parameters:

Param Type Description
cacheFound number The number of entries found in the cache for this integration
cacheGood number The number of valid entries found in the cache for this integration
cacheLookup number The number of entries looked up in the cache for this integration
cacheRecentAvgMS number How long it takes to look up this integration from the cache
directError number The number of entries queried directly from the integration that failed
directFound number The number of entries found directly from the integration
directGood number The number of valid entries queried directly from the integration
directLookup number The number of entries queried directly from the integration
directRecentAvgMS number How long it takes to look up directly from the integration
name string The name of the integration
total number The number of times the integration was asked for a result

A Link object

Links are used to navigate to external sources.

Parameters:

Param Type Description
name string The name of the link
color string The color of the link
itypes Array.<string> The type of cont3xt results that pertain to this link
url string The url of the link. Links can include placeholder values that will be filled in with the data from the Cont3xt results
infoField string An optional text field to display as an informative tooltip.
externalDocUrl string An optional URL to link out to external documentation.
externalDocName string An optional name to label the external documentation.

LinkGroup Type

A Link Group object

Link Groups are used to list links to external sources.

Parameters:

Param Type Description
_id string The id of the link group
name string The name of the link group
creator string The creator of the link group
links Array.<Link> The array of links in this link group
editRoles array The Arkime roles that can edit this link group
viewRoles array The Arkime roles that can view this link group
_editable boolean Whether the logged in user is allowed to edit this link group
_viewable boolean Whether the logged in user is allowed to view this link group

Cont3xtOverviewField Type

A Cont3xt Overview Field Object

Cont3xt Overview Fields configure the display for an entry in an overview

Parameters:

Param Type Description
from string The name of the integration to use a field from
field string The label of the field to use
alias string | undefined Optional replacement label to display for this field in the overview

Cont3xtOverview Type

A Cont3xt Overview Object

Cont3xt Overviews are used to configure the default display for an itype

Parameters:

Param Type Description
_id string The id of the overview
creator string The creator of the overview
name string The name of the overview
title string The title of the overview, filled for display on the integration card panel
iType string The itype this overview can be displayed for
fields Array.<Cont3xtOverviewField> The array of fields to be displayed by this overview
editRoles array The Arkime roles that can edit this overview
viewRoles array The Arkime roles that can view this overview
_editable boolean Whether the logged in user is allowed to edit this overview
_viewable boolean Whether the logged in user is allowed to view this overview

Cont3xtView Type

A Cont3xt View object

Cont3xt Views are used to save lists of integrations to apply to a query.

Parameters:

Param Type Description
_id string The id of the view
name string The name of the view
creator string The creator of the view
integrations Array.<string> The array of integration names in this view
editRoles array The Arkime roles that can edit this view
viewRoles array The Arkime roles that can view this view
_editable boolean Whether the logged in user is allowed to edit this view
_viewable boolean Whether the logged in user is allowed to view this view