User Guide

Synapse-URLScan User Guide

Synapse-URLScan adds new Storm commands to allow you to query the URLScan API using your existing API key.

For more information on the query syntax for urlscan.search please visit the Search API reference.

Getting Started

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

Examples

Setting your personal API key

To set-up a personal use API key:

> urlscan.setup.apikey --self myapikey
Setting URLScan API key for the current user.

Search by domain:

> urlscan.search domain:time.gov --yield --size 2
Issuing URLScan search: domain:time.gov
inet:url=http://time.gov
        .created = 2024/02/29 15:40:28.537
        .seen = ('2021/04/23 21:59:58.559', '2021/04/23 21:59:58.560')
        :base = http://time.gov
        :fqdn = time.gov
        :params =
        :path =
        :port = 80
        :proto = http
inet:url=https://www.time.gov/
        .created = 2024/02/29 15:40:28.633
        .seen = ('2021/03/18 07:15:16.801', '2021/03/18 07:15:16.802')
        :base = https://www.time.gov/
        :fqdn = www.time.gov
        :params =
        :path = /
        :port = 443
        :proto = https

Enrich nodes:

> inet:fqdn#aurl | urlscan.enrich
WARNING: URLScan search HTTP code: 400 - Bad Request
inet:fqdn=time.gov
        .created = 2024/02/29 15:40:28.728
        :domain = gov
        :host = time
        :issuffix = false
        :iszone = true
        :zone = time.gov
        #aurl

Pivot to created inet:dns:a nodes:

> inet:fqdn#aurl -> inet:dns:a

Pivot to created inet:urlredir nodes:

> inet:fqdn#aurl -> inet:urlredir:src:fqdn
inet:urlredir=('http://time.gov', 'https://time.gov/')
        .created = 2024/02/29 15:40:28.569
        .seen = ('2021/04/23 21:59:58.559', '2021/04/23 21:59:58.560')
        :dst = https://time.gov/
        :dst:fqdn = time.gov
        :src = http://time.gov
        :src:fqdn = time.gov

Print usage limits:

> urlscan.quota
URLScan API Quotas:
search (daily usage): 22 out of 1000
search (hourly usage): 3 out of 1000
search (minutely usage): 1 out of 120

Use of meta:source nodes

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

> meta:source=bc2da0701447a730af49d5a2beb68607
meta:source=bc2da0701447a730af49d5a2beb68607
        .created = 2024/02/29 15:40:28.462
        :name = urlscan api

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

> inet:url=https://time.gov -> inet:urlredir +{ <(seen)- meta:source=bc2da0701447a730af49d5a2beb68607 }