Using the Command Line Interface (CLI)

The runZero CLI

The runZero Command Line Interface (CLI) supports a wide range of options, including the ability to run scans, sample network traffic, and collect data from integrations. The --help output provides basic documentation on the available options. Please note that the scan command requires enablement by our support team and is only available to users of the full runZero Platform.

runZero CLI commands and options

The runZero CLI supports a wide range of options, including the ability to limit scans to specific ports, probes, and SNMP communities. The --help output provides basic documentation on the available options.

Commands

censys: Import Censys data files
completion: Generate the autocompletion script for the specified shell
help: Help about any command
license: Display license information
scan: Start a runZero active scan, passive discovery, or integration task
script: Run a Starlark custom integration script for development
upgrade: Upgrade to the latest version of the runZero CLI
verify: Perform an internal signature verification
version: Print the version number of runZero

Flags

-h, --help: help for runZero
-v, --verbose: Display verbose output
--very-verbose: Display very verbose output

Scanner

The scan command has the same options and similar performance characteristics to the runZero Explorer. The output file named scan.runzero.gz can be uploaded to the runZero Console through the Inventory Import menu. This

The CLI scanner works best with root privileges on Linux/macOS and Administrator privileges on Windows. Although the CLI will function without privileged access, many probe types will be unavailable. The sudo command can be used to run the CLI as root on Linux and macOS, while the tool is best run from an elevated command shell on Windows. On the Windows platform, the runZero CLI will look for an existing npcap installation and try to install it if the software is not found. This behavior can be disabled with the --nopcap flag.

Note: Some components of the application still reference the name "Rumble" for backwards compatibility. The documentation will be updated as these are changed.

The runZero CLI defaults to a semi-interactive terminal interface that writes multiple output files to a directory. The default directory name is runzero-[current-date]. To switch to plain text output, use the --text option. To skip artifact generation and only produce the raw JSON output file, use the flags --text -o disable --output-raw scan.runzero.

Input can be provided as arguments on the command-line or by specifying an input file using the --input (or -i) parameter. Input can consist of specific IPv4 addresses or IPv4 CIDRs. Supported formats include:

10.0.0.1
10.0.0.0/24
10.0.0.0/255.255.255.0
10.0.0.1-10.0.0.255
example.com
example.com/24

For hostnames, each IPv4 address in the response will be expanded with the optional mask.

The example below downloads and runs the CLI on a Linux x86_64 host. This URL will be different for your installation. The current download links for your organization are available from the CLI page of the runZero Console. If you are using a self-hosted console or a region other than our US-based SaaS, you can find the download link under the Deploy navigation menu.

$ wget https://console.runzero.com/download/cli/[unique-link]/runzero-cli-linux-amd64.bin
$ chmod +x runzero-cli-linux-amd64.bin
$ sudo runzero scan 192.168.0.0/24 -o output-dir

Please note that the hexadecimal values in the download URL are specific for your account and organization.

Performance

The default speed of runZero scans is limited to 1,000 packets per second with a single pass. This setting works great for reliable wired networks without stateful firewalls between the scanning system and the destination networks. This rate can be changed via the --rate (or -r) option, with a reasonable maximum being 10000 for most networks. On slow, unreliable networks, a rate of 300 with --passes set to 3 may provide better results.

A second parameter, --max-host-rate limits how many packets are sent per second to each individual host. This defaults to 40, which is low, but may be necessary when scanning low-power embedded devices. In cases where a small number of hosts (or a single host) should be scanned quickly, the --max-host-rate parameter can be increased to match the --rate.

Examples

The following example demonstrates a scan of 65,535 TCP ports on all hosts in the 192.168.0.0/24 subnet running at 10,000 packets per second:

$ sudo runzero scan 192.168.0.0/24 -r 10000 --tcp-ports 1-65535 -o output-dir

The following example demonstrates a scan on all hosts in the 192.168.0.0/24 and 10.0.0.0/24 subnets running at 5,000 packets per second:

