OX CLI

Note: This capability is currently in Early Access (EA) and is not generally available. To request access, please contact OX technical support.

OX CLI tool allows developers to scan modified files in their local repositories for security issues. It works similarly to the IDE extension, but is designed for command-line usage.

Currently the following issue categories are supported: Open Source Security, Code Security, SBOM, IaC, Secret/PII.

The repository you scan must exist in your organization and be known to OX.

In case the repository is not recognized, scans will fail.

Prerequisites

Before you begin the installation process, make sure the following tools are installed:

• Node.js (latest LTS version recommended)

• npm

• Git

Installing OX CLI

OX CLI is available in two distribution models: Early Access (EA) and General Availability (GA). Follow the procedure that matches your distribution type.

EA Installation

EA builds are provided as .tgz package files. You must install and update these builds manually.

To install OX CLI in the EA distribution:

1. Get the .tgz file (for example, oxappsec-ox-cli-1.2.3.tgz) from your OX contact.

2. Save the file to a known location on your computer, such as your Downloads folder or a project directory.

3. Open your terminal:

   • On Windows, open Command Prompt.

   • On macOS or Linux, open Terminal.

4. Go to the folder where you saved the file.

   Copy

   cd path/to/your/downloaded/files

5. Run the following command to install the CLI globally. Replace <filename>.tgz with the actual file name you received.

   Copy

   npm install -g ./<filename>.tgz

   For example:

   Copy

   npm install -g ./oxappsec-ox-cli-1.2.3.tgz

GA Installation

The GA installation method is for users installing from the public npm registry.

To install OX CLI in the GA distribution:

npm install -g @oxappsec/ox-cli

Verifying successful installation

To verify that the CLI is working, run ox-cli --version. The available commands, options, and the current version appear.

Updating OX CLI

The update process differs between GA and EA distributions. GA users update by running the update command. EA users update manually by reinstalling the provided .tgz file.

To update OX CLI in EA distribution:

1. Receive the updated .tgz file from your OX contact.

2. Run:

npm install -g ./<new-filename>.tgz

To update OX CLI in GA distribution, update public NPM builds:

• Run:

ox-cli update

To verify the update in both distributions:

ox-cli --version

Uninstalling OX CLI

To uninstall OX CLI, run:

npm uninstall -g @oxappsec/ox-cli

Before you begin running scans in OX CLI

Before you start scanning, you need to perform the initial configuration, which includes configuring the OX CLI tool with the necessary credentials. In addition, you can set API endpoints for staging or development environments, and also enable sending logs/events to datalog.

To perform the initial configuration:

1. Retrieve your IDE/CLI integration key from the OX platform.

2. In OX CLI, run:

ox-cli config <your-api-key>

Alternative:

ox-cli config set api-key <your-api-key>

You can also run ox-cli config with no parameters to be prompted for the API key interactively.

1. (Optional) Set API endpoint for staging or development environments:

ox-cli config set api-host https://custom.api.endpoint.com

1. (Optional) Enable telemetry.

ox-cli config set enable-telemetry true

1. Use environment variables as an alternative to config:

   Copy

   export OX_API_KEY=your-api-key
   export OX_API_ENDPOINT=https://your-api-endpoint.com
   ox-cli scan

   Recommended: Run ox-cli config without arguments to securely enter your API key.

2. To confirm your current configuration:

ox-cli config get <parameter>

Scanning modified files in OX CLI

During the scan process, OX CLI detects changes in the repository, such as new lines, changed dependencies, deleted files and so on using the scan [targetDir] command.

It compresses only those changes and then sends them securely to the backend for analysis.

Important: Only local modifications are scanned, not the entire repository. The scanned repository must already exist in your OX organization.

OX CLI scans a repository for security issues. If targetDir is not provided, the current directory is scanned.

Usage:

ox-cli scan [targetDir] [options]

Arguments:

• targetDir Directory to scan (defaults to the current directory)

Options:

Example command:

ox-cli scan ./my-project --severity Critical,High --format json

Example output:

Specifying Git remote

You can compare your local changes against a specific Git remote, which helps determining what is new or modified compared to the remote repository.

To compare your local changes against a specific Git remote:

• Replace origin with the name of your Git remote and run:

ox-cli scan --git-remote-name origin

Git Hook Integration

OX CLI can be integrated with Git hooks to block risky code before commit or push.

To integrate Git hooks:

1. To install pre-push hook (default):

ox-cli install-git-hook --type pre-push 

1. To install pre-commit hook:

ox-cli install-git-hook --type pre-commit

1. To uninstall pre-push hook:

ox-cli uninstall-git-hook --type pre-push

1. To overwrite an existing hook, use --force .

For further support, contact your OX Security representative.