DEV Community: Scott Gerlach

Using StackHawk in GitLab - Know Before You Go (Live)

Scott Gerlach — Tue, 21 Apr 2020 17:45:31 +0000

The earlier you find application bugs, the cheaper it is to fix them. That’s one of the reasons so many organizations have adopted Test Driven Development (TDD). TDD enables Developers to more accurately identify if the code you are about to commit is going to break and not pass the tests you’ve instrumented in CI/CD. Analogous to the TDD process, we believe in automating application security testing. That’s why we created StackHawk!

Check Out How it Works

This post demonstrates how to leverage StackHawk to automate testing for AppSec bugs in your CI/CD pipeline. We’ll walk through:

An Example App, “Vulny Django”, used for testing StackHawk
How I Dockerized my Django App
Building and testing my app in GitLab
Finding application security bugs in the pipeline with StackHawk

Note: StackHawk is a dynamic application security testing (DAST) scanner that actively tests the code that developers write for security bugs

Example App: Polling with Django + Local StackHawk Scan

I took the Django tutorial on making a polls application and modified it into a project I call Vulny Django to test StackHawk. I’m not the best coder, so as I created the app, I wanted to run the tests that we built in with the tutorial alongside the StackHawk DAST scanner. Running StackHawk locally allows me to ensure that I have not introduced any AppSec bugs as I build.

The StackHawk scanning capability is configured via a yaml file that describes how to scan your application. In this example app, we have a pretty simple StackHawk config to scan locally, as we mostly have to instrument how to log in to the admin page and a few URLs to exclude. With this configuration, I can easily scan my Polls app and the admin interface from my local laptop using the command:

vulny_django_play/ $ docker run -e API_KEY=${HAWK_API_KEY} --rm -v $(pwd):/hawk:rw -it stackhawk/hawkscan:latest

This command dynamically scans my running Django app to test it for security issues that can be triaged on the StackHawk platform.

Containerizing The Polls App for Testing in Pipeline

I have also dockerized my Django project, because why wouldn’t you!? I want to be able to scan my Django project in GitLab’s awesome DevOps platform. To do that, my application needs to be running somewhere. While I could deploy my app onto a staging site and have HawkScan, the StackHawk scanner, scan it there, I choose the ephemeral route, where everything only lives temporarily while I test it. This allows me to break builds if I find an issue before deploying my app to a place that may be being used for user testing or other things.

Using docker, I can create a docker network and attach my Django and StackHawk/HawkScan containers to it so they can talk to each other. Doing that looks like this on the command line.

/vulny_django_play/ $ docker network create scan_net

/vulny_django_play/ $ docker run --detach -p 8020:8020 --network scan_net --name vuln-django --rm vuln_django:latest

/vulny_django_play/ $ docker run -e API_KEY=${HAWK_API_KEY} -e HOST=http://vuln-django --rm -v $(pwd):/hawk:rw --tty --network scan_net stackhawk/hawkscan:latest

With these commands, we are:

Building the docker virtual network named ‘scan_net’
Running the Django docker image attached to the scan network that we built ( docker build . -t vuln_django:latest )
Running the Django docker image attached to the scan network that we built ( docker build . -t vuln_django:latest )
Running HawkScan while attaching it to the scan_net and overriding the HOST variable in the stackhawk.yml to point at the docker network name of the Django App

PSA: Django will not let you put underscores in a host name like this http://vuln_django because it’s not RFC compliant. If you do that, you will Google search for a while to try and figure out why your app is not working in the docker network only to find that if you change that to a dash, http://vuln-django, everything will work fine and you will be embarrassed (actually that last part might just be me).

Once this is all set, you’ll have two Docker containers talking to each other over a virtual Docker network. This is a perfect time to start working on our GitLab config, since we can do Docker-In-Docker in GitLab.

Go Go Gadget GitLab!

GitLab’s DevOps Platform has awesome capabilities. I wanted to wire up my Django project with a platform that could run my tests on PRs when I commit code, or when I want to merge code. GitLab CI/CD made that process pretty easy. They employ a pretty simple yml config file to instrument what the pipeline should look like and do.

I chose a few tests to run, like flake8 and the migrations and tests I had written to run in the test phase using the python:3.7-buster image. So here we are installing the python library requirements, running flake8, then pre-populating the DB with info and running the test suite.

