Admin Guide

Synapse-Censys Admin Guide

Configuration

Synapse-Censys requires a Censys API key. For information on how to sign up, please visit the Censys API documentation.

Setting API key for global use

To set-up a global API key:

> censys.setup.apikey myapiid myapisecret
Setting Synapse-Censys API key for all users.

Using per-user API keys

A user may set-up their own API key:

> censys.setup.apikey --self myapiid myapisecret
Setting Synapse-Censys API key for the current user.

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 )

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 : 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

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.