CensysEx

Tiny Elixir ⚗️ wrapper for the Censys Search 2.0 API

Note: this is NOT an official Censys library, and is not supported by or affiliated with Censys at this time. I do not own Censys Trademarks or Copyrights

Installation

Available in Hex, the package can be installed by adding censys_ex to your list of dependencies in mix.exs:

def deps do
  [
    {:censys_ex, "~> 2.0.1"}
  ]
end

Setup

via Application variables

config :censys_ex,
  api_id: "*****",
  api_key: "*****"

# ...

CensysEx.API.client()

or directly

CensysEx.API.client("*****", "*****")

API secrets can be found here

Hosts

View a host

View all the data on an IP at a given time.

CensysEx.Hosts.view(client, "127.0.0.1")

# Lookup the host as it was at a certain time
CensysEx.Hosts.view(client, "127.0.0.1", ~U[2021-06-07 12:53:27.450073Z])

Get host names

Returns a stream of names for that IP.

iex(1)> CensysEx.Hosts.names(client, "127.0.0.1") |>
...(1)> Stream.take(25) |>
...(1)> Enum.to_list()
["example.com", "foo.net", ...]

Search hosts

Search returns a stream of results using the cursors provided by the API.

iex(1)> CensysEx.Hosts.search(client, "same_service(service_name: SSH and not port: 22)") |>
...(1)> Stream.take(25) |>
...(1)> Stream.map(&Map.get(&1, "ip")) |>
...(1)> Enum.to_list()
["10.0.0.6", "10.2.0.1", ...]

Aggregate hosts

Aggregate data about hosts on the internet.

CensysEx.Hosts.aggregate(client, "location.country_code", "services.service_name: MEMCACHED")

CensysEx.Hosts.aggregate(client, "location.country_code", "services.service_name: MEMCACHED", 10)

Diff hosts

Diff hosts at given times

# diff the current host with it self 🤷
CensysEx.Hosts.diff(client, "8.8.8.8")

# diff two hosts
CensysEx.Hosts.diff(client, "8.8.8.8", "1.1.1.1")

# diff a host with itself at a time in the past
CensysEx.Hosts.diff(client, "8.8.8.8", nil, ~U[2021-06-07 12:53:27.450073Z])

# diff two hosts in the past
CensysEx.Hosts.diff(client, "8.8.8.8", "8.8.4.4" ~U[2021-06-07 12:53:27.450073Z], ~U[2021-06-07 12:53:27.450073Z])

Hosts API Docs

• view
• names
• aggregate
• diff
• search
• search-syntax

Certs

View a cert by fingerprint

# NOTE this actually a V1 API
CensysEx.Certs.view(client, "fb444eb8e68437bae06232b9f5091bccff62a768ca09e92eb5c9c2cf9d17c426")

Get hosts that present a cert

CensysEx.Certs.get_hosts_by_cert(client, "fb444eb8e68437bae06232b9f5091bccff62a768ca09e92eb5c9c2cf9d17c426")
|> Stream.take(25)
|> Stream.map(&Map.get(&1, "ip"))
|> Enum.to_list()
["10.0.0.6", "10.2.0.1", ...]

Certs API Docs

• View
• hosts

Experimental

CensysEx.Experimental.host_events(client, "127.0.0.1")
|> Stream.take(25)
|> Stream.map(&Map.get(&1, "_event"))
|> Enum.to_list()
["service_observed", "location_updated", ...]

Experimental V2 API Docs

• events

Metadata

CensysEX.Metadata.host_metadata()
{:ok, %{
  "code": 200,
  "status": "OK",
  "result": {
    "services": [
      "HTTP",
      "IMAP",
      "MQTT",
      "SSH",
      "..."
    ]
  }
}}

Metadata API Docs

• hosts metadata

---

Other Languages

Official

• Node
• Python

Unofficial

• Ruby