REST API

UNDER CONSTRUCTION

Overview

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

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

Examples

Routes

$ curl localhost:5000
{
  "DELETE /tokens": "delete a token or set of tokens",
  "GET /": "this message",
  "GET /feed": "filter for a data-set, aggregate and apply respective whitelist",
  "GET /help": "this message",
  "GET /help/confidence": "get a list of confidence values",
  "GET /indicators": "search for a set of indicators",
  "GET /ping": "ping the router interface",
  "GET /search": "search for an indicator",
  "GET /tokens": "search for a set of tokens",
  "PATCH /token": "update a token",
  "POST /indicators": "post indicators to the router",
  "DELETE /indicators": "delete a set of indicators based on id or filters"
  "POST /tokens": "create a token or set of tokens"
}

Simple Filters

$ curl -H ... -i "https://localhost/indicators?q=example.com"
$ curl -H ... -i "https://localhost/indicators?itype=ipv4&limit=5"
$ curl -H ... -i "https://localhost/indicators?provider=csirtg.io"
$ curl -H ... -i "https://localhost/indicators?cc=us"
$ curl -H ... -i "https://localhost/indicators?itype=ipv4&tags=scanner&feed=1"
$ curl -H ... -i "https://localhost/indicators?tags=botnet,zeus&confidence=65&cc=us"

Basic

$ curl -v -H "Authorization: Token token=1234" -i https://localhost/indicators?indicator=example.com

> GET / HTTP/1.1
> User-Agent: curl/7.37.0
> Host: localhost:5000
> Accept: */*
> 
* HTTP 1.0, assume close after body
< HTTP/1.0 200 OK
< Content-Type: application/json
< Content-Length: 592
< Server: Werkzeug/0.11.10 Python/3.5.2
< Date: Wed, 08 Mar 2017 00:59:29 GMT

{"status":"success","data":[{"lasttime":"2017-03-08T01:07:20.190000Z","tlp":"amber","description":null,"id":1,"indicator":"example.com","firsttime":"2017-03-08T01:07:10.700000Z","count":4,"group":"everyone","reporttime":"2017-03-08T01:07:20.190000Z","itype":"fqdn","tags":["search"],"provider":"admin","confidence":10.0}]}

Query

$ curl -i -k -H "Authorization: Token token=1234..." 'https://localhost/indicators?itype=ipv4&limit=1'
[]

DELETE

$ curl -i -k -H "Content-Type: application/json" -XDELETE -H "Authorization: Token token=1234..." 'https://localhost/indicators' -d '{"id":"2"}'
$ curl -i -k -H "Content-Type: application/json" -XDELETE -H "Authorization: Token token=1234..." 'https://localhost/indicators' -d '{"indicator":"example.com"}'
$ curl -i -k -H "Content-Type: application/json" -XDELETE -H "Authorization: Token token=1234..." 'https://localhost/indicators' -d '{"indicator":"example.com", "provider":"openphish.com"}'

Current Version

By default, all requests receive the v3 of the API. We encourage you to explicitly request this version via the Accept header.

Accept: application/vnd.cif.v3+json

Authorization

$ curl -H "Authorization: Token token=1234" https://localhost

Schema

All data is sent and received as JSON.

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

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/indicators?{itype,indicator,limit,nolog,...}"

Current supported parameters include:

Name	Type	Description
q	string	The observable to query for
itype	string	(ipv4, ipv6, fqdn, url, email, md5, sha1, sha256)
nolog	int	Do NOT log the query
indicator	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)
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
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