censys
SecurityHow 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.