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
-
NowSecure Platform REST API- URL that access the NowSecure Platform API:
Getting Started
Install
- Download the NowSecure Platform CLI from this GitHub repo.
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. - The repo contains two .pkg files, arm64 (For Apple Silicon Macs) and x64 (For Intel-based Macs). (If you are not sure which to use, click the apple logo in the upper left corner of your screen and select "About this Mac")
Configure
- After the
ns-cli
has been installed on your system, runns-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
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 |
|
Commands | |
|
commands to manipulate apps for analysis |
|
commands to retrieve assessment data |
|
displays autocomplete installation instructions |
|
configures the CLI with your NowSecure Platform account |
|
displays help for ns-cli |
|
commands for the user's organization |
|
lists installed plugins |
|
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 process
Uploads 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 autocomplete
provides 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
Comments
Article is closed for comments.