From c4a6a55c509f3a83f8196432b166811e7f77530b Mon Sep 17 00:00:00 2001 From: Peter Haag Date: Thu, 1 Aug 2024 12:44:23 +0200 Subject: [PATCH] Add file torlookup.1 man page --- man/torlookup.1 | 144 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100755 man/torlookup.1 diff --git a/man/torlookup.1 b/man/torlookup.1 new file mode 100755 index 00000000..8b53a823 --- /dev/null +++ b/man/torlookup.1 @@ -0,0 +1,144 @@ +.\" Copyright (c) 2024, Peter Haag +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are met: +.\" +.\" * Redistributions of source code must retain the above copyright notice, +.\" this list of conditions and the following disclaimer. +.\" * Redistributions in binary form must reproduce the above copyright notice, +.\" this list of conditions and the following disclaimer in the documentation +.\" and/or other materials provided with the distribution. +.\" * Neither the name of the author nor the names of its contributors may be +.\" used to endorse or promote products derived from this software without +.\" specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate$ +.Dt TORLOOKUP 1 +.Os +.Sh NAME +.Nm torlookup +.Nd tor exit node lookup for IP addresses +.Sh SYNOPSIS +.Nm +.Op Fl H Ar torDBfile +.Ar iplist +.Nm +.Fl d Ar directory +.Fl w Ar torDBfile +.Sh DESCRIPTION +.Nm +is a tool to lookup tor exit node information and their valid time intervals. +You need to create the nfdump specific lookup database first, before using +.Nm . +.Pp +.Nm +is also used to create the nfdump formatted lookup database file from a bunch of tor archive files. +There is no account required to download and build the nfdump tor database. +See the section below for the building instructions. +.Pp +.Nm +accepts a list of IP addresses either on the command line, separated by spaces +or on +.Ar stdin +line by line. The IP address on each line can be embedded in a string separated be +spaces on the left and right, therefore it can read the piped output from other tools. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl d Ar directory +Use the tor archive files in +.Ar directory +to build the binary lookup database file. With this argument +.Nm +creates a new binary lookup database file. +.It Fl w Ar torDBfile +Name of the new lookup database file. +.It Fl H Ar torDBfile +Use the binary torDBfile as lookup database for the tor exit node lookups. +.El +.Pp +To specify the tor lookup database +.Nm +searches at the following places: +.Bl -bullet -compact +.It +If the default +.Ar nfdump(1) +configuration file exists, it reads the tag +.Ar tordb.path +.It +If the environment variable +.Ar NFTORDB +is set, use this setting as lookup database. +.It +The command line argument +.Fl H +.El +If multiple locations are given, the environment variable +.Ar NFTORDB +overwrites the nfdump config file and the command line option +.Fl H +overwrites the environment variable +.Ar NFTORDB . +.Sh RETURN VALUES +.Nm +returns 0 on success and 255 otherwise. +.Sh ENVIRONMENT +.Nm +reads the environment variable +.Ar NFTORDB +.Sh EXAMPLES +The easiest way for creating or updating the binary lookup database is the use of the script +.Ar updateTorDB.sh +provided with all other nfdump files. The script takes a single integer argument. The integer argument +specifies for how many months back, you want to have the information available in the torDB. This means +you need to update the torDB and a regular basis, to have up to date information. Do not forget to +move the lookup database to the final location. +.El +.Pp +Lookup an IP with torlookup: +.Pp +.Dl % ./torlookup -H tordb_full.nf 178.218.144.18 +.Dl Node: 178.218.144.18, last published: 2024-07-31 11:53:12, intervals: 7 +.Dl 0 first: 2022-10-25 20:16:03, last: 2022-11-21 20:55:32 +.Dl 1 first: 2022-12-19 23:16:38, last: 2022-12-28 18:17:01 +.Dl 2 first: 2023-01-08 02:04:07, last: 2023-03-25 07:13:15 +.Dl 3 first: 2023-03-29 05:08:45, last: 2023-09-12 17:05:01 +.Dl 4 first: 2023-09-18 13:11:30, last: 2023-12-05 21:19:41 +.Dl 5 first: 2024-01-05 03:05:32, last: 2024-03-22 21:08:22 +.Dl 6 first: 2024-04-24 04:47:28, last: 2024-08-01 04:09:14 +.Pp +.Nm +returns the number of intervals, the IP was registered as exit node limited by first/last timestamps. +.Pp +Pipe the output of an nfdump statistic to torlookup for tor exit node verification: +.Dl % nfdump -r nfcapd.202408011200 -s ip | torlookup -H tordb_full.nf +.Pp +.Sh IMPLEMENTATION NOTES +If you use the tordb with +.Cm nfdump +to list flows and mark them as tor exit nodes, the IP address as well as +the flow start or flow end timestamp must fall into the approrpiate tor exit node interval. +In the pipe example above, torlookup does not care about timestamps. +.Pp +Use nfdump with the tordb: +.Dl % nfdump -H tordb.nf -r nfcapd.2024081200 -o tor +.Pp +.Sh SEE ALSO +.Ar nfdump +has already builtin lookup options to decorate the text output with tor information. See tags %stor, %dtor +.Pp +.Xr nfdump 1