Page tree

Contents


Dossier (Legacy) Data Provider Returns

Dossier (Legacy) aggregates threat data from multiple partners in order to generate a full report.

The following sections will provide a brief description of what information is retrieved, and display the expected return data from each Dossier (Legacy) provider in JSON format. Key names are what can be expected in request response, and the key’s value is the data type that can be expected.

GET /api/services/intel/lookup/targets

Returns a list of indicator types.

Ex: curl –u <api_key>: “https://api.activetrust.net:8000/api/services/intel/lookup/targets

Response:

[
"ip",
"host",
"url",
"hash", "email"
]

GET /api/services/intel/lookup/sources

Returns a list of Dossier sources.

Ex: curl –u <api_key>: “https://api.activetrust.net:8000/api/services/intel/lookup/sources

Response:

{
 "alexa": true,
 "atp": true,
 "atp_ps": false,
 "dns": true,
 "gcs": true,
 "geo": true,
 "gsb": true,
 "isight": true,
 "malware_analysis": true,
 "pdns": true,
 "ptr": true,
 "rlabs": true,
 "rwhois": true,
 "whois": true
}

GET /api/services/intel/lookup/sources/target/{target_type}

Returns sources that support queries for an indicator type.

Ex: curl –u :”https://api.activetrust.net:8000/api/services/intel/lookup/sources/target/ip

Response:

{
"atp": true, 
"atp_ps": true, 
"gcs": true,
"geo": true,
"gsb": true, 
"isight": true,
"malware_analysis": true, 
"pdns": true,
"ptr": true,
"whois": true
}

GET /api/services/intel/lookup/source/{source}/targets

Return a list of indicator types supported by a given source. Ex: curl –u <api_key>:

https://api.activetrust.net:8000/api/services/intel/lookup/source/atp/targets

Response:

[
“ip”,
“host”, “url”
]

GET /api/services/intel/lookup/indicator/{target_type}

Required parameters:

Value: indicator to search for, Source: source to search.

Optional parameters:

Wait: whether to wait for the lookup to complete – true or false [defaults to false] Start a new Dossier lookup job for a specified indicator and source(s).

Ex: curl –u <api_key>: “https://api.activetrust.net:8000/api/services/intel/lookup/indicator/host?value=google.com&sour ce=alexa&source=dns&wait=false”

Response:

{
"status": "pending",
"job_id": "aef7e05a-42c6-45f2-9be4-02139caf31a4", "job": {
"id": "aef7e05a-42c6-45f2-9be4-02139caf31a4", "state": "created",
"status": "pending", "create_ts": 1501802999664,
"create_time": "2017-08-03T23:29:59.664186262Z",
"pending_tasks": [
"8e4d8ac5-9772-42f6-8644-0a23fb509870", "6c19c40f-c5c6-4d89-b099-e92b036e92d5"
],
"org": "org",
"user": "user@test.com"
},
"tasks": {
"6c19c40f-c5c6-4d89-b099-e92b036e92d5": { "id": "6c19c40f-c5c6-4d89-b099-e92b036e92d5",
"state": "created",
"status": "pending", "create_ts": 1501802999664,
"create_time": "2017-08-03T23:29:59.664186262Z",
"params": { "type": "host",
"target": "google.com",
"source": "dns"
}
},
"8e4d8ac5-9772-42f6-8644-0a23fb509870": {
<status>
}
}
}

GET /api/services/intel/lookup/indicator/{indicator_type}?value=<indocator_data>&source=<optional_source_one>&source=<source_n>

Simplified Single Target Lookup

In selected cases, there exists a need to determine if a host has been previously detected and described as malicious.  This API details  how query the Dossier API for a single host a previous determination. It should be noted that not all the API sources express an opinion as to if a host is malicious.  For instance, the presence of a positive whois response does not resolve the question of if a host is malicious. In general, the modules that are most likely to help answer this question are:

  • ATP

  • Google Web Risk (gwr)

