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: run, discover, ls, catalogue, 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
• catalogue to show details of available audits, similar to the test cases docs page
• 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 catalogue action will present details about each available audit, similar to what is presented on this website. This includes a description of what the test will do, what will cause the test to fail, and each parameter.

$ bw_cli catalogue
...
## UDS Security Access

Validates security access seed strength and failure timeout. The test will validate that Service 27 always returns a unique seed of sufficient length and is protected from brute force attacks.

### Parameters

| Name | Default Value | Description |
| - | -- | ------ |
| CAN Interface | can0 | The network interface on which to interact with the CAN Bus |
| Extended ID | False | Whether or not to use 29 bit arbitration IDs |
| Request Arbitration ID | 0x7e0 | The arbitration ID to send requests to |
| Response Arbitration ID | 0x7e8 | The arbitration ID where replies will be sent |
| Expected Minimum Seed Length | 8 | The minimum number of bytes the seed shall be to pass this test |
| Number of Seeds Requested | 5 | Number of seeds requested when checking for duplicates |
| Diagnostic session | 1 | The diagnostic session (or pair) to enter for this test |

### Fail Conditions

If duplicate seeds are obtained, or a seed of insufficient length is seen for any access level, this test will be marked as failed. If insufficient timeout is implement between seed access attempts, this test will be marked as failed.
...

Discovering Targets

By running bw_cli discover <interface> the application will attempt to discover targets reachable via a specific interface if supplied, or all interfaces if none are supplied. This may include scanning for protocols such as UDS or XCP on a CAN interface, or performing ARP queries and IPv6 neighbor discovery on ethernet interfaces. 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. You can find similar example commands to begin an audit (including every applicable parameter) below each test case in the Test Sets section of this website.

Just like with the API, the CLI will return NORESULT if it is unable to perform the requested test, PASS if the test was performed successfully, or FAIL if the test found any behavior that may indicate a vulnerability in the device under test.

Automation with the CLI

When an audit is run, bw_cli may print some logs and debug information to the console via stderr. The only output to stdout shall be a JSON object representing the results of an audit (returned value from run_audit) enabling this output to be consumed by other scripts.