$ sudo runzero scan 192.168.0.0/24 10.0.0.0/24 -r 5000 -o output-dir

The following example demonstrates a scan on all hosts in the 192.168.0.0/24 and 10.0.0.0/8 subnets running at a max host rate of 20 packets per host:

$ sudo runzero scan 192.168.0.0/24 10.0.0.0/8 –-max-host-rate 20 -o output-dir

The following example demonstrates a scan on all hosts in the 192.168.0.0/24 subnet and the domain “example.com” running at 7,500 packets per second:

$ sudo runzero scan 192.168.0.0/24 example.com -r 7,500 -o output dir

The following example demonstrates a scan on all hosts in the 10.0.0.0/8 subnet and a particular ASN4 value at a default speed of 1,000 packets per second.

$ sudo runzero scan 10.0.0.0/8 asn4:[ID] -o output dir

The following example demonstrates a scan on all hosts in the 192.168.0.0/24 subnet with the max TTL set at 128 and a scan rate of 2,500 packets per second:

$ sudo runzero scan 192.168.0.0/24 -r 2,500 -–max-ttl 128 -o output-dir

The following example demonstrates a scan based on an input file:

$ sudo runzero scan -i /path/to/input-file.txt -o output dir

Here is an example input file:

www.example.com
192.168.0.0/24

Automatic web screenshots

The --screenshots option defaults to true and tells runZero to obtain a screenshot of all web services identified during the scan. This feature depends on the system running the Explorer having a local installation of the Google Chrome or Chromium browsers. The acquired screenshots will be reported as a base64 string, stored in the “screenshot.image” field of the containing service scan result.

To disable automatic web screenshots, set the --screenshots option to false (--screenshots=false).

Scanner defaults

Standard ports scanned

