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"},{"date":"2006-11-16","cc":"CN","prefix":"122.224.0.0\/12","asn_description":"CW Cable and Wireless Worldwide plc,GB","asn":"1273","rir":"apnic"},{"asn_description":"TELIANET TeliaSonera International Carrier,SE","asn":"1299","rir":"apnic","date":"2006-11-16","cc":"CN","prefix":"122.224.0.0\/12"},{"rir":"apnic","asn":"2914","asn_description":"NTT-COMMUNICATIONS-2914 NTT America, Inc.,US","cc":"CN","prefix":"122.224.0.0\/12","date":"2006-11-16"},{"asn":"3257","rir":"apnic","asn_description":"TINET-BACKBONE Tinet SpA,DE","cc":"CN","prefix":"122.224.0.0\/12","date":"2006-11-16"},{"date":"2006-11-16","cc":"CN","prefix":"122.224.0.0\/12","asn_description":"LEVEL3 Level 3 Communications, Inc.,US","rir":"apnic","asn":"3356"},{"asn_description":"INTERNET2-TRANSITRAIL-CPS Internet2,US","rir":"apnic","asn":"11164","date":"2006-11-16","cc":"CN","prefix":"122.224.0.0\/12"}],"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}]

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
observable	string	The observable to query for
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)

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"