User Guide

Synapse-Google Search User Guide

Synapse-Google Search adds new Storm commands to allow you to query the Google Search API using the /customsearch your existing API key.

Additionally, each URL in the search results is also downloaded to the Axon, and the corresponding inet:urlfile node is created.

Getting Started

Check with your Admin to enable permissions and find out if you need a personal API and CX key.

Examples

Setting your personal API key

To set-up a personal use API key and CX key:

> google.search.setup.apikey --self myapikey
Setting Synapse-Google Search API key for the current user.
> google.search.setup.cx --self mycxkey
Setting Synapse-Google Search CX key for the current user.

Performing Google Searches

The google.search.enrich command will perform a search based on the primary property of a node. In this case, we’re searching for the IP address 1.2.3.4.

> inet:ipv4=1.2.3.4 | google.search.enrich
inet:ipv4=1.2.3.4
        .created = 2025/05/10 11:04:34.806
        :type = unicast

You can also yield the search results as well.

> inet:ipv4=1.2.3.4 | google.search.enrich --yield | limit 3
inet:search:result=aa6472693513581a4d2b5884ec96be0f
        .created = 2025/05/10 11:04:34.988
        :query = 09d02195b4f6fb1b386909d3639bab2b
        :rank = 0
        :title = kegg enzyme: 1.2.3.4
        :url = https://www.genome.jp/dbget-bin/www_bget?ec:1.2.3.4
inet:search:result=7bbca69dfff1f29f315257c471fc9021
        .created = 2025/05/10 11:04:35.000
        :query = 09d02195b4f6fb1b386909d3639bab2b
        :rank = 1
        :title = 1.2.3.4 ip address geolocation lookup demo | ip2location
        :url = https://www.ip2location.com/demo/1.2.3.4
inet:search:result=8b5dcc2c84c60e849d7571102828f9ab
        .created = 2025/05/10 11:04:35.011
        :query = 09d02195b4f6fb1b386909d3639bab2b
        :rank = 2
        :title = 1.2.3.4 oxalate oxidase - enzyme
        :url = https://enzyme.expasy.org/EC/1.2.3.4

From those results, you can pivot directly to the URLS.

> inet:ipv4=1.2.3.4 | google.search.enrich --yield | limit 3 | -> inet:url
inet:url=https://www.genome.jp/dbget-bin/www_bget?ec:1.2.3.4
        .created = 2025/05/10 11:04:34.989
        :base = https://www.genome.jp/dbget-bin/www_bget
        :fqdn = www.genome.jp
        :params = ?ec:1.2.3.4
        :path = /dbget-bin/www_bget
        :port = 443
        :proto = https
inet:url=https://www.ip2location.com/demo/1.2.3.4
        .created = 2025/05/10 11:04:35.001
        :base = https://www.ip2location.com/demo/1.2.3.4
        :fqdn = www.ip2location.com
        :params =
        :path = /demo/1.2.3.4
        :port = 443
        :proto = https
inet:url=https://enzyme.expasy.org/EC/1.2.3.4
        .created = 2025/05/10 11:04:35.012
        :base = https://enzyme.expasy.org/EC/1.2.3.4
        :fqdn = enzyme.expasy.org
        :params =
        :path = /EC/1.2.3.4
        :port = 443
        :proto = https

The google.search command can be used to perform arbitrary searches based on user provided strings.

> google.search "cloud computing" --yield | limit 3
inet:search:result=f41241b773c63483315f6bd3cef0a01c
        .created = 2025/05/10 11:04:36.643
        :query = d862ea16c5af8cecc6f40a1ad37209f7
        :rank = 0
        :title = cloud computing - wikipedia
        :url = https://en.wikipedia.org/wiki/Cloud_computing
inet:search:result=b2c061771861732d6a682da8de0c8d00
        .created = 2025/05/10 11:04:36.652
        :query = d862ea16c5af8cecc6f40a1ad37209f7
        :rank = 1
        :title = what is cloud computing? | ibm
        :url = https://www.ibm.com/cloud/learn/cloud-computing
inet:search:result=c599d400d1491640bc504a6e151bf8a2
        .created = 2025/05/10 11:04:36.661
        :query = d862ea16c5af8cecc6f40a1ad37209f7
        :rank = 2
        :title = what is cloud computing? a beginner's guide | microsoft azure
        :url = https://azure.microsoft.com/en-us/overview/what-is-cloud-computing/

If you wanted to do exact matches in Google searches, you need to enclose the string with quotes. You can do the following as an example:

> google.search '"vertex project synapse"' --yield | limit 2
inet:search:result=be655f1ad1118c5ad2968e6bb727b2a9
        .created = 2025/05/10 11:04:36.788
        :query = cfa442a2223a651559f5e2d3cfffcbd3
        :rank = 0
        :title = synapse documentation release 2.54.0 the vertex project
        :url = https://synapse.docs.vertex.link/_/downloads/en/stable/pdf/
