CLI Usage

Before continuing please ensure you have successfully configured your credentials.

censys config

The configuration file by default is written to ~/.config/censys/censys.cfg, but you can change this by setting the CENSYS_CONFIG_PATH environment variable.

export CENSYS_CONFIG_PATH=/path/to/config/file

Optionally, you can enable tab completion for the CLI by adding this line to your ~/.bashrc, ~/.zshrc, or equivalent.

eval "$(register-python-argcomplete censys)"

Note

Please note that autocomplete is supported for field names in the search command.

search

Below we show an example of searching hosts from the CLI.

censys search 'services.http.response.html_title: "Dashboard"'

By combining the search command with jq we can easily manipulate the output to get the desired fields.

censys search 'services.service_name: ELASTICSEARCH' | jq -c '.[] | {ip: .ip}'

By setting the --pages flag to -1 we can get all pages of results.

censys search 'ip: 8.8.8.0/16' --pages -1 | jq -c '[.[] | .ip]'

By settings the --index-type flag we can search other indexes such as certificates.

censys search 'parsed.subject_dn: "censys.io"' --index-type certificates

For the certificates index we can also add the --fields flag to specify which fields we want returned.

censys search 'parsed.subject.country: AU' --index-type certificates --fields parsed.issuer.organization

view

Below we show an example of viewing a host from the CLI.

censys view 8.8.8.8

Below we show an example of viewing a certificate from the CLI.

censys view 9b267decc8d23586dc4c56dd0789574cab0f28581ef354ff2fcec8ca6d992fc2 --index-type certificates

You can save results to a file using the -o argument.

censys view 8.8.8.8 -o google.json

We can then parse this json with something like jq.

cat google.json | jq '[.services[] | {port: .port, protocol: .service_name}]'

If you have access to historical hosts data you can view the data at a specific point in time using the --at-time argument.

censys view 1.1.1.1 --at-time 2023-01-01

Note

The --at-time argument is only available for the hosts index.

subdomains

Below we show an example of subdomain enumeration from the CLI.

censys subdomains censys.io

You can limit the number of results by setting the --max-records flag.

censys subdomains censys.io --max-records 10

We can then output the results in JSON format using the --json flag.

censys subdomains censys.io --json

account

Below we show an example of viewing your account information from the CLI.

censys account

You can also request the JSON version of your account information.

censys account --json

asm

add-seeds

See CLI command asm add-seeds for detail documentation of parameters.

Below we show an example of adding seeds from the CLI.

censys asm add-seeds -j '["1.1.1.1"]'

You can add seeds from JSON or CSV files. JSON is assumed unless --csv is specified. The CSV file option is shown here.

censys asm add-seeds --csv -i 'good_seeds.csv'

CSV File Format

type	value	label
IP_ADDRESS	1.1.1.1	Example Label
DOMAIN_NAME	one.one.one.one	Example Label

You can also add seeds from STDIN using the -i - argument. In the example below we are adding IPs from a Censys Search.

censys search 'services.tls.certificates.leaf_data.issuer.common_name: "Roomba CA"' | jq '[.[] | .ip]' | censys asm add-seeds -i -

You can also add seeds from an nmap XML file using the --nmap-xml argument. In the example below we are adding IPs from a nmap scan on censys.io.

nmap censys.io -oX censys.xml
censys asm add-seeds --nmap-xml censys.xml

delete-seeds

See CLI command asm delete-seeds for detail documentation of parameters.

Below we show an example of deleting seeds from the CLI.

censys asm delete-seeds -j '["1.1.1.1"]'

You can delete seeds using file input as well, including CSV files.

censys asm delete-seeds --csv -i 'bad_seeds.csv'

CSV File Format

id	type	value	label
1	IP_ADDRESS	1.1.1.1	Example Label
2	DOMAIN_NAME	one.one.one.one	Example Label

delete-all-seeds

See CLI command asm delete-all-seeds for detail documentation of parameters.

Below we show an example of deleting all seeds from the CLI. You will be prompted to confirm.

censys asm delete-all-seeds

If you want to delete all seeds without a prompt, you can use the --force parameter.

censys asm delete-all-seeds --force

delete-labeled-seeds

See CLI command asm delete-labeled-seeds for detail documentation of parameters.

Below we show an example of deleting all seeds with a given label from the CLI.

censys asm delete-labeled-seeds -l "Some Label"

replace-labeled-seeds

See CLI command asm replace-labeled-seeds for detail documentation of parameters.

Below we show an example of replacing labeled seeds from the CLI, which will replace all existing seeds that have the specified label with the provided seeds, which will also have that label applied.

censys asm replace-labeled-seeds -l "Some Label" -j '["1.1.1.1"]'

You can also use a variety of methods to specific the new seeds, including providing them in a CSV file.

censys asm replace-labeled-seeds -l "Some Label" --csv -i 'new_seeds.csv'

list-seeds

See CLI command asm list-seeds for detail documentation of parameters.

Below we show an example of listing all seeds in CSV file format and appending it to a file.

censys asm list-seeds --csv >> seeds.csv

You can also filter the seeds by type (-t) and/or label (-l).

censys asm list-seeds -t 'IP_ADDRESS' -l 'Some Label' >> filtered_seeds.json

list-saved-queries

See CLI command asm list-saved-queries for detail documentation of parameters.

Below we show an example of listing all saved queries in CSV file format and appending it to a file.

censys asm list-saved-queries --csv >> saved_queries.csv

You can also filter the saved queries by query name prefix (--query-name-prefix) and/or filter term (--filter-term).

censys asm list-saved-queries --query-name-prefix 'Some Prefix' --filter-term 'Some Term' >> filtered_saved_queries.json

add-saved-query

See CLI command asm add-saved-query for detail documentation of parameters.

Below we show an example of adding a saved query from the CLI.

censys asm add-saved-query --query-name 'Some Query' --query 'services.http.response.html_title: "Dashboard"'

get-saved-query-by-id

See CLI command asm get-saved-query-by-id for detail documentation of parameters.

Below we show an example of getting a saved query by ID from the CLI.

censys asm get-saved-query-by-id --query-id 'Some ID'

edit-saved-query-by-id

See CLI command asm edit-saved-query-by-id for detail documentation of parameters.

Below we show an example of editing a saved query by ID from the CLI.

censys asm edit-saved-query-by-id --query-id 'Some ID' --query-name 'Some Query' --query 'services.http.response.html_title: "Dashboard"'

delete-saved-query-by-id

See CLI command asm delete-saved-query-by-id for detail documentation of parameters.

Below we show an example of deleting a saved query by ID from the CLI.

censys asm delete-saved-query-by-id --query-id 'Some ID'

execute-saved-query-by-name

See CLI command asm execute-saved-query-by-name for detail documentation of parameters.

Below we show an example of executing a saved query by name from the CLI.

censys asm execute-saved-query-by-name --query-name 'Some query name'

execute-saved-query-by-id

See CLI command asm execute-saved-query-by-id for detail documentation of parameters.

Below we show an example of executing a saved query by ID from the CLI.

censys asm execute-saved-query-by-id --query-id 'Some query ID'

search

See CLI command asm search for detail documentation of parameters.

Below we show an example of executing an inventory search query from the CLI.

censys asm search --query 'Some query'