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

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

Onload Events

Synapse-Censys uses the onload event to run required data migrations.

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 onload 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.