Quick Start Guide

The Censys Platform offers an expansive, structured view of global internet assets, with rich context on hosts, services, certificates, and infrastructure. Query structured datasets for comprehensive internet-wide analysis, using data such as WHOIS, CPEs, CVEs, TLS hashes, and helpful labels, fully indexed for fast searching, pivoting, and correlation.

This guide provides you with the quickest route to using the Platform to search the Censys datasets, how to understand the data, and other tools and features that enrich your experience.

Create account

It's easy to get started with a Free account. To sign up for an account:

1. Go to the account creation page.
2. Enter the required information and click Create Account.
3. You receive an email to verify your account. Once your account is verified select Censys Platform.
4. Enter your credentials. Once you sign in, you land on the Censys Platform interface.

What you can search for in the Censys Platform

Censys scans the entire public internet to find reachable IPs, services, certificates, and more. These scans discover and build structured data records such as hosts, web properties, and certificates that help you to quickly search, investigate, and connect related assets.

Hosts

Provides current records of internet-facing IPv4 and IPv6 hosts. Each host is identified by an IP address and includes detailed information about exposed services, such as IP addresses, protocols, software, and ports. Use the Platform to search structured host fields such as service details, DNS names, location, and known vulnerabilities.

As a security practitioner, you could search on fields like host.services.software.product to discover hosts running a specific application, or host.services.port to identify exposed services on sensitive ports.

Certificates

Certificates are cryptographic files used to authenticate websites and secure communications. Search on fields such as the issuer, subject, validity period, subject alternative names, and signature algorithm to find certificates issued to specific organizations or domains.

For example, search cert.parsed.subject.organization:"Google" to identify all certificates issued to Google.

Web Properties

Consist of websites, APIs, and web-based apps. Web properties are identified by a hostname and a port. Hostnames can be name-based records (such as app.censys.io) or IP-based records (such as 104.18.10.85). Search across web properties to find hostname-level detail, HTTP response data, or visibility into services running on top of HTTP for web-facing applications. They provide a direct window into application behavior and communication with clients.

Search on fields such as web.endpoints.banner or web.endpoints.http.body_hash to find reused infrastructure or cloned malicious content. If you know a specific service banner associated with a known malicious service, you could search for web properties with that banner, for exampleweb.endpoints.banner: "Apache HTTP Server".

Go to the Data Definitions page in the Platform web console for a complete list of fields for all data record types.

Search the Platform dataset

Now that your account is set up, you’re ready to start exploring Platform datasets. Use the example queries below to begin your search. You can click on the query description to run a query, or copy and paste the query syntax into the search bar at the top of the UI.

See Example Queries in the web app for an expanded list of suggested queries.

Example host queries

Use the example queries below to explore common patterns in the Censys hosts dataset and familiarize yourself with the search syntax.

Example certificate queries

Use the example queries below to explore common patterns in the Censys Certificates dataset and familiarize yourself with the search syntax.

Example web property queries

Use the example queries below to explore common patterns in the Censys Web Properties dataset and familiarize yourself with the search syntax.

Censys Query Language

Censys Query Language (CenQL) is a structured search syntax designed to help you find and filter internet-facing assets. There are two primary ways to search the Censys datasets.

• A full-text search across the entire record for a value, such as "example.com." It matches any document that contains the search term in any field.
• A field query, which targets a specific field like host.location.city = "Ann Arbor" to find matching records. This query is searching for host records where the location.city field contains the exact value Ann Arbor.

All field names include the dataset (host, cert, or web) they are a part of. Field queries must include an operator or set of operators that define what will be considered a match for your query. Field queries typically follow the format {dataset.field} {operator} {value}. This structure can be extended with nested fields, lists, and logical operators as needed.

There are numerous operators available for search. Two key operators are : and =. The :operator performs a contains match. It returns records where the field contains the specified value. The = operator performs an exact match. It returns records where the field exactly equals the value.

You can also combine multiple conditions with AND, OR, NOT, and () to build more complex queries.

See Censys Query Language for a complete description of the CenQL syntax.

Search results

To interpret search results, host.location.country = "China" is used as an example. The search results show a list of hosts located in China.

