├── .gitignore └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | .vscode 2 | .idea 3 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Workshop Guidebook: Automating Application Security Testing in GitHub Actions 2 | 3 | This workshop is designed to help you get started with application security testing in GitHub Actions. Participants get hands-on experience with: 4 | 5 | * GitHub Actions workflows 6 | * Dependabot software composition analysis (SCA) 7 | * CodeQL static application security testing (SAST) scanning 8 | * StackHawk dynamic application security test (DAST) scanning 9 | 10 | You can find the slide deck for this workshop [here](https://docs.google.com/presentation/d/1MWh_7iD6E9ygjWOjSh7XYkvWaL7GR62eIIVDerSbJnM/). 11 | 12 | Not attending our workshop right now? [Watch it](https://www.youtube.com/watch?v=TI7E14vYWtU) on your own schedule. 13 | 14 | ## Prerequisites 15 | 16 | To get the most out of this workshop, make sure you have the following prerequisites before getting started. 17 | 18 | * Discord 19 | * [Join the StackHawk Discord server](https://discord.gg/XnbM52B9AU)! 20 | * Find us in the **[#oct-2022-webapp-security-testing](https://discord.com/channels/854097000261222410/1017518378757394554)** channel 21 | * GitHub - [Sign up](https://github.com/signup) if you don't have an account 22 | 23 | ## Step 1: Continuous Integration Workflows in GitHub Actions 24 | 25 | Fork the [`vuln_node_express`](https://github.com/kaakaww/vuln_node_express) app: 26 | 27 | 28 | 29 | Go to the **Code** section of your newly forked repository in GitHub. Create a new file using the **Add file --> Create new file** button. Name the file `.github/workflows/build-and-test.yml`, and add the following contents: 30 | 31 | ```yaml 32 | # .github/workflows/build-and-test.yml 33 | name: Build and Test 34 | on: 35 | push: 36 | branches: 37 | - main 38 | pull_request: 39 | jobs: 40 | build-and-test: 41 | name: Build and test 42 | runs-on: ubuntu-20.04 43 | steps: 44 | - name: Checkout code 45 | uses: actions/checkout@v3 46 | - name: Install Node.js 14.x 47 | uses: actions/setup-node@v3 48 | with: 49 | node-version: 14 50 | cache: npm 51 | - name: Install dependencies 52 | run: npm install 53 | - name: Run unit tests 54 | run: npm test 55 | ``` 56 | 57 | Commit the change. 58 | 59 | Go to the **Actions** section of your repository, and you should see the new workflow running. 60 | 61 | ## Step 2: Dependency Scanning with Dependabot 62 | 63 | Go to the **Settings** section of your repo, and find the **Code security & analysis** section in the left pane. 64 | 65 | Enable the **Dependency graph**, **Dependabot alerts**, and **Dependabot security updates** features in this section. 66 | 67 | Dependabot is now configured. 68 | 69 | Go to the **Security** section of your GitHub repo, and click into the **Dependabot alerts** on the left pane. Examine some of the dependency alerts, and see if you can resolve them. 70 | 71 | ## Step 3: Static Code Analysis with CodeQL 72 | 73 | Go to the **Security** section of your repo. Click on **Set up code scanning**. Click the big green button to **Configure CodeQL alerts**. 74 | 75 | Examine the GitHub Actions workflow, `.github/workflows/codeql-analysis.yml`, and commit it to the repo. 76 | 77 | Now go to the **Actions** section of your repo, and watch your new CodeQL workflow run. 78 | 79 | When CodeQL has finished, examine the results in the **Security** section under **Code scanning alerts** in the left pane. 80 | 81 | ## Step 4: Dynamic App Scanning with StackHawk 🦅 82 | 83 | [Sign up](https://app.stackhawk.com) for a StackHawk Developer account. When prompted, select **Scan My Application**. Follow the Get Started flow to create your StackHawk API key and first application. 84 | 85 | ### Create a StackHawk API Key 86 | 87 | When you first log on to the StackHawk web app, it will prompt you to create and save an API key so that the scanner can send results back to the platform. 88 | 89 | Stash your new StackHawk API key in GitHub Secrets. In your repo, navigate to the **Settings** section, and find **Secrets → Actions** in the left pane. 90 | 91 | Add a secret named `HAWK_API_KEY`, and add your StackHawk API key as the value. 92 | 93 | ### Create your First Application in StackHawk 94 | 95 | After creating your StackHawk API key, the StackHawk web app will prompt you to create your fist app. Enter the details about your new application using the name, `vuln_node_express`, an environment of: `Development`, and a host url of: `http://localhost:3000`. 96 | 97 | For the Application Type, select **Dynamic Web Application**. And for the API Type, select **Other**. 98 | 99 | ### Commit the `stackhawk.yml` Configuration File 100 | 101 | Copy the contents of the `stackhawk.yml` file that you created in the Get Started flow in the StackHawk platform. And then paste the contents into a new file at the base of your repo named `stackhawk.yml`. Commit the file. 102 | 103 | ### Add a StackHawk Scan to your Build and Test Workflow 104 | 105 | Update your Build and Test workflow. Add a step to start the `vuln_node_express`, and a step to run HawkScan using the StackHawk Action at the end: 106 | 107 | ```yaml 108 | # .github/workflows/build-and-test.yml 109 | name: Build and Test 110 | on: 111 | push: 112 | branches: 113 | - main 114 | pull_request: 115 | jobs: 116 | build-and-test: 117 | name: Build and test 118 | runs-on: ubuntu-20.04 119 | steps: 120 | - name: Checkout code 121 | uses: actions/checkout@v3 122 | - name: Install Node.js 14.x 123 | uses: actions/setup-node@v3 124 | with: 125 | node-version: 14 126 | cache: npm 127 | - name: Install dependencies 128 | run: npm install 129 | - name: Run unit tests 130 | run: npm test 131 | 132 | ### NEW STEPS BELOW! ### 133 | 134 | - name: Daemonize our Node API service 135 | run: npm run start & 136 | - name: Run HawkScan 137 | uses: stackhawk/hawkscan-action@v2.0.0 138 | with: 139 | apiKey: ${{ secrets.HAWK_API_KEY }} 140 | ``` 141 | 142 | Commit this change. 143 | 144 | ### Check your Scan Results 145 | 146 | Go to the **Actions** section of your repo, and watch your updated Build and Test workflow run. Examine the **Run HawkScan** step console logs. 147 | 148 | [Check your scan results](https://app.stackhawk.com/scans) on the StackHawk platform. 149 | 150 | ### Set a HawkScan Failure Threshold 151 | 152 | To make the HawkScan break your build for high severity alerts, add the following section to the end of your `stackhawk.yml` configuration file at the root of your repository. 153 | 154 | ```yaml 155 | hawk: 156 | failureThreshold: high 157 | ``` 158 | 159 | Rerun your GitHub Actions workflow, and check to make sure the scan succeeds and the Action run fails due to your new failure threshold being exceeded. Triage all high severity alerts in the StackHawk platform. After triaging all high severity alerts, you should be able to rerun the Actions workflow, and the workflow should succeed. 160 | 161 | ### Link StackHawk to CodeQL (DAST + SAST) 162 | 163 | To pull your GitHub CodeQL SAST findings directly into StackHawk, install the GitHub integration! 164 | 165 | From the StackHawk integrations page, click the `GitHub CodeQL` tile > `Enable GitHub`, then follow the prompts to install the app to the same GitHub account where you forked the example repo. 166 | 167 | Next, connect your GitHub Repository to the StackHawk Application you've been scanning through StackHawk's integration management page. 168 | 169 | Rerun your GitHub Actions workflow and notice corresponding vulnerabilities getting linked directly in StackHawk's scan details! 170 | 171 | ## Workshop Complete 172 | 173 | You just automated SCA, SAST, and DAST scanning with GitHub Actions! 174 | 175 | Read more about [GitHub Actions](https://docs.github.com/en/actions), [CodeQL](https://codeql.github.com/docs/), and [Dependabot](https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates). And check out the [GitHub Actions Marketplace](https://github.com/marketplace?type=actions), where you can find other Actions to build out your pipeline. 176 | 177 | Finally, here are some additional resources for tuning StackHawk to scan *your* applications. 178 | 179 | * [HawkDocs](https://docs.stackhawk.com), where you can read all the details on how to configure and run HawkScan in your environment. 180 | * [Authenticated Scanning](https://docs.stackhawk.com/hawkscan/authenticated-scanning.html) - Guides for authenticating HawkScan to your application for deeper scans. 181 | * [Continuous Integration](https://docs.stackhawk.com/continuous-integration/), where you can see our guides for integrating HawkScan with the most popular CI/CD systems. 182 | * [StackHawk Blog](https://www.stackhawk.com/blog), with technical tips, tricks, and walkthroughs to help you secure and test your applications. 183 | --------------------------------------------------------------------------------