API

SDK Examples

For more examples, be sure to check out the SDK implementations.

Overview

This describes the resources that make up the official CIF API v2. If you have any problems or requests please log an issue

• Current Version
• Authorization
• Schema
• Root Endpoint
• Parameters

Current Version

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

Authorization

$ curl -H "Accept: application/vnd.cif.v2+json" -H "Authorization: Token token=8b66f1594f40fc81d907860f2e89b76aeaab6f78941f7a2001f092135421366a" https://localhost

Schema

All data is sent and received as JSON.

Blank fields are can be included as 'null' or omitted.

Basic

$ 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

[]

Query

$ 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

Root Endpoint

The root endpoint for the API is /observables.

Parameters

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"