Installation
AppSweep offers a CLI which offers convenient functionality to interact with AppSweep to automate your scans. The installation depends on the your host system:
MacOS, Linux
MacOS, Linux
Automatic installation is available 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 applications header.
Once you have your API key, add it as an environment variable in your terminal:
export APPSWEEP_API_KEY="gs_appsweep_dummy_notarealkey"
Using 'guardsquare scan' to Upload and Analyze Your App
guardsquare scan <input-file> [flags]
Supported file formats are:
for Android: apk, aab, aar
for iOS: ipa, xcarchive
For an in-depth analysis of iOS apps, AppSweep relies on debug symbols being present in your application. Make sure to include them when archiving your ipa, or use an xcarchive, which includes debug symbols by default.
Options:
--browser
Open build in browser
--commit-hash <string>
Commit hash of your build
--dsym <strings>
[iOS only] Path to dSYMs
--format <string>
format output using a custom template:
'json': print in json format
TEMPLATE: print output using the given go template
--mapping-file <string>
[Android only] Obfuscation mapping file
--tag <strings>
Tag your build
Viewing a Summary of Results with 'guardsquare scan summary'
guardsquare scan summary <build-id> [flags]
View the number of issues found in your app by severity.
Options:
--format <string>
format output using a custom template:
'json': print in json format
TEMPLATE: print output using the given go template.
--timeout <duration>
Timeout for this command to run.
--wait-for <string>
The stage to wait for: static | interactive. It will wait for as long as --timeout
Formatting
By default guardsquare will output results in a plain text format. This commands supports an optional --format flag to make the output easier to process by other tools.
json will print the output as json.
The --format flag also supports go template syntax to print only a subset of the json values.
The available arguments are:
High: The amount of high issuesMedium: The amount of medium issuesLow: The amount of low issuesURL: The build url
To learn more about Go templates, see: https://golang.org/pkg/text/template/.
Viewing the Results of a Scan With 'guardsquare scan results'
Note: Accessing the full results of a scan with the CLI is an AppSweep Enterprise feature
guardsquare scan results <build-id> [flags]
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.
Interactive Analysis (Android only)
AppSweep not only performs static analysis, but also supports interactive analysis (IAST). 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 after completing the initial Static scan, you can call
guardsquare scan instrumented-app <build-id> [flags]
Options
-o, --output <string>
Where to put the instrumented app
--timeout <duration>
Timeout for this command to run.
--wait
Wait for the instrumented app to be ready. It will wait for as long as --timeout
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>
Fore more information on available CLI options
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!