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

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 = 2025/11/05 21:02:45.797
        .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 = 2025/11/05 21:02:45.802
        .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 = 2025/11/05 21:02:45.856
        .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 = 2025/11/05 21:02:45.860
        .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 = 2025/11/05 21:02:45.802
        .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 = 2025/11/05 21:02:45.781
        :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 = 2025/11/05 21:02:45.802
        .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 = 2025/11/05 21:02:45.918
        :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 = 2025/11/05 21:02:45.918
        :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 tor.setup.tagprefix command must be run prior to executing the migration, 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 = 2025/11/05 21:02:45.931
        :type = unicast
        #foo.tor = (2021/01/01 00:00:00.000, 2021/01/01 00:00:00.001)

> tor.setup.tagprefix foo.tor
Setting Tor tag prefix to foo.tor.

> yield $lib.import(tor).migrateTags(tag="foo.tor")
inet:ipv4=5.6.7.8
        .created = 2025/11/05 21:02:45.931
        :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 = 2025/11/05 21:02:45.946
        :type = unicast
        #baz.tor = (2022/01/01 00:00:00.000, 2022/01/01 00:00:00.001)

> tor.setup.tagprefix bam.tor
Setting Tor tag prefix to bam.tor.

> yield $lib.import(tor).migrateTags(tag="baz.tor")
inet:ipv4=9.0.1.2
        .created = 2025/11/05 21:02:45.946
        :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 = 2025/11/05 21:02:45.946
        :type = unicast
        #bam.tor.exit = (2022/01/01 00:00:00.000, 2022/01/01 00:00:00.001)