Web API

GET /config

Returns JavaScript code to set client-side configuration values

Status Codes:
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

  • 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:
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

Status Codes:
Response JSON Object:

  • int – count

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

Get top values from Nmap, View, Passive & RIR databases

Parameters:

  • subdb (str) – database to query (must be “scans”, “view”, “passive” or “rir”)

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

Query Parameters:

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

  • f (str) – filter

  • 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:
Response JSON Array of Objects:

  • label (str) – field value

  • value (int) – count for this value

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

Get distinct values from Nmap, View, Passive & RIR databases

Parameters:

  • subdb (str) – database to query (must be “scans”, “view”, “passive” or “rir”)

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

Query Parameters:

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

  • f (str) – filter

  • 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:
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

  • 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:
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:
Response JSON Object:

  • count (int) – number of inserted results

GET /flows

Get a flow graph, count, or details payload.

The query is JSON-encoded under the q URL parameter and carries nodes / edges filter lists in the flow.Query grammar plus the pagination / mode knobs listed below. action=details returns details for a single node or edge instead of a graph.

Query Parameters:

  • q (str) –

    JSON-encoded query object. Recognised keys:

    • nodes list of node-filter clauses

    • edges list of edge-filter clauses

    • limit cap on returned edges; defaults to

      config.WEB_GRAPH_LIMIT (1000)

    • skip pagination offset; defaults to 0

    • mode default / flow_map / talk_map

    • count true returns ``{clients, servers,

      flows}`` instead of the graph

    • orderby src / dst / flow (or unset)

    • timeline true embeds data.meta.times per edge

    • before / after "YYYY-MM-DD HH:MM" time bounds

  • action (str) – "details" to fetch host_details / flow_details for the node or edge id supplied in q.id; q.type is "node" or "edge".

Status Codes:
Response JSON Object:

  • object – results

POST /flows

Ingest a bulk of flow records.

Mirrors the bulk-insert API documented in ivre.db.mongo.MongoDBFlow: the request body is a JSON object {"records": [{"kind": "...", ...}, ...]} where each entry carries one of the three ingestion kinds:

  • {"kind": "any", "name": "<zeek-log>", "rec": {...}} maps to db.flow.any2flow(),

  • {"kind": "conn", "rec": {...}} maps to db.flow.conn2flow(),

  • {"kind": "flow", "rec": {...}} maps to db.flow.flow2flow().

Records are dispatched in order, then a single db.flow.bulk_commit() flushes the bulk. Returns {"count": <records-ingested>}.

Status Codes:
Response JSON Object:

  • count (int) – number of records ingested

POST /flows/cleanup

Run the backend’s cleanup_flows heuristic.

The handler dispatches to the configured backend’s cleanup_flows() (a no-op on the SQL backend until the host-swap heuristic is ported); the response carries no body besides {"status": "ok"} so the ivre.db.http.HttpDBFlow client can treat any non-2xx as an error.

Status Codes:
GET /ipdata/(addr)

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

Parameters:

  • addr (str) – IP address to query

Status Codes:
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:
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

  • 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:
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

Status Codes:
Response JSON Object:

  • int – count

GET /dns

Return a merged DNS view across the active scan database (db.nmap) and the passive observation database (db.passive).

Each result is a pseudo-record keyed on (name, addr): a single row aggregates every observation of that pair across both backends, with count being the sum of the per-source counts (rec['count'] on the passive side, one per matching nmap document on the active side). types and sources are unions of the contributing backend values (e.g. ["A", "PTR", "user"], ["sensor1", "scan-2024-Q1"]); firstseen / lastseen extend the union of the contributing intervals.

Results are sorted lastseen descending, then count descending. The user’s q= filter is applied to both backends — tokens that are meaningful only on one side (e.g. recontype: on passive, port: on nmap) are silently dropped on the other via the standard hasattr(dbase, "searchXXX") gate in flt_from_query.

Note: the merge happens in-process; every contributing record is materialised before sorting and pagination. The server-side MONGODB_QUERY_TIMEOUT_MS cap bounds the worst-case request time. For deployments where this matters, a future change can introduce a materialised summary collection updated at ingest time.

Query Parameters:

  • q (str) – query (filter, plus skip, limit meta-params)

  • datesasstrings (bool) – emit ISO-ish date strings rather than Unix timestamps

  • format (str) – "json" (default) or "ndjson"

Status Codes:
Response JSON Array of Objects:

  • object – pseudo-records as {name, addr, count, firstseen, lastseen, types, sources}

GET /rir

Get records from the RIR database.

Records are sorted narrowest-first by default (most-specific inet[6]num allocation at the top), so a host: / net: / range: filter naturally surfaces the leaf record covering the queried address. aut-num records (no range, no size) sort to the end. Pass ?sortby=<field> (or ?sortby=~<field> for descending) to override.

Query Parameters:

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

  • f (str) – filter

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

  • sortby (str) – optional sort field; default is size ascending then start descending then stop ascending (narrowest range first)

Status Codes:
Response JSON Array of Objects:

  • object – results

GET /rir/count

Count records from the RIR database.

Query Parameters:

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

  • f (str) – filter

Status Codes:
Response JSON Object:

  • int – count

GET /auth/check

When auth is disabled, allow all requests.