DevOps Guide

Overview

For a general overview of common devops tasks for Synapse services see Synapse Devops Guide - Overview.

Devops Details

Axon Usage

Although optional, it is highly recommended to configure an Axon for the Synapse Rapid7 SonarSSL service. Without an Axon:

Raw Rapid7 files will not be saved, preventing resuming a partially indexed file.

Raw certificate bytes will not be saved, and therefore only the SHA256 of the certificate will be available.

There are also benefits to configuring Synapse Rapid7 SonarSSL with the same Axon as that used by the Cortex so that the certificate bytes can be more seamlessly shared.

Storage Requirements

Since Synapse Rapid7 SonarSSL is locally indexing the data, the service should be deployed and configured with sufficient storage, and monitored as indexing progresses. For example, all of the historical raw zipped files alone require at least 750GB.

Indexing

The Rapid7 data is retrieved as files linking the SHA1 of an X.509 SSL certificate to other data from the scan. The following names are used as keys for the file types:

ssl_certs: Links the certificate SHA1 to the base64-encoded certificate itself. The SHA256 is generated from this data.
ssl_endpoints: Links the certificate SHA1 to a scanned host IPv4 and port.
ssl_names: Links the certificate SHA1 with the Common Name or one of the SubjectAltName entries.

The Rapid7 file name is also used to extract the scan timestamp.

The following fields are then indexed, which allows for fast querying:

Address (host IPv4 and port from ssl_endpoints)
SHA256 of the certificate
SHA1 of the certificate

Docker Images

The Synapse Rapid7 SonarSSL service is available as a Docker container from Docker Hub. The repository can be found at:

https://hub.docker.com/repository/docker/vertexproject/synapse-rapid7/

Note

There are tagged images available on Docker Hub which correspond to software releases seen in the changelog. The docker tag master is the latest development release. A generic major version tag is available, representing the latest release on a given major version. For example, the v3.x.x tag represents the most current release for the v3.x.x release line. You can utilize specific tagged versions, or a major version specifier, depending on your chosen deployment strategy.

Configuration Options

The following is a list of available configuration options.

aha:admin

An AHA client certificate CN to register as a local admin user.

Type: string
Environment Variable: SYN_RAPID7SONARSSL_AHA_ADMIN

aha:leader

The AHA service name to claim as the active instance of a storm service.

Type: string
Environment Variable: SYN_RAPID7SONARSSL_AHA_LEADER

aha:name

The name of the cell service in the aha service registry.

Type: string
Environment Variable: SYN_RAPID7SONARSSL_AHA_NAME

aha:network

The AHA service network. This makes aha:name/aha:leader relative names.

Type: string
Environment Variable: SYN_RAPID7SONARSSL_AHA_NETWORK

aha:provision

The telepath URL of the aha provisioning service.

Type: ['string', 'array']
Environment Variable: SYN_RAPID7SONARSSL_AHA_PROVISION

aha:registry

The telepath URL of the aha service registry.

Type: ['string', 'array']
Environment Variable: SYN_RAPID7SONARSSL_AHA_REGISTRY

aha:user

The username of this service when connecting to others.

Type: string
Environment Variable: SYN_RAPID7SONARSSL_AHA_USER

auth:anon

Allow anonymous telepath access by mapping to the given user name.

Type: string
Environment Variable: SYN_RAPID7SONARSSL_AUTH_ANON

auth:passwd

Set to <passwd> (local only) to bootstrap the root user password.

Type: string
Environment Variable: SYN_RAPID7SONARSSL_AUTH_PASSWD

axon

Telepath url to axon.

Type: string
Environment Variable: SYN_RAPID7SONARSSL_AXON

backup:dir

A directory outside the service directory where backups will be saved. Defaults to ./backups in the service storage directory.

Type: string
Environment Variable: SYN_RAPID7SONARSSL_BACKUP_DIR

dmon:listen

A config-driven way to specify the telepath bind URL.

Type: ['string', 'null']
Environment Variable: SYN_RAPID7SONARSSL_DMON_LISTEN

https:headers

Headers to add to all HTTPS server responses.

Type: object
Environment Variable: SYN_RAPID7SONARSSL_HTTPS_HEADERS

https:parse:proxy:remoteip

Enable the HTTPS server to parse X-Forwarded-For and X-Real-IP headers to determine requester IP addresses.

Type: boolean
Default Value: False
Environment Variable: SYN_RAPID7SONARSSL_HTTPS_PARSE_PROXY_REMOTEIP

https:port

A config-driven way to specify the HTTPS port.

Type: ['integer', 'null']
Environment Variable: SYN_RAPID7SONARSSL_HTTPS_PORT

limit:disk:free

Minimum disk free space percentage before setting the cell read-only.

Type: ['integer', 'null']
Default Value: 5
Environment Variable: SYN_RAPID7SONARSSL_LIMIT_DISK_FREE

max:users

Maximum number of users allowed on system, not including root or locked/archived users (0 is no limit).

Type: integer
Default Value: 0
Environment Variable: SYN_RAPID7SONARSSL_MAX_USERS

nexslog:en

Record all changes to a stream file on disk. Required for mirroring (on both sides).

Type: boolean
Default Value: False
Environment Variable: SYN_RAPID7SONARSSL_NEXSLOG_EN

onboot:optimize

Delay startup to optimize LMDB databases during boot to recover free space and increase performance. This may take a while.

Type: boolean
Default Value: False
Environment Variable: SYN_RAPID7SONARSSL_ONBOOT_OPTIMIZE