HawkScan Scripting Documentation

Comprehensive documentation for creating custom security scanning extensions with HawkScan's Kotlin-based scripting framework.

Overview

This repository provides complete documentation for developing HawkScan scripts across five categories: Authentication, Session Management, HTTP Sender, Active Scanning, and Passive Scanning. It serves as both a reference for published documentation and a contextual workspace for script development.

Repository Structure

scripting-docs/
├── README.md                           # This file
├── CLAUDE.md                          # AI assistant context for script development
├── docs/                               # Published documentation (synced to hawkdocs)
│   ├── index.md                        # Documentation index
│   ├── key_objects_scripting.md        # Core classes, methods, and utilities reference
│   ├── quick_start_guide.md            # Quick start guide
│   ├── working_with_sdk_scripting.md   # SDK setup and development environment
│   └── script-types/                   # Script type documentation
│       ├── index.md                    # Script types index
│       ├── authentication_scripting.md # Authentication script documentation
│       ├── session_scripting.md        # Session management script documentation
│       ├── httpsender_scripting.md     # HTTP sender script documentation
│       ├── active_scripting.md         # Active scanning script documentation
│       └── passive_scripting.md        # Passive scanning script documentation
└── hawkscript-sdk-4.7.1/              # Dokka-generated API documentation
    └── -hawk-script-s-d-k/             # Complete SDK API reference

Documentation Files

Getting Started

• index.md - Documentation index and overview
• working_with_sdk_scripting.md - SDK setup, IntelliJ integration, and development environment configuration
• quick_start_guide.md - Quick start guide for script development

Core Reference

• key_objects_scripting.md - Complete reference for:
  • Core HTTP classes (HttpMessage, HttpRequestHeader, HttpResponseHeader, etc.)
  • Script helper objects (AuthenticationHelper, SessionWrapper, ScriptsActiveScanner, etc.)
  • High-value utility imports (Jackson, Nimbus JWT, Apache Commons, etc.)
  • Essential imports organized by script type
  • Links to Dokka API documentation

Script Type Documentation

Each script type has comprehensive documentation with:

• Usage overview and scenarios
• Simple template examples
• Advanced real-world examples
• Function signatures and parameters
• Configuration examples
• Common patterns and best practices
• Troubleshooting guidance
• Testing workflows

authentication_scripting.md

Custom authentication mechanisms including form-based auth, OAuth flows, API key authentication, and multi-step processes.

Core Functions: authenticate(), getRequiredParamsNames(), getCredentialsParamsNames()

Example Use Cases:

• Form authentication with CSRF tokens
• OAuth 2.0 client credentials flow
• External command authentication
• Multi-factor authentication

session_scripting.md

Session token management, JWT processing, and session lifecycle handling.

Core Functions: extractWebSession(), processMessageToMatchSession(), clearWebSessionIdentifiers()

Example Use Cases:

• JWT token extraction and header injection
• Token expiration detection and re-authentication
• External command session management
• Multi-token management (headers + cookies)

httpsender_scripting.md

HTTP request/response interception and modification.

Core Functions: sendingRequest(), responseReceived()

Example Use Cases:

• Custom header injection (e.g., AWS SigV4 signing)
• Request/response logging for debugging
• Dynamic behavior based on responses
• Rate limiting and request throttling

active_scripting.md

Custom vulnerability detection rules that actively test endpoints.

Core Functions: scan(), scanNode()

Example Use Cases:

• Parameter fuzzing with dynamic payloads
• Multi-tenancy violation detection
• Custom injection pattern testing
• Business logic vulnerability testing

passive_scripting.md

Pattern-based analysis of HTTP traffic without sending additional requests.

Core Functions: scan(), appliesToHistoryType()

Example Use Cases:

• Sensitive data detection (PII, API keys, credentials)
• Security header validation (CSP, HSTS, CORS)
• Compliance checking (PCI DSS, HIPAA)
• Hardcoded secret detection in JavaScript

SDK Documentation

The hawkscript-sdk-4.7.1/ directory contains Dokka-generated API documentation for all classes and methods available in the HawkScript SDK.

Key Package Documentation:

• com.stackhawk.hste.authentication - Authentication classes and helpers
• com.stackhawk.hste.session - Session management classes
• com.stackhawk.hste.extension.script - Script helper classes
• com.stackhawk.hste.network - Network and HTTP utilities
• org.parosproxy.paros.network - Core HTTP message classes

Quick Start

1. Review Getting Started Documentation

Start with docs/index.md or docs/quick_start_guide.md to understand the scripting framework and available script types.

2. Set Up Your Development Environment

Follow docs/working_with_sdk_scripting.md to:

• Download the HawkScript SDK
• Configure IntelliJ IDEA for script development
• Set up syntax highlighting and auto-completion

3. Choose Your Script Type

Review the documentation for your specific use case:

• Custom authentication? → authentication_scripting.md
• Session/token management? → session_scripting.md
• Request/response modification? → httpsender_scripting.md
• Custom vulnerability detection? → active_scripting.md
• Traffic pattern analysis? → passive_scripting.md

4. Reference Core Objects

Use key_objects_scripting.md as your primary reference for:

• HTTP message manipulation
• Helper object methods
• Utility class usage
• Common import patterns

5. Leverage Examples

All documentation includes:

• Simple template examples to get started
• Advanced real-world examples from production use cases
• Links to hawkscan-examples repository

Development Workflow

Basic Script Development Process

1. Start with a template from the relevant script type documentation
2. Add required imports from key_objects_scripting.md
3. Implement required functions with your custom logic
4. Test incrementally using hawk perch or hawk validate
5. Add comprehensive logging for debugging
6. Configure in stackhawk.yml using the hawkAddOn section
7. Run a limited scan to validate behavior
8. Review logs and iterate as needed

