Login Start Free Trial Login Start Free Trial
 

HawkScan Scripting

HawkScan Scripting

HawkScan Scripting Overview

What is HawkScan Scripting?

HawkScan Test Engine (HSTE) scripting allows StackHawk users to add extreme customization to their HawkScan test cycles. This can include custom authentication and session management, custom business logic checks which may not be included in the default ruleset, and even include granular manipulation of every single HTTP message emitted from the test engine, e.g. for AWS signing or similar.

Each of the supported script types implements a type-specific Java interface contract, which requires certain functions to be defined. Scripts can be written with Kotlin syntax, while also allowing direct call of Java and Kotlin classes and functions from the HawkScript SDK. As an extension of the JSR223 standard Java scripting interface, these scripts provide powerful customization capabilities with the safety and performance of the JVM.

In addition to templates, the hawkscan-examples repository contains many full-fledged scripts that can be used as-is, customized for similar purposes, or simply referenced for usage examples of logic and imports. StackHawk will continue to add to this collection over time.

Why Kotlin?

Imagine that Java and Python fell in love and had a baby… and JetBrains named it Kotlin.

  • Popularity: Not a great metric for language quality, but good for ballparking future job opportunities. Millions of coders now use Kotlin as one of their top 3 languages.
  • Java Interops: Kotlin is fully interoperable with the Java JVM and existing libraries, so it’s inherently cross-platform, type-safe, and compiles/executes as fast as Java. Plus one can seamlessly re-use existing Java libraries with an improved, simplified syntax.
  • Language Features: Kotlin is designed to implement much of the language conciseness and multi-modal features–object-oriented and functional programming–of Python and Scala without compromising type safety or speed.
  • Versatility: Since 2019, Kotlin is the preferred language for Android development and also supported on iOS since 2020. Kotlin is Turing-complete and has been used for Back-end/Server-side Web, Full-stack, and Data Science applications.
  • Community: There’s a large and growing community around Kotlin and many available purpose-built libraries.

Note: Python scripting support is not provided in HSTE because the Jython wrapper/bridge between Python and Java, which allows Python to act as a JSR223 compatible scripting language, only supports Python 2.

Script Types Overview

HawkScan supports five script types, each enabling different customization capabilities. Each of these types has an extensive page of documentation under the Script Types nav.

Configuration Pattern

All scripts are configured in the hawkAddOn section of your stackhawk.yml file. Each script type uses a consistent configuration pattern with:

  • name: Script filename
  • type: Script category (authentication, session, httpsender, active, passive)
  • path: Parent directory only - type subdirectory is added automatically (e.g., "hawkscripts" not "hawkscripts/authentication")
  • language: KOTLIN
  • id: Plugin ID - required for active and passive scripts only (obtained via hawk register plugin)
  • vars: Optional script-specific variables

Key Configuration Differences:

  • Authentication & Session scripts: Require dual configuration (app.authentication.script + hawkAddOn.scripts[])
  • HTTP Sender scripts: Single configuration (hawkAddOn only, no plugin ID)
  • Active & Passive scripts: Single configuration (hawkAddOn only) + required plugin registration (id field)

Path Construction: Full script path = {path}/{type}/{name}

  • Example: path: "hawkscripts" + type: "authentication" + name: "my-auth.kts" → hawkscripts/authentication/my-auth.kts

For complete configuration examples and patterns, see the detailed documentation for your specific script type.

Reference Documentation

  1. Core Reference Documentation

Essential references for script development:

  • SDK setup and IntelliJ integration description coming soon
  • key_objects_scripting.html - Core classes, methods, and utilities reference
  1. SDK API Documentation

The HawkScript SDK API documentation contains Dokka-generated API reference for all classes and methods available in the HawkScript SDK. This provides detailed API references for all packages, classes, and methods used in script development.

  1. External Documentation
  2. Community and Support

For questions, issues, or contributions:

  • Review existing documentation for your use case
  • Check hawkscan-examples for similar implementations
  • Consult the SDK API documentation in the hawkscript-docs repository
  • Reach out to the HawkScan team for complex scenarios

Version Information:

  • Documentation Version: Latest
  • SDK Version: 4.7.1
  • Supported Languages: Kotlin