eCTF Tools ========== The eCTF Tools allow teams to have a standard interface to the :ref:`HSM <2026_hsm>` functionality described in :doc:`../specs/functional_reqs`, the :doc:`eCTF bootloader `, and the :doc:`api`. Using the eCTF Tools -------------------- This year, the eCTF tools are `published to PyPi `_. The supported way to use this toolset is with the ``uv`` package manager. First, install ``uv`` following `their docs `_. Then, all you need to do to get the ``ectf`` tools up and running is run ``uvx ectf --help`` and it will automatically be installed. There are a couple of nested command processors: * ``ectf tools`` has subcomands that are used to interact with a running :ref:`HSM <2026_hsm>`. See :ref:`2026_hsm_tool_calls` * ``ectf api`` has subcomands that are used to interact with the :doc:`api` * ``ectf hw`` has subcommands that are used to interact with the :doc:`eCTF Bootloader `. See :ref:`2026_bl_tool_calls` .. code-block:: $ uvx ectf --help Usage: ectf [OPTIONS] COMMAND [ARGS]... Interact with the eCTF hardware, design, and API ╭─ Options ─────────────────────────────────────────────────────────────────────────────────────╮ │ --verbose -v INTEGER Enable debug prints [default: 0] │ │ --install-completion Install completion for the current shell. │ │ --show-completion Show completion for the current shell, to copy it or │ │ customize the installation. │ │ --help Show this message and exit. │ ╰───────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ────────────────────────────────────────────────────────────────────────────────────╮ │ config Create or update the configuration file │ │ docs Open the API documentation website │ │ rules Open the eCTF rules website │ │ tools Run the host tools │ │ api Interact with the API │ │ hw Interact with the MITRE bootloader │ ╰───────────────────────────────────────────────────────────────────────────────────────────────╯ .. warning:: `uvx` will use the currently installed version of `ectf` by default. If you need to update to a more recent version, run `uvx ectf@latest` .. _2026_hsm_tool_calls: HSM Tool Reference Calls ------------------------ All host tools are provided by the organizers and create simplistic interfaces for communication between the :ref:`2026_host_computer` and the :ref:`2026_hsm`. These tools define the uniform interface utilized to meet the technical requirements on the HSM. See :ref:`2026_host_interface` for the details of the protocol of the interface the Host Tools use to communicate with the HSM. These commands are in the ``tools`` subprocessor. .. code-block:: $ uvx ectf tools --help Usage: ectf tools [OPTIONS] PORT COMMAND [ARGS]... Run the host tools ╭─ Arguments ─────────────────────────────────────────────────────────────╮ │ * port TEXT Serial port [required] │ ╰─────────────────────────────────────────────────────────────────────────╯ ╭─ Options ───────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ──────────────────────────────────────────────────────────────╮ │ read Read a file stored on the HSM │ │ write Write a file stored to the HSM │ │ receive Receive a file stored on another HSM │ │ listen Alert the HSM to listen for another HSM │ │ list List the files stored on the current HSM │ │ interrogate Interrogate files stored on a connected HSM │ ╰─────────────────────────────────────────────────────────────────────────╯ List Tool ^^^^^^^^^ The list tool executes the list command and displays the result from the HSM. The list tool requires a pin. .. code-block:: uvx ectf tools COM10 list --help Usage: ectf tools PORT list [OPTIONS] PIN List the files stored on the current HSM ╭─ Arguments ─────────────────────────────────────────────────────────────╮ │ * pin TEXT The 6 digit pin to authenticate the HSM device │ │ [required] │ ╰─────────────────────────────────────────────────────────────────────────╯ ╭─ Options ───────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────╯ Example Utilization: .. code-block:: bash uvx ectf tools COM10 list 123456 Read File Tool ^^^^^^^^^^^^^^ The read file tool executes the read command and writes the result from the HSM to a file on the host. The read file tool takes in the pin for the HSM, the slot from which to read, and the path on the host system to which to write the output file. The read file tool will send the read command to the HSM and write the file to the directory specified (it will use the name and contents from the HSM to write it). The force option must be specified in order to *overwrite* an existing file. .. code-block:: uvx ectf tools COM10 read --help Usage: ectf tools PORT read [OPTIONS] PIN SLOT READ_FILE_PATH Read a file stored on the HSM ╭─ Arguments ─────────────────────────────────────────────────────────────╮ │ * pin TEXT The 6 digit pin to authenticate │ │ the HSM device │ │ [required] │ │ * slot INTEGER RANGE The slot on the device for the │ │ file │ │ [required] │ │ * read_file_path PATH Path to write the file to │ │ [required] │ ╰─────────────────────────────────────────────────────────────────────────╯ ╭─ Options ───────────────────────────────────────────────────────────────╮ │ --force -f │ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────╯ Example Utilization: .. code-block:: bash uvx uv run ectf tools COM10 read 123456 0 ./out/ Write File Tool ^^^^^^^^^^^^^^^ The write file tool executes the write command and returns the result from the HSM. The write file tool takes in the pin for the HSM, the slot to which to write, the group id for the file, and a path to the file to write to the system (the host tool will use the name of that file as well as its contents to determine what is to be written). .. code-block:: uvx ectf tools COM10 write --help Usage: ectf tools PORT write [OPTIONS] PIN SLOT GID FILE Write a file stored to the HSM ╭─ Arguments ─────────────────────────────────────────────────────────────╮ │ * pin TEXT The 6 digit pin to authenticate the HSM │ │ device │ │ [required] │ │ * slot INTEGER RANGE The slot on the device for the file │ │ [required] │ │ * gid DEC_OR_HEX_INT ID of the group that owns the HSM file │ │ [required] │ │ * file FILENAME Path to a file on the host filesystem to │ │ send to the HSM │ │ [required] │ ╰─────────────────────────────────────────────────────────────────────────╯ ╭─ Options ───────────────────────────────────────────────────────────────╮ │ --uuid -u TEXT UUID of the file [default: (dynamic)] │ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────╯ Example Utilization: .. code-block:: bash uvx ectf tools COM10 write 123456 1 0x1234 ./asdf.txt Listen Tool ^^^^^^^^^^^ The listen tool executes the listen command and returns the result from the HSM. This will put the HSM in a state where it can receive cross-HSM communication from the interrogate files and receive file functionalities. .. code-block:: uvx ectf tools COM10 listen --help Usage: ectf tools PORT listen [OPTIONS] Alert the HSM to listen for another HSM ╭─ Options ───────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────╯ Example Utilization: .. code-block:: bash uvx ectf COM10 listen Interrogate Files Tool ^^^^^^^^^^^^^^^^^^^^^^ The interrogate files tool executes the interrogate command and returns a list of files from the neighboring HSM. The interrogate files tool takes in the pin for the HSM and outputs the in the same format as the list tool. .. code-block:: uvx ectf tools COM10 interrogate --help Usage: ectf tools PORT interrogate [OPTIONS] PIN Interrogate files stored on a connected HSM ╭─ Arguments ─────────────────────────────────────────────────────────────╮ │ * pin TEXT The 6 digit pin to authenticate the HSM device │ │ [required] │ ╰─────────────────────────────────────────────────────────────────────────╯ ╭─ Options ───────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────╯ Example Utilization: .. code-block:: bash uvx ectf tools COM10 interrogate 12345 Receive File Tool ^^^^^^^^^^^^^^^^^ The receive file tool executes the receive command and returns the result from the HSM. The receive file tool takes in the pin for the HSM, the slot on the neighbor HSM from which to read, and the slot on the local HSM to which to write. This copies a file from a neighbor HSM to the local HSM from which it can then be listed and read with the list tool and the read file tool. .. code-block:: uvx ectf tools COM10 receive --help Usage: ectf tools PORT receive [OPTIONS] PIN READ_SLOT WRITE_SLOT Receive a file stored on another HSM ╭─ Arguments ─────────────────────────────────────────────────────────────╮ │ * pin TEXT The 6 digit pin to authenticate the │ │ HSM device │ │ [required] │ │ * read_slot INTEGER RANGE The slot on the device for the file │ │ [required] │ │ * write_slot INTEGER RANGE The slot on the device for the file │ │ [required] │ ╰─────────────────────────────────────────────────────────────────────────╯ ╭─ Options ───────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────╯ Example Utilization: .. code-block:: bash uvx ectf tools COM10 receive 123456 0 0 .. _2026_bl_tool_calls: eCTF Bootloader Tools --------------------- The ``ectf hw`` commands are used to interact with the :doc:`eCTF bootloader `. .. code-block:: uvx ectf hw --help Usage: ectf hw [OPTIONS] PORT COMMAND [ARGS]... Interact with the MITRE bootloader ╭─ Arguments ─────────────────────────────────────────────────────────────╮ │ * port TEXT Serial port [required] │ ╰─────────────────────────────────────────────────────────────────────────╯ ╭─ Options ───────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ──────────────────────────────────────────────────────────────╮ │ status Get the bootloader status from the MSPM0L2228 │ │ erase Erase a design from the MSPM0L2228 │ │ flash Flash a design onto the MSPM0L2228 │ │ start Start the application │ │ reflash Shortcut for erase, flash, then start │ │ digest Print the cryptographic digest of a file │ │ flash_fthr Flash a design onto the MAX78000FTHR │ │ unlock_fthr Unlock the secure MITRE bootloader of the MAX78000FTHR │ ╰─────────────────────────────────────────────────────────────────────────╯ .. _2026_bl_status_tool: BL Status Tool ^^^^^^^^^^^^^^ This tool retrieves the version, whether it is secure or insecure, and the name of the installed application from the bootloader. It takes no arguments. .. code-block:: uvx ectf hw COM10 status --help Usage: ectf hw PORT status [OPTIONS] Get the bootloader status from the MSPM0L2228 ╭─ Options ───────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────╯ Example Utilization: .. code-block:: bash uvx ectf hw COM10 status .. _2026_bl_erase_tool: BL Erase Tool ^^^^^^^^^^^^^ This tool wipes the APP region of flash. You must run it before installing a new application. It takes no arguments. .. code-block:: uvx ectf hw COM10 erase --help Usage: ectf hw PORT erase [OPTIONS] Erase a design from the MSPM0L2228 ╭─ Options ───────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────╯ Example Utilization: .. code-block:: bash uvx ectf hw COM10 erase .. _2026_bl_flash_tool: BL Flash Tool ^^^^^^^^^^^^^ This tool is used to flash an application onto the MSPM0L2228. The bootloader must be erased prior to flashing. This command takes a path to the application image as an argument. .. code-block:: uvx ectf hw COM10 flash --help Usage: ectf hw PORT flash [OPTIONS] INFILE Flash a design onto the MSPM0L2228 ╭─ Arguments ─────────────────────────────────────────────────────────────╮ │ * infile PATH Path to the build output (e.g., abc.hsm) │ │ [required] │ ╰─────────────────────────────────────────────────────────────────────────╯ ╭─ Options ───────────────────────────────────────────────────────────────╮ │ --name -n TEXT Name of the binary │ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────╯ Example Utilization: .. code-block:: bash uvx ectf hw COM10 flash ./2026-ectf-insecure-example/build.hsm/ -n HSM .. _2026_bl_start_tool: BL Start Tool ^^^^^^^^^^^^^ This tool exits bootloader mode and boots the user application. It does not require any arguments. .. code-block:: uvx ectf hw COM10 start --help Usage: ectf hw PORT start [OPTIONS] Start the application ╭─ Options ───────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────╯ Example Utilization: .. code-block:: bash uvx ectf hw COM10 start .. _2026_bl_digest_tool: BL Digest Tool ^^^^^^^^^^^^^^ This tool queries the bootloader for a file digest. It takes a slot as an argument. .. code-block:: uvx ectf hw COM10 digest --help Usage: ectf hw PORT digest [OPTIONS] SLOT Print the cryptographic digest of a file ╭─ Arguments ─────────────────────────────────────────────────────────────╮ │ * slot INTEGER Slot of the file [required] │ ╰─────────────────────────────────────────────────────────────────────────╯ ╭─ Options ───────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────────────╯ Example Utilization: .. code-block:: bash uvx ectf hw COM10 digest 0