This repository has been archived by the owner on Jun 17, 2023. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 18
REST API
Wes edited this page Mar 23, 2017
·
11 revisions
This describes the resources that make up the CIFv3 REST API. If you have any problems or requests please log an issue.
###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"
## 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
```bash
$ curl -H "Authorization: Token token=1234" https://localhost
All data is sent and received as JSON.
Blank fields are can be included as 'null' or omitted.
$ 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}]}
$ curl -i -k -H "Authorization: Token token=1234..." 'https://localhost/indicators?itype=ipv4&limit=1'
[]
$ 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':'csirtg.io'}"
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 |