# Web API

GET /config

  Returns JavaScript code to set client-side configuration values

  Status Codes:

    - 200 OK – no error

    - 400 Bad Request – invalid referer

  Response JSON Object:

    - config (object) – the configuration values

GET /(subdb:re:scans|view)/(action:re:onlyips|ipsports|timeline|coordinates|countopenports|diffcats)

  Get special values from Nmap & View databases

  Parameters:

    - subdb (str) – database to query (must be “scans” or “view”)

    - action (str) – specific value to get (must be one of “onlyips”, “ipsports”, “timeline”, “coordinates”, “countopenports” or “diffcats”)

  Query Parameters:

    - q (str) – query (including limit/skip and sort)

    - f (str) – filter

    - callback (str) – callback to use for JSONP results (forces “json” format)

    - ipsasnumbers (bool) – to get IP addresses as numbers rather than as strings

    - datesasstrings (bool) – to get dates as strings rather than as timestamps

    - format (str) – “json” (the default), “ndjson” or “txt”

  Status Codes:

    - 200 OK – no error

    - 400 Bad Request – invalid referer

  Response JSON Array of Objects:

    - object – results

GET /(subdb:re:scans|view)/count

  Get special values from Nmap & View databases

  Parameters:

    - subdb (str) – database to query (must be “scans” or “view”)

  Query Parameters:

    - q (str) – query (including limit/skip and sort)

    - f (str) – filter

    - callback (str) – callback to use for JSONP results

  Status Codes:

    - 200 OK – no error

    - 400 Bad Request – invalid referer

  Response JSON Object:

    - int – count

GET /(subdb:re:scans|view|passive)/top/(field: path)

  Get top values from Nmap, View & Passive databases

  Parameters:

    - subdb (str) – database to query (must be “scans” or “view”)

    - field (str) – (pseudo-)field to get top values (e.g., “service”)

  Query Parameters:

    - q (str) – query (including limit/skip and sort)

    - f (str) – filter

    - callback (str) – callback to use for JSONP results

    - ipsasnumbers (bool) – to get IP addresses as numbers rather than as strings

    - datesasstrings (bool) – to get dates as strings rather than as timestamps

    - format (str) – “json” (the default) or “ndjson”

  Status Codes:

    - 200 OK – no error

    - 400 Bad Request – invalid referer

  Response JSON Array of Objects:

    - label (str) – field value

    - value (int) – count for this value

GET /(subdb:re:scans|view|passive)/distinct/(field: path)

  Get distinct values from Nmap, View & Passive databases

  Parameters:

    - subdb (str) – database to query (must be “scans” or “view”)

    - field (str) – (pseudo-)field to get distinct values (e.g., “service”)

  Query Parameters:

    - q (str) – query (including limit/skip and sort)

    - f (str) – filter

    - callback (str) – callback to use for JSONP results

    - ipsasnumbers (bool) – to get IP addresses as numbers rather than as strings

    - datesasstrings (bool) – to get dates as strings rather than as timestamps

    - format (str) – “json” (the default) or “ndjson”

  Status Codes:

    - 200 OK – no error

    - 400 Bad Request – invalid referer

  Response JSON Array of Objects:

    - label (str) – field value

    - value (int) – count for this value

GET /(subdb:re:scans|view)

  Get records from Nmap & View databases

  Parameters:

    - subdb (str) – database to query (must be “scans” or “view”)

  Query Parameters:

    - q (str) – query (including limit/skip and sort)

    - f (str) – filter

    - callback (str) – callback to use for JSONP results

    - ipsasnumbers (bool) – to get IP addresses as numbers rather than as strings

    - datesasstrings (bool) – to get dates as strings rather than as timestamps

    - format (str) – “json” (the default) or “ndjson”

  Status Codes:

    - 200 OK – no error

    - 400 Bad Request – invalid referer

  Response JSON Array of Objects:

    - object – results

POST /(subdb:re:scans|view)

  Add records to Nmap & View databases

  Parameters:

    - subdb (str) – database to query (must be “scans” or “view”)

  Form Parameters:

    - categories – a coma-separated list of categories

    - source – the source of the scan results (mandatory)

    - result – scan results (as XML or JSON files)

  Status Codes:

    - 200 OK – no error

    - 400 Bad Request – invalid referer, source or username missing

  Response JSON Object:

    - count (int) – number of inserted results

GET /flows

  Get special values from Nmap & View databases

  Query Parameters:

    - q (str) – query (including limit/skip, orderby, etc.)

    - callback (str) – callback to use for JSONP results

    - action (str) – can be set to “details”

  Status Codes:

    - 200 OK – no error

    - 400 Bad Request – invalid referer

  Response JSON Object:

    - object – results

GET /ipdata/(addr)

  Returns (estimated) geographical and AS data for a given IP address.

  Parameters:

    - addr (str) – IP address to query

  Query Parameters:

    - callback (str) – callback to use for JSONP results

  Status Codes:

    - 200 OK – no error

    - 400 Bad Request – invalid referer

  Response JSON Object:

    - object – the result values

GET /passivedns/(query: path)

  Query passive DNS data. This API is compatible with the Common Output Format and implemented in CIRCL’s PyPDNS.

  It accepts two extra parameters, not supported (yet?) in PyPDNS:

  > - subdomains: if this parameter exists and a domain name is queried, records for any subdomains will also be returned.

  > - reverse: if this parameter exists and a domain name is queried, records pointing to the queried domain (CNAME, NS, MX) will be returned.

  It also returns additional information:

  > - “sensor”: the “sensor” field of the record; this is useful to know where this answer has been seen.

  > - “source”: the IP address of the DNS server sending the answer.

  Parameters:

    - query (str) – IP address or domains name to query

  Query Parameters:

    - subdomains (bool) – query subdomains (domain name only)

    - reverse (bool) – use a reverse query (domain name only)

    - type (str) – specify the DNS query type

  Status Codes:

    - 200 OK – no error

    - 400 Bad Request – invalid referer

  Response JSON Object:

    - object – the result values (JSONL format: one JSON result per line)

GET /passive

  Get records from Passive database

  Query Parameters:

    - q (str) – query (only used for limit/skip and sort)

    - f (str) – filter

    - callback (str) – callback to use for JSONP results

    - ipsasnumbers (bool) – to get IP addresses as numbers rather than as strings

    - datesasstrings (bool) – to get dates as strings rather than as timestamps

    - format (str) – “json” (the default) or “ndjson”

  Status Codes:

    - 200 OK – no error

    - 400 Bad Request – invalid referer

  Response JSON Array of Objects:

    - object – results

GET /passive/count

  Get special values from Nmap & View databases

  Query Parameters:

    - q (str) – query (only used for limit/skip and sort)

    - f (str) – filter

    - callback (str) – callback to use for JSONP results

  Status Codes:

    - 200 OK – no error

    - 400 Bad Request – invalid referer

  Response JSON Object:

    - int – count