node-censys

An unofficial javascript wrapper for Censys.io API

If you are interested to see the official documentation visit the Censys.io API page.

Installation

Install it locally to your project to use it as a node module:

npm install censys.io

Or globally to use it as a cli tool:

npm install --global censys.io

Than you should have censys command available on your path, try it out with the --help menu.

$ censys --help

On the command line tool you can specify the API id and secret as an option before the commands or you can setup environment variables called CENSYS_ID and CENSYS_SECRET that will be used by default.

Usage

The censys client is promise based and must be instanciated with the API id and secret obtained from the Censys website, like the example below.

import Censys from 'censys.io'

const instance = new Censys({
  apiID: '<your-api-id>',
  apiSecret: '<your-api-secret>'
})

const data = await instance.search('certificates', {
  query: '80.http.get.headers.server: nginx'
})

This project is typescript based and provides the module definitions for a better experience.

Methods

search

The search endpoint allows searches against the current data in the IPv4, Top Million Websites, and Certificates indexes using the same search syntax as the primary site. The endpoint returns a paginated result set of hosts (or websites or certificates) that match the search. Data should be posted as a JSON request document.

const data = await censys.search('ipv4', {
  query: '8.8.8.8'
});
console.log(data);

view

The view endpoint fetches the structured data we have about a specific host, website, or certificate once you know the host's IP address, website's domain, or certificate's SHA-256 fingerprint. report

const data = await censys.view('websites', 'google.com');
console.log(data);

report

The report endpoint allows you to determine the aggregate breakdown of a value for the results a query, similar to the "Build Report" functionality available in the primary search interface. For example, if you wanted to determine the breakdown of cipher suites selected by all websites in the Top Million.

const data = censys.report('ipv4', {
  query: '80.http.get.headers.server: nginx',
  field: 'location.country_code'
});
console.log(data);

data

The Get Series endpoint returns a data on the types of scans we regularly perform ("series").

const data = await censys.data();
console.log(data);

account

The account endpoint returns information about your Censys account.

const data = await censys.account();
console.log(data);

License

MIT © Filippo Conti