kaie/sphere-detection

Various modules to implement the DetecTor design from http://detector.kuix.de

sphere-detection

Various modules to implement the DetecTor design from http://detector.io

Use these instructions to get and run the initial sphere-detection code on a Linux system, which implements parts of the DetecTor design. You must use a terminal to build and run.

Get the code and build

$ git clone https://github.com/kaie/sphere-detection
$ cd sphere-detection
$ git clone https://git.torproject.org/stem.git
$ git clone https://github.com/ndevilla/iniparser
$ hg clone https://hg.mozilla.org/projects/nspr
$ hg clone https://hg.mozilla.org/projects/nss
$ ./build-libs.sh
$ ./build.sh

Ensure you have the python and the tor system packages installed. Check if your tor binary is in /usr/bin/tor or /usr/sbin/tor If necessary, edit file sphere_control.config to adjust the tor_path setting.

Run interactively once

$ source env.sh
$ python -c "import sphere_control; controller, proc = sphere_control.start()"

Be patient. The previous command will take a while when you first execute it, while we bootstrap 5 separate Tor connections. You may use the following command to watch the progress. You should wait until all spheres have reported 100% done. (Hit CTRL-C to exit following the log files.)

$ tail -f tor_data_dir/sphere*/tor.log
$ sphere-probe -p 443 -h en.wikipedia.org

Be patient for about 30 seconds. The certificate obtained from the server using the direct connection will be printed, and the number of matches using Tor network connections. If at least 4 matches were found, it will print SUCCESS, or it will print FAILURE if less than 4 matches were found. Repeat sphere-probe using other hosts or ports, e.g.:

$ sphere-probe -p 465 -h smtp.gmail.com

You may use the -D parameter to request that the certificates seen are dumped to a file (PEM format). If you wish to stop the detection spheres, run:

$ python -c "import sphere_control; sphere_control.stop()"

Run in monitoring mode

You may use a configuration file that lists multiple servers to probe and the certificate(s) you expect. They will be probed periodically. You may use your own alert script, which will be called when unexpected certificates are encountered. Your script will be called with one paramter, a filename that contains a report, which includes the certificates that were seen. An example configuration file name sphere_probe.ini is provided which will probe the hosts mentioned in the previous sectoin. An example alert script is provided, but it doesn't do anything besides printing a statement. You must adjust the script according to your needs.

To test using the provided example configuration, execute:

$ sphere-probe -C ./sphere-probe.ini -A ./alert.sh

Of course, the included certificates are examples, only. The servers might change their certificates.

The purpose of this software is to monitor your own server! You should change the configuration to monitor servers that you control, and update your configuration whenever you change the certificate on your server.

At this time, no system integration is available, but you could start using it by running it in a "screen" terminal session on your server.

It's probably a good idea to run sphere-probe on a separate server, preferably at separate location, but not on the server you're monitoring.

Installation

At this time, no automatic installation is supported. You should build this software locally, make sure the terminal's current working directory is the main directory where you unpacked and built this software, and execute the commands from within that directory. If used in this way, the software shouldn't modify any files in unrelated directories.

sphere-detection's Issues

Create Fedora/RHEL/CentOS RPM packages

We need to package the sphere controller and the sphere probe utility for RPM based distributions, Fedora/RHEL/CentOS flavors.

Create Debian/Ubuntu/Mint DEB packages

We need to package the sphere controller and the sphere probe utility for DEB based distributions, Debian/Ubuntu/Mint flavors.

Nagios Plugin

The project suggests that administrators of servers monitor their own server for unexpected certificates.

The sphere-utility enables that, however, it should be made easy to setup.

It has been suggested to implement a plugin for the Nagios monitoring environment.

sphere-probe should use different exit codes

The sphere-probe should return an exit code that describes the results of the probe.
It's not yet decided how it should behave.

Proposal A:
exit status 0 on success
exit status 1 on failure

(The definitions of success and failure might change over time and would be based on parameters.)

