Rapid7 InsightAppSec Extension
The Rapid7 InsightAppSec Extension for Azure DevOps is a TypeScript-based project that leverages the Rapid7 InsightAppSec RESTful API to automate the scanning and gating of Dynamic Application Security Testing (DAST) as part of an Azure DevOps build or release pipeline. The project utilizes the tfx-cli node-based utility for interacting with Azure DevOps and follows the standard development framework as documented.
More information about InsightAppSec can be found here: https://www.rapid7.com/products/insightappsec/
If you would like to start using the InsigtAppSec Extension for Azure DevOps today, it can be found on the Visual Studio Marketplace: https://marketplace.visualstudio.com/items?itemName=rapid7.rapid7-insightappsec-extension
The details provided in this README are for those maintaining the extension. For details on Getting Started using the published extension, either reference the extension listing on Visual Studio Marketplace or the included Overview. To get started developing the Rapid7 InsightAppSec Extension for Azure DevOps, an Azure DevOps organization is required.
The below prerequisites must first be installed on the development environment in order to get started with local development and testing:
- Visual Studio Code was used in the course of its development and is recommended as an IDE
- Azure DevOps organization with permissions to install extensions
- Visual Studio Marketplace publisher account
- Installation of Node.js
- Installation of node development dependencies
Ensure the necessary node development dependencies are installed prior to making modifications or packaging the extension. From within the project, run:
> npm install -g tfx-cli > npm install -g typescript > cd tasks/InsightAppSec > npm install
Prior to publishing the extension to Visual Studio for testing within Azure DevOps, ensure it has been tested locally. There are several parameters that must be supplied to correctly execute the logic contained within. This is because parameters are traditionally pulled by the extension from the user-entered values in the Azure DevOps UI, and those will not exist in local testing.
The following block of code contains the required parameters that must be set:
// Vars for testing locally var application = "Application Name"; var scanConfig = "Scan Configuration Name"; var region = "us"; var apiKey = "your-api-key"; var waitForCompletion = true; var scanCheckInterval = 5; var hasTimeout = true; var scanTimeout = 60; var hasScanGating = false; var generateFindingsReport = true;
With all prerequisites and configurations in place, you can now compile the project and then test:
> cd tasks/InsightAppSec > tsc task.ts --lib ES2015 > node task.js
After completing a checkout of the project from GitHub, open and build it in your IDE.
VS Code was originally used in the development of this project. The following steps can be used in VS Code to build it:
Tasks: Run Build Task
- Choose the single tsconfig.json file
In a command prompt,
cd to the project root directory and run the command:
tfx extension create --manifest-globs vss-extension.json
This should create a .vsix file, which is a Visual Studio Extension file that will be uploaded to the Marketplace to share the extension. If this fails, there should be output in the CLI listing the errors.
UPLOADING & SHARING
The following steps can be used in uploading the extension to the Marketplace, and then sharing it with a specific organization. There are two options - uploading it manually via the website, or doing it via CLI.
Publishing Via Browser
Navigate to the VS Marketplace at https://marketplace.visualstudio.com/manage/publishers
Login with a publisher account
+ New Extensionbutton and select Azure DevOps
Navigate locally to select the .vsix file that was previously created
Right click the extension once it appears in the UI and select
+ Organizationand enter the organization name
Close the window and ensure the Share has saved
Publishing Via CLI
Go to Security under your profile in your Azure DevOps organization
Generate a new personal access token with the
All accessible organizationsoption selected under the Organization field
Save this token
In the CLI,
cdto the root project directory
Use the command
tfx extension publish --token [token]to package and publish the extension, replacing
[token]with the personal access token that was previously generated
The following steps can be used in installing the shared extension within an organization.
Navigate to your organization (eg., dev.azure.com/orgName)
Navigate to the Extensions section there
Select the Rapid7 InsightAppSec extension
When redirected to the extension's page in the Marketplace, select
Get it freeand follow the directions to complete the installation process
The following steps can be used in configuring the extension within a project's build or release pipeline. This is invaluable for doing any troubleshooting or testing within the actual product.
Before configuring the build or release pipeline, we need to setup a custom service connection to allow for connection to the InsightAppSec API.
Navigate to the desired project in Azure DevOps
Select Project Settings > Service Connections
+ New service connection
Select Rapid7 InsightAppSec as the type
Enter the connection name, InsightAppSec region, and API key accordingly
Save the connection and ensure it appears in the list of service connections for that project
The following steps detail configuration within a build pipeline, though the same can be done for releases as well.
Click the icon at the top right of the page that contains account settings
Select Preview Features
Scroll down to the
New YAML pipeline creation experienceoption and turn it off
Return to the main menu bar on the left and select
Buildsunder the Pipelines section
+ Newand choose the
New Pipeline Buildoption
Select your repository and click Continue
Empty joboption at the top of the page to start a new build pipeline from scratch
+on Agent job 1 to add a new task
Search for InsightAppSec in the task window
Select it and click
Click on the task that's been added under the Agent job
Enter required parameters as desired (see below for details on parameters)
Saveoption to save the build (
Save & queueto immediately run it for your project)
Once the build completes, you're able to see whether the build succeeded or failed, as well as return to the build pipeline and edit your task as desired.
|Display name||The name of the task as it will appear in the pipeline.||true|
|InsightAppSec Connection||A service connection that allows for connection and authentication to the InsightAppSec API. Drop-down menu containing the connection that was shown configured in a previous step.||true|
|Application||A drop-down menu to select the InsightAppSec application that will be scanned.||true|
|Scan Configuration||A text field to input the InsightAppSec scan configuration that will be utilized in the scan.||true|
|Wait for scan completion?||Option used to determine whether the pipeline will continue to the next step after launching the scan, or whether it will wait for its completion.||false|
|Scan Status Interval||The frequency (in minutes) that the scan’s status will be checked upon and logged. Dependent on the option
|Generate findings report?||Option used to generate a raw JSON report that contains all findings from a completed scan.||false|
|Fail scan on timeout?||Option used to determine whether the scan will be cancelled and marked as failed if it reaches the timeout limit (value set in minutes). Dependent on “Wait for scan completion” being checked.||false|
|Timeout||The timeout for the scan completion (in minutes). Dependent on the option
|Scan Gating||Option used to determine whether the build will fail if the provided query returns results.||false|
|Vulnerability Query||The query executed against the completed scan's findings to retrieve any matching vulnerabilities. Dependent on the option