-
Notifications
You must be signed in to change notification settings - Fork 62
API
For more examples, be sure to check out the SDK implementations.
This describes the resources that make up the official CIF API v2. If you have any problems or requests please log an issue
By default, all requests receive the v2 of the API. We encourage you to explicitly request this version via the Accept
header.
Accept: application/vnd.cif.v2+json
$ curl -H "Accept: application/vnd.cif.v2+json" -H "Authorization: Token token=8b66f1594f40fc81d907860f2e89b76aeaab6f78941f7a2001f092135421366a" https://localhost
All data is sent and received as JSON.
Blank fields are can be included as 'null' or omitted.
$ curl -H ... -i https://localhost/observables -H "Authorization: Token token=8b66f1594f40fc81d907860f2e89b76aeaab6f78941f7a2001f092135421366a"
HTTP/1.0 200 OK
Date: Mon, 01 Dec 2014 13:09:43 GMT
Server: HTTP::Server::PSGI
Content-Length: 2096429
Date: Mon, 01 Dec 2014 13:09:43 GMT
Content-Type: application/json
X-CIF-Media-Type: cif.v2
[]
$ curl -i -k -H "Accept: application/vnd.cif.v2+json" -H "Authorization: Token token=0b0bc0da9d596462ab4fbeaf1243318d164cd4371d59e96688570b0f65f45162" 'https://localhost/observables?cc=cn&otype=ipv4&limit=1'
HTTP/1.1 200 OK
Date: Thu, 04 Dec 2014 17:46:54 GMT
Server: Apache/2.4.7 (Ubuntu)
X-CIF-Media-Type: cif.v2
Content-Length: 1734
Content-Type: application/json
[{"prefix":"122.224.0.0\/12","lasttime":"2014-12-04T09:39:57Z","timezone":"Asia\/Shanghai","asn":"4134","provider":"dragonresearchgroup.org","otype":"ipv4","citycode":"Hangzhou","asn_desc":"CHINANET-BACKBONE No.31,Jin-rong Street,CN","tags":["scanner"],"firsttime":"2014-12-04T09:39:57Z","portlist":"22","cc":"CN","lang":"EN","reporttime":"2014-12-04T13:16:47Z","latitude":30.2936,"tlp":"amber","observable":"122.225.109.221","peers":[{"asn_description":"COGENT-174 Cogent Communications,US","asn":"174","rir":"apnic","date":"2006-11-16","prefix":"122.224.0.0\/12","cc":"CN"}],"group":["everyone"],"subdivision":"33","altid_tlp":"green","altid":"http:\/\/dragonresearchgroup.org\/insight\/sshpwauth.txt","longitude":120.1614,"id":"216cba10185b97dfb148f98c3dcc1f40023ec5055592561f896df87dbdef72ee","rir":"apnic","confidence":85,"application":"ssh","protocol":6}]
an expanded version of this can be found here
The root endpoint for the API is /observables
.
Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:
$ curl -H ... -i "https://localhost/observables?cc=us"
In this example, the ‘observables’ is provided for the :observables parameters in the path while :cc is passed in the query string.
For PUT requests, parameters not included in the URL should be encoded as JSON with a Content-Type of ‘application/x-www-form-urlencoded’.
Current supported parameters include:
Name | Type | Description |
---|---|---|
q | string | The observable to query for |
otype | string | (ipv4, ipv6, fqdn, url, email) |
nolog | int | Do NOT log the query |
observable | string | The observable to query for |
portlist | string | list of ports (ex: 1,2,445-557) |
protocol | string | layer 4 protocol (icmp, tcp, udp) |
cc | string | The country code to filter on |
asn | int | The ASN to filter on |
confidence | int | The confidence (or greater) to filter on |
group | string | The group(s) to filter on (CSV accepted as OR) |
tags | string | The tag(s) to filter on (CSV accepted as OR) |
provider | string | The provider(s) to filter on (CSV accepted as AND) |
application | string | The application(s) to filter on (CSV accepted as AND) |
description | string | Text description of the observable |
rdata | string | Related data: used mainly by cif-worker when re-injecting intelligence |
reporttime | string | Reported timestamp, (YYYY-MM-DDTHH:MM:SSZ) - Greater than or equal to |
reporttimeend | string | A filter to limit results, (YYYY-MM-DDTHH:MM:SSZ) - Less than or equal to |
firsttime | string | First seen machine generated timestamp, (YYYY-MM-DDTHH:MM:SSZ) - Greater than or equal to |
lasttime | string | Last seen machine generated timestamp, (YYYY-MM-DDTHH:MM:SSZ) - Less than or equal to |
limit | int | limit the results returned |
adata | string | Additional data: could be a text string or json blob |
Examples include:
$ curl -H ... -i "https://localhost/observables?cc=us"
$ curl -H ... -i "https://localhost/observables?q=example.com"
$ curl -H ... -i "https://localhost/observables?observable=1.2.3.4&provider=dragonresearchgroup.com"
$ curl -H ... -i "https://localhost/observables?tags=botnet,zeus&confidence=65&cc=us"