I’m thrilled to announce the release of Hac Hack, a comprehensive open-source solution for automating SAP Commerce/Hybris HAC (hybris Administration Console) operations. This project addresses a common challenge for developers and administrators who need to programmatically interact with HAC endpoints while maintaining security and managing VPN connectivity via Tunnelblick.

What is Hac Hack?

Hac Hack is a Python library combined with a FastAPI-based HTTP API that provides a secure, programmatic interface to Hybris HAC operations. Whether you need to run Groovy scripts or import impex data, Hac Hack offers a streamlined API that handles authentication and security for you.

The project emerged from the need to automate repetitive HAC tasks that are typically performed manually through the web interface. By providing a REST API wrapper around HAC functionality, it enables integration into CI/CD pipelines, monitoring systems, and custom automation workflows.

Key Features

Hac Hack comes packed with features designed to make HAC automation both powerful and secure:

Core Functionality

  • Authentication: Secure login to HAC with session management
  • Groovy Script Execution: Run custom Groovy scripts for advanced operations
  • Impex Script Execution: Execute Impex import operations as strings
  • Impex File Upload: Upload and import Impex files with optional file retention
  • VPN Tunnel Management: Built-in Tunnelblick VPN control for secure network access
  • Health Check: Simple root endpoint to verify API availability

Security Features

  • mTLS Authentication: Mutual TLS authentication for enhanced security
  • Certificate Management: Automatic generation and management of SSL certificates via included script
  • Environment Variable Configuration: Secure credential management through environment variables
  • Session Management: Secure session handling with proper cleanup

Integration Capabilities

  • REST API: Full FastAPI-based HTTP API with OpenAPI documentation
  • Python Library: Direct Python integration for custom applications
  • Tunnelblick VPN Support: Built-in VPN tunnel management via Tunnelblick for Mac
  • Flexible Configuration: Environment-based configuration for different deployment scenarios

Security Features

mTLS Authentication

One of the standout features of Hac Hack is its robust mutual TLS (mTLS) authentication system. This provides two-way authentication between the client and server, ensuring that both parties verify each other’s identity.

The mTLS implementation includes:

  • Certificate Generation Script: Included generate_certificates.zsh script creates SSL certificates
  • Certificate Validation: Proper validation of server certificates
  • Secure Key Management: Safe handling of private keys and certificates
  • Configurable TLS Settings: Flexible TLS configuration for different environments

Certificate Generation

The library provides a shell script for generating certificates:

# Run the certificate generation script
./generate_certificates.zsh

# This creates:
# - certs/ca/ca-cert.pem and ca-key.pem
# - certs/server/server-cert.pem and server-key.pem
# - certs/client/client-cert.pem and client-key.pem

Environment Variables

Hac Hack uses environment variables for secure configuration:

# Required configuration
HAC_URL=https://your-hac-instance.com/hac
HAC_USERNAME=your-username
HAC_PASSWORD=your-password

# Optional timeout configuration
HAC_TIMEOUT=60

# VPN configuration (optional, for Tunnelblick on Mac)
VPN_SCRIPT_PATH=tunnelblick.zsh
VPN_TIMEOUT=60

although my recommendation is to use a vault solution for sensitive information - I tend to use 1Password.

API Endpoints and Usage Examples

Hac Hack provides a comprehensive REST API with the following endpoints:

EndpointMethodDescriptionParameters
/GETHealth check / Root endpoint-
/loginPOSTLogin to HAChac_url, username, password
/execute_groovyPOSTExecute Groovy scriptshac_url, username, password, script
/import_impexPOSTImport Impex scriptshac_url, username, password, script
/import_impex_filePOSTUpload & import Impex filehac_url, username, password, file, retain
/vpnGETCheck VPN statusconnection
/vpnPUTControl VPN connectionconnection, action, timeout

API Usage Examples

Login to HAC

curl -X POST "https://localhost:8037/login" \
  -H "Content-Type: application/json" \
  -d '{
    "hac_url": "https://your-hybris-instance.com/hac",
    "username": "admin",
    "password": "your-password"
  }'

Execute Groovy Script

curl -X POST "https://localhost:8037/execute_groovy" \
  -H "Content-Type: application/json" \
  -d '{
    "hac_url": "https://your-hybris-instance.com/hac",
    "username": "admin",
    "password": "your-password",
    "script": "println \"Hello from Hac Hack!\"; return \"Success\""
  }'

Import Impex Script

curl -X POST "https://localhost:8037/import_impex" \
  -H "Content-Type: application/json" \
  -d '{
    "hac_url": "https://your-hybris-instance.com/hac",
    "username": "admin",
    "password": "your-password",
    "script": "INSERT_UPDATE Product;code[unique=true];name\n;test-product;Test Product"
  }'

Upload and Import Impex File

curl -X POST "https://localhost:8037/import_impex_file" \
  -F "hac_url=https://your-hybris-instance.com/hac" \
  -F "username=admin" \
  -F "password=your-password" \
  -F "file=@sample.impex" \
  -F "retain=false"

Installation and Setup

Prerequisites

Before installing Hac Hack, ensure you have:

  • Python 3.8 or higher
  • Access to a SAP Commerce/Hybris instance with HAC
  • Network connectivity to your HAC instance
  • (Optional) VPN client software for tunnel management

Installation

Install Hac Hack using pip:

pip install hachack

For development or from source:

git clone https://github.com/storizzi/hachack.git
cd hachack
pip install -e .

