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.
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:
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.
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.
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.
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).