NowSecure Platform CLI Overview

George Anderson

September 24, 2024 22:15

Introduction
Prerequisites
Getting Started
Configure
Usage

Introduction

The NowSecure Platform CLI is a downloadable tool that enables users with an alternative way to interact with the NowSecure Platform with useful commands. The NowSecure Platform CLI is a command line interface that enables users to perform a variety of key tasks including:

Uploading apps to NowSecure Platform
Accessing assessment data
Managing your NowSecure organization, including listing users, sending invitations, and listing and revoking outstanding invitations

Benefits

The NowSecure Platform CLI provides developers and analysts an easier and more intuitive interaction with NowSecure Platform. The NS Platform CLI can be leveraged to integrate NowSecure Platform functions with CI/CD tools and workflows for faster and more efficient delivery.

Users can take a more programmatic approach to utilize the key capabilities of NowSecure Platform.

The NowSecure Platform CLI also provides information and feedback to ensure the interactions they are adding will work as intended.

Note: If desired, the autocomplete feature on NowSecure Platform CLI can be integrated into your shell to improve interaction.

Prerequisites

The following is needed to use the ns-cli:

A valid NowSecure Platform account.
A valid NowSecure Platform API token. Instructions on how to acquire an API token is in the Creating an API Bearer Token in Platform article.
Have the following URLs available:
- NowSecure Platform REST API- URL that access the NowSecure Platform API:
  https://lab-api.nowsecure.com
- NowSecure Graph API- URL that accesses the NowSecure Graph API:
  https://api.nowsecure.com
- NowSecure Platform UI- URL that accesses the NowSecure Platform UI:
  https://app.nowsecure.com
If you are using a single tenant deployment of NowSecure Platform, you will need to specify the URLs of your deployment during configuration. Please be sure to have the following URLs available:
- The URL of your NowSecure Platform REST API. This is the URL that you will use to access the NowSecure Platform API. This URL will be in the format of lab-api.<tenant>.nowsecure.com.
- The URL of your NowSecure Graph API. This is the URL that you will use to access the NowSecure Graph API. This URL will be in the format of api.<tenant>.nowsecure.com.
- The URL of your NowSecure Platform UI. This is the URL that you will use to access the NowSecure Platform UI. This URL will be in the format of app.<tenant>.nowsecure.com.

Getting Started

Install

The NowSecure CLI currently supports macOS, Debian based Linux distributions (Ubuntu), and Microsoft Windows (beta). Below are the steps to install on each operating system:

Navigate to the Releases page and download the appropriate binary for your operating system/architecture (32 or 64bit).
Install based on your operating system:
- MacOS: Right click the .pkg file and select run.
- Linux: sudo dpkg -i ns-cli_<VERSION>.deb
- Window: Double-click ns-cli_<VERSION>.exe

Note: Be sure you are signed in to your GitHub account prior to accessing the link, otherwise you may not be prompted with the download.

Configure

After the ns-cli has been installed on your system, run ns-cli configure to configure the CLI with your NowSecure Platform account.
The first prompt asks to enter the profile you are using. Select enter for the default profile of default.
Note: Most users will only need to use the default profile.
The next prompt asks for the Platform API token. Paste the token into the field provided and select enter.
The next prompt asks for the GraphQL endpoint for the NowSecure Platform.
Press 'enter' if you are using the CLI to interact with the default production instance of NowSecure Platform.
If you are using a single tenant deployment of NowSecure Platform, enter the URL of your GraphQL endpoint in this format:
https://api.<tenant>.nowsecure.com
The next prompt asks for the REST endpoint for the NowSecure Platform.
Press 'enter' if you are using the CLI to interact with the default production instance of NowSecure Platform.
If you are using a single tenant deployment of NowSecure Platform, enter the URL of your REST endpoint in this format:
https://lab-api.<tenant>.nowsecure.com
The next prompt will ask you to enter the UI Server for the NowSecure Platform.
Press 'enter' if you are using the CLI to interact with the default production instance of NowSecure Platform.
If you are using a single tenant deployment of NowSecure Platform, enter the URL of your UI server in this format:
https://app.<tenant>.nowsecure.com

Once completed, verify the CLI functions as expected by running ns-cli app list. A listing of the apps in your platform account will be displayed. To return results in JSON format, run ns-cli app list --json

Windows Configuration

In some cases, the ns-cli configure will return, "Error: N ot a valid token" when using CTRL-V to paste a valid token into the Windows Command or Powershell Prompt. If this occurs, paste the token into the command prompt by using right click from your mouse. When you do this, you should see asterisks to represent the token that is being submitted. If this does not work, we recommend manually creating the .nsclirc file via the steps below.

Manual Configuration of .nsclirc File

The .nsclircfile holds the configuration for the ns-cli. If you want to manually configure this file, it should be created in the root of the user's home directory and should be named .nsclirc with no extensions (.txt, .env, etc). The contents of this file should be configured as follows:

[Profile]: The ns-cli supports multiple profiles with the default profile being aptly named [default].
token: The token that you are using.
graphql (optional): The graphql API endpoint that will be used. This parameter is optional if you are using the default, https://api.nowsecure.com.
rest: (optional): The rest API endpoint that will be used. This parameter is optional if you are using the default, https://lab-api.nowsecure.com.
ui: (optional): The URL to the UI that will be used. THis parameter is optional if you are using the default, https://app.nowsecure.com