1 7 9 13 17 19 21 22 23 25 37 42 43 49 53 69 70 79 80 81 82 83 84 85 88 102 105 109 110 111 113 119 123 135 137 139 143 161 179 222 264 280 384 389 402 407 442 443 444 445 465 500 502 512 513 515 523 524 540 541 548 554 587 617 623 631 636 664 689 705 717 743 771 783 830 873 888 902 903 910 912 921 990 993 995 998 1000 1024 1030 1035 1080 1083 1089 1090 1091 1098 1099 1100 1101 1102 1103 1128 1129 1158 1199 1211 1220 1234 1241 1260 1270 1300 1311 1352 1433 1434 1440 1443 1468 1494 1514 1521 1530 1533 1581 1582 1583 1604 1610 1611 1723 1755 1801 1811 1830 1883 1900 2000 2002 2021 2023 2049 2068 2074 2082 2083 2100 2103 2105 2121 2181 2199 2207 2222 2224 2323 2362 2375 2376 2379 2380 2381 2443 2525 2533 2598 2601 2604 2638 2809 2947 2967 3000 3001 3003 3033 3037 3050 3057 3071 3083 3128 3200 3217 3220 3260 3268 3269 3273 3299 3300 3306 3311 3312 3351 3389 3460 3500 3502 3628 3632 3690 3780 3790 3817 3871 3872 3900 4000 4092 4322 4343 4353 4365 4366 4368 4369 4406 4433 4443 4444 4445 4567 4659 4679 4730 4786 4840 4848 4949 4950 4987 5000 5001 5007 5022 5037 5038 5040 5051 5060 5061 5093 5168 5222 5247 5250 5275 5347 5351 5353 5355 5392 5400 5405 5432 5433 5498 5520 5521 5554 5555 5560 5580 5601 5631 5632 5666 5671 5672 5683 5800 5814 5900 5901 5902 5903 5904 5905 5906 5907 5908 5909 5910 5911 5920 5938 5984 5985 5986 5988 5989 6000 6001 6002 6050 6060 6070 6080 6082 6101 6106 6112 6161 6262 6379 6405 6443 6481 6502 6503 6504 6514 6542 6556 6660 6661 6667 6905 6988 7000 7001 7002 7021 7070 7071 7077 7080 7100 7144 7181 7210 7373 7443 7474 7510 7547 7579 7580 7676 7700 7770 7777 7778 7787 7800 7801 7879 7902 8000 8001 8003 8006 8008 8009 8010 8012 8014 8020 8023 8028 8030 8080 8081 8082 8083 8086 8087 8088 8089 8090 8095 8098 8099 8100 8123 8127 8161 8172 8180 8181 8182 8205 8222 8300 8303 8333 8400 8443 8444 8445 8471 8488 8500 8503 8530 8531 8545 8649 8686 8787 8800 8812 8834 8850 8871 8880 8883 8888 8889 8890 8899 8901 8902 8903 8983 9000 9001 9002 9042 9060 9080 9081 9084 9090 9091 9092 9099 9100 9111 9152 9160 9200 9300 9380 9390 9391 9401 9418 9440 9443 9471 9495 9524 9527 9530 9593 9594 9595 9600 9809 9855 9999 10000 10001 10008 10050 10051 10080 10098 10162 10202 10203 10250 10255 10257 10259 10443 10616 10628 11000 11099 11211 11234 11333 12174 12203 12221 12345 12379 12397 12401 13364 13500 13778 13838 14330 15200 15671 15672 16102 16443 16992 16993 17185 17200 17472 17775 17776 17777 17778 17781 17782 17783 17784 17790 17791 17798 18264 18881 19300 19810 19888 20000 20010 20031 20034 20101 20111 20171 20222 20293 22222 23472 23791 23943 25000 25025 25565 25672 26000 26122 27000 27017 27018 27019 27080 27888 28017 28222 28784 30000 31001 31099 32764 32844 32913 33060 34205 34443 34962 34963 34964 37718 37777 37890 37891 37892 38008 38010 38080 38102 38292 40007 40317 41025 41080 41523 41524 44334 44343 44818 45230 46823 46824 47001 47002 47290 48899 49152 50000 50013 50021 50051 50070 50090 50121 51443 52302 52311 54321 54921 54922 54923 55553 55580 57772 61614 61616 62078 62514 65002 65535

Scan outputs

The runZero CLI generates a directory of output files by default. This directory includes the following items.

scan.runzero.gz: The raw scan data compressed via gzip, this can be imported or reprocessed via --import
assets.jsonl: The new optimized format for correlated, fingerprinted assets.
nmap.xml: A Nmap XML compatible data file that can be imported into various security tools.
urls.txt: A list of discovered web services in URL format.
protocols.csv: A list of protocols with their ports and URLs.
assets.html: A rudimentary HTML report with screenshots.
screenshots: A directory of raw screenshot images, headers in JSON format, and HTML bodies.
Various lists including addresses.txt, addresses_all.txt, hostnames.txt, and domains.txt

Raw Scan Data

The runZero CLI raw data is stored in a file named scan.runzero.gz within the output directory. This file contains JSONL-formatted records. An example ARP response record is shown below.

{
  "type": "result",
  "host": "192.168.0.1",
  "port": "0",
  "proto": "arp",
  "probe": "arp",
  "name": "192.168.0.1",
  "info": {
    "mac": "f0:9f:c2:11:1a:13",
    "macDateAdded": "2014-12-17",
    "macVendor": "Ubiquiti Networks Inc."
  },
  "ts": 1551584126253853200
}

The info field is a JSON map of strings to strings. Multiple values are encoded using the tab character (0x09), which are otherwise escaped as \t (along with \r and \n for carriage return and line feed bytes and \x00 for null bytes). runZero scans may return more than one record of the same type for the same host if multiple responses were received.

In addition to the result type, there are also records for status messages, stats, and an initial config type that contains the scan parameters.

Updated December 19, 2024

Previous: Leveraging the API Next: Glossary