Best Practices

HawkScan is designed for developers and IT professionals who want to continually run security tests against their applications. To run HawkScan in a scalable and safe fashion, we recommend the following:

1. Configuration as Code
2. Pre-Production Scanning
   1. Local Development Scans
   2. Pipeline Scans
   3. Seed / Fixture Database
3. Production Scanning

Configuration as Code

The scanner configuration should be managed through your organization’s source control flows. This ensures that the configuration lives with the application itself, can be updated by developers who know the most about the application, and improves security procedures. HawkScan configuration is managed by the stackhawk.yml file in your application’s working directory. For more information, see the Configuration guide.

A few specific best practices in terms of configuration instrumentation are included below:

• Commit the stackhawk.yml configuration to your source control repository with your application code.
• Employ Environment Variable Runtime Overrides in your stackhawk.yml configuration wherever appropriate.
• If you have multiple application hosts to scan across different environments, you should create separate YAML configuration files and pass the appropriate configuration in as a parameter to the HawkScan Docker command.
• If your application uses an OpenAPI v2 spec file, HawkScan can leverage that by specifying the parameters under app.openApiConf in the stackhawk.yml. HawkScan will use the OpenAPI file to deliver an improved scanning experience by pre-seeding the sitemap with the routes defined in the spec file. See the OpenAPI Configuration Page for more details.
• If your application is a SOAP API, HawkScan can more efficiently and effectively generate payloads when provided a WSDL endpoint or Schema Definition file. See the SOAP API Configuration Page for more details.

Pre-Production Scanning

Local Development Scans

Run HawkScan in your development environment before merging changes into your build pipeline. Development environments are typically more conducive to tinkering. Making changes earlier in development ensures you are able to address any found vulnerabilities prior to the build process.

Ideal configuration for local development scans may include the use of Environment Variable Runtime Overrides and proper instrumentation of your seed database.

Pipeline Scans

HawkScan can be instrumented to run as part of the build pipeline. We have provided documentation for all of the different Continuous Integration providers that we support.

As with local scans, we recommend the use of Environment Variable Runtime Overrides and proper instrumentation of your seed database.

Seed / Fixture Database

To get the best results from HawkScan running in your development or CI/CD environment, we recommend running your application with a seed or fixture database, similar to what you might do for integration or end-to-end testing. This way you can measure if serious security vulnerabilities are found, as well as if other unwanted input/data is being allowed in by your application.

When instrumenting a seed database it is important to think about the width of the data vs. the depth. For example, if your application has a user posts feature that allows users to post arbitrary text that other users can see in your app, you should add a few users and posts to your seed database so the scanner can test all the routes involved in those features (width). However it is not recommend that you add hundreds of posts or users. This will cause HawkScan to re-check the same functional path in your application unnecessarily (depth).

For more information on seed databases, see Migrations and Seed Data (Ruby on Rails) or
Database Seeding (PHP).

Production Scanning

HawkScan performs active penetration testing of all inputs, resulting in data being inserted into your database. While we offer “Production-Safe” scan policies, you are responsible for ensuring the appropriateness and safety of your scan targets. StackHawk is not liable for damages or outages that may occur while scanning in production.