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 (imcp, 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
rdata	string
reporttime	string	Format: YYYY-MM-DDTHH:MM:SSZ - Greater than or equal to
reporttimeend	string	Format: YYYY-MM-DDTHH:MM:SSZ - Less than or equal to
firsttime	string	Format: YYYY-MM-DDTHH:MM:SSZ - Greater than or equal to
lasttime	string	Format: YYYY-MM-DDTHH:MM:SSZ - Less than or equal to

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"