Admin Guide
Synapse-Censys Admin Guide
Configuration
Synapse-Censys requires a Censys Platform API key and organization ID. For information on how to sign up, please visit the Censys Platform API reference.
Censys Platform users will need to be granted the “API Access” role in the Censys Platform Account Management panel. Instructions on how to do that can be found in Role-Based Access Control on the Censys website.
Setting API key for global use
To set-up a global API key:
> censys.config.add default myapikey myorgid
Synapse-Censys config "default" added
Using per-user API keys
A user may set-up their own API key:
> censys.config.add --scope self myconfig myapikey myorgid
Synapse-Censys config "myconfig" added
Censys Legacy API configuration
The Censys Legacy API commands are deprecated and will be removed when the Censys
Legacy API reaches end of life on 2026-12-31. They use separate
synapse-censys-legacy configurations, which hold a Censys Legacy API ID, a
tag prefix, and the proxy and SSL verification settings, with the Censys Legacy
API secret stored as a secret. The
censys.legacy.config.* commands manage these configurations, and the
Censys Platform censys.config.* commands do not see them.
To set-up a global Censys Legacy API ID and secret:
> censys.legacy.config.add default myapiid mysecret
WARNING: "censys.legacy.config.add" is deprecated: This command relies on the Censys Legacy API.
Synapse-Censys legacy config "default" added
A user may set-up their own Censys Legacy API ID and secret:
> censys.legacy.config.add --scope self mylegacy myapiid mysecret
WARNING: "censys.legacy.config.add" is deprecated: This command relies on the Censys Legacy API.
Synapse-Censys legacy config "mylegacy" added
To change the tag prefix used by a legacy configuration:
> censys.legacy.config.update default --tag-prefix my.censys
WARNING: "censys.legacy.config.update" is deprecated: This command relies on the Censys Legacy API.
Updated Synapse-Censys legacy config "default"
Users may select a legacy configuration other than their default by passing
--config <name> to the Censys Legacy API commands.
On upgrade, the global Censys Legacy API key and tag prefix are migrated to a
global synapse-censys-legacy:default configuration, and per-user keys are
migrated to user-scoped configurations named synapse-censys-legacy:<useriden>.
The global tag prefix is also applied to the migrated user configurations.
Malformed keys and an invalid tag prefix are skipped with a warning.
Dependencies
Synapse-Censys requires the following Power-Ups to be installed:
Name : synapse-fileparser
Version: >=4.9.0,<=5.0.0
Desc : Synapse-FileParser is used to parse raw certificates. If not installed the fields from the JSON response will be used.
Synapse-Censys will conflict with the following Power-Ups:
Name : censys
Version: any
Desc : Synapse-Censys conflicts with a deprecated Power-Up named "censys".
Permissions
Package (synapse-censys) defines the following permissions:
power-ups.censys.user : Controls user access to Synapse-Censys. ( default: false )
power-ups.censys.admin : Controls access to Synapse-Censys admin options. ( default: false )
You may add rules to users/roles directly from storm:
> auth.user.addrule visi power-ups.censys.user
Added rule power-ups.censys.user to user visi.
or:
> auth.role.addrule ninjas power-ups.censys.user
Added rule power-ups.censys.user to role ninjas.
Exported APIs
Synapse-Censys does not currently export any APIs.
Node Actions
Synapse-Censys provides the following node actions in Optic:
Name : platform.hosts.enrich
Desc : Enrich IP nodes with host data
Forms: inet:ipv4, inet:ipv6
Name : platform.certs.enrich
Desc : Enrich nodes that resolve to a SHA-256
Forms: hash:md5, hash:sha1, file:bytes, hash:sha256, inet:ssl:cert, inet:tls:clientcert, inet:tls:servercert, crypto:x509:cert
Name : platform.certs.observations
Desc : Get certificate observations nodes from a SHA-256
Forms: hash:md5, hash:sha1, file:bytes, hash:sha256, inet:ssl:cert, inet:tls:clientcert, inet:tls:servercert, crypto:x509:cert
Name : platform.certs.download
Desc : Download and parse certificate PEM file from a SHA-256
Forms: hash:md5, hash:sha1, file:bytes, hash:sha256, inet:ssl:cert, inet:tls:clientcert, inet:tls:servercert, crypto:x509:cert
Name : hosts.enrich
Desc : Enrich IP nodes with host data
Forms: inet:ipv4, inet:ipv6
Name : hosts.domain
Desc : Search for hosts by domain
Forms: inet:fqdn
Name : certs.enrich
Desc : Enrich nodes that resolve to a SHA-256
Forms: hash:md5, hash:sha1, file:bytes, hash:sha256, inet:ssl:cert, inet:tls:clientcert, inet:tls:servercert, crypto:x509:cert
Name : certs.subdomains
Desc : Discover subdomains
Forms: inet:fqdn
Name : certs.observations
Desc : Get certificate observations nodes from a SHA-256
Forms: hash:md5, hash:sha1, file:bytes, hash:sha256, inet:ssl:cert, inet:tls:clientcert, inet:tls:servercert, crypto:x509:cert
Ingesting CPE strings
The Censys API may sometimes return invalid CPE strings. Invalid CPE strings will be rejected by Synapse when attempting to ingest the API data. As a workaround, the Synapse-Censys Power-Up peforms the following transformations on CPE strings before attempting to ingest them:
Replace
\-with-. Dashes (hyphens) should not be escaped according to the CPE 2.3 specification.
Synapse v2.187.0 migration
Synapse v2.187.0 added a model migration (v0.2.31) that removed all invalid
it:sec:cpe nodes from the Cortex. The Synapse-Censys init migration
uses the above transformations to attempt to automatically repair and restore
invalid it:sec:cpe nodes that originated from the Synapse-Censys Power-Up.