Installation
AppSweep offers a CLI which offers convenient functionality to interact with AppSweep. The installation depends on the your host system:
MacOS, Linux
MacOS, Linux
Automatic installation is avaibale via:
curl -sS https://platform.guardsquare.com/cli/install.sh | sh
Windows
Windows
Download the most recent version
Extract the archive
Move the executable to the desired directory
Add this directory to the PATH environment variable
Verify that you have execute permission on the file
Usage (macOS, Linux, Windows)
To interact with AppSweep through the CLI, you will need an API key.
You can generate an API key by clicking on Integrations in your application´s header.
Once you have your API key, add it as an environment variable:
export APPSWEEP_API_KEY="gs_appsweep_dummy_notarealkey"
Perform Static Analysis
You can start an AppSweep scan of your application with guardsquare scan.
The following snippet shows the most basic usage of this command. It will print the url of your build.
guardsquare scan my_app.apk
For the following commands, you need to know the build ID of this scan.
This ID is printed as last part of the build URL from the above command. Alternatively, you can call scan with --format '{{.ID}}' to directly print the ID.
If you want to programmatically use the results from the scan command, you can append --format json to print all results as json.
If you want to get the summary of your scan, you can call:
guardsquare scan summary --wait-for static $BUILD_ID
If you add --wait-for static, this command will block until the static analysis is finished.
Interactive Analysis (Android only)
AppSweep not only performs static analysis, but also supports Interactive Analysis. In this analysis, AppSweep enriches your app with analysis capabilities. Once you then execute the enriched app in your normal environment (e.g., on a real device), additional information is evaluated, which allows detection of additional issues in the app.
To download the instrumented app, you can call
guardsquare scan instrumented-app --wait $BUILD_ID
Once you downloaded the enriched app, you can install the instrumented app on an emulator or a physical device and use it like a user would.
AppSweep already collects all necessary information during this execution, so once done, simply start the evaluation of this data with the following command.
guardsquare scan start-interactive-analysis $BUILD_ID
The summary will now also include the issues found during interactive analysis.
guardsquare scan summary --wait-for interactive $BUILD_ID
More commands
To see all available commands, you can simply call guardsquare scan --help
Continuous Integration (macOS, Linux, Windows)
This section will show some example scripts you can adapt to integrate AppSweep in your existing CI pipeline.
The first snippet shows a simple script that uploads your app to AppSweep and start the scan.
It will then wait for the scan to finish and print a summary of the results to stdout.
#!/usr/bin/env bash app=$1
# Start the scan.
build_id=$(guardsquare scan $app --format "{{.ID}}")
# Get a summary of the scan results.
guardsquare scan summary --wait-for static $build_id
The next snippet shows how you can take advantage of our IAST feature automatically.
It will start a scan in the same way as the previous snippet, but instead of waiting for the results, it will wait for the instrumented app to be available and then download it.
For easier scripting it uses the -o flag to make sure the app is output to a well-known location.
After retrieving the instrumented app from AppSweep you can for example run your own Appium scripts to interact with the app.
Once your script finishes it will wait for the results of the interactive analysis and get just the amount of high severity issues. In this case, if there are any high severity issues the script will exit with status 1 and the CI step will fail.
#!/usr/bin/env bash app=$1
# Start the scan.
build_id=$(guardsquare scan $app --format '{{.ID}}')
# Wait for the instrumented app to be ready and download it as `instrumented_app.apk`.
guardsquare scan instrumented-app --wait -o instrumented_app.apk $build_id
# Do something with the instrumented app here.
# e.g.: run an Appium script.
./my_custom_script.sh
# Start the interactive analysis.
guardsquare scan start-interactive-analysis $build_id
# Get the number of high issues
nb_high=$(guardsquare scan summary --wait-for interactive $build_id --format '{{.High}}')
# Use the amount of high issues a self-defined quality gate.
# e.g.: if there are high severity issues, fail the pipeline:
if [ "$nb_high" -gt "0" ]; then
echo "Found $nb_high high severity issues."
exit 1
else
exit 0
fi
If you are looking for more advanced functionality from our CLI to integrate your findings, you can review our AppSweep Enterprise extended CLI feature.
Need more? Come chat with us via the chat icon on the bottom right!