inet:search:result=f088c89737c1aa9ee570191802a295db
        .created = 2025/05/10 11:04:36.802
        :query = cfa442a2223a651559f5e2d3cfffcbd3
        :rank = 1
        :title = the vertex project - synapse is a versatile central intelligence ...
        :url = https://lu.ma/vertexproject

Since this is a user provided string, it can also be a variable. The following example searches for file hash and word malware together.

> file:bytes#cno.mal +:md5 $text=$lib.str.format('{m} malware', m=:md5) google.search $text --debug --yield | limit 3
Searching google for [a38a367d6696ba90b2e778a5a4bf98fd malware]
inet:search:result=25fe0a9fdbe586a5f80b4b14af235cb4
        .created = 2025/05/10 11:04:36.965
        :query = af186f85ae52e1a8e03ac1fc64abd179
        :rank = 0
        :title = apt1 static malware analysis: webc2-cson - vitali kremez
        :url = http://vkremez.weebly.com/cyber-security/apt1-static-malware-analysis-webc2-cson_sample

Both of the Google commands create inet:search:query nodes. These have a :engine=google secondary property. The inet:search:result nodes are linked back to these queries.

> inet:search:query
inet:search:query=09d02195b4f6fb1b386909d3639bab2b
        .created = 2025/05/10 11:04:34.927
        :engine = google
        :text = 1.2.3.4
inet:search:query=af186f85ae52e1a8e03ac1fc64abd179
        .created = 2025/05/10 11:04:36.915
        :engine = google
        :text = a38a367d6696ba90b2e778a5a4bf98fd malware
inet:search:query=cfa442a2223a651559f5e2d3cfffcbd3
        .created = 2025/05/10 11:04:36.739
        :engine = google
        :text = "vertex project synapse"
inet:search:query=d862ea16c5af8cecc6f40a1ad37209f7
        .created = 2025/05/10 11:04:36.594
        :engine = google
        :text = cloud computing

By default, search result URLs will not have their content retrieved. This behavior can be enabled with the --get-content option:

> google.search '"vertex project synapse"' --yield --get-content | limit 2
inet:search:result=be655f1ad1118c5ad2968e6bb727b2a9
        .created = 2025/05/10 11:04:36.788
        :query = cfa442a2223a651559f5e2d3cfffcbd3
        :rank = 0
        :title = synapse documentation release 2.54.0 the vertex project
        :url = https://synapse.docs.vertex.link/_/downloads/en/stable/pdf/
inet:search:result=f088c89737c1aa9ee570191802a295db
        .created = 2025/05/10 11:04:36.802
        :query = cfa442a2223a651559f5e2d3cfffcbd3
        :rank = 1
        :title = the vertex project - synapse is a versatile central intelligence ...
        :url = https://lu.ma/vertexproject

This will retrieve the content of the URLs and store it in the Axon that the Cortex is configured to use. There is a five minute timeout on this download, to account for pages which may not be online or accessible to the Cortex. You can view the file:bytes created from a given search with the following pivot:

> inet:search:query:text='"vertex project synapse"' -> inet:search:result -> inet:url -> inet:urlfile -> file:bytes
file:bytes=sha256:e0189b491f87bbce7a7bdc10ab8bb3123bfa0064e7d3dd2ea41b1727593908b0
        .created = 2025/05/10 11:04:37.149
        :md5 = de65eecf40f3d44eb96cd100f44e0c73
        :mime = application/pdf
        :sha1 = 995afe53a8ab8aefe40f1110bab9271693cfcd86
        :sha256 = e0189b491f87bbce7a7bdc10ab8bb3123bfa0064e7d3dd2ea41b1727593908b0
        :size = 62
file:bytes=sha256:33f882b1246a6e7bb71d8b78097a662f31e7682c8b1b86b2681676da04d5d275
        .created = 2025/05/10 11:04:37.224
        :md5 = a2d670d783515d3a1b1aeaa155bbfa32
        :mime = text/html
        :sha1 = b99f9ae0e19dc3771c0558913d29db18fb9f0300
        :sha256 = 33f882b1246a6e7bb71d8b78097a662f31e7682c8b1b86b2681676da04d5d275
        :size = 31

Use of meta:source nodes

Synapse-Google Search uses a meta:source node and -(seen)> light weight edges to track nodes observed from the Google Search API.

> meta:source=a753bb4cf2ff32f6f894e52624ec392c
meta:source=a753bb4cf2ff32f6f894e52624ec392c
        .created = 2025/05/10 11:04:34.914
        :name = google search api

Storm can be used to filter nodes to include/exclude nodes which have been observed by Synapse-Google Search. The following example shows how to filter the results of a query to include only results observed by Synapse-Google Search:

> #cool.tag.lift +{ <(seen)- meta:source=a753bb4cf2ff32f6f894e52624ec392c }