test:
  stage: test
  image: python:3.7-buster
  script:
  # This configures the test stuff
    - apt-get update -qy
    - apt-get install -y python-dev python-pip
    - pip install -r src/requirements.txt
    - flake8 vuln_django --max-line-length=127
    - cd src
    - python manage.py migrate
    - python manage.py test

This allows me to make sure my code is healthy before I do anything else, like, say...

Testing the Build of The Docker Container

Now it’s time for me to make sure my docker container will successfully build in CI/CD. Here, I need to tell GitLab Runner how to build my image, which is SUPER easy. I tell it I need the docker image and that I would also like the Docker-in-Docker server to make sure that doesn’t introduce any issues with my build:

docker-build:
  stage: build
  image: docker:19.03.1
  services:
    - docker:19.03.1-dind
  script:
   - docker build -t vuln_django:latest .

This section is pretty straightforward and is similar to building a docker image on your workstation or laptop. This again is just making sure the image will build so that we can get to the good stuff.

Scanning My Dockerized Polls App with StackHawk

Now it’s time to scan the dockerized version of my Django app. We know we can scan the application on our workstation in either Virtual Environment or dockerized versions. We know we can make one Docker container talk to another Docker container, so let's tell the GitLab runner how to do that.

We’ll need the docker image to build upon
We’ll need the Docker-in-Docker service
We’ll build the Docker virtual network
We have to build the Django container and download the StackHawk/HawkScan container
We’ll have to set the two Docker images to run on the virtual network
We’ll use a YML override to tell the StackHawk scanner about a new environment and where to find the running application.

This section of our .gitlab-ci.yml file looks like this:

hawk_scan_execute:
  stage: scan
  image: docker:19.03.1
  services:
    - docker:19.03.1-dind
  script:
    - docker build -t vuln_django:latest .
    - docker network create scan_net
    - docker pull stackhawk/hawkscan:latest
    - docker run --detach -p 8020:8020 --network scan_net --name vuln-django --rm vuln_django:latest
    - |
      docker run --network scan_net --volume $(pwd):/hawk:r --tty --rm \
        --env API_KEY="hawk.${HAWK_API_ID}.${HAWK_API_SECRET}" \
        --env BRANCH=GitLab:${CI_COMMIT_BRANCH} \
        --env NO_COLOR=true \
        stackhawk/hawkscan:latest stackhawk.yml stackhawk-gitlab.yml

Here we used an override yml file and configuration call to tell the scanner some new things. That override file looks like this:

app:
  env: GitLab-CI
  # The url of your application to scan
  host: http://vuln-django:8020 # (required)

We are overriding two settings in the yml file: env and host. The host override is pretty simple, just identifying how the scanner can find the application, so for this configuration we gave it a simple, short name. The env is so I can tell in the StackHawk app which environment ran my scan. I could have other pieces of technology introduce or remove security bugs here, so I want to be able to differentiate. The StackHawk scanner will make the Environment in the Portal GitLab-CI.

(Interestingly, We had a customer use this to identify git branch name.. They wanted to know which branch introduced any issues they found. I think this is a really neat way to think about how to group results, but I think I prefer my Environment more loosely grouped, like CI/CD or GitLab.. I will and I will push that branch name to a Tags feature we will implement later.)

Now I have a configured GitLab Runner for my Django project, with the output looking like this:

And the results in the StackHawk Platform look like this:

Now it’s Easy to Know Before You Go!

As you can see, it’s really easy to implement DAST AppSec Scanning into the GitLab CI/CD pipeline and have the results available in an organized fashion that can help you understand the AppSec bugs that may exist in your application before it goes live. If you’d like to integrate StackHawk into your CI/CD pipeline, sign up for StackHawk Early Access and we’ll get you started. Also, if you would like to play with my Django app, feel free to fork it and use it to test out StackHawk in your CI pipeline.

Scanning the Damn Vulnerable Web App with StackHawk

Scott Gerlach — Sat, 18 Apr 2020 17:02:48 +0000

When we first introduced StackHawk to some of our close friends in the security industry and asked them to try it out, they tested it the same way we did. They ran HawkScan through its paces with one of the many vulnerable web applications security professionals set up online to help the community learn. They did this to have a semi-known outcome to see how StackHawk works. Enter Damn Vulnerable Web App.

