User Guide

Synapse-Tor User Guide

Synapse-Tor adds new Storm commands to automatically tag TOR exit nodes.

Getting Started

Check with your Admin to enable permissions.

Examples

List available configurations

Synapse-Tor does not require an API key, but uses a configuration to store the tag prefix, proxy, and SSL verification settings used when ingesting. A global configuration named default is created when the Power-Up is installed. To list the available configurations, use the tor.config.list command:

> tor.config.list
 name                      | scope    | owner
===========================|==========|====================================================
 default                   | global   | root

Set the tag prefix used to record ingested nodes

When ingesting exit and relay nodes, tags will be applied to the inet:ipv4/inet:ipv6 nodes using the value of the configuration’s tag prefix. The default tag prefix is cno.infra.anon.tor, which can be changed with the tor.config.update command:

> tor.config.update default --tag-prefix my.cno.infra.anon.tor
Updated Synapse-Tor config "default"

Download and annotate the current TOR exit nodes

The --yield option includes the newly annotated inet:ipv4 nodes in the Storm runtime.

> tor.sync --yield | limit 2
inet:ipv4=185.244.195.103
        .created = 2026/10/22 20:06:00.664
        .seen = ('2023/02/02 18:38:58.000', '2023/02/02 18:38:58.001')
        :type = unicast
        #cno.infra.anon.tor.exit = (2023/02/02 18:38:58.000, 2023/02/02 18:38:58.001)
inet:ipv4=109.70.100.88
        .created = 2026/10/22 20:06:00.668
        .seen = ('2023/02/02 18:38:58.000', '2023/02/02 18:38:58.001')
        :type = unicast
        #cno.infra.anon.tor.exit = (2023/02/02 18:38:58.000, 2023/02/02 18:38:58.001)

If the --relays option is specified all running relays will be also be ingested and inet:ipv4 and inet:ipv6 nodes created.

> tor.sync --yield --relays | limit 3
inet:ipv4=109.70.100.73
        .created = 2026/10/22 20:06:00.713
        .seen = ('2023/02/02 17:00:00.000', '2023/02/02 17:00:00.001')
        :type = unicast
        #cno.infra.anon.tor.relay = (2023/02/02 17:00:00.000, 2023/02/02 17:00:00.001)
inet:ipv6=2a03:e600:100::73
        .created = 2026/10/22 20:06:00.716
        .seen = ('2023/02/02 17:00:00.000', '2023/02/02 17:00:00.001')
        :scope = global
        :type = unicast
        #cno.infra.anon.tor.relay = (2023/02/02 17:00:00.000, 2023/02/02 17:00:00.001)
inet:ipv4=109.70.100.88
        .created = 2026/10/22 20:06:00.668
        .seen = ('2023/02/02 17:00:00.000', '2023/02/02 18:38:58.001')
        :type = unicast
        #cno.infra.anon.tor.exit = (2023/02/02 18:38:58.000, 2023/02/02 18:38:58.001)
        #cno.infra.anon.tor.relay = (2023/02/02 17:00:00.000, 2023/02/02 17:00:00.001)

Use of `meta:source` nodes

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

> meta:source=ed3394443fbf53cc48b2efb4fd06fce1
meta:source=ed3394443fbf53cc48b2efb4fd06fce1
        .created = 2026/10/22 20:06:00.650
        :name = tor api

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

> #cno.infra.anon.tor +{ <(seen)- meta:source=ed3394443fbf53cc48b2efb4fd06fce1 } | limit 1
inet:ipv4=109.70.100.88
        .created = 2026/10/22 20:06:00.668
        .seen = ('2023/02/02 17:00:00.000', '2023/02/02 18:38:58.001')
        :type = unicast
        #cno.infra.anon.tor.exit = (2023/02/02 18:38:58.000, 2023/02/02 18:38:58.001)
        #cno.infra.anon.tor.relay = (2023/02/02 17:00:00.000, 2023/02/02 17:00:00.001)

Migrating tags from v3.x.x

In version 3.x.x the tor.sync command only ingested exit nodes, and the default tag applied was cno.infra.anon.tor.

In version 4.0.0 the tor.sync command can ingest both exit nodes and relay nodes, and uses a default tag prefix of cno.infra.anon.tor to apply cno.infra.anon.tor.exit and cno.infra.anon.tor.relay tags respectively.

The Synapse-Tor Storm API can be used to migrate the tags, which will remove cno.infra.anon.tor from inet:ipv4 nodes and apply cno.infra.anon.tor.exit with the existing time interval.

> [ inet:ipv4=1.2.3.4 +#cno.infra.anon.tor=2020 ]
inet:ipv4=1.2.3.4
        .created = 2026/10/22 20:06:00.757
        :type = unicast
        #cno.infra.anon.tor = (2020/01/01 00:00:00.000, 2020/01/01 00:00:00.001)

> yield $lib.import(tor).migrateTags()
inet:ipv4=1.2.3.4
        .created = 2026/10/22 20:06:00.757
        :type = unicast
        #cno.infra.anon.tor.exit = (2020/01/01 00:00:00.000, 2020/01/01 00:00:00.001)

If custom tags are used, the new tag prefix can be passed to the migration API directly with the tagpref argument, and then the API can be called with the old tag name.

> [ inet:ipv4=5.6.7.8 +#foo.tor=2021 ]
inet:ipv4=5.6.7.8
        .created = 2026/10/22 20:06:00.768
        :type = unicast
        #foo.tor = (2021/01/01 00:00:00.000, 2021/01/01 00:00:00.001)

> yield $lib.import(tor).migrateTags(tag="foo.tor", tagpref="foo.tor")
inet:ipv4=5.6.7.8
        .created = 2026/10/22 20:06:00.768
        :type = unicast
        #foo.tor.exit = (2021/01/01 00:00:00.000, 2021/01/01 00:00:00.001)

If the custom tag prefix differs from what was used in version 3.x.x the user may need to prune the tag tree to remove the parents. See the tag.prune documentation for further details on this command.

> [ inet:ipv4=9.0.1.2 +#baz.tor=2022 ]
inet:ipv4=9.0.1.2
        .created = 2026/10/22 20:06:00.778
        :type = unicast
        #baz.tor = (2022/01/01 00:00:00.000, 2022/01/01 00:00:00.001)

> yield $lib.import(tor).migrateTags(tag="baz.tor", tagpref="bam.tor")
inet:ipv4=9.0.1.2
        .created = 2026/10/22 20:06:00.778
        :type = unicast
        #bam.tor.exit = (2022/01/01 00:00:00.000, 2022/01/01 00:00:00.001)
        #baz

> inet:ipv4#bam.tor.exit tag.prune baz.tor
inet:ipv4=9.0.1.2
        .created = 2026/10/22 20:06:00.778
        :type = unicast
        #bam.tor.exit = (2022/01/01 00:00:00.000, 2022/01/01 00:00:00.001)