The example query is constructed to integrate these two sources (atp , gsb).  For completeness, the full set of sources are listed below:

  • Active Trust (atp)

  • Google Web Risk (gwr)

  • Google Custom Search (gcs)

  • DNS Lookup (dns)

  • iSight (isight)

  • Secure Domain Foundation (sfd)

  • Domain Tools (whois)

  • Alexa (alexa)

  • PDNS (pdns)


Description

Used to start a new lookup job with one indicator to lookup. It's a simplified version of the "POST /api/services/intel/lookup/jobs" call.

Method

GET

Path

/api/services/intel/lookup/indicator/{indicator_type}



Query

String

Parameters

"value" - (required) the indicator value to lookup.

"source" - (optional) the lookup sources to use (use multiple instances to specify more than one source)

"wait" - (optional) "true", "false" or a number of seconds to wait. wait for 30 seconds (by default) before returning (with results if the tasks are finished)

Sample Request:


curl -u insert_api_key_here: \ 'https://platform.activetrust.net:8000/api/services/intel/lookup/indicator/host?value=tacomapower.com&source=gsb&source=atp&wait=true'


Response:

{
  "status": "success",
"job_id": "eba56e54-20ee-4c04-8011-4dc72ac6c56a",
"job": {
"id": "eba56e54-20ee-4c04-8011-4dc72ac6c56a",
"state": "completed",
"status": "success",
"create_ts": 1470069690653,
"create_time": "2016-08-01T16:41:30.653Z",
"completed_tasks": [
"34bcbb2d-c5b4-41da-931c-24265be9b6e0",
"c021837f-c3e6-49a4-b23b-a15f2baab582"
],
"org": "IID",
"user": "mike.brown@internetidentity.com"
},
"tasks": {
"34bcbb2d-c5b4-41da-931c-24265be9b6e0": {
"id": "34bcbb2d-c5b4-41da-931c-24265be9b6e0",
"state": "completed",
"status": "success",
"create_ts": 1470069690653,
"create_time": "2016-08-01T16:41:30.653Z",
"start_ts": 1470069693283,
"start_time": "2016-08-01T16:41:33.283Z",
"end_ts": 1470069693352,
"end_time": "2016-08-01T16:41:33.352Z",
"params": {
"type": "host",
"target": "tacomapower.com",
"source": "gsb"
}
},
"c021837f-c3e6-49a4-b23b-a15f2baab582": {
"id": "c021837f-c3e6-49a4-b23b-a15f2baab582",
"state": "completed",
"status": "success",
"create_ts": 1470069690653,
"create_time": "2016-08-01T16:41:30.653Z",
"start_ts": 1470069693283,
"start_time": "2016-08-01T16:41:33.283Z",
"end_ts": 1470069693654,
"end_time": "2016-08-01T16:41:33.654Z",
"params": {
"type": "host",
"target": "tacomapower.com",
"source": "atp"
}
}
},
"results": [
{
"task_id": "34bcbb2d-c5b4-41da-931c-24265be9b6e0",
"params": {
"type": "host",
"target": "tacomapower.com",
"source": "gsb"
},
"v": "2.0.1",
"status": "success",
"time": 67,
"data": {
"status": "nomatch"
}
},
{
"task_id": "c021837f-c3e6-49a4-b23b-a15f2baab582",
"params": {
"type": "host",
"target": "tacomapower.com",
"source": "atp"
},
"v": "2.0.0",
"status": "success",
"time": 370,
"data": {
"available_record_count": 0,
"record_count": 0,
"threat": []
}
}
]
}

GET /api/services/intel/lookup/jobs/{job_id}

Returns status of a Dossier lookup job.

Ex: curl –u <api_key>: “https://api.activetrust.net:8000/api/services/intel/lookup/jobs/aef7e05a- 42c6-45f2-9be4-02139caf31a4”

Response:

