Automate with GitHub Actions

Run your first automated security scan using GitHub Actions—no local setup required.

This tutorial uses Javaspringvulny, a sample Java Spring application with intentional vulnerabilities. You’ll fork the repo, configure a GitHub Actions workflow, and see real security findings in StackHawk.

Prerequisites

• StackHawk account
• GitHub account

---

Step 1: Get an API Key

HawkScan authenticates with the StackHawk platform using an API Key. You’ll store this key as a GitHub secret so your workflow can run scans securely.

1. Click your user icon → Settings
2. Click API Keys → Create New API Key
3. Copy and save the key securely

---

Step 2: Fork the Repository

You’ll need your own copy of the sample app to configure the workflow and trigger scans. Forking creates a copy under your GitHub account.

1. Go to kaakaww/javaspringvulny
2. Click Fork → Create fork

---

Step 3: Add the API Key as a Secret

GitHub secrets keep sensitive values like API keys out of your code. The workflow will reference this secret to authenticate HawkScan.

1. In your fork, go to Settings → Secrets and variables → Actions
2. Click New repository secret
3. Name: HAWK_API_KEY
4. Value: your StackHawk API key
5. Click Add secret

---

Step 4: Create an Application in StackHawk

Applications in StackHawk organize your scan results by project and environment. Create one now so HawkScan knows where to send findings.

1. In StackHawk, click Add an App
2. Name: Javaspringvulny
3. Environment: GitHub Actions
4. Host: https://localhost:9000
5. Type: Dynamic Web Application
6. API: REST/OpenAPI
7. Click Finish
8. Copy the Application ID from your app list

---

Step 5: Enable the GitHub Integration

The GitHub integration posts scan summaries directly to your pull requests. This gives your team visibility into security findings without leaving GitHub.

1. In StackHawk, go to Integrations → GitHub
2. Click Enable GitHub → Install
3. Click Add to connect your Javaspringvulny fork

---

Step 6: Enable GitHub Actions

GitHub disables workflows in forked repos by default as a security measure. You need to explicitly enable them before your workflow can run.

1. In your fork, go to the Actions tab
2. Click I understand my workflows, go ahead and enable them

---

Step 7: Add the Workflow File

This workflow builds the sample app with Docker Compose, then runs HawkScan against it. The scan results are sent to StackHawk and posted to your PR.

Create .github/workflows/stackhawk-actions-workflow.yml:

name: StackHawk

on:
  pull_request:
    branches: [main]
  workflow_dispatch:

jobs:
  hawkscan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build and start application
        run: docker compose up -d --build

      - name: Run HawkScan
        uses: stackhawk/hawkscan-action@v2.2.0
        with:
          apiKey: ${{ secrets.HAWK_API_KEY }}
          configurationFiles: stackhawk-actions.yml
        env:
          COMMIT_SHA: ${{ github.event.pull_request.head.sha }}
          BRANCH_NAME: ${{ github.head_ref }}

---

Step 8: Trigger a Scan

Opening a pull request triggers the workflow. Edit the HawkScan config file to add your Application ID—this creates a PR that kicks off your first scan.

1. Open stackhawk-actions.yml in your fork
2. Replace applicationId with your Application ID
3. Select Create a new branch and start a pull request
4. Click Create pull request
5. Watch the workflow run in the Actions tab

---

Step 9: View Your Results

Once the scan completes, you can explore findings in the StackHawk platform. Each finding includes remediation guidance, evidence, and the ability to triage issues.

1. Click View on StackHawk platform in the workflow log
2. Explore findings by severity
3. Click any finding for remediation guidance

---

Resources