Filter results

Filter the results of your search using the options on the left side of the page. Filters vary depending on the type of asset you target with your search.

Select the aggregation button in a filter section to generate a report of your search results broken down by that field.

📘

Note

If your search results contain multiple asset types, then the aggregation button will not appear in the filter sidebar.

Actionable data

Click on a host in the search results to see important information about the host.

An example details page for a host record is shown below.

At the top, the IP address is displayed. There are 13 open ports and services on this host. The host is located in Shanghai, under China Telecom (AS4812).

Actionable data for this host includes:

• There is an exposed remote access (SSH on port 22) service. This is significant because SSH is open to the public internet and is often targeted for brute-force attacks.
• There are numerous HTTP services on high or non-standard ports. Port 3000 often indicates a development environment. 18080 is a non-standard port often used as an alternative to the standard HTTP port 80 or HTTPS port 443. Ports 9981 through 9986 are within the range of non-standard ports, often used for various applications and services.

While these ports can indicate a development environment or alternative configurations, they can also signal a security measure that obscures services from attackers relying on standard port scans.

Collections

Collections allow you to track and monitor the results of a Censys query over time. Collections save you time and resources as they tracks additions and removals to assets that match your queries.

Follow the steps below to quickly create a collection.

1. In the left sidebar, click Collections.
2. Click Create Collection and enter a Collection Name.
3. Enter a valid query that defines the collection membership. A collection may only target one query. Multiple queries or search criteria can be combined using the or operator.
4. Use the Size Estimator to view the number of assets it currently returns.
5. (Optional) Add a description to explain the purpose of the collection. Select a Collection Category to filter collections and displayed alerts, enhancing triage efficiency.
6. Click Create.

Webhooks

Collection webhooks provide organizations with the ability to receive trigger-based updates when new assets are added to or removed from their collection. Webhooks deliver Censys data to various applications, enabling users to monitor events and take action as needed.

To configure webhooks, you need a target URL from the application that receives the webhook. Follow the instructions below to create a webhook:

1. Go to Settings in the side navigation menu and click Alerts and Notifications.
2. On the Alerts and Notifications page, click Create New Webhook and name it.
3. Enter the target URL. This URL is where Censys sends HTTPS requests for event delivery. The target URL is provided by the web service that receives the events.
4. Select one or more collections as the source of trigger events.
5. In the Event Types section, select the checkbox for each collection event you want to trigger the webhook.
6. In the Advanced Settings section, Select an optional payload template. The payload template defines the structure and content of the data sent to your webhook URL when a collection event occurs.
7. Click Test Webhook.

Organization Switcher

The Organization Switcher allows users to switch between organizations they belong to and their Free account. Users can seamlessly access their different accounts, navigate, and interact with organization-specific data and functionality. You can use your Free tier as a sandbox environment to explore search capabilities, refine queries, test Platform features, and more, without using your paid credits. You must have a Starter or Enterprise tier account or be a member of an organization to use the Organization Switcher.

Click Switch in the upper left and select the org you want to use.

To learn more, see Organization Switcher.

Censys Platform API

The Censys Platform API offers numerous endpoints for Global Aata and Collections. The quickest way to make an API call is on the reference documentation using the the Try It feature. For example, go to the Asset/Host endpoint, on the right side of the page click Try It to run a live API call and see the results instantly.

Before you try to make call, read the Get Started guide. To make a call with this endpoint, you need to locate your Org ID, create a Personal Access Token, and provide an IP address in the host_id path parameter. After you locate and enter the required information, click Try It and the response displays below.

Legacy Search users

Users transitioning from Legacy Search to the Censys Platform are encouraged to review the transition guides. These guides are designed to streamline the process and accelerate time to value.

• Transition Guides for Free Users, Solo, and Teams Subscribers
• Censys Platform Syntax Differences
• Dataset Differences: Censys Platform vs. Legacy Search

Query Converter

The Query Converter is designed to help users transition the queries they used in Legacy Search to the Platform. Enter a Legacy Search query into the Query Converter to identify syntax differences and view recommended changes to correct your query.

To learn more, see the Query Converter documentation.