Vertex Synapse
Vertex Synapse keeps your threat intelligence as a graph in a Cortex: indicators,
infrastructure, files, threats, techniques and reports as nodes, with your
analysts' and feeds' assessments recorded as tags such as #rep.vendor.c2 or
#cno.threat.lockbit. Connect a Cortex and Huntbase queries it where it is, in
Storm, Synapse's query language. Nothing is copied out of the Cortex, and
Huntbase never changes it.
With a Vertex Synapse connection you can:
- run Storm from a query tab, in hunts and from the starter query templates;
- let Scout check your Cortex for the IPs, domains, URLs and hashes in an investigation, alongside your other connected tools;
- see what your intel says about a value next to what your telemetry says about it.
To bring the hunts on the Huntbase Hub into your Cortex, see Use Huntbase Hub hunts in Vertex Synapse.
Before you start
You need:
- a Synapse 3.x Cortex whose HTTPS API (port 4443 by default) Huntbase can reach;
- a Synapse user for Huntbase that can read the view you want to hunt in;
- an API key for that user.
Huntbase only reads, so the user needs no write permissions. In Storm, as an admin:
auth.user.add huntbase
auth.user.addrule huntbase view.read
To limit the user to one view, add the rule on that view only, with the view's
iden from view.list:
auth.user.addrule huntbase view.read --gate <view iden>
Then create the key:
$u = $lib.auth.users.byname(huntbase)
($key, $info) = $u.genApiKey(huntbase)
$lib.print($key)
The key starts with syn-. Copy it now: Synapse doesn't show it again.
Give Huntbase its own user rather than reusing an analyst's key, so you can see its activity and revoke it on its own.
Connect Vertex Synapse
- Go to Connections, click New connection and pick Vertex Synapse.
- On Details, name the connection.
- On Connect, enter the Cortex URL, such as
https://synapse.example.com:4443, and paste the API key. - If the Cortex still uses the self-signed certificate Synapse creates, paste its CA under CA certificate (PEM), or turn off Verify TLS certificate.
- On Verify, click Create & check.
Settings
| Field | Notes |
|---|---|
| Cortex URL | The Cortex HTTPS API, with its port. It must be reachable from Huntbase and can't point at localhost. |
| API key | The Synapse user's API key. It is sent in the X-API-KEY header. |
| View | Under Advanced. The iden of the view to query, from view.list (32 hexadecimal characters). Leave it empty to query the user's default view. |
| Verify TLS certificate | On by default. Turn it off only to skip the check for a self-signed certificate. |
| CA certificate (PEM) | Under Advanced. The Cortex's certificate, or the CA that signed it. When it is set, Huntbase checks the certificate against it instead of turning verification off. |
| Row limit | Under Advanced. The most nodes one query returns: 10,000 by default, and never more than 10,000. |
The connection check
Create & check, and Test connection on the connection page later, run one read-only Storm call against the Cortex. It checks the URL, the key and the view together. When it fails, it says which:
| Message | What to do |
|---|---|
| Synapse rejected the API key. | Check the key, and that the user isn't locked. |
| The Synapse user can't read this view. Grant it view.read. | Add the view.read rule to the user, on that view. |
| Synapse has no view with this iden. | Copy the iden again from view.list, or clear View. |
| No Synapse Storm API at this URL. | Check the Cortex URL and port. Use the HTTPS API, not Optic. |
| Synapse did not answer in time. | Check the URL and port, and that your firewall lets Huntbase in. |
After the check passes, Huntbase reads the Cortex's data model and lists the
forms that have nodes in the view, largest first, up to 100. They appear under
Discovered Schema on the connection page and in the query tab's Schema
tree, with each form's properties as columns. Synapse's own syn:* forms are
left out.
Query Synapse in Storm
In a query tab, pick Storm and your
Vertex Synapse connection. A Storm query lifts nodes by form, property or tag,
filters them with + and -, and pivots through the graph:
inet:fqdn#rep.vendor.c2 -> inet:dns:a -> inet:ip
- The editor completes the forms in your Cortex and, after a
|, the read-only Storm commands. - Storm has no time-range pill. Filter on time in the query, for example
+.created>=-7days. - Use
?=to try a value that might not fit the form:inet:ip?=example.comreturns nothing instead of failing. - In a template, a
{{name}}parameter arrives as a quoted Storm string. Assign it to a variable and use the variable:$tag = {{tag}}then#$tag.
See Query languages › Storm for more.
Starter queries
The connection ships with four templates in Content library › Queries:
| Template | What it returns |
|---|---|
| Look up an indicator in Synapse | The node for an IP address, domain, URL or file hash (MD5, SHA-1 or SHA-256), with its properties and tags. Nothing, if the Cortex has never seen the value. |
| Nodes tagged with a threat | Every node carrying a tag or one of its child tags, such as cno.threat.lockbit or rep.vendor.c2. The IPs, domains and hashes it returns can seed a retro-hunt in your logs. |
| Recent threats and their techniques | Threats (risk:threat) added in the last few days that have techniques linked, together with those techniques (meta:technique). |
| Huntbase Hub hunts in Synapse | The Huntbase Hub hunts in your Cortex, filtered to an ATT&CK technique and its sub-techniques. Use T1 to list them all. |
Result columns
Each node the query returns is one row:
| Column | Contents |
|---|---|
| form | The node's form, such as inet:ip or risk:threat. |
Value (valu) | The node's primary value, as Synapse displays it. IP addresses and domains become entity chips. |
| threat_tags | The node's reputation and threat tags: #rep.*, #cno.threat.*, #cno.mal.*, #threat.* and #mal.*. |
| tags | All the node's tags, without the parent tags Synapse adds. |
| iden | The node's identifier in the Cortex. |
| created | When the node was created in the Cortex. |
| props.<name> | One column per property, such as props.asn or props.title. |
Rows feed entity extraction, the entity graph and insights like any other source's.
Scout and Synapse
When you ask Scout whether you were affected by an IP, domain, URL or hash, it searches every connected tool for them at once. A Vertex Synapse connection is one of those tools: Scout runs one read-only Storm lookup for all the values.
A match in Synapse is not a sighting. It means your own intelligence graph knows the value, and Scout quotes the node's tags as what your intel says about it. Whether the value was seen in your estate comes from your telemetry and your other tools.
This search follows the Scout mode you've chosen. In Guide, Scout says which tools it would search and asks first. In Collaborator it searches up to five tools at once and asks before more. In Operator it searches straight away. Scout uses a connection only while its Scout access is on. See The connection page.
Limits
- Read-only. Every query runs with Storm's read-only option. A query that tries to create, edit or delete nodes, tags or edges fails with Huntbase runs Storm read-only, and this query edits the graph and changes nothing.
- Row limit. A query returns at most the connection's Row limit, and
never more than 10,000 nodes. Huntbase stops reading at the limit, so narrow
the query or end it with
| limit. - Run time. A query that takes more than five minutes is stopped.
- One view. Each connection queries one view. To hunt in another view, create a second connection.
- Errors. When Synapse rejects a query, the run shows Synapse's own error, for example Query rejected by Synapse (BadSyntax): ….