StackHawk technical onboarding guide

Article
11/13/2024

StackHawk makes API and application security testing part of software delivery. The StackHawk platform offers engineering teams the ability to find and fix application bugs at any stage of software development and gives Security teams insight into the security posture of applications and APIs being developed.

Security testing approach

StackHawk is a modern Dynamic Application Security Testing (DAST) and API security testing tool that runs in CI/CD, enabling developers to quickly find and fix security issues before they hit production.

StackHawk's modern DAST approach with an emphasis on shifting security left changes the way organizations develop and test applications today. An essential next step to helping security teams shift left is understanding what APIs they have, where they live, and who they belong to. StackHawk incorporates generative AI technology into its tool for discovering security issues with code in GitHub repositories. It can identify hidden APIs within source code and describe associated problems via natural language responses.

Enablement

Microsoft customers looking to prioritize application security now have a seamless path with StackHawk. The StackHawk platform is intricately woven into the Microsoft ecosystem, allowing developers to explore multiple paths tailored to their needs, whether orchestrating workflows through GitHub Actions or Azure DevOps. Once Microsoft Defender for API is mapped to a GitHub or ADO repo, developers can turn on SARIF to take advantage of StackHawk’s advanced security tooling.

Developers can activate a free trial of StackHawk and run a Hawkscan, and explore multiple paths tailored to their needs, whether orchestrating workflows through GitHub Actions or Azure DevOps.

When expanding out of the free tier, Microsoft customers can purchase StackHawk through the Azure Marketplace to reduce or completely eliminate procurement time.

Connect your DevOps environments to Microsoft Defender for Cloud

This feature requires connecting your DevOps environment to Defender for Cloud.

See how to onboard your GitHub organizations.

See how to onboard your Azure DevOps organizations.

Configure StackHawk API security testing scan

For GitHub Actions CI/CD environments

Note

This workflow assumes you have GitHub Code Scanning enabled. If enabled, ensure the upload-to-code-scanning option is set to true. In case you do not have GitHub Code Scanning enabled, follow the additional steps below in the section Enabling Defender for Cloud integration without GitHub Code Scanning.

To use the StackHawk HawkScan Action, make sure you're logged into GitHub, and have a StackHawk account.
From GitHub, you can use a GitHub repository with a defined GitHub Actions workflow process already in place, or create a new workflow. We scan this GitHub repository for API vulnerabilities as part of the GitHub Actions workflow.

Note

Ideally you should select to scan a GitHub repository that corresponds to a dynamic web API. This can be a REST, GraphQL or gRPC API. HawkScan works better with a discoverable API specification file like an OpenAPI specification, and with authenticated scanning. StackHawk provides JavaSpringVulny as an example vulnerable API you can fork and try, if you don’t have your own vulnerable web API to scan.
From StackHawk, make sure you collected your API Key and have a StackHawk Application created, and the stackhawk.yml scan configuration checked into your GitHub repository.
Go to StackHawk HawkScan Action to view the details of the StackHawk HawkScan Action for GitHub Actions CI/CD. From your repository /settings/secrets/actions page, assign your StackHawk API Key to HAWK_API_KEY. Then to add it to your GitHub actions workflow, add the following step to your build:
```
# Make sure your app.host web application is started and accessible before you scan.
#  - name: Start Web Application
#     run: docker run --rm --detach --publish 8080:80 --name my_web_app nginx
   - name: API Scan with StackHawk
      uses: stackhawk/hawkscan-action@v2.1.3
      with:
      apiKey: ${{ secrets.HAWK_API_KEY }}
      env:
         SARIF_ARTIFACT: true
```
This starts HawkScan on the runner pointed at the app.host defined in the stackhawk.yml. Be sure to include with.env.SARIF_ARTIFACT: true to get the SARIF output from the scan. The HawkScan action has more documented configuration inputs. You can see an example of the action in use here.
You can also follow these steps to add stackhawk/hawkscan-action to a new workflow action:
1. Sign in to GitHub.
2. Select a GitHub repository you want to configure the GitHub action to.
3. Select Actions.
4. Select New Workflow.
5. Filter by searching for StackHawk HawkScan in the search box.
6. Select Configure for the StackHawk workflow.
7. Modify the sample workflow in the editor. Review the GitHub Actions documentation.
8. Select Commit changes. You can either directly commit to the main branch or create a pull request. We recommend following GitHub best practices by creating a PR, as the default workflow launches when a PR is opened against the main branch.
9. Select Actions and verify the new action is running.
10. After the workflow is completed, select Security, then select Code scanning to view the results.
11. Select a Code Scanning alert detected by StackHawk. You can also filter by tool in the Code scanning tab. Filter on StackHawk.
You now verified that the StackHawk security scan results are showing in GitHub Code Scanning. Next, verify that these scan results are available within Defender for Cloud. It might take up to 30 minutes for results to show in Defender for Cloud.

