CI/CD integration¶
Integrating ONEKEY into the development lifecycle, particularly through CI/CD systems, allows you to automatically test builds and immediately report or fix potential regressions.
There are many ways to integrate ONEKEY, and the actual integration depends heavily on the use cases, processes, and requirements.
ONEKEY provides a general API that you can use for all types of integration. This supports a number of commands to ease the integration process, regardless of whether the commands are used directly or only as inspiration.
ONEKEY client installation¶
The client is available at https://github.com/onekey-sec/python-client, or you can install it as a python package:
General usage¶
Use the client with the onekey command, which offers multiple options and subcommands:
--email TEXT # Email to authenticate on the
ONEKEY platform [required]
--password TEXT # Password to authenticate on the ONEKEY platform
[required]
--tenant TEXT # Tenant name on ONEKEY platform [required]
--api-url TEXT # ONEKEY platform API endpoint
[default: https://app.eu.onekey.com/api]
--disable-tls-verify # Disable verifying server certificate,
use only for esting
--help # Show this message and exit.
To use the ONEKEY platform, you need to provide a valid email and password as well as a tenant name.
Specify the required parameters through command line arguments or by using environment variables with the ONEKEY prefix:
Tip
You can mix environment variables and command line arguments. Environment variables are more useful when the client is used by CI/CD jobs/tasks.
Firmware upload (upload-firmware)¶
You can use the client to upload firmware images to the platform, enabling automated scenarios. Once you upload a firmware image, the system automatically schedules and queues the analysis.
To upload a firmware to the ONEKEY platform run:
--product TEXT # Product name to add the firmware [required]
--vendor TEXT # Vendor name to add the firmware [required]
--product-group TEXT # Product group name to add the firmware [default:
Default; required]
--version TEXT # Firmware version
--name TEXT # Firmware name
--help # Show this message and exit.
Product and vendor name must be provided along with the firmware image; the firmware version is optional. You can also create a custom firmware name, otherwise it will be generated automatically from vendor, product, version and name.
You can also select the product group to assign the uploaded product. If you omit this step, the Default product group will be assigned.
Info
Make sure that you have Upload permission on the selected product group. See Permissions to learn more.
You can use command line arguments or environment variables prefixed with ONEKEY_UPLOAD_FIRMWARE to upload a firmware:
Once a firmware is successfully uploaded, the command prints the uploaded firmware ID (UUID) to the STDOUT.
Success
Save the UUID as you can use it to check analysis progress and fetch analysis result.
When an analysis worker becomes available, the firmware is analyzed. The progress can be queried using the API and the firmware ID. Once the analysis is complete, you can fetch the results using the API.
CI/CD results (ci-result)¶
In a typical CI/CD integration scenario, after the firmware image (build artifact) has been uploaded, you must go through the following steps:
- Wait until the firmware analysis is complete.
- Find the previously uploaded firmware (for example the previous nightly build or the previous release).
- If the previous firmware is available, compare the analysis results and fetch the new and dropped issues/CVEs.
- In case no previous firmware is available, fetch only the results (issues/CVEs).
- (Optional) Generate a JUNIT .xml file with the results, which you can use in a CI/CD job output.
- (Optional) Fail the CI/CD job if new issues or CVEs have been identified.
For your convenience however, these steps are all included in a subcommand:
--firmware-id UUID # Firmware ID [required]
--exit-code-on-new-finding INTEGER # Exit code to use when findings are
identified compared to previous firmware
upload [default: 1]
--check-interval INTEGER # Wait time between checking for result
[default: 60]
--retry-count INTEGER # Number of times to retry fetching results
due to communication problem [default: 10]
--retry-wait INTEGER # Wait time between retries due to
communication problem [default: 60]
--junit-path PATH # File to export JUNIT xml
--help # Show this message and exit.
You only need to provide the firmware ID from the upload firmware step; everything else is handled automatically. The previous firmware is identified by searching for the previous uploaded firmware within the same product.
Similar to the previous commands, you can use command line arguments or environment variables with ci-result:
The client prints the findings to the STDOUT:
Waiting for analysis to finish on firmware: <firmware-ID>
Firmware analysis finished successfully, results:
https://app.eu.onekey.com/firmwares?firmwareId=<firmware-ID>
Previous firmware results:
https://app.eu.onekey.com/firmwares?firmwareId=<previous-firmware-ID>
############################################################################
New / dropped issue count: 0 / 0
New / dropped CVE count: 0 / 0
No changes since previous firmware
In case no new issues or CVEs were found the command exits with exit-code 0.
CI/CD jobs¶
Depending on the use case and the requirements a CI/CD job can be configured to:
- Upload a firmware image
- Wait for the analysis to complete
- Compare the results with the previous run.
Depending on the CI/CD setup, you can configure either one or two jobs:
- A single job that covers the entire process.
- Separate jobs for the upload and analysis result fetching steps.
Tips
Typically, a single job is easier to implement as it avoids the need to pass the firmware ID between jobs. However, for better granularity or error handling, two jobs may be more effective.
Use the same product name for all uploaded firmware images that need to be compared with each other.
Using a build ID or a version as firmware version helps to identify the firmware images.