Breakwater CLI

Overview

It is also possible to run audits via a CLI application on any VSEC Test Bench!

$ bw_cli -h
usage: bw_cli [-h] [-a AUDIT] [-p PARAMETER [PARAMETER ...]] action

positional arguments:
  action                action must be one of: example, run, ls, help

options:
  -h, --help            show this help message and exit
  -a AUDIT, --audit AUDIT
                        Name of audit to run
  -p PARAMETER [PARAMETER ...], --parameter PARAMETER [PARAMETER ...]
                        Override default parameter value in key=value format

The CLI provides a few different actions:

run to start an audit
discover to discover targets
ls to show a quick list of available audits
help a help menu

Listing Available Audits

The ls action will present a list of all available audits’ friendly names, followed by their internal names. The internal names will be used by the CLI when starting a test, this is a quick way to find the internal name for a test.

$ bw_cli ls
UDS Read Memory by Address (uds_read_by_addr)
UDS Security Access (uds_security_access)
...

The description, fail conditions and parameters of each audit are listed on the Test Cases pages.

Discovering Targets

By running bw_cli discover -p iface=can0 the application will attempt to discover targets reachable via the named interface, or all interfaces if -p iface=... is left out. On a CAN interface it scans for UDS and XCP servers. Ethernet discovery is not available at the moment and returns no targets. This list of targets found is useful to fill in parameter values and run tests against the discovered targets!

Running an Audit

An audit can be started with the run action, followed by the -a parameter specifying the audit to run by its internal name. Any parameters can be supplied using -p followed by a parameter name, an equal sign, and the value to set that parameter to without any spaces.

bw_cli run -a uds_security_access -p device=can0 -p extended_id=False -p req_arb=0x7e0 -p resp_arb=0x7e8 -p session=1

For example, this command will start an audit with internal ID uds_security_access (friendly name “UDS Security Access”) and override the default parameter values for device, extended_id, req_arb, resp_arb and session parameters. Any parameter you leave out keeps its default value. The parameters of UDS Security Access are:

Parameter	Name	Default Value	Description
`device`	CAN Interface	can0	The network interface on which to interact with the CAN Bus
`extended_id`	Extended ID	False	Whether or not to use 29 bit arbitration IDs
`is_fd`	Flexible Data Rate	False	Whether or not to use CAN FD frames for this test
`frame_len`	Static Frame Length	0	Pad every CAN frame out to this fixed length, 0 leaves each frame at its natural length. Lengths above 8 (12, 16, 20, 24, 32, 48, 64) require CAN FD
`frame_fill`	Frame Fill Byte	0x00	The byte used to pad frames up to the static frame length
`req_arb`	Request Arbitration ID	0x7e0	The arbitration ID to send requests to
`resp_arb`	Response Arbitration ID	0x7e8	The arbitration ID where replies will be sent
`min_seed_len`	Expected Minimum Seed Length	8	The minimum number of bytes the seed shall be to pass this test
`seeds_requested`	Number of Seeds Requested	5	Number of seeds requested when checking for duplicates
`session`	Diagnostic session	1	The diagnostic session (or pair) to enter for this test

You can find similar example commands to begin an audit (including every applicable parameter) below each test case on the Test Cases pages of this website.

The CLI reports the outcome of a run in its exit code:

Exit code	Meaning
`0`	Pass: the test was performed and found no vulnerable behavior.
`1`	Fail: the test found behavior that may indicate a vulnerability in the device under test.
`2`	No result: the test could not be performed, or it raised an error.
`3`	Usage error. `ls` and `discover` also exit with `3`.

Automation with the CLI

When an audit is run, bw_cli prints its logs and debug information to stderr, and prints the results of the audit to stdout as a JSON object. Usage errors are printed to stdout as plain text, so check the exit code before parsing the output.

Updating Breakwater

Breakwater is distributed as an APT package. Benches built from images generated since late August 2026 update Breakwater on their own: they check for a new version 10 minutes after boot and every 12 hours after that, and they already have the Breakwater APT repository configured.

To update a Bench now, or to update an older Bench, first access the Bench either over SSH or by opening the Remote Terminal. Then add the Breakwater signing key and APT repository, including the deb-src source repository:

wget -qO- https://deb.vsec.blockharbor.io/breakwater-signing-key.asc \
  | gpg --dearmor \
  | sudo tee /usr/share/keyrings/breakwater-signing-key.gpg >/dev/null \
  && printf '%s\n' \
    "deb [arch=arm64 signed-by=/usr/share/keyrings/breakwater-signing-key.gpg] https://deb.vsec.blockharbor.io stable non-free" \
    "deb-src [signed-by=/usr/share/keyrings/breakwater-signing-key.gpg] https://deb.vsec.blockharbor.io stable non-free" \
  | sudo tee /etc/apt/sources.list.d/breakwater.list >/dev/null \
  && sudo apt update

This downloads the repository signing key, installs it to the keyring, registers the deb.vsec.blockharbor.io binary and source repositories, and refreshes the package lists.

Then install (or upgrade to) the latest Breakwater package:

sudo apt-get install -y breakwater

Finally, restart the Breakwater service so the Bench begins using the updated package:

sudo systemctl restart breakwater

Note: Running the repository setup again is harmless. Once it has been done on a Bench, later updates only need sudo apt update && sudo apt-get install -y breakwater followed by sudo systemctl restart breakwater.

Last updated on October 11, 2026

Remote Terminal Access WiFi Hotspot