Basic Setup

  1. Create a virtual environment (recommended):
python -m venv hachack-env
source hachack-env/bin/activate  # On Windows: hachack-env\Scripts\activate
  1. Install dependencies:
pip install hachack[all]  # Includes optional dependencies
  1. Configure environment variables: Create a .env file with your configuration:
HAC_BASE_URL=https://your-hybris-instance.com/hac
HAC_USERNAME=your-username
HAC_PASSWORD=your-password

Running the Server

Start the Hac Hack API server:

# Using Python directly with default port 8037
python hac_api.py

# Or specify a custom port
python hac_api.py --port 8000

# Or specify a timeout
python hac_api.py --port 8000 --timeout 120

The API will be available at https://localhost:8037 (or your specified port) with interactive documentation at https://localhost:8037/docs.

Sample curl Commands

Here are some practical examples of using Hac Hack with curl:

Check API Health

curl -X GET "https://localhost:8037/"

Login to HAC

curl -X POST "https://localhost:8037/login" \
  -H "Content-Type: application/json" \
  -d '{
    "hac_url": "https://your-hybris-instance.com/hac",
    "username": "admin",
    "password": "your-password"
  }'

Execute a Groovy Script

curl -X POST "https://localhost:8037/execute_groovy" \
  -H "Content-Type: application/json" \
  -d '{
    "hac_url": "https://your-hybris-instance.com/hac",
    "username": "admin",
    "password": "your-password",
    "script": "println \"Hello from Groovy\"; return \"Executed successfully\""
  }'

Import Impex Data

curl -X POST "https://localhost:8037/import_impex" \
  -H "Content-Type: application/json" \
  -d '{
    "hac_url": "https://your-hybris-instance.com/hac",
    "username": "admin",
    "password": "your-password",
    "script": "INSERT_UPDATE Product;code[unique=true];name\n;sample-001;Sample Product"
  }'

Tunnelblick VPN Management

For environments where HAC instances are behind VPNs, Hac Hack provides built-in VPN tunnel management specifically for Tunnelblick on macOS:

VPN Configuration

The VPN management uses the included tunnelblick.zsh script:

VPN_SCRIPT_PATH=tunnelblick.zsh
VPN_TIMEOUT=60

VPN Control via API

Check VPN connection status:

curl -X GET "https://localhost:8037/vpn?connection=Your+VPN+Name"

Connect to VPN with auto-revert:

curl -X PUT "https://localhost:8037/vpn?connection=Your+VPN+Name&action=on&timeout=300"

Disconnect from VPN:

curl -X PUT "https://localhost:8037/vpn?connection=Your+VPN+Name&action=off"

Cancel scheduled revert:

curl -X PUT "https://localhost:8037/vpn?connection=Your+VPN+Name&action=revert"

Automatic Tunnel Management

Hac Hack can automatically:

  1. Connect to VPN before making HAC requests
  2. Maintain connection state with status tracking
  3. Auto-revert connections after a specified timeout
  4. Handle reconnection with proper error handling

Open Source Project Details

Hac Hack is fully open source and available on GitHub:

Repository Information

Contributing

We welcome contributions from the community! Here’s how you can get involved:

  1. Fork the repository on GitHub
  2. Create a feature branch for your changes
  3. Write tests for new functionality
  4. Submit a pull request with a clear description

Project Structure

hachack/
├── hac_api.py              # FastAPI server
├── hac_client.py           # HAC client library
├── generate_certificates.zsh  # Certificate generation script
├── tunnelblick.zsh         # VPN control script
├── requirements.txt        # Python dependencies
├── README.md              # Main documentation
├── README-tunnelblick.md  # VPN-specific docs
├── CHANGELOG.md           # Version history
├── LICENSE                # MIT License
├── samples/               # Sample files
└── demos/                 # Demo scripts

Roadmap

We have exciting plans for Hac Hack’s future development:

  • Enhanced Monitoring: Built-in metrics and observability features
  • Additional HAC Operations: More HAC console operations
  • Cross-platform VPN Support: Support for VPN clients beyond Tunnelblick
  • Batch Operations: Execute multiple HAC operations in sequence
  • Improved Error Handling: Better error messages and retry logic
  • Docker Support: Containerized deployment options

Conclusion

Hac Hack for me made quite a difference in automating common SAP Commerce/Hybris HAC operations, and testing things on local installations. By combining security, flexibility, and ease of use, it provides a comprehensive solution for me to integrate HAC functionality into workflows. So I decided to share it, to help out fellow developers and administrators who have a workflow or toolset they would like to be able to streamline.

The project’s focus on security through mTLS authentication, combined with features like VPN tunnel management and a comprehensive REST API, makes it suitable for both development and production environments - albeit in a production environment, then I would strongly advise you test carefully as this is a new project! Whether you’re building CI/CD pipelines, monitoring systems, or custom automation tools, my hope is that Hac Hack will provide the foundation you need to be able to make life a bit easier for day-to-day tasks.

As an open-source project, I’m committed to its continued development and welcome community feedback and contributions. Roadmap tbc, but I have a few ideas that might be quite interesting to folks!

Get started with Hac Hack today by visiting the GitHub repository and following the installation guide. We’re excited to see what you’ll build with it!

Have questions about Hac Hack or want to share your use cases? Join community discussions on GitHub or reach out through the issues page. Your feedback helps to shape the future of HAC automation!