The Damn Vulnerable Web App (DVWA) is a tool made by Dewhurst Security to help security professionals and developers alike find and exploit Web Application Vulnerabilities. It’s a great tool and worth checking out if you haven’t already.

Results of StackHawk’s Dynamic Application Security Test (DAST) scan of the Damn Vulnerable Web App.

Below are the details on how you can test StackHawk with the DVWA yourself. Note that this whole process can be done in ~10 minutes and provides a great example of how StackHawk works.

Initial Set Up

StackHawk is built to find security bugs in a running application. To get DVWA up and running, I went the easy route and deployed the web app via a Docker container. This gave me the freedom to use the app and not worry about fiddling with a LAMP stack. The default docker instructions docker run --rm -it -p 80:80 vulnerables/web-dvwa exposes DVWA to the host machine interfaces on port 80, including http://localhost/. From there, I could easily log in to the web interface and ensure everything was working as expected.

If you’re following along at home, you’ll have to follow three simple steps to fully get DVWA up and running:
Open http://localhost and log in to the admin console using username: admin and password: admin
Scroll to the bottom of the page to initialize the application database by clicking Create / Reset Database
Confirm you can log in again with username: admin and password: password and make sure you see the left side menu this time.

Starting a StackHawk Scan

To start, if you don’t have an API key, please make your way over to https://stackhawk.com and signup to get access. Once you have an API key and have defined an application and received the applicationId for your test you are ready to configure the scanner.

StackHawk has a simplified configuration file written in YAML to make implementation easier and scalable. Automating scanning across the wide variety of applications out there introduces significant complexity, but we’ve simplified the configuration so you can get up and running quickly.

Since we know the application lives on http://localhost/, the beginning of our config file (stackhawk.yml) should look something like this:

app:
  applicationId: {your applicationID uuid}
  env: Development
# The url of the application to scan
  host: http://localhost # (required)
hawk:
#  # The web crawler / spider configuration
  spider:
#    # Enable the base spider for discovering your app's routes
    base: true # (default)

Within this section of our config file, we tell the scanner what the StackHawk applicationId is, what environment DVWA is running in, where the application can be found and what web crawling to do. In this instance, DVWA is a PHP application, so the base spider will work nicely to find and parse links and forms in the page (we support single page apps too – check out the docs). If we save this file to a directory on our local computer, say ~/dvwatest/, we can then begin a scanning run. To start StackHawk with our stackhawk.yml file defined, we simply run the command:

cd ~/dvwatest/
docker run --rm -v $(pwd):/hawk:rw -it stackhawk/hawkscan:latest stackhawk.yml

Since all of the functionality of the web app is behind Form/Session authentication, running HawkScan at this point only discovers the login.php page. While that part is nifty, there’s no real meat there.

DVWA comes with a default admin user that we set the password for in the beginning part of the article. Reviewing the login form, there is Login, the name of the Submit button with the value Login. It’s important for StackHawk to know that, because that’s how it will try to log in. There are also three different fields submitted:

Username
Password
user_token

The first two fields are fairly self explanatory. The third field, user_token, is the CSRF field that helps prevent form stuffing, or automated attempts to bypass the login page. The value for user_token is generated by the server and displayed in the page. The server expects that value back when the user attempts a login to validate the form was read and submitted in a regular fashion. It’s important for StackHawk to know the user_token as well so it can scrape the login page, find the value, pass it back to the server and complete the CSRF challenge. With all these additions, our config file is starting to look a bit more robust.

We also need to set up some of the authentication parameters for the scanner to be able to log into the DVWA. We know it uses Form based authentication.

When we made HawkScan, one the the things we wanted to improve was the Authentication process. The base scanner is sort of agnostic to whether or not your authentication worked and getting feedback to tell if authentication actually worked is at best, difficult. We’ve made that process better in the authentication section. We ask for a URL and a response code that should be accessible after authentication. When those succeed, the scanner continues. If they don’t the scanner stops and give you feedback about what didn’t go correctly in authentication.

app:
  applicationId: {your applicationID uuid}
  env: Development
  # The url of your application to scan
  host: http://localhost # (required)
  # Our scanner's capability is still in Alpha; If we notice a bug we'll use this email to reach out or provide a fix.
  # We will never use this contact for marketing purposes.
  contactEmail: steve.s.hawk@example.com # (optional)
  # The risk level of the app
  riskLevel: MEDIUM # The DVWA poses a Medium risk to my fictional company
  # The type of data sensitivity the web app maintains
  appDataType: PII # It holds PII data and that’s pretty much it
 #  # The name of your anti csrf parameter
  antiCsrfParam: user_token # here we define the CSRF field name so the scanner can pick it up

