Using custom fingerprints

Community Platform

If you run a self-hosted instance or the standalone scanner, you can write your own fingerprints. Custom fingerprints add coverage for one-of-a-kind or custom assets and services, such as device prototypes or proprietary applications and services. They can also override similar built-in runZero fingerprints when you give them a same-or-higher certainty value. Understanding fingerprints explains how runZero builds its own.

Create new fingerprints

Custom fingerprints follow the structure and format of the open-source Recog fingerprint database. Write your fingerprint XML entries in files named and formatted like those in Recog. When an asset or service matches both a built-in runZero fingerprint and a custom fingerprint of the same kind, the fingerprint with the higher “certainty” value(s) wins (for example hw.certainty, os.certainty, service.certainty). If the certainty values tie, the custom fingerprint wins.

Add new fingerprints to your self-hosted runZero instance

Custom fingerprints must live inside the runZero installation directory (/opt/runzero by default) so the self-hosted instance can read them. To set them up:

• Create a new directory within the runZero install directory (for example 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 (for example cp *.xml /opt/runzero/myfingerprints)

To point /etc/runzero/config at your custom fingerprints directory, add this line to the end of the file with your favorite editor, replacing myfingerprints with the name of the directory you created:

RUNZERO_EXTERNAL_FINGERPRINTS=myfingerprints

You only need to create the directory and update /etc/runzero/config once. After that, add, remove, or modify custom fingerprints in the directory as needed, then restart the runZero application to reload them.

Restart the runZero service

Restart the self-hosted instance whenever you add, remove, or update custom fingerprints. Watch the runZero log file during the restart to confirm that the fingerprints loaded or to catch an error. A successful load logs a message like this:

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

If runZero hits a problem loading or processing the custom fingerprints, or reaches a 10 second timeout, it logs a warning and keeps running without any custom fingerprints.

Verify your fingerprints

After you add the custom fingerprints and restart the instance, check that they behave as expected in one of two ways:

• Run a scan task against a relevant asset or service, or
• Import an existing scan data file for the relevant asset or service

When the scan task or the import finishes, open the asset or service in the inventory and confirm that your custom fingerprints took effect.