Testing Commands

# Interactive development and testing
hawk perch --config stackhawk.yml

# Validate authentication scripts
hawk validate auth --config stackhawk.yml --watch

# Run limited scan for testing
hawk scan --config stackhawk.yml --spider-max 5

# Review script logs
tail -f hawkscan.log | grep "your-script-name"

Configuration Example

All scripts are configured in the hawkAddOn section of stackhawk.yml:

hawkAddOn:
  scripts:
    # Authentication script (also requires app.authentication.script configuration)
    - name: "custom-auth.kts"
      type: authentication
      path: "hawkscripts"          # Parent directory only - type subdirectory automatic
      language: KOTLIN

    # Session management script (also requires app.authentication.sessionScript configuration)
    - name: "jwt-session.kts"
      type: session
      path: "hawkscripts"          # Parent directory only
      language: KOTLIN

    # HTTP sender script (single configuration - no dual config)
    - name: "custom-headers.kts"
      type: httpsender
      path: "hawkscripts"          # Parent directory only
      language: KOTLIN
      vars:
        - name: custom_header
          val: "X-API-Version"
        - name: custom_value
          val: "v2"

    # Active scanning script (requires plugin registration)
    - name: "fuzzer.kts"
      id: 1000014                  # REQUIRED - from hawk register plugin
      type: active
      path: "hawkscripts"          # Parent directory only
      language: KOTLIN
      vars:
        - name: iterations
          val: "10"
        - name: stringStartLength
          val: "1"
        - name: stringEndLength
          val: "100"

    # Passive scanning script (requires plugin registration)
    - name: "sensitive-data.kts"
      id: 1000015                  # REQUIRED - from hawk register plugin
      type: passive
      path: "hawkscripts"          # Parent directory only
      language: KOTLIN
      vars:
        - name: check_emails
          val: "true"
        - name: check_ssn
          val: "false"

Authentication and Session Scripts Dual Configuration:

app:
  authentication:
    script:
      name: "custom-auth.kts"      # Must match hawkAddOn name
      parameters:
        loginPagePath: "/login"
        loginPath: "/api/v1/authenticate"
      credentials:
        username: "${USERNAME}"
        password: "${PASSWORD}"
    sessionScript:                 # Nested under authentication
      name: "jwt-session.kts"      # Must match hawkAddOn name
      parameters:
        jwt_token_field: "access_token"
        token_type_field: "Bearer"

Common Development Patterns

Pattern 1: JSON Response Parsing (Authentication/Session)

import com.fasterxml.jackson.databind.ObjectMapper
import com.fasterxml.jackson.databind.node.ObjectNode

val mapper = ObjectMapper()
val jsonObject = mapper.readValue(responseBody, ObjectNode::class.java)
val accessToken = jsonObject.get("access_token").asText()

Pattern 2: JWT Token Management (Session)

import com.nimbusds.jwt.SignedJWT

val jwt = SignedJWT.parse(tokenString)
val expiresAt = jwt.jwtClaimsSet.expirationTime.time
val isExpired = System.currentTimeMillis() > expiresAt

Pattern 3: Header Injection (HttpSender)

fun sendingRequest(msg: HttpMessage, initiator: Int, helper: HttpSenderScriptHelper) {
    msg.requestHeader.setHeader("Authorization", "Bearer $token")
    msg.requestHeader.setHeader("X-Custom-Header", "value")
}

Pattern 4: Parameter Fuzzing (Active)

import com.github.javafaker.Faker

val faker = Faker()
val fuzzedValue = faker.lorem().characters(10, 100)
activeScanner.setParam(msg, param, fuzzedValue)
activeScanner.sendAndReceive(msg, false, false)

if (msg.responseHeader.statusCode >= 500) {
    raiseAlert(activeScanner, msg, evidence, param, fuzzedValue)
}

Pattern 5: Regex Pattern Matching (Passive)

val emailPattern = Regex("[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}")
val body = msg.responseBody.toString()

if (emailPattern.containsMatchIn(body)) {
    val matches = emailPattern.findAll(body)
    raiseAlert(ps, msg, matches.first().value)
}

Troubleshooting

Common Issues

Script not being called:

• Verify script type matches configuration (type: authentication, etc.)
• Check file path is correct relative to project root
• Look for compilation errors in hawkscan.log
• Ensure required functions are defined

Variables not accessible:

• Verify variable names match exactly between script and config
• Check hawkAddOn.scripts.vars section in stackhawk.yml
• Use ScriptVars.getScriptVar("script-name.kts", "var_name")

Authentication failures:

• Add debug logging to see request/response details
• Use hawk validate auth to test authentication in isolation
• Check logged-in/logged-out indicator patterns
• Verify credentials and parameters

Performance issues:

• Minimize complex operations in high-frequency functions
• Filter unwanted content types early in passive scripts
• Use initiator filtering in httpsender scripts
• Cache expensive operations outside function scope

Additional Resources

External Documentation

• HawkScan Official Documentation
• HawkScan Examples Repository
• HawkScan Scripting Examples

Related Repositories

• hawkscan-examples - Complete collection of working script examples
• HawkScan Core - Main scanner framework and CLI
• HSTE - HawkScan Test Engine components

Contributing

This documentation is maintained to support HawkScan script developers. For questions, issues, or contributions:

1. Review existing documentation for your use case
2. Check hawkscan-examples for similar implementations
3. Consult the SDK API documentation in hawkscript-sdk-4.7.1/
4. Reach out to the HawkScan team for complex scenarios

Version Information

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

---

Note: This documentation repository is designed to work seamlessly with AI assistants (Claude, etc.) through the included CLAUDE.md context file, enabling rapid script development with comprehensive contextual understanding.