Login Start Free Trial Login Start Free Trial
 

Quick Start Guide

Step 1: Understand Script Types

Review the Script Types Overview above to identify which script type matches your use case. Each script type serves a specific purpose in the security scanning lifecycle.

Step 2: Set Up the HawkScript SDK

The HawkScript SDK provides a complete development environment for writing HawkScan scripts with full IDE support, including:

  • Type-safe APIs for all HawkScan scripting interfaces
  • IntelliJ IDEA integration with syntax highlighting, auto-completion, and inline error detection
  • Comprehensive class documentation via Dokka-generated API reference
  • Access to powerful libraries including Jackson (JSON), Nimbus JWT, Apache Commons, and more

Getting Started with the SDK:

  1. SDK setup and IntelliJ integration description coming soon
  2. Reference core objects and utilities: Key Objects and Utilities
  3. Explore the Dokka API documentation in the hawkscript-docs repository

Key SDK Packages:

Step 3: Choose Your Script Type and Follow the Detailed Guide

Once you’ve set up your development environment, navigate to the detailed documentation for your chosen script type:

Each guide includes:

  • Template examples to get started quickly
  • Advanced real-world examples from production use cases
  • Complete function signatures and parameters
  • Configuration examples for stackhawk.yml
  • Common patterns and best practices
  • Troubleshooting guidance
  • Testing workflows

Step 4: Test and Iterate

Use HawkScan’s testing tools to validate your scripts:

# 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"

AI-Assisted Script Development

The HawkScan scripting documentation repository is designed to accelerate script development through AI assistance.

Repository: https://github.com/kaakaww/hawkscript-docs

How It Works

The repository includes a comprehensive CLAUDE.md context file that provides AI assistants (like Claude, ChatGPT, or other LLMs) with complete knowledge of:

  • The entire HawkScan scripting framework across all five script types
  • Core classes, methods, and utilities with examples
  • Common development patterns and best practices
  • Configuration patterns and testing workflows
  • Links to all detailed documentation and API references

Getting Started with AI-Assisted Development

  1. Clone the repository to your local machine
  2. Open the repository in Claude Code, Cursor, or your preferred AI-enabled IDE
  3. Reference CLAUDE.md when asking your AI assistant to help write scripts
  4. Leverage contextual awareness - The AI will have full understanding of:
    • Available script types and their interfaces
    • Required function signatures
    • SDK classes and utilities
    • Working examples from the hawkscan-examples repository
    • Best practices and common patterns

Benefits

  • Faster Development: Reduce script development time from hours to minutes
  • Reduced Errors: AI assistance helps avoid common mistakes and follows best practices
  • Learning Accelerator: Understand the framework while building working scripts
  • Complete Context: No need to manually copy documentation - CLAUDE.md provides everything

Example Workflow 

# Clone the repository
git clone https://github.com/kaakaww/hawkscript-docs.git
cd hawkscripting-docs

# Open with Claude Code or your AI-enabled editor
claude-code .

# Ask your AI assistant (with CLAUDE.md context):
# "Create a JWT session management script that extracts tokens from JSON responses
# and handles expiration with automatic re-authentication"

The AI assistant will have complete context about session scripts, JWT handling, the SessionWrapper interface, required functions, and can generate production-ready code following established patterns.

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.html
  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

Common Development Patterns

HawkScan scripts commonly use several development patterns to accomplish their tasks. Each pattern is fully documented with code examples in the individual script type documentation:

JSON Response Parsing

Used in authentication and session scripts to extract tokens from API responses. See authentication_scripting.html and session_scripting.html for examples.

JWT Token Management

Common pattern for parsing JWT tokens, checking expiration, and handling renewal. See session_scripting.html for complete examples.

Header Injection

Used in HTTP sender scripts to add or modify headers dynamically. See httpsender_scripting.html for implementation patterns.

Parameter Fuzzing

Active scanning pattern for testing input validation and error handling. See active_scripting.html for fuzzing examples.

Regex Pattern Matching

Passive scanning pattern for detecting sensitive data and security issues. See passive_scripting.html for pattern matching examples.

For detailed code examples and implementation guidance, refer to the specific script type documentation linked above.