Synapse (The Vertex Project)

Synapse, from The Vertex Project, is a threat intelligence platform. It stores intelligence as nodes in a graph, and analysts query and pivot on that graph with Storm, its query language, from an in-app command line. The DomainTools Power-Up adds Storm commands that call DomainTools APIs and bring the results back into Synapse as nodes.

The Vertex Project builds and maintains the Power-Up. This page covers what the Power-Up provides, what you need to run it, and how DomainTools Threat Feeds fit in. For the authoritative command reference and setup steps, follow the links to the Vertex documentation throughout.

Supported DomainTools products

The Power-Up surfaces these DomainTools APIs as Storm commands:

Iris Investigate: search and pivot across the Iris Investigate attribute model (domain, IP, email, name server, mail server, SSL, and more).
Iris Enrich: enrich a domain with the Iris data set.
Iris Detect: pull monitored and newly discovered domains.
WHOIS History: retrieve historical WHOIS records for a domain.
Hosting History: retrieve IP, name server, and registrar history for a domain.
Farsight DNSDB: run passive DNS rrset and rdata lookups, and flexible search.

Each API requires its own DomainTools entitlement. Farsight DNSDB uses a separate API key (see Requirements). If you aren’t sure what your account includes, contact your DomainTools representative.

Requirements

A Synapse deployment with the DomainTools Power-Up installed.
A DomainTools API username and API key, with entitlement to the APIs you plan to use.
A Farsight DNSDB API key, if you use the passive DNS commands (domaintools.pdns, domaintools.pdns.search).
The power-ups.domaintools.user permission in Synapse, granted by an administrator.

Install and set up

The DomainTools Power-Up installs from within Synapse, and your DomainTools representative can help you get set up. After it’s installed, an administrator grants access and sets the API credentials. The exact steps live in the Vertex admin guide and user guide. This page summarizes the Storm commands.

Set the DomainTools credentials for all users:

domaintools.setup.apikey YOUR_API_USERNAME YOUR_API_KEY

Or set them for your own user only, with --self:

domaintools.setup.apikey --self YOUR_API_USERNAME YOUR_API_KEY

Set the Farsight DNSDB key used by the passive DNS commands:

domaintools.farsight.setup.apikey YOUR_DNSDB_API_KEY

The Power-Up tags command results under the rep.domaintools prefix by default. Change it with domaintools.setup.tagprefix if you follow a different tag convention.

Grant a user or role permission to use the Power-Up:

auth.user.addrule USERNAME power-ups.domaintools.user
auth.role.addrule ROLE power-ups.domaintools.user

Verify the setup

Confirm the Power-Up can reach the DomainTools API:

domaintools.limits

Then enrich a known domain and confirm nodes return:

inet:fqdn=domaintools.com | domaintools.iris.investigate --yield

If a command returns an authorization error, check that the user holds the power-ups.domaintools.user permission and that the API credentials are in place.

Storm commands

Run these from the Synapse command line after you install and configure the Power-Up. Each command takes input nodes such as inet:fqdn or inet:ipv4, plus options. For the full option list, see the Vertex package documentation.

Command	Description
`domaintools.iris.investigate`	Search and pivot with Iris Investigate.
`domaintools.iris.enrich`	Enrich a domain with Iris Enrich.
`domaintools.iris.detect`	Retrieve monitored and newly discovered domains from Iris Detect.
`domaintools.whois.history`	Retrieve WHOIS History for a domain.
`domaintools.hosting.history`	Retrieve Hosting History for a domain.
`domaintools.pdns`	Run a Farsight DNSDB passive DNS lookup (rrset, or rdata with `--rdata`).
`domaintools.pdns.search`	Run a Farsight DNSDB flexible search.
`domaintools.limits`	Show your current DomainTools API usage and limits.

Use domaintools.iris.enrich for straightforward attribute enrichment, and domaintools.iris.investigate to search and pivot across the Iris data model.

Search and pivot on a domain with Iris Investigate, and yield the resulting nodes:

inet:fqdn=example.com | domaintools.iris.investigate --yield

Reverse off an IP address to find connected domains:

inet:ipv4=8.8.8.8 | domaintools.iris.investigate --ip $node --yield

Enrich nodes in the Synapse UI

Beyond the Storm command line, the Power-Up adds right-click actions in the Synapse tabular view. Select one or more nodes, right-click, then navigate to Actions > synapse-domaintools to choose an enrichment operation.

The available operations are:

iris.enrich — Enrich the selected domains with Iris Enrich data.
whois.history — Retrieve WHOIS History for the selected domains.
hosting.history — Retrieve Hosting History (IP, name server, and registrar history) for the selected domains.
pdns — Run a Farsight DNSDB passive DNS lookup for the selected nodes.
pdns (include subdomains) — Run a Farsight DNSDB passive DNS lookup and include subdomains.

These UI actions call the same underlying Storm commands as the command-line equivalents. Results are added to the graph as nodes.

Ingest DomainTools Threat Feeds

Beyond interactive enrichment, you can pull DomainTools Real-Time Threat Feeds directly into Synapse using core Storm, independent of the Power-Up commands. Use cron.add to poll a feed on a schedule and model each record as a node.

Adding a cron job requires Synapse cron rights (the cron.add permission), which an administrator grants separately from the Power-Up permission. If cron.add returns an authorization error, ask your administrator to grant it.

The following cron job polls the Newly Observed Domains (NOD) feed every five minutes and records each new domain as an inet:fqdn node tagged #rep.domaintools.nod. When a batch is large, the feed can return a 206 (partial content). The job repeats the request with the same sessionID until it receives a 200, so it drains the full backlog instead of dropping records:

cron.add --name "DomainTools NOD feed" --minute +5 {
    $url = 'https://api.domaintools.com/v1/feed/nod/?sessionID=synapse'
    $headers = ({ 'X-Api-Key': 'YOUR_API_KEY' })

    $more = (1)
    while ($more = (1)) {
        $resp = $lib.inet.http.get($url, headers=$headers)
        $ingest = (0)
        if ($resp.code = 200) {
            $ingest = (1)
            $more = (0)
        }
        elif ($resp.code = 206) {
            $ingest = (1)
        }
        else {
            $more = (0)
        }
        if ($ingest = (1)) {
            for $line in $resp.body.decode('utf-8').split("\n") {
                if ($lib.len($line) > 0) {
                    $item = $lib.json.load($line)
                    [ inet:fqdn=$item.domain .seen=$item.timestamp +#rep.domaintools.nod ]
                }
            }
        }
    }
}

The feed returns newline-delimited JSON, one record per line, each with a domain and a timestamp. The sessionID tracks your position, so each poll returns only records seen since the last request. For authentication options, session behavior, and query parameters, see the API reference for the NOD feed.

Confirm records are landing by lifting the tagged nodes:

inet:fqdn#rep.domaintools.nod | limit 10

Other feeds follow the same pattern against their own endpoint. The Domain Hotlist feed, for example, adds risk fields (overall_risk, proximity_risk, malware_risk, phishing_risk, spam_risk) that you can store on each node. See the Threat Feeds API documentation for feed endpoints, fields, and authentication.