How to Use Public API Docs from Censys.io

Censys.io is a website that provides a platform for Internet-wide scanning. It has a public API that allows users to access their services programmatically. In this blog, we will discuss how to use the API docs from Censys.io, including some example code in JavaScript.

Getting Started

Before we can use the Censys.io API, we need to sign up for a free account and get an API key. Once we have our API key, we can use it to make requests to the API.

API Documentation

Censys.io provides comprehensive documentation for their API on their website. The documentation is organized into sections that cover different aspects of the API, such as authentication, data retrieval, and search. Each section provides detailed information about the endpoints, parameters, and response formats of the API.

Example Code in JavaScript

To help you get started with using the Censys.io API, here is some example code in JavaScript.

Authentication

To authenticate with the Censys.io API, we need to include our API key in the requests we make. Here is an example of how to add the API key to a request using the axios library.

const axios = require('axios');

const apiKey = 'your-api-key';

axios.get('https://censys.io/api/v1/data', {
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Basic ${Buffer.from(apiKey).toString('base64')}`
  }
})
.then((response) => {
  console.log(response.data);
})
.catch((error) => {
  console.error(error);
});

Data Retrieval

To retrieve data from the Censys.io API, we can use the /data endpoint. Here is an example of how to make a request to retrieve information about a specific IP address.

const axios = require('axios');

const apiKey = 'your-api-key';
const ipAddress = '192.0.2.1';

axios.post('https://censys.io/api/v1/data', {
  query: `ip:${ipAddress}`,
  fields: ['ip', 'protocols', 'ports']
}, {
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Basic ${Buffer.from(apiKey).toString('base64')}`
  }
})
.then((response) => {
  const data = response.data.results[0];
  console.log(`IP address: ${data.ip}`);
  console.log(`Protocols: ${data.protocols.join(', ')}`);
  console.log(`Ports: ${data.ports.join(', ')}`);
})
.catch((error) => {
  console.error(error);
});

Search

To search for data with the Censys.io API, we can use the /search endpoint. Here is an example of how to make a request to search for SSL certificates with a specific common name.

const axios = require('axios');

const apiKey = 'your-api-key';
const commonName = 'example.com';

axios.post('https://censys.io/api/v1/search/certificates', {
  query: `parsed.subject.common_name:"${commonName}"`,
  fields: ['parsed.subject.common_name', 'parsed.validity.start', 'parsed.validity.end']
}, {
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Basic ${Buffer.from(apiKey).toString('base64')}`
  }
})
.then((response) => {
  const results = response.data.results;
  console.log(`Found ${results.length} SSL certificates with common name "${commonName}":`);
  results.forEach((result) => {
    console.log(`- Common Name: ${result.parsed.subject.common_name}`);
    console.log(`  Validity: ${result.parsed.validity.start} to ${result.parsed.validity.end}`);
  });
})
.catch((error) => {
  console.error(error);
});

Conclusion

In this blog, we have discussed how to use the public API docs from Censys.io, including some example code in JavaScript. With this knowledge, you should be able to start using the Censys.io API to access their Internet-wide scanning services.