Login Start Free Trial Login Start Free Trial
 

HawkScan and Travis CI

It’s easy to integrate StackHawk into your pipeline with Travis CI. The basic steps are:

  1. Secure your API key as an environment variable in your Travis CI Project
  2. Configure your Travis CI job by adding or editing the .travis.yml file in your project repository
  3. Configure HawkScan with a stackhawk.yml file

We will first describe the simple scenario of scanning a publicly available example app, example.com. Then under Local Scanning, we will show you how to run and test your app all within the self-contained Travis CI build environment.

Secure Your API Key

When you signed up on StackHawk, you created an API key. To keep it a secret, copy it to the Environment Variables for your project. In the Travis CI web app, find your repository, and select More options –> Settings. From here, find the Environment Variables section. Add your StackHawk API key as a variable called HAWK_API_KEY.

Configure Your Travis CI Job

At the base directory of your code repository, add a .travis.yml file to configure Travis CI to run HawkScan. An example is provided below.

.travis.yml

language: shell
services:
  - docker
script:
  - >
    docker run -v $(pwd):/hawk:rw -t
    -e API_KEY="${HAWK_API_KEY}"
    -e NO_COLOR=true
    stackhawk/hawkscan

This configuration tells Travis CI to run a single script, which runs HawkScan as a Docker container. The StackHawk API key injected from the secure environment variable, HAWK_API_KEY. The NO_COLOR environment variable suppresses colorized text so that HawkScan’s output is more readable in the Travis CI console.

Configure HawkScan

At the base directory of your code repository, create a stackhawk.yml appropriate for scanning your application. For our example, we will create a minimal config pointing to our Development environment API endpoint.

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  host: http://example.com
  env: Development

Replace the host entry with your test endpoint, and replace applicationId with your App ID from StackHawk.

Run It

Check those two files into source control, and head over to the Travis CI console to watch your job run. When your job is complete, check your account at StackHawk to review your scan details!

Local Scanning

The previous example assumes that you have an integration environment that is publicly accessible. Alternatively, you can run your app and scan it directly on the ephemeral Travis CI build host. Here are two common ways of doing that.

Localhost

One way to test an app after building it is to launch it directly on the build environment VM, and scan it on the localhost address. You can launch the HawkScan container with the flag --network host to give it access to localhost, and set app.host in stackhawk.yml to http://127.0.0.1.

For our example app, we will launch an Nginx container listening on port 80. Then we will scan it at the localhost address with HawkScan running in host networking mode. This method works with any app you wish to scan, containerized or not, as long as it is listening on the localhost address.

Here’s our modified GitHub workflow.

.travis.yml

language: shell
services:
  - docker
before_install:
  - docker run --detach --publish 80:80 nginx
script: 
  - >
    docker run -v $(pwd):/hawk:rw -t --network host
    -e API_KEY="${HAWK_API_KEY}"
    -e NO_COLOR=true
    stackhawk/hawkscan

Notice the --network host flag appended to the HawkScan docker run command. This gives HawkScan direct access to the host’s network stack, including the localhost address. This is what allows it to reach Nginx running on the localhost.

Finally, here’s our modified HawkScan configuration pointing to the localhost address, 127.0.0.1.

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  host: http://127.0.0.1
  env: Development

Pro Tip: avoid using localhost, because that name won’t resolve in Docker containers running on a Linux host. Instead, use 127.0.0.1.

When you run this job, it will launch Nginx, scan it with HawkScan, and post the results to your StackHawk scan list.

Docker Compose

Another way to test your app is to run it in a container and scan it on a Docker bridge network. You can do this with docker run commands, but we will be using Docker Compose for simplicity and flexibility. Docker Compose allows you to define a set of containers that can address one another by name using a declarative YAML configuration.

First we add a Docker Compose configuration file, docker-compose.yml, to the root of our repository.

docker-compose.yml

version: "3.2"
services:
  # Fire up the app to test, nginx_test
  nginx_test:
    image: nginx
    networks:
      - scan_net
  # Fire up hawkscan to scan the test app (nginx_test)
  hawkscan:
    image: stackhawk/hawkscan
    environment:
      API_KEY: "${HAWK_API_KEY}"
    volumes:
      - type: bind
        source: .
        target: /hawk
    tty: true
    networks:
      - scan_net
    depends_on:
      - nginx_test
# Make the scan_net network to run hawkscan against the app
networks:
  scan_net:

This configuration creates 2 containers (a.k.a. services) named nginx_test and hawkscan running on the bridge network scan_net.

In the Travis CI configuration, we replace the docker script with docker-compose, which reads docker-compose.yml by default for its configuration. And since Nginx is represented in Docker Compose, we can remove it from the before_install section.

.travis.yml

language: shell
services:
  - docker
script: 
  - docker-compose up --abort-on-container-exit

The flag, --abort-on-container-exit, tells Docker Compose to tear down all of the containers as soon as any one of them exits. This will stop all containers once the HawkScan container is finished. Without this flag, the nginx_test container would continue running, and the job would hang until the build timeout was reached.

Finally, update the HawkScan configuration to point to your test app, http://nginx_test.

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  host: http://nginx_test
  env: Development

Check it in and watch your build in Travis CI. Then head over to StackHawk to view your scan results.

With this approach you can build sophisticated arrangements of Docker containers, adding databases and other services as needed to create realistic test environments.