Alternative Idea B:
Exit status equals the number of successful comparisons that were found with the direct route.

Which one should we use?

Better handling of delayed/unavailable Tor connections

Occassionally sphere-probe might print the following error while probing:
sphere-probe: read from socket failed: PR_END_OF_FILE_ERROR: Encountered end of file

This might happen multiple times.

This could be related of the Tor connection being not yet ready. For example, I saw it after having had the Tor connections up for a while, but not having used them recently. When initially calling sphere-probe, it might print the error. When executing the same command a second time, the errors might go away.

The tool should be able to detect the ready-state of the Tor connections, wait longer if necessary, and give better error messages.

Build.sh not working, new NSS?

DetecTor doesn't seem to compile at the moment. This is the results of build.sh:

gcc -o Linux4.7_x86_64_cc_glibc_PTH_64_DBG.OBJ/sphere-probe.o -c -g -fPIC -DLINUX2_1 -m64 -pipe -ffunction-sections -fdata-sections -DLINUX -Dlinux -DHAVE_STRERROR -Wall -Werror -DXP_UNIX -DDEBUG -UNDEBUG -DDEBUG_system -D_REENTRANT -DNSS_NO_INIT_SUPPORT -DUSE_UTIL_DIRECTLY -DNO_NSPR_10_SUPPORT -DSSL_DISABLE_DEPRECATED_CIPHER_SUITE_NAMES -I../nss/../dist/Linux4.7_x86_64_cc_glibc_PTH_64_DBG.OBJ/include -I../nss/../dist/public/nss -I../nss/../dist/private/nss -I../nss/../dist/public/seccmd -I../nss/../dist/public/dbm  -I../iniparser/src sphere-probe.c
sphere-probe.c: In function ‘probeOne’:
sphere-probe.c:824:9: error: variable ‘numDetectorResults’ set but not used [-Werror=unused-but-set-variable]
     int numDetectorResults;
         ^~~~~~~~~~~~~~~~~~
sphere-probe.c: In function ‘main’:
sphere-probe.c:1243:46: error: passing argument 3 of ‘SECU_ParseSSLVersionRangeString’ makes pointer from integer without a cast [-Werror=int-conversion]
                             enabledVersions, enableSSL2,
                                              ^~~~~~~~~~
In file included from sphere-probe.c:11:0:
../nss/../dist/private/nss/secutil.h:402:1: note: expected ‘SSLVersionRange * {aka struct SSLVersionRangeStr *}’ but argument is of type ‘PRBool {aka int}’
 SECU_ParseSSLVersionRangeString(const char *input,
 ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
sphere-probe.c:1242:25: error: too many arguments to function ‘SECU_ParseSSLVersionRangeString’
           case 'V': if (SECU_ParseSSLVersionRangeString(optstate->value,
                         ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In file included from sphere-probe.c:11:0:
../nss/../dist/private/nss/secutil.h:402:1: note: declared here
 SECU_ParseSSLVersionRangeString(const char *input,
 ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
cc1: all warnings being treated as errors
make: *** [../nss/coreconf/rules.mk:393: Linux4.7_x86_64_cc_glibc_PTH_64_DBG.OBJ/sphere-probe.o] Error 1

Building this project in 2021 :^)

I know this project hasn't been updated in a few years, but it seems quite useful and I hoped to make it work.

I had to comment out the Werror.mk line in unix.mk to avoid errors (the getcwd definitions in nsinstall mostly) and also added the fPIC flag when making iniparser in build-libs.sh. I also used autopep8 on sphere_control.py to fix errors due to tabs/indentation and changed print to print(). Finally, ConfigParser changed to configparser so I copied configparser.py to its old name. It seems to work now.

sphere-probe compilation, however, is problematic: it returns an error with nss (seccomon.h:17:10: fatal error: prtypes.h: No such file or directory). In case you're still around could you please fix it?

EDIT: solved, I was trying to build it via makefile, build.sh is enough.