Skip to main content

Ragger

codecov Quality Gate Status CodeQL

This library aims at reducing the cost of running code on both Speculos emulator or on a real device.

It mainly consists of an interface which is implemented by three backends:

  • an emulator-only backend, SpeculosBackend, which uses SpeculosClient to run an app on a Speculos emulator. With this backend, APDU can be sent directly, without having to connect a device, start a docker or anything.

  • two physical backends (although technically they are agnostic, but the SpeculosClient is superior with an emulator), LedgerCommBackend and LedgerWalletBackend, which use respectively the LedgerComm library or the LedgerWallet library to discuss with a physical device. In these cases, the physical device must be started, with the expected application installed and running, and connected to the computer through USB.

More complete documentation can be found here.

Installation

Python package

Ragger is available on https://pypi.org. To install it fully, just run:

pip install ragger[all_backends]

You can also install it from sources. At the root of the git repository, run:

pip install '.[all_backends]'

Extras

Sometimes we just need some function embedded in the library, or just one backend. It can be bothersome (and heavy) to import all dependencies when just one or none are needed.

This is why backends are stored as extra in ragger. Installing ragger without extra means it comes without any backends.

Extra are straightforward: [speculos], [ledgercomm] and [ledgerwallet]. In the previous section, [all_backends] was used: it is a shortcut to [speculos,ledgercomm,ledgerwallet].

Speculos dependencies

If the Speculos extra is installed (to use the SpeculosBackend), system dependencies are needed. Check the doc for these.

Features

The src/ragger/backend/interface.py file describes the methods that can be implemented by the different backends and that allow to interact with a device (either a real device or emulated):

  • send: send a formatted APDU.
  • send_raw: send a raw APDU.
  • receive: receive a response APDU.
  • exchange: send a formatted APDU and wait for a response (synchronous).
  • exchange_raw: send a raw APDU and wait for a response (synchronous).
  • exchange_async: send a formatted APDU and give back the control to the caller (asynchronous).
  • exchange_async_raw: send a raw APDU and give back the control to the caller.
  • right_click: perform a right click on a device.
  • left_click: perform a left click on a device.
  • both_click: perform a click on both buttons (left + right) of a device.
  • finger_touch: performs a finger touch on the device screen.
  • compare_screen_with_snapshot: compare the current device screen with the provided snapshot.
  • pause_ticker: pause the backend time.
  • resume_ticker: resume the backend time.
  • send_tick: request the backend to increase time by a single step.

The src/ragger/navigator/navigator.py file describes the methods that can be implemented by the different device navigators and that allow to interact with an emulated device:

  • navigate: navigate on the device according to a set of navigation instructions provided.
  • navigate_and_compare: navigate on the device according to a set of navigation instructions provided then compare each step screenshot with "golden images".
  • navigate_until_snap: navigate on the device until a snapshot is found and then validate.
  • navigate_until_text: navigate on the device until a text string is found on screen and then validate.
  • navigate_until_text_and_compare: same as navigate_until_text but compare screenshots taken at each step with "golden images".

Examples

With pytest

The backends can be easily integrated in a pytest test suite with the following files:

  • A conftest.py which can be heavily based on this template.
  • A usage.md which can be heavily based on this template.
  • Tests files which would looks like:
#---------- some_tests.py ----------

TESTS_ROOT_DIR = Path(__file__).parent


def test_something(backend, firmware):
    rapdu: RAPDU = backend.exchange(<whatever>)
    assert rapdu.status == 0x9000


def test_with_user_action_and_screenshot_comparison(backend, firmware, navigator, test_name):
    with backend.exchange_async(<whatever>)
        if firmware.device == "nanos":
            instructions = [
                NavIns(NavInsID.RIGHT_CLICK),
                NavIns(NavInsID.RIGHT_CLICK),
                NavIns(NavInsID.BOTH_CLICK),
            ]
        elif firmware.device == "stax":
            instructions = [
                    NavIns(NavInsID.USE_CASE_REVIEW_TAP),
                    NavIns(NavInsID.USE_CASE_REVIEW_TAP),
                    NavIns(NavInsID.USE_CASE_REVIEW_CONFIRM),
                    NavIns(NavInsID.USE_CASE_STATUS_WAIT)
                ]
        else:
            instructions = [
                NavIns(NavInsID.RIGHT_CLICK),
                NavIns(NavInsID.BOTH_CLICK),
            ]
        navigator.navigate_and_compare(TESTS_ROOT_DIR, test_name, instructions)
    rapdu: RAPDU = backend.last_async_response
    assert rapdu.status == 0x9000
    assert verify(rapdu.data)

The backend fixture used to discuss with the instantiated backend is documented here.

The navigator fixture used to navigate with the instantiated backend is documented here.

After implementing the tests, the test suite can be easily switched on the different backends:

pytest <tests/path>                                               # by default, will run tests on the Speculos emulator
pytest --backend [speculos|ledgercomm|ledgerwallet] <tests/path>  # will run tests on the selected backend

The tests of this repository are basically the same as this example, except the tests run on the three current firmwares (NanoS, NanoX and NanoS+).

Documentation

The complete documentation can be found here. If you want to generate it locally, you'll need the doc dependencies to generate the documentation:

pip install .[doc]

You will also need the graphviz package in order to generate some dependency diagrams:

apt-get install graphviz

Once done, you can generate the documentation:

(cd doc && make gen_resources && make html)

Repository deployment, versions & tags

Versions and changes are documented into the CHANGELOG.md file.

Merging on master or pushing a tag on the GitHub repository triggers a deployment. Python packages are deployed into pypi.org.

  • if triggered via a merge, the package will be a "pre-release", with a version matching <M>.<m>.<p+1>-dev<N> with:
    • M the major number of the latest version,
    • m the minor number of the latest version,
    • p the patch number of the latest version,
    • N the number of commits since the latest version.
  • if triggered via a tag, the package will be a release with the tag as the version. The version embedded into the tag must also fit with the latest version documented into the CHANGELOG.md file. If not, the CI will fail.

Metadata

Release files for ragger 1.49.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ragger 1.49.0
File Size Uploaded Provenance Actions
ragger-1.49.0.tar.gz 364.0 kB Without provenance Details for ragger-1.49.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ragger 1.49.0
File Interpreter ABI Platform Actions
ragger-1.49.0-py3-none-any.whl Python 3 none any Details for ragger-1.49.0-py3-none-any.whl

Total release size: 565.5 kB

Release files / ragger-1.49.0.tar.gz

Download URL ragger-1.49.0.tar.gz
Size 364.0 kB
Tags Source
SHA-256 checksum
How to use checksums
529bc808da9cb59483bd1c813eec4ff9c1aa4c68528fd4cd1521ac361d94fd08
BLAKE2b-256 checksum
How to use checksums
146879736f9e220a2c4b65de28c38ee92a9bce0ffbf5c7142ffeae977e313c19
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.14

Release files / ragger-1.49.0-py3-none-any.whl

Download URL ragger-1.49.0-py3-none-any.whl
Size 201.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dc4d51bb487c18661144abfa6913dc1afb90575a9cc906195dc88f0623609aaf
BLAKE2b-256 checksum
How to use checksums
887c42b32ca55f243c63a6ddc9d5aad1ed718c1b30ccdee45fd0a1ff4adeb8b2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.14

Security for ragger 1.49.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.49.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page