Admin Guide

Synapse-DomainTools Admin Guide

Configuration

Synapse-DomainTools requires a DomainTools API user and API key. For PDNS data, the Farsight DNSDB requires an additional separate API key. A configuration may hold the DomainTools API credentials, a Farsight DNSDB API key, or both. For information on how to sign up, please visit the DomainTools API documentation.

Setting the configuration for global use

To set-up a global configuration:

> domaintools.config.add default --apiuser myapiuser --apikey myapikey --farsight-apikey myfarsightkey
Synapse-DomainTools config "default" added

The API keys are validated with DomainTools and Farsight when a configuration is added or updated. Use --no-check-apikey to skip the validation.

Commands which use the DomainTools API require the DomainTools API credentials, and commands which use the Farsight DNSDB API require the Farsight API key, in the configuration that is used.

Creating a configuration for role-based use

Add an unscoped configuration:

> domaintools.config.add myunscoped --apiuser myapiuser --apikey myapikey --scope unscoped
Synapse-DomainTools config "myunscoped" added

Grant another user admin permissions to the new configuration:

> domaintools.config.update myunscoped --perm user visi admin --no-check-apikey
Updated Synapse-DomainTools config "myunscoped"

Grant a role read permissions to the new configuration:

> domaintools.config.update myunscoped --perm role ninjas read --no-check-apikey
Updated Synapse-DomainTools config "myunscoped"

Setting the Farsight DNSDB API URL

The Farsight DNSDB API URL defaults to https://api.dnsdb.info and may be changed for a configuration:

> domaintools.config.update myunscoped --farsight-url https://api.dnsdb.info --no-check-apikey
Updated Synapse-DomainTools config "myunscoped"

Overriding the proxy configuration

In order to override the default proxy configuration in the Cortex the user must have the power-ups.domaintools.admin or storm.lib.inet.http.proxy permission.

When the proxy configuration is set to (false) or a URL the permission will be checked when a configuration is created/updated, and when it is used to make an HTTP request.

Authenticating to the proxy

A configuration with a proxy URL may also provide credentials for the proxy:

> domaintools.config.update myunscoped --proxy http://proxy.vertex.link:3128 --proxy-user visi --proxy-passwd secret --no-check-apikey
Updated Synapse-DomainTools config "myunscoped"

The username is stored in the configuration and the password is stored in the configuration secrets. The credentials are only valid with a proxy URL, and are removed if the proxy is later set to (true) or (false). The values must be URL safe, see $lib.inet.http.urlencode.

Dependencies

Synapse-DomainTools does not have any dependencies.

Permissions

Package (synapse-domaintools) defines the following permissions:
power-ups.domaintools.user       : Controls user access to Synapse-DomainTools. ( default: false )
power-ups.domaintools.admin      : Controls access to Synapse-DomainTools admin options. ( default: false )

You may add rules to users/roles directly from storm:

> auth.user.addrule visi power-ups.domaintools.user
Added rule power-ups.domaintools.user to user visi.

or:

> auth.role.addrule ninjas power-ups.domaintools.user
Added rule power-ups.domaintools.user to role ninjas.

Exported APIs

Synapse-DomainTools does not currently export any APIs.

Workflows

Synapse-DomainTools provides the following workflows in Optic:

Title: Configuration

Node Actions

Synapse-DomainTools provides the following node actions in Optic:

Name : iris.enrich
Desc : Enrich nodes using Synapse-DomainTools
Forms: inet:fqdn

Name : whois.history
Desc : Enrich nodes with Whois history data using Synapse-DomainTools
Forms: inet:fqdn

Name : hosting.history
Desc : Enrich nodes with hosting history data using Synapse-DomainTools
Forms: inet:fqdn

Name : pdns
Desc : Enrich nodes with PDNS data using Synapse-DomainTools
Forms: inet:fqdn, inet:ipv4, inet:ipv6, inet:cidr4, inet:cidr6

Name : pdns (include subdomains)
Desc : Include subdomains when searching for PDNS data using Synapse-DomainTools
Forms: inet:fqdn

Onload Events

Synapse-DomainTools uses an onload event to add extended model properties for DomainTools data. It uses Storm package inits to run required data migrations.

The node migrations run in every view and require Synapse v2.255.0 or later. They migrate the nodes in the write layer of each view. A layer which is not the write layer of any view is not migrated. Views with a read-only write layer are skipped with a warning. Each migration runs once.