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, which installs the hawk CLI and runs a scan
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 install and run HawkScan. An example is provided below.

language: shell
# Optional: pin a version (6.0.0 or later). Leave it unset to install the latest release.
# env:
#   global:
#     - HAWK_INSTALL_VERSION=6.6.0
install:
  - curl -fsSL https://download.stackhawk.com/hawk/install.sh | sh
  - export PATH="$HOME/.hawk/bin:$PATH"
script:
  - hawk --api-key="${HAWK_API_KEY}" --no-color scan

This configuration installs the hawk CLI with the hawk CLI install script, which downloads the latest HawkScan release and checks its checksum. The script doesn’t change the PATH, so the next line adds its install directory, ~/.hawk/bin. Travis CI runs the install and script phases in the same shell, so the script phase can then run the scan. The StackHawk API key is injected from the secure environment variable, HAWK_API_KEY. The --no-color flag suppresses colorized text so that HawkScan’s output is more readable in the Travis CI console.

Docker Alternative

If you’d rather run HawkScan as a Docker container, use this .travis.yml instead:

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

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.

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. Because the hawk CLI runs directly on the build VM, it can reach the localhost address with no extra network configuration.

For our example app, we will launch an Nginx container listening on port 80. Then we will scan it at the localhost address. 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 Travis CI workflow.

language: shell
services:
  - docker
before_install:
  - docker run --detach --publish 80:80 nginx
install:
  - curl -fsSL https://download.stackhawk.com/hawk/install.sh | sh
  - export PATH="$HOME/.hawk/bin:$PATH"
script:
  - hawk --api-key="${HAWK_API_KEY}" --no-color scan

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

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

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

If you run HawkScan as a Docker container instead, add the --network host flag to the docker run command so the container can reach the host’s localhost address:

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

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

Docker Compose

Another way to test your app is to run it, and any services it needs, in Docker Compose. Docker Compose allows you to define a set of containers that can address one another by name using a declarative YAML configuration. Publish your app’s port on the build host, and scan it there with the hawk CLI.

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

version: "3.2"
services:
  # Fire up the app to test, nginx_test
  nginx_test:
    image: nginx
    ports:
      - 80:80

In the Travis CI configuration, we start Docker Compose in the background before installing and running HawkScan.

language: shell
services:
  - docker
before_install:
  - docker-compose up --detach
install:
  - curl -fsSL https://download.stackhawk.com/hawk/install.sh | sh
  - export PATH="$HOME/.hawk/bin:$PATH"
script:
  - hawk --api-key="${HAWK_API_KEY}" --no-color scan

Point the HawkScan configuration at the published port, as in the Localhost example, http://127.0.0.1.

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.

Docker Compose Alternative

You can also run HawkScan itself as a Docker Compose service on the same bridge network as your app, and scan the app by its service name. Use this 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, run docker-compose in place of the install and scan commands:

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.

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