- Cont3xt v4.x-5.x API
- /audit API
- /audits API
- /audit/:id API
- /settings API
- /settings API
- /integration API
- /integration/search API
- /integration/:itype/:integration/search API
- /integration/settings API
- /integration/settings API
- /integration/stats API
- /linkGroup API
- /linkGroup API
- /linkGroup/:id API
- /linkGroup/:id API
- /overview API
- /overview/:id API
- /overviews API
- /overview/:id API
- /views API
- /view API
- /view/:id API
- /view/:id API
- IntegrationFieldDef Type
- IntegrationFieldType Type
- IntegrationTidbitContainer Type
- IntegrationTidbit Type
- IntegrationField Type
- IntegrationCard Type
- Integration Type
- Itype Type
- DataChunkPurpose Type
- IntegrationChunk Type
- IntegrationSetting Type
- Stat Type
- Link Type
- LinkGroup Type
- Cont3xtOverviewField Type
- Cont3xtOverview Type
- Cont3xtView Type
Cont3xt v4.x-5.x API
This API is not final and is subject to change.
This is the documentation for versions 4.x-5.x.
/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 (sorted by issuedAt) 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 EPOC) |
| stopMs | string |
an optional query parameter to specify the end of results (milliseconds since Unix EPOC) |
| seeAll | string |
an optional query parameter to request viewing all history (only works for admin users) |
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 | Array.<Integrations> |
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 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 |
|---|---|---|
| views | 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 |
|---|---|---|
| views | 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 |
|---|---|---|
| views | 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 |
How long results will be cached, -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 :
object
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 cache |
| 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
An 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 if 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 | number |
The name of the integration |
| total | number |
The number of times the integration was asked for a result |
Link Type
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.<Links> |
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 |