Example of an .nsclirc file supporting a single profile using the default endpoints:

Example of an .nsclirc file supporting a single profile using single tenant endpoints:

[default]
token=eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.eyTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenTokenwC
graphql=https://api.st1.nowsecure.com
rest=https://lab-api.st1.nowsecure.com
ui=https://rainier.st1.nowsecure.com

Usage

Running ns-cli help provides a top level list of the available CLI options.

Version

 @nowsecure/cli/1.0.0-alpha.2 darwin-arm64 node-v16.19.1

Usage

ns-cli [COMMAND]

Commands
`ns-cli app`	commands to manipulate apps for analysis
`ns-cli assessment`	commands to retrieve assessment data
`ns-cli autocomplete`	displays autocomplete installation instructions
`ns-cli configure`	configures the CLI with your NowSecure Platform account
`ns-cli help`	displays help for ns-cli
`ns-cli organization`	commands for the user's organization
`ns-cli plugins`	lists installed plugins
`ns-cli user`	commands for users and accounts

Command Options

App options

App commands provide steps to manipulate app binaries for analysis. Use the --help option to get more details on each of the options.

The following app commands are available:

ns-cli app archive Allows archive or unarchive an app that was uploaded to NowSecure Platform
ns-cli app config Retrieves the analysis configuration for an application that has been uploaded to NowSecure Platform
ns-cli app create Creates an app resource without a binary
ns-cli app last-assessment Shows the details and findings of an assessment based on platform (ios or android) and package name (com.facebook.katana). If the app exists in multiple groups, provide the group reference using the -g or --group option
ns-cli app list Lists available applications in your platform account
ns-cli app processUploads and analyze an app binary
ns-cli app update Updates the app's analysis configuration
ns-cli app upload Uploads an app binary
ns-cli app vulnerabilities Shows app vulnerabilities

Assessment options

Assessment commands are used to interact with assessments created in in NowSecure Platform. Use the --help option to get more details on each of the options.

The following commands are available:

ns-cli assessment cancel Cancels a running assessment
ns-cli github-snapshot Creates a SARIF report from an assessment
ns-cli assessment list Lists assessments in your NowSecure Platform account
ns-cli assessment raw Gets the raw data for an assessment
ns-cli assessment sarif Creates a SARIF report from an assessment
ns-cli assessment show Shows the details and findings of an assessment
ns-cli assessment start Starts an assessment

App Process Options

You may specify the assessment type in the CLI using the app process command:

app process <ipa_or_apk> --analysis-type=<type>

The analysis types are listed below:

full configures the assessment to run both static and dynamic analysis.
static configures the assessment to run only static analysis.
dependencies configures the assessment to only analyze dependencies in the app.

To retrieve findings from CLI, run: ns-cli assessment show ASSESSMENT REF

when analysis-type = static, you should get a list of findings with kind=static
when analysis-type = full, you should get a list of static + dynamic findings
when analysis-type = dependencies, run:
ns-cli assessment show ASSESSMENT REF --no-findings --no-state --dependencies --json

Note: Assessments ran using NowSecure Platform CLI reflect in the NowSecure Platform UI as well. If an assessment type is set to anything other than full, Partial Results or Failed Dynamic Analysis assessment status labels appear in the Platform UI. These status labels do not reflect or impact completion of a static-only analysis or dependencies-only analysis.

Autocomplete options

Running ns-cli autocompleteprovides details on how to integrate the ns-cli into your .zshrc to perform autocomplete actions

Configure options

ns-cli configure is described above in the Configure section.

Help options

ns-cli help provides help for the ns-cli.

Organization options

Organization commands provide steps that can be used to manipulate an organization within NowSecure Platform. Use the --help option to get more details on each of the options.

The following commands are available:

ns-cli organization groups Returns the groups that have been configured in an NowSecure Platform organization
ns-cli organization invitations Lists invitations that have been created within your NowSecure Platform organization
ns-cli organization invite Creates an invitation to add someone to your NowSecure Platform organization
ns-cli organization revoke-invitation Revokes an invitation that has been created in your NowSecure Platform organization
ns-cli organization users Lists the users that exist in your NowSecure Platform organization

Plugins options

The ns-cli plugins option will list plugins that have been added to the ns-cli

User options

User commands provide steps that can be used to manipulate users within NowSecure Platform. Use the --help option to get more details on each of the options.

The following commands are available:

ns-cli user account Lists the user details from NowSecure Platform for the user account that was used to create the token that the ns-cli has been configured to use
ns-cli user groups Lists the NowSecure Platform group membership for the user account that was used to create the token from which the ns-cli has been configured

Developer's Guide

This is a Monorepo containing the following items.

Building

Note: Ensure you are using Node >=16 and have installed yarn before proceeding.

If you are looking to build a specific library or tool, see Building specific tools.

Run the following to build everything: yarn run build

Run the following to clean up all build artifacts: yarn run clean

Building Specific Tools

Tool	Build Command	Clean Command
NowSecure REST and GQL API Library	`yarn run build:lib`	`yarn run clean:lib`
NowSecure Sarif Conversion Module	`yarn run build:sarif`	`yarn run clean:sarif`
NowSecure GitHub Snapshot Module	`yarn run build:github-snapshot`	`yarn run clean:github-snapshot`
NowSecure CLI	`yarn run build: cli`	`yarn run clea:cli`