#  # Form POST based authentication configuration for scanning as a user.
#  # Enabling will force the scanner to scan as an
#  # authenticated user of your app.
#  # Authenticated requests will pass cookies received from the form POST
#  # to maintain authentication.
  authentication:
#    # A regex to match against http responses to determine if the scan user is
#    # still logged in to your app
    loggedInIndicator: "\\QLogout\\E" # (required)
#    # A regex to match against http responses to determine if the scan user is
#    # logged out of your app
    loggedOutIndicator: "\\QloginInput\\E" # (required)
#   # A page that is only accessible being logged in. We will try to access this page
#   # to validate authentication worked
    testPath:
      path: /vulnerabilities/javascript/
      type: HEADER
      success: ".*200.*"
    usernamePassword:
      type: FORM # (optional)
#    # The route to a form POST to authenticate a user
      loginPath: /login.php # (required)
#    # The route to logout a user
      logoutPath: /logout.php # (required)
#    # The username field name in your authentication form
      usernameField: username # (required)
#    # The password field name in your authentication form.
      passwordField: password # (required)
#    # Other parameters that may be required by your log in form
      otherParams: # (optional)
        - name: Login  # The login form parameter is needed to make login work
          val: "Login"
        - name: "security" # I'm not sure what this does in the app, but scans don't work without it
          val: "low"
#    # The username to authenticate as when scanning
      scanUsername: admin # (required)
#    # The password of the scanUsername
      scanPassword: password # (required)

hawk:
#  # Web crawler / spider configuration
  spider:
#    # Enable the base spider for discovering your app's routes
    base: true # (default)

With this config file, StackHawk knows how to log in to the app. However, when I ran some scans, the results and discovered URLs are not quite what I was expecting. There were not enough URLs and WAY less vulnerabilities than I expected. When investigating the DVWA in my browser, I can see a few things that I must tell StackHawk for it to do a more thorough job.

Browsing to the Logout Menu, the application instantly logs me out. What that means, is the scanner is logging me into the application to do the spidering of the app, browsing the links it can find and logging me out before it can test any of the pages. I need to tell the scanner about these things. My config now looks like this.

app:
  applicationId: {your applicationID uuid}
  env: Development
  # The url of your application to scan
  host: http://localhost # (required)
  # Our scanner's capability is still in Alpha; If we notice a bug we'll use this email to reach out or provide a fix.
  # We will never use this contact for marketing purposes.
  contactEmail: steve.s.hawk@example.com # (optional)
  # The risk level of the app
  riskLevel: MEDIUM # The DVWA poses a Medium risk to my fictional company
  # The type of data sensitivity the web app maintains
  appDataType: PII # It holds PII data and that’s pretty much it
  sessionTokens: # the session cookies DVWA uses in some fashion
    - "PHPSESSID"
    - "dvwaSession"

#  # The name of your anti csrf parameter
  antiCsrfParam: user_token # here we define the CSRF field name so the scanner can pick it up
  # What pages to not scan
  excludePaths:
    -"logout.php" # the scanner will log itself out if you don't ignore it

#  # Form POST based authentication configuration for scanning as a user.
#  # Enabling will force the scanner to scan as an
#  # authenticated user of your app.
#  # Authenticated requests will pass cookies received from the form POST
#  # to maintain authentication.
  formAuth: # This app uses Form Based auth
#    # The route to a form POST to authenticate a user
    loginPath: /login.php # this is the login page
#    # The route to logout a user
    logoutPath: /logout.php # tell the scanner where logout happens.
#    # The username field name in your authentication form
    usernameField: username # here is the name of a field in the login form
#    # The password field name in your authentication form.
    passwordField: password # here is the name of a field in the login form
#    # A regex to match against http responses to determine if the scan user is
#    # still logged in to your app
    loggedInIndicator: "\\QLogout\\E" # the \\Q and \\E are important indicators, but this field also take standard regex
#    # A regex to match against http responses to determine if the scan user is
#    # logged out of your app
    loggedOutIndicator: "\\QloginInput\\E" #
#    # Other parameters that may be required by your log in form

