Driftnet API

A comprehensive RESTful JSON API.

Scan Content

Overview

For some protocols — particularly HTTP — full retrieved bodies are available from the scan/protocols/body endpoint.

These bodies are also themselves searchable, via the same API endpoint.

Content Retrieval

To retrieve a specific scan body, find the the item with type obj-sha1 in the return from a scan/protocols call. Take the value of this item, and the date on which it was seen, and then call:

curl -s -H 'Authorization: Bearer <your-api-token>' \
     'https://api.driftnet.io/v1/scan/protocols/body?hash=9b523c5bbf7416334bd46f2d5463e6830a58d795&date=2019-05-13' \
  | jq -rc '.results[0].body' | base64 -d \
  | less -S

➟

<HTML><HEAD><meta http-equiv="content-type" content="text/html;charset=utf-8">
<TITLE>302 Moved</TITLE></HEAD><BODY>
<H1>302 Moved</H1>
The document has moved
<A HREF="https://dns.google/en/">here</A>.
</BODY></HTML>

The result from the API is returned base64-encoded; the example assumes that you have the GNU base64 utility installed. On Mac, use base64 -D instead of base64 -d.

Content Searches

We can also search for specific strings within the content:

curl -s -H 'Authorization: Bearer <your-api-token>' \
     'https://api.driftnet.io/v1/scan/protocols/body?q=STUNNEL' \
  | jq . \
  | less -S

➟

{
  "page": 0,
  "pages": 15,
  "result_count": 1499,
  "results": [
    {
      "body": "PCFET0NUWVBFIGh0bWwgUFVCTElDICItLy9XM0Mv..."
      "hash": "9df069d39ed8f4d7487b79c44ef0ef87e7af9809"
    },
    ...

For technical reasons, content searches are limited to strings that occur outside HTML tags. This means that you cannot usually search for snippets of page javascript, etc. However! The Driftnet collection system does include an advanced regex-based collection time tagging system, which can be used to extract specific patterns from anywhere. If you have something interesting that you would like to look for, then just drop us a line and we'll likely add it.

The scan/protocols/body endpoint also supports the from= / to=, prefix= and slop= qualifiers. These work exactly as described in the Internet Scans section.

If you find something interesting in the body search, and you want to retrieve data on the IP/port pairs where it was found, you can perform a scan/protocols search for the extracted hash. For example, to find the STUNNEL results that we searched for above:

curl -s -H 'Authorization: Bearer <your-api-token>' \
     'https://api.driftnet.io/v1/scan/protocols&keyword=obj-sha1:9df069d39ed8f4d7487b79c44ef0ef87e7af9809' \
  | jq . \
  | less -S