This article is part of a series on configuring HawkScan. Click here for the previous article: StackHawk Configuration Basics.
In this article, we'll explore how to extend your HawkScan configuration using overlays. As you deploy HawkScan across more applications, you may find common configuration elements that you'd like to share. We'll dive into what overlays are, how to use them in your HawkScan configuration, and best practices to follow.
Table of Contents
Introduction to Overlays
Overlays are a powerful way to extend and modify your base HawkScan YAML configuration with application-specific settings or environment adjustments. They are separate YAML files merged with the base configuration at scan time, allowing you to create modular configurations tailored to specific environments, applications, or use cases while keeping the base configuration intact.
How to Use Overlays with HawkScan
To use overlays, create separate YAML files with the settings you wish to apply. Create a subfolder called stackhawk-configs/ and place your overlays there. Your folder structure might look like this:
my_project/
│
├── stackhawk.yml
│
└── stackhawk-configs/
├── discovery_openapi.yml
Your base stackhawk.yml file will contain your core application configuration:
app:
applicationId: xxxxxxxx-XXXX-xxxx-XXXX-xxxxxxxxxxxx
env: ${SH_ENVIRONMENT:Development}
host: ${SH_APP_HOST:http://localhost:3000}
In this example, the application uses OpenAPI, so create the overlay file discovery_openapi.yml in stackhawk-configs/ with your standard OpenAPI configuration:
app:
openApiConf:
path: /openapi
customVariables:
- field: username
values:
- "testUser1"
To apply the overlay at scan time, execute HawkScan like this:
$ hawk scan \
stackhawk.yml \
stackhawk-configs/discovery_openapi.yml
This command will run HawkScan with a configuration that merges both the base stackhawk.yml file and the discovery_openapi.yml overlay, resulting in the following combined configuration:
app:
applicationId: xxxxxxxx-XXXX-xxxx-XXXX-xxxxxxxxxxxx
env: ${SH_ENVIRONMENT:Development}
host: ${SH_APP_HOST:http://localhost:3000}
openApiConf:
path: /openapi
customVariables:
- field: username
values:
- "testUser1"
Overlays give you the ability to modularize your configuration, so common elements can be shared across projects. You can extend this approach to authentication, custom scan discovery, custom test scripts, or any other configuration fitting your use case.
Using Multiple Overlays with HawkScan
Suppose you have an application that uses OpenAPI and requires specific authentication settings common to several other applications. You can create multiple overlays to handle these configurations. Your folder structure might look like this:
my_project/
│
├── stackhawk.yml
│
└── stackhawk-configs/
├── discovery_openapi.yml
├── discovery_grpc.yml
├── discovery_graphql.yml
├── auth_basic.yml
└── auth_oauth.yml
Your base stackhawk.yml would contain the core application configuration and your discovery_openapi.yml overlay contains the OpenAPI configuration as shown in the previous example.
Create an auth_basic.yml overlay for the basic authentication configuration:
app:
authentication:
loggedInIndicator: "\\QLog out\\E"
loggedOutIndicator: "\\QLog in\\E"
external:
type: TOKEN
value: ${SH_AUTH_TOKEN}
testPath:
path: /authenticated/path
success: '.*200.*'
To run HawkScan with multiple overlays, execute the following command:
hawk scan \
stackhawk.yml \
stackhawk-configs/discovery_openapi.yml \
stackhawk-configs/auth_basic.yml
This command will run HawkScan with a configuration that combines the base stackhawk.yml file and the specified overlays. The final configuration will include settings from the base file, OpenAPI discovery settings and authentication settings.
Using Overlays with HawkScan in CI/CD
To run a scan with HawkScan in a CI/CD environment using overlays, you'll need to modify your CI/CD pipeline configuration. In this example, we'll use GitHub Actions to run the scan.
If you haven't already, add the StackHawk HawkScan GitHub Action to your workflow YAML file:
jobs:
hawkscan:
name: HawkScan
runs-on: ubuntu-latest
steps:
- name: Clone repo
uses: actions/checkout@v2
- name: Run HawkScan
uses: stackhawk/hawkscan-action@v2
with:
apiKey: ${{ secrets.SH_API_KEY }}
Next, modify the 'Run HawkScan' step to include the base configuration file and overlay files:
- name: HawkScan
uses: stackhawk/hawkscan-action@v1
with:
apiKey: ${{ secrets.SH_API_KEY }}
configurationFiles: 'stackhawk.yml stackhawk-config/openapi.yml stackhawk-config/auth_basic.yml'
This configuration will execute HawkScan with the base stackhawk.yml configuration file and specified overlay files, merging them to create the final configuration.
Best Practices for Using Overlays
Keep overlays modular and focused: Create separate overlay files for specific configurations or environments to maintain modularity and make them easier to manage. For example, you might have overlays for OpenAPI, authentication, development, staging, and production environments.
Keep overlay files organized: Store overlay files in a dedicated folder, such as
stackhawk-configs/, to keep them organized and easily accessible.Use descriptive file names: Name overlay files to clearly indicate their purpose. This makes it easier for team members to understand and locate the appropriate overlay for a specific use case. For example, use names like
discovery_openapi.yml,auth_basic.yml, orauth_oauth.yml.Avoid duplication: When creating overlays, avoid duplicating settings that are already present in the base
stackhawk.ymlfile. Overlays should only include settings that need to be changed or added for a specific configuration.Use environment variables for sensitive data: Avoid storing sensitive information, such as API keys, in overlay files. Instead, use environment variables to reference this data securely.
Test overlay combinations: When using multiple overlays, test their combinations to ensure that they work as expected and do not cause any conflicts or unexpected behaviors.
Document overlay usage: Keep documentation up to date on how and when to use overlays in your project. This will help team members understand the purpose of each overlay and how to use them correctly.
Version control your overlay files: Track changes to overlay files in your version control system to maintain a history of updates and enable easy rollback if necessary.
Review and update overlays regularly: As your project evolves, it's important to review and update your overlays to ensure they remain relevant and effective. Regularly review your overlays to remove outdated settings and add new ones as needed.
Conclusion
In conclusion, overlays in HawkScan configuration provide a powerful and flexible solution to manage and scale your vulnerability scanning setup across multiple applications. By using overlays, you can create modular configurations that address specific environments, applications, or use cases while keeping your base configuration intact. By following the best practices outlined in this article, you can maintain a scalable, maintainable, and adaptable HawkScan configuration system that evolves with your application's needs. As a result, you'll be better equipped to protect your applications from security vulnerabilities and maintain a secure and robust software development environment.