The Engine | FAQ | Contact
DICE is an engine to orchestrate network measurements. At the core, DICE falls into the category of vulnerability identification. It was first thought as a tool for Internet surveys and monitoring networks, a far broader scope than single host scanning. However, DICE can be used at many different levels. It's main purpose is to provide flexibility for as many measurements as you can think of.
Important
We made available a PoC mini version of DICE. It contains many (but not all) features out of the box, and is written in Python (thus, not as fast IO). We have used this version in multiple Internet measurements and as a demo to showcase the engine's potential.
Table of Conent
Tip
DICE may be an overkill for simpler measurements (e.g., SYN-ACK scans). Check out our frequently asked questions to figure what DICE can do for you. As an engine to orchestrate measurements, use cases may vary greatly.
Here you can find a quick guide to intall and start using DICE.
-
Download DICE's latest release using curl or the link on DICE's github page
curl -OL https://github.com/RicYaben/dice/releases/download/latest/dice.linux-amd64.tar.gz
-
Remove any previous DICE installation by deleting the /usr/local/dice folder, and extract the new installation
rm -rf /usr/local/dice && tar -C /usr/local -xzf dice.linux-amd64.tar.gz -
Add dice to your PATH environment variable
Add the following line to your
$HOME/.profilefile. Note: this file may be located or named differently depending on your environment and terminal.export PATH=$PATH:usr/local/dice/bin
-
Verify you have installed DICE.
dice version
-
Create a DICE project in the current directory
The first time running this command, DICE will setup dependancies, databases, configurations, etc. Then, DICE will create a
.dicefile with the project configuration.# Initialize a project dice init d1 -
Run DICE with modules or signatures
Using DICE to orchestrate Internet-wide measurements is as simple as using the
scancommand with modules (-M) or signatures (-S). Once the measurement is done, you can check the results under the newly created measurement -- check the output logs to find the ID if you did not provide one, -- in the sources directory, or directly from the resultscosmos.db.Note: Learn more about DICE measurement results cosmos databases here
# Scan the whole IPv4 with a module dice scan -M mqtt-anonTo list all known to DICE use the following command:
# List all modules dice modules list --allFor more information on DICE's commands and configuration options check out the list of commands.
-
Query DICE's results
# Query the results of a measurement dice query 'certificate.hash:029af973ce92ac14dee1a2d8dbaf0c6a' s1/cosmos.db
To start using DICE, we only need to tell the engine which actions we want to use, and which modules or signatures to load.
Note: You do not need to initialize a new project to start using DICE, although, it is highly recommended.
# Scan the whole IPv4 using a single signature
dice scan -S routerThis will output the results to the current directory.
You should see a structure containing (at the very least) a sources folder containing results from the different sources and scanners (e.g., ZGrab2, Censys, Shodan, Greynoise, etc.), and a cosmos.db with DICE results.
$ ls -lah
sources // scanning raw results
sources/zgrab2 // zgrab2 results
sources/zmap // zmap results
cosmos.db // results database
However, DICE can do much more, and as with many other tools, the simplest and most common cases, are only the beggining. Big part of measurements and network analysis is the ability to replay results, and as such, DICE includes commands to ingest data from different sources and classify using a set of modules or full signatures. This allows for predictive and deterministic results, helping to share and compare processing pipelines and metrics.
# Classify previously collected zgrab2 records using all signatures
# that start with "iot-" or "ot-"
dice classify -S "iot-*,ot-*" --source zgrab2 This command shows how we would classify previously-collected results with a set of signatures.
We have covered the tip of the iceberg, simple scans, simple classifications. Here we cover DICE more in depth, and showcase other use-cases more interesting for tinkers and those looking to conduct or evaluate complex measurements.
We can use DICE with local signatures without registering them into the main database using the --local flag.
This will effectively create an in-memory copy of the main database and register the local signature and mentioned modules.
It is particularly useful during the latest stages experimenting of developing signatures.
Most will use this mode in one-off measurements and testing environments.
Note: This mode requires the signature to pointing to modules using relative paths.
# Temporarily run DICE with a local signature
dice scan -S local-sig.dice --local We can also pass environment variables as values for module or signature arguments.
# Use variables as arguments for modules
dice scan -M telnet-brute --module-args 'dictionary=$(cat dict.pass)'There are occasions where we need to layer measurements with different signatures. DICE can layer measurements as a sequence.
# Scan for healthcare devices and then for iot devices
dice scan -S healthcare --layer=1 -S iot --layer=2Right now, the best way to support DICE is by using it or contributing to its development.
If you are a researcher using or discussing about DICE, please use the reference included in this repository. You are welcome to cite any other of our recent publications using DICE, we maintain a separate repository with all the publications where we used DICE, including presentation slides, posters, etc. If you have any question, get in contact.