OpenAPI Specification Generation

This feature is available on the StackHawk Enterprise plan.

After API discovery has completed, StackHawk can then follow-on with a detailed analysis and automated generation of OpenAPI Specifications for found APIs within applicable code repositories. Generated specs can be reviewed as part of repository analysis, or used in HawkScan as part of OpenAPI Configuration.

This is an additional feature that can be separately disabled from other API Discovery features.

Using OpenAPI Spec File from OpenAPI Spec Gen

When API Discovery is enabled, StackHawk generates OpenAPI Specifications (OAS) for detected APIs. An OpenAPI spec is a machine-readable definition of an API’s endpoints, request/response formats, and parameters. By scanning against this spec, HawkScan knows exactly what to test—leading to more complete coverage and fewer blind spots.

The repository must be mapped to an application in StackHawk to use its generated spec in a scan.

From Attack Surface

Click the OAS pill in the Attack Surface table to open the slideout.

generated oas attack surface pills

From there, use the dropdown to select a generated spec, review endpoints, search, or filter by verb.

generated oas attack surface

From Application Details

Go to the OAS tab to see all specs for the app. Each entry shows the repo, path, and a hawk:// URI. Click a spec to open its slideout.

Download the file or copy the hawk:// URI. Add it to your stackhawk.yaml under openApiConf.filePaths to use it in scans:

app:
  openApiConf:
    filePaths:
      - hawk://<oas-id>

generated-oas-application-details

On the Scan Details Panel

An OAS pill in the Scans table means the scan used a StackHawk-generated OpenAPI spec. Opening the scan shows the Scan Details panel with Generated Open API Spec, confirming the generated definition was used for broader, more accurate coverage.

generated-oas-scan-details

Applicable Code Repositories

Code Repositories that have been processed in the attack surface will be analyzed for possible OAS generation, if it meets a supported language/framework pair. Currently supported repositories include those written in:

Java with the https://spring.io/ framework.
Javascript with the ExpressJS framework.
Scala with the Play Framework is coming soon.
C# with the ASP.Net Core Framework is coming soon.
Python with the Flask Framework is coming soon.

Code repositories will be reanalyzed weekly, and after API discovery processing if spec generation is enabled for the organization.

Disabling OpenAPI Specification Generation

OpenAPI specification generation additionally requires exposing repository source code to (LLM) inputs. This may be unappealing to some businesses, so this functionality can be optionally disabled by going to Settings -> Org Settings -> HawkAI under OpenAPI Spec Gen.

Disabling this feature will stop automatic spec generation, requiring manual specification management and potentially reducing attack surface coverage.