Skip to main content

Usage with SDKs

The Corellium MATRIX solution can be used via our CLI and REST API. This allows you to integrate MATRIX tests into your application or other automation workflows. If you're looking to use MATRIX in a CI-based workflow, please see our CI-based workflow guide and GitHub Action where we demonstrate an example of doing this with our CLI.

Prerequisites​

Before you can start using the Corellium CLI to run MATRIX tests, you'll need to have the following:

  • A Corellium account with a license that has MATRIX enabled i.e. Viper Advanced or higher.
  • A Corellium project with at least one virtual device
  • An API token for your Corellium account

How It Works​

The Corellium CLI allows you to interact with your Corellium account, projects, and devices programmatically. This means you can use both the CLI to create, start, and stop virtual devices, as well as run MATRIX tests.

For the examples below, we'll be using:

  • {projectId} as a placeholder for the ID of the project
  • {instanceId} as a placeholder for the ID of the virtual device
  • {wordlistId} as a placeholder for the ID of the wordlist file
  • {assessmentId} as a placeholder for the ID of the test
  • {apiToken} as a placeholder for your Corellium API token

Create a Device​

To use MATRIX, you'll want to start off by creating a virtual device.

corellium instance create ranchu 13.0.0 {projectId}

Create a Wordlist Image (optional)​

After running the following command to upload a wordlist file (also referred to as the "keywords" file), the output will display a JSON object that contains key-value pairs. In order to use this uploaded wordlist file for your assessment, you need to reference the value of "id" in the JSON Object when creating the assessment.

The keywords (wordlist) file is a newline-separated list of keywords that are case sensitive and will be used to search for vulnerabilities in the application. To specify regular expressions (regexes) in your keywords .txt file, wrap them in regex(/.../). For instance, to find all credit card numbers that start with “1234,” create a new line in the .txt file that says regex(/^1234/).

info

Please review our Known Issues MATRIX page for more information regarding if your iOS device supports regex or not.

corellium image create \
--project {projectId} \
--instance {instanceId} \
wordlist.txt extension plain ./wordlist.txt

Example output:

[
  {
    "status": "active",
    "id": "{wordlistId}",
    "name": "wordlist.txt",
    "type": "extension",
    "size": null,
    "project": "{projectId}",
    "created_at": "2024-03-28T13:58:14.389Z",
    "updated_at": "2024-03-28T13:58:14.389Z"
  }
]

Create a Test​

To create a test, you'll need to have a virtual device running and your app installed. Optionally reference a wordlist identifier as mentioned in the previous section. You can create a test by accessing the /matrix/assessments/create endpoint. The {instanceId} is the ID of the virtual device and both the {wordlistID} and {bundleID} are passed in as data binaries:

corellium matrix create-assessment \
--instance {instanceId} \
--bundle {bundleID} \
--wordlist {wordlistId} \
--verbose true

Start Monitoring​

Once the test has been created, you can start monitoring by accessing the /matrix/{instanceId}/assessments/{assessmentId}/start endpoint. The {assessmentId} is the ID of the test you just created and {instanceId} is the ID of the virtual device:

corellium matrix start-monitor \
--assessment {assessmentId} \
--instance {instanceId} \
--verbose true

Orchestrate Interactions​

MATRIX will now be monitoring the virtual device. You can orchestrate the interactions with the target applications by sending commands to the /instances/{instanceId}/input endpoint, where {instanceId} is the ID of the virtual device:

corellium input {input.json}

You can learn more about orchestrating interactions on the Interactions page.

Stop Monitoring​

Once you have finished interacting with the target application, you can stop monitoring by accessing the /matrix/{instanceId}/assessments/{assessmentId}/stop endpoint. The {assessmentId} is the ID of the test and {instanceId} is the ID of the virtual device:

corellium matrix stop-monitor \
--assessment {assessmentId} \
--instance {instanceId} \
--verbose true

Run the Test​

The final step is to run the test, which includes the checks and artifact analysis. This is done by making a POST request to the /matrix/{instanceId}/assessments/{assessmentId}/test endpoint. The {assessmentId} is the ID of the test and {instanceId} is the ID of the virtual device:

corellium matrix test \
--assessment {assessmentId} \
--instance {instanceId} \
--grep "string" \
--invert true \
--verbose true

Download the Report​

Once the test has finished running, you can download the report by making a GET request to the /matrix/{instanceId}/assessments/{assessmentId}/download?format=html endpoint. The {assessmentId} is the ID of the test, format=html specifies the download format, and {instanceId} is the ID of the virtual device:

corellium matrix download-report \
--assessment {assessmentId} \
--instance {instanceId} \
--format html
--verbose true

Delete the Device​

Once you're done with the device, you can delete it by running the following command:

corellium instance delete {instanceId}