Using custom fingerprints

Community Platform

Customers running a self-hosted instance or using the standalone scanner have the ability to use custom-written fingerprints. This can be useful in adding new fingerprint coverage for very unique or custom assets and services, such as device prototypes or proprietary applications/services. Custom fingerprints can also be used to override existing, similar runZero fingerprints by using a same-or-higher certainty value.

Create new fingerprints

Custom fingerprints follow the structure and format of the open-source Recog fingerprint database. You can author your own fingerprint XML entries in files of similar name and format to those found in Recog. For cases where an asset or service matches both a built-in runZero fingerprint and a custom fingerprint of the same kind, preference will be given to the fingerprint with higher “certainty” value(s) (e.g. hw.certainty, os.certainty, service.certainty). In the event of a certainty “tie” (i.e. same certainty value(s)), the custom fingerprint will be given preference.

Add new fingerprints to your self-hosted runZero instance

To ensure the self-hosted instance of runZero can properly access your custom fingerprints, they will need to exist within the runZero installation directory (/opt/runzero by default). The following steps will get your custom fingerprints setup for use by runZero:

• Create a new directory within the runZero install directory (e.g. mkdir /opt/runzero/myfingerprints)
• Update your /etc/runzero/config file with the new directory location (see below)
• Copy your custom fingerprint XML files into the new directory (e.g. cp *.xml /opt/runzero/myfingerprints)

The /etc/runzero/config file needs to be updated with the location of your custom fingerprints directory, which you can do by using your favorite editor to add the following line to the end of your config file (swapping myfingerprints with the name of the directory you added):

RUNZERO_EXTERNAL_FINGERPRINTS=myfingerprints

Note that you only need to do the directory creation and update of /etc/runzero/config file once. After that, you can add, remove, or modify your custom fingerprints in the directory as needed and then restart the runZero application to reload the current custom fingerprints.

Restart the runZero service

The runZero self-hosted instance will need to be restarted when custom fingerprints are added, removed, or updated. On restart, the runZero log file can be monitored to verify if the custom fingerprints were successfully applied or if an error occurred. On successful load of custom fingerprints, a log message like the following should be present:

@cee:{"level":"info","msg":"loaded (5) external fingerprints","time":"2022-09-12T19:51:49Z"}

If issues are encountered when loading or processing custom fingerprints, or if a 10 second timeout is reached, a warning message will be logged and the runZero application will continue running without any custom fingerprints.

Verify your fingerprints

Once your custom fingerprints have been added to your self-hosted runZero instance and the instance restarted, you can verify that the custom fingerprints are performing as-expected in one of the following ways:

• Running a scan task to go scan a relevant asset/service, or
• Importing an existing scan data file of the relevant asset/service

Following completion of the scan task OR the import of scan data, depending on which method you chose, you can then navigate to a specific asset or specific service and verify that your custom fingerprints are acting as-expected.