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:
- Configuration as Code
- Pre-Production Scanning
- Production Scanning
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.ymlconfiguration to your source control repository with your application code.
- Employ Environment Variable Runtime Overrides in your
stackhawk.ymlconfiguration 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.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.
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. We have provided documentation for all of the different Continuous Integration providers that we support.
To get the best results from HawkScan running in your development or CI/CD environment, we recommend running your application with a
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).
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.