OX CLI

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, version 16 and newer

• npm

• Git

Installing OX CLI

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

To install OX CLI:

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

To update OX CLI, 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 set api-key <your-api-key>

Note: You can also run ox-cli config with no parameters and press Enter, 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:

   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:

Option	Description
--format <format>	Set the output format. Supported values: text (default), json, sarif.
--severity <severities>	Filter results by severity. Provide a comma-separated list, e.g., Critical,High. Supported severities: Critical, High, Medium, Low, Info. The Appoxalypse severity level issues are always presented by default and you cannot set the CLI not to display them.
--group <group>	OX CLI allows the same grouping options, as OX IDE extension. Group results in the report. Supported values: severity (default), category.
--git-remote-name <remote>	Specify the Git remote name.

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.