StackHawk Scripting SDK

The StackHawk scanner, hawk, has a built-in Kotin scripting engine that enables developers to build authentication, session management, and even custom security test scripts. The HawkScript SDK adds built-in highlighting, comprehensive documentation, and code-completion, plus developers can integrate the SDK with their projects and preferred AI helper to make the coding job faster and easier.

StackHawk recommends using the IntelliJ IDEA Community Edition IDE to develop HawkScripts. The IDE can be obtained from the JetBrains IDEA Download page. Once installed and running, developers can apply the HawkScript SDK to scripting folders in their projects for a smooth HawkScripting experience.

Disable K2 Mode in IntelliJ

Start IntelliJ IDEA. The latest versions of IntelliJ have a setting to enhance typical Kotlin development that breaks the use of external Kotlin SDKs. To use the HawkScan Scripting SDK, the first step is to turn off the K2 setting. Navigate to IntelliJ IDEA --> Settings --> Languages & Frameworks --> Kotlin. The top checkbox on the default Kotlin settings page is Enable K2 mode. Uncheck the box, and restart IntelliJ.

Applying HawkScript SDK with Gradle

First, clone the JavaSpringVulny repo. It has a Gradle build script that assists in applying the SDK in IntelliJ IDEA.

git@github.com:kaakaww/javaspringvulny.git

or navigate to https://github.com/kaakaww/javaspringvulny and use one of the alternative clone options.

Open a shell in the root of the javaspringvulny repository and run…

./gradlew :hawkscripts:download

This will download the latest version of the hawkscripting sdk zip into the `hawkscripts/build` directory as required by the dependencies defined in hawkscripts/hawkscripts.gradle.kts.
[hawkscripts.gradle.kts](hawkscripts.gradle.kts).

Be sure to disable K2 mode (see above). When IntelliJ has restarted, open Javaspringvulny as a new gradle project by:

1. Navigating to File --> New --> Project from Existing Sources.
2. When the file browser opens, select the newly cloned JavaSpringVulny repository.
3. On the Import Project screen that follows, select Import project from external model and select Gradle.

**Wait for the indexer!**
Depending on the speed of the development machine, this may take 5+ minutes. The indexer progress can be observed in the lower right status bar.

When indexing is complete open any of the `.kts` files in the
defined source directories under hawkscripts/: authentication, session, httpsender, active, proxy to see activated code highlighting, auto-completion, and inline compilation errors.

Use hawk perch and hawk validate auth --watch from the Hawk CLI to
develop and test authentication and session scripts against running web API’s.

Applying HawkScript SDK with the UI

Alternatively, developers can apply the HawkScript SDK to their software projects from the UI in IntelliJ IDEA.

First, manually download the HawkScript SDK from the StackHawk Downloads Page. Unzip hawkscript-sdk.zip into a directory, hawkscript-sdk.

Open an existing project in IDEA to develop HawkScripts, or create a new project in IDEA. Be sure to disable K2 mode as shown above.

Within the project base directory, create a HawkScript base directory, e.g. hawkscripts. Under hawkscripts, create a set of script directories named for the types of scripts to create, e.g. authentication, active, httpsender, or session scripts.

mywebapp/
  stackhawk.yml
  hawkscripts/
    active/
      my-active.kts
    authentication/
      my-auth.kts
    httpsender/
      my-httpsender.kts
    session/
      my-session.kts

In IDEA, select File → Project Structure to open the Project Structure dialog, where the HawkScript SDK can be applied to the hawkscript folder.

Next, in the Project Structure dialog,

• Select Modules in the left pane
• Select the name of the web application’s default module in the middle pane, e.g
• Select the Dependencies tab in the right pane
• Select the + button and select JARs or Directories under Module SDK.

From the file selector, find the unzipped HawkScript SDK directory, e.g. hawkscript-sdk

With the hawkscript-sdk dependency added to the list, hit Apply.

Finally, mark the hawkscripts directory as a Source in the Source tab of the right pane of the Project Structure dialog, and hit Apply.

HawkScript SDK code completion is now enabled for the hawkscripts folder!

Using the SDK in IntelliJ

JetBrains provides a lot of great documentation for learning IntelliJ. See here: https://www.jetbrains.com/help/idea/getting-started.html and here: https://www.jetbrains.com/help/idea/mastering-keyboard-shortcuts.html.

For exploring the hawkscripting SDK, consider using Double Shift or Command-O to open the search, allowing developers to search for classes, files, symbols in the SDK as well as across the project, and leverage this documentation to learn more about some of the Key Objects and Helpers available in different script types.