As a Product Manager here at StackHawk, I work closely with many of our largest customers so I understand the need to scale the HawkScan vulnerability scanner across multiple applications while maintaining a consistent and easy-to-manage setup. In this article, I'll guide you through effectively utilizing YAML configuration files and environment variables with HawkScan, allowing you to efficiently scale StackHawk across many applications.
Table of Contents
Getting Started with HawkScan
At its core, HawkScan is StackHawk's dynamic application security testing (DAST) solution that scans web applications for vulnerabilities. It is designed to be easily integrated into development workflows and CI/CD pipelines. HawkScan offers a powerful and flexible configuration system using YAML files and environment variables, enabling users to customize their scans and adapt them to various environments.
If you haven't already, please refer to our Quick Start Guide to install and setup HawkScan in your local environment.
Configuring HawkScan
HawkScan utilizes a YAML configuration file, typically named stackhawk.yml, to define scan settings, target applications, and authentication details. The configuration file is organized hierarchically using indentation, making it easy to read and modify. Here's an example of a basic stackhawk.yml file:
app:
applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
env: Development
host: http://localhost:8080
It is recommended you keep your stackhawk.yml configuration file at the root-level of the code-base for each application so it is available to the team working on it and can be effortlessly integrated into your CI/CD pipeline.
Incorporating Environment Variables
To make your HawkScan configuration more flexible, environment variables can be integrated into the stackhawk.yml file. This allows users to easily adapt the settings for different environments and store sensitive information securely. Environment variable substitution in HawkScan configuration files is denoted with curly braces, like ${ENV_VAR_NAME}.
Example: HawkScan Configuration with Environment Variables
Consider the following stackhawk.yml file with environment variables:
app:
applicationId: ${SH_APPLICATION_ID}
env: ${SH_ENVIRONMENT}
host: ${SH_APP_HOST}
In this example, the environment variables SH_APPLICATION_ID, SH_ENVIRONMENT, and SH_APP_HOST are used as placeholders. The actual values for these environment variables can be set in your local development environment or CI/CD pipeline. When HawkScan runs, it will automatically substitute the placeholders with the corresponding environment variable values.
Setting Default Values for Environment Variables
Default values can be specified for environment variables in YAML configuration files to ensure that your HawkScan setup continues to work seamlessly even when the environment variable is not set. To define a default value for an environment variable, use the following syntax: ${ENV_VAR_NAME:default_value}. If the environment variable is not set at the time HawkScan is run, the default value will be used.
Example: HawkScan Configuration with Default Values
Consider the following stackhawk.yml configuration file:
app:
applicationId: ${SH_APPLICATION_ID}
env: ${SH_ENVIRONMENT:Development}
host: ${SH_APP_HOST:http://localhost:9000}
In this example, the environment variables SH_ENVIRONMENT, and SH_APP_HOST have default values defined. This allows developers working locally to get up and running without modifying their local configuration file or defining multiple environment variables.
Best Practices for Configuring HawkScan
Use clear and descriptive names for environment variables related to HawkScan.
Consider adding a prefix like
SH_to your environment variables to ensure they don't conflict with others in your system.Take advantage of defaults to ensure required environment variables always have a value.
Keep sensitive information, such as API keys and authentication credentials, in environment variables to avoid exposure.
Ensure that required environment variables are set in the relevant environment or CI/CD pipeline.
Document the environment variables and their purposes in your project README or documentation.
Conclusion
StackHawk's HawkScan leverages the power of YAML configuration files, environment variables, and default values to provide a flexible, reusable, and maintainable configuration system for its vulnerability scanner. By following the guidelines and best practices outlined in this article, you can efficiently set up HawkScan to meet your application security testing needs across different environments and applications, effectively scaling StackHawk across your entire organization.
Next up, we'll learn about modularizing your HawkScan configuration using Overlays.