Best Practices

Recommended instrumentation of your application for continuous scanning.

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

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 app.api: "./path/to/openapi.json" field in the stackhawk.yaml. 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.

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. Features to further support this functionality will be released soon, including integrations with popular CI tooling.

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 and 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

At this point, it is not recommended to scan your production application with HawkScan. HawkScan performs active penetration testing of all inputs, resulting in data being inserted into your database.

Functionality to support production scanning is coming soon.