Enabling Defender for Cloud integration without GitHub Code Scanning

If you do not have GitHub Code Scanning for your environment and wish to integrate security scan results from StackHawk into Defender for Cloud, you can follow these steps. After adding in the StackHawk workflow step, add the following steps to your GitHub workflow to send scan results directly to Defender for Cloud using the Microsoft Security DevOps GitHub Action.

- name: Upload SARIF file
        uses: actions/upload-artifact@v4
        with:
          name: StackHawk_Report_${{ github.run_id }}
          path: stackhawk.sarif
          if-no-files-found: error
- name: Upload results to MSDO
        uses: microsoft/security-devops-action@v1
        id: msdo
        with:
          existingFilename: stackhawk.sarif

Next, add an additional permission to the workflow, setting id-token to write.

After running the workflow, it might take up to 30 minutes for the results to show in Defender for Cloud.

Navigate to Defender for Cloud

Select Recommendations.
Filter by searching for API security testing.
Select the recommendation GitHub repositories should have API security testing findings resolved.

For Azure Pipelines environments

To use the StackHawk HawkScan extension, make sure you're logged into Azure Pipelines (https://dev.azure.com/{yourorganization}), and have a StackHawk account.
From Azure Pipelines, you can use a defined pipeline with a defined azure-pipelines.yml process already in place, or create a new workflow. We scan this Azure DevOps repository for API vulnerabilities as part of the azure-pipelines.yml workflow.

Once the HawkScan extension is added to your Azure DevOps Organization, you can use the HawkScanInstall task and the RunHawkScan task to add HawkScan to your runner and kick off HawkScan as separate steps.

- task: HawkScanInstall@1.2.8
   inputs:
   version: "3.7.0"
   installerType: "msi"

# start your web application in the background
# - script: |
#    curl -Ls https://GitHub.com/kaakaww/javaspringvulny/releases/download/0.2.0/java-spring-vuly-0.2.0.jar -o ./java-spring-vuly-0.2.0.jar
#    java -jar ./java-spring-vuly-0.2.0.jar &


- task: RunHawkScan@1.2.8
   inputs:
   configFile: "stackhawk.yml"
   version: "3.7.0"
   env:
   HAWK_API_KEY: $(HAWK_API_KEY) # use variables in the azure devops ui to configure secrets and env vars
   APP_ENV: $(imageName)
   APP_ID: $(appId)
   SARIF_ARTIFACT: true

This installs HawkScan on the runner pointed at the app.host defined in stackhawk.yml. Be sure to include env.SARIF_ARTIFACT: true on the task specification to get the SARIF output from the scan. The HawkScan action has more documented configuration inputs. You can see an example of the action in use here.

Install the HawkScan extension on your Azure DevOps organization.
1. Visit the StackHawk website and sign up for a free trial.
2. For Windows developers, reference this sample app for building software on Windows.
3. Review the HawkScan and Azure Pipelines documentation.
Create a new Pipeline or clone StackHawk’s sample app within your Azure DevOps project. For a tutorial for creating your first pipeline, see Create your first pipeline.
Run the pipeline.
To verify the results are being published correctly in Azure DevOps, validate that stackhawk.sarif is being uploaded to the Build Artifacts under the CodeAnalysisLogs folder.
You completed the onboarding process. Next verify the results shown in Defender for Cloud.

Navigate to Defender for Cloud:

Select Recommendations.
Filter by searching for API security testing.
Select the recommendation Azure DevOps repositories should have API security testing findings resolved.

FAQ

How is StackHawk licensed?

StackHawk is licensed based on the number of code contributors that are provisioned on the platform. For more information on the pricing model, visit the Azure Marketplace listing. For custom pricing, EULA, or a private contract, contact marketplace-orders@stackhawk.com.

Is StackHawk available on the Azure Marketplace?

Yes, StackHawk is available for purchase on the Azure Marketplace.

If I purchase StackHawk from Azure Marketplace, does it count towards my Microsoft Azure Consumption Commitment (MACC)?

Yes, purchases of StackHawk through the Azure Marketplace count towards your Microsoft Azure Consumption Commitments (MACC).

Microsoft Defender for APIs overview

Share via

StackHawk technical onboarding guide

Security testing approach

Enablement

Connect your DevOps environments to Microsoft Defender for Cloud