{
"status": "success",
 "job_id": "aef7e05a-42c6-45f2-9be4-02139caf31a4", "job": {
 "id": "aef7e05a-42c6-45f2-9be4-02139caf31a4", "state": "completed",
 "status": "success", "create_ts": 1501802999664,
 "create_time": "2017-08-03T23:29:59.664Z",
 "completed_tasks": [
 "8e4d8ac5-9772-42f6-8644-0a23fb509870", "6c19c40f-c5c6-4d89-b099-e92b036e92d5"
 ],
 "org": "org",
 "user": "user@test.com"
 },
 "tasks": {
 "6c19c40f-c5c6-4d89-b099-e92b036e92d5": { "id": "6c19c40f-c5c6-4d89-b099-e92b036e92d5",
 "state": "completed", "status": "success", "create_ts": 1501802999664,
 "create_time": "2017-08-03T23:29:59.664Z",
 "start_ts": 1501802999908,
 "start_time": "2017-08-03T23:29:59.908Z", "end_ts": 1501802999960,
 "end_time": "2017-08-03T23:29:59.96Z",
 "params": { "type": "host",
 "target": "google.com",
 "source": "dns"
 }
 },
 "8e4d8ac5-9772-42f6-8644-0a23fb509870": {
 <status>
 }
 }
 }
 }

GET /api/services/intel/lookup/jobs/{job_id}/results

Returns results of a Dossier lookup job.

Ex: curl –u <api_key>: “https://api.activetrust.net:8000/api/services/intel/lookup/jobs/aef7e05a- 42c6-45f2-9be4-02139caf31a4/results”

Response:

{
"state": "completed", "status": "success",
"job_id": "aef7e05a-42c6-45f2-9be4-02139caf31a4", "results": [
{
"task_id": "8e4d8ac5-9772-42f6-8644-0a23fb509870", "params": {
"type": "host",
"target": "google.com",
"source": "alexa"
},
"v": "2.0.1",
"status": "success", "data": {
<data>
}
},
{
"task_id": "6c19c40f-c5c6-4d89-b099-e92b036e92d5", "params": {
"type": "host",
"target": "google.com",
"source": "dns"
},
"v": "2.0.0",
"status": "success", "time": 25,
"data": {
<data>
}
}
]
}

GET /api/services/intel/lookup/jobs/{job_id}/tasks/{task_id}

Returns status of a single task in a Dossier lookup job.

Ex: curl –u <api_key>: “https://api.activetrust.net:8000/api/services/intel/lookup/jobs/aef7e05a- 42c6-45f2-9be4-02139caf31a4/tasks/6c19c40f-c5c6-4d89-b099-e92b036e92d5”

Response:

{
"state": "completed", "status": "success", "task": {
"id": "6c19c40f-c5c6-4d89-b099-e92b036e92d5",
"state": "completed", "status": "success", "create_ts": 1501802999664,
"create_time": "2017-08-03T23:29:59.664Z",
"start_ts": 1501802999908,
"start_time": "2017-08-03T23:29:59.908Z", "end_ts": 1501802999960,
"end_time": "2017-08-03T23:29:59.96Z",
"params": { "type": "host",
"target": "google.com",
"source": "dns"
}
}
}

GET /api/services/intel/lookup/jobs/{job_id}/tasks/{task_id}/results

Returns results of a single task in a Dossier lookup job.

Ex: curl –u <api_key>: “https://api.activetrust.net:8000/api/services/intel/lookup/jobs/aef7e05a- 42c6-45f2-9be4-02139caf31a4/tasks/6c19c40f-c5c6-4d89-b099-e92b036e92d5/results”

Response:

{
"state": "completed", "status": "success", "results": {
"task_id": "6c19c40f-c5c6-4d89-b099-e92b036e92d5", "params": {
"type": "host",
"target": "google.com",
"source": "dns"
},
"v": "2.0.0",
"status": "success", "time": 25,
"data": {
<data>
}
}
}

  • No labels

This page has no comments.