#    # Other parameters that may be required by your log in form
    otherParams: # (optional)
      - name: Login  # The login form parameter is needed to make login work
        val: "Login"
#    # The username to authenticate as when scanning
    scanUsername: admin # DVWA default
#    # The password of the scanUsername
    scanPassword: password # DVWA default
hawk:
#  # Web crawler / spider configuration
  spider:
#    # Enable the base spider for discovering your app's routes
    base: true # (default)

Now we are starting to get better results, but something is still missing causing the scanner to not find all the links and test the pages. While we have described our application well, the scanner is still doing something incorrectly with the session when spidering links in the app. We can tell it to not browse or test some of the pages that are giving us trouble. For instance, the setup.php page has a button that rebuilds the entire database, that’s probably not helping our cause. Also, the security.php page has a button that turns on PHPIDS and make the app more secure and while that’s great, it makes our test not work well. The last one we are concerned about is the /vulnerabilities/csrf/ path that has the ability to change the users password. While that doesn’t affect the current scan, the scanner will change the password of the user and confuse you a lot!

# Complete configuration for DWVA StackHawk Scan
app:
  applicationId: {your applicationID uuid}
  env: Development
  # The url of your application to scan
  host: http://localhost # (required)
  # Our scanner's capability is still in Alpha; If we notice a bug we'll use this email to reach out or provide a fix.
  # We will never use this contact for marketing purposes.
  contactEmail: steve.s.hawk@example.com # (optional)
  # The risk level of the app
  riskLevel: MEDIUM # The DVWA poses a Medium risk to my fictional company
  # The type of data sensitivity the web app maintains
  appDataType: PII # It holds PII data and that’s pretty much it
  sessionTokens: # the session cookies DVWA uses in some fashion
    - "PHPSESSID"
    - "dvwaSession"

#  # The name of your anti csrf parameter
  antiCsrfParam: user_token # here we define the CSRF field name so the scanner can pick it up
  excludePaths:
    - "/setup.php" # The scanner resets the DB :)
    - "/security.php" #the scanner turns on PHPIDS here
    - "/vulnerabilities/csrf/*" #this page changes the admin password
    - "/logout.php" # the scanner will log itself out if you don't ignore here

#  # Form POST based authentication configuration for scanning as a user.
#  # Enabling will force the scanner to scan as an
#  # authenticated user of your app.
#  # Authenticated requests will pass cookies received from the form POST
#  # to maintain authentication.
  formAuth: # This app uses Form Based auth
#    # The route to a form POST to authenticate a user
    loginPath: /login.php # this is the login page
#    # The route to logout a user
    logoutPath: /logout.php # tell the scanner where logout happens.
#    # The username field name in your authentication form
    usernameField: username # here is the name of a field in the login form
#    # The password field name in your authentication form.
    passwordField: password # here is the name of a field in the login form
#    # A regex to match against http responses to determine if the scan user is
#    # still logged in to your app
    loggedInIndicator: "\\QLogout\\E" # the \\Q and \\E are important indicators, but this field also take standard regex
#    # A regex to match against http responses to determine if the scan user is
#    # logged out of your app
    loggedOutIndicator: "\\QloginInput\\E" #
#    # Other parameters that may be required by your log in form

#    # Other parameters that may be required by your log in form
    otherParams: # (optional)
      - name: Login  # The login form parameter is needed to make login work
        val: "Login"
#    # The username to authenticate as when scanning
    scanUsername: admin # DVWA default
#    # The password of the scanUsername
    scanPassword: password # DVWA default
hawk:
#  # Web crawler / spider configuration
  spider:
#    # Enable the base spider for discovering your app's routes
    base: true # (default)

Now we have a working config for DVWA and can effectively scan the app and get results from the scanner. All of the results of these scans should be viewable from the direct link printed at the end of the scan in the terminal. From there you should be able to browse each of the issue and find the request response pairs that made an alert trigger.

While the iteration to make this work was not difficult, you do need to understand how the application behaves and what things could be causing the scanner to not be able to do its job. Now we have a working config for DVWA and can effectively scan the app and get results from the scanner. While the iteration to make this work was not difficult, you do need to understand how the application behaves and what things could be causing the scanner to not be able to do its job. To test StackHawk scanning the Damn Vulnerable Web App or your own application, sign up for an account at stackhawk.com