Hac Hack

Project Overview

Hac Hack is an open-source Python library and secure FastAPI-based HTTP API for automating SAP Commerce/Hybris HAC (hybris Administration Console) operations. This project addresses the common challenge of programmatically interacting with HAC endpoints while maintaining robust security and automatically managing VPN network connectivity via Tunnelblick on macOS.

The solution emerged from the need to automate repetitive HAC tasks that are typically performed manually through the web interface - e.g. for testing, loading sample data, running groovy scripts etc., but could also be used as part of a pipeline process. By providing a REST API wrapper around HAC functionality, it enables seamless integration into CI/CD pipelines, monitoring systems, and custom automation workflows.

In order to ensure security if running the endpoint on one laptop / server and accessing the API from another, the library includes certificate generation via the included generate_certificates.zsh script to ensure the API isn’t easily hijacked from another computer.

If you are using it on one laptop only though, the REST API is not necessary, and you can run jobs via a python script using the hac_client.py module directly.

Samples of both approaches are given in the repository.

Key Features

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
Health Check: Simple root endpoint to verify API availability
VPN Tunnel Management: Built-in Tunnelblick VPN control for Mac (if needed)

Integration Capabilities

REST API: Full FastAPI-based HTTP API with OpenAPI documentation
Python Library: Direct Python integration for custom applications via hac_client.py
Tunnelblick VPN Support: Built-in VPN tunnel management if you happen to use Tunnelblick on Mac
Flexible Configuration: Environment-based configuration for different deployment scenarios

Security Features

mTLS Authentication

Hac Hack features robust mutual TLS (mTLS) authentication system providing two-way authentication between client and server:

Certificate Generation Script: Included generate_certificates.zsh creates all necessary 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

Environment Variable Configuration

Secure credential management through environment variables:

# 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

It’s never a good idea to keep these values lying around in an .env file directly - I’d recommend using your favourite password vault - I tend to use 1Password

Installation and Setup

Prerequisites

Python 3.8 or higher
Access to a SAP Commerce/Hybris instance with HAC
Network connectivity to your HAC instance
(Optional) Tunnelblick VPN client for Mac if HAC requires VPN access

Installation

# Clone from source
git clone https://github.com/storizzi/hachack.git
cd hachack

# Install dependencies
pip install -r requirements.txt

Basic Setup

Install dependencies:

pip install -r requirements.txt

Generate SSL certificates:

./generate_certificates.zsh

Configure environment variables: Create a .env file with your configuration:

HAC_URL=https://your-hybris-instance.com/hac
HAC_USERNAME=your-username
HAC_PASSWORD=your-password

Start the API server:

# Using default port 8037
python hac_api.py

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

The API will be available at https://localhost:8037 with interactive documentation at https://localhost:8037/docs.

Usage Examples

API Usage with curl

Check API Health

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

curl -k -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 -k -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 \"Success\""
  }'

Execute Impex Script

curl -k -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 -k -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"

Python Library Usage

from hac_client import HACClient

# Initialize client
client = HACClient(
    hac_url="https://your-hybris-instance.com/hac",
    username="your-username",
    password="your-password",
    timeout=60
)

# Login to HAC
result = client.login()
if result.get("success"):
    print("✅ Login successful")

# Execute Groovy script
groovy_result = client.execute_groovy_script(
    'println "Hello from Groovy"; return "Success"'
)

# Import Impex script
impex_result = client.import_impex(
    "INSERT_UPDATE Product;code[unique=true];name\n;test-product;Test Product"
)

# Import Impex file
file_result = client.import_impex_file("path/to/sample.impex")

API Documentation

Available Endpoints

Endpoint	Method	Description	Parameters
`/`	GET	Health check / Root endpoint	-
`/login`	POST	Login to HAC	`hac_url`, `username`, `password`
`/execute_groovy`	POST	Execute Groovy scripts	`hac_url`, `username`, `password`, `script`
`/import_impex`	POST	Import Impex scripts	`hac_url`, `username`, `password`, `script`
`/import_impex_file`	POST	Upload & import Impex file	`hac_url`, `username`, `password`, `file`, `retain`
`/vpn`	GET	Check VPN status	`connection`
`/vpn`	PUT	Control VPN connection	`connection`, `action`, `timeout`

Certificate Generation

Generate SSL certificates using the included script:

# 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

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 Control via API

Check VPN connection status:

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

Connect to VPN with auto-revert:

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

Disconnect from VPN:

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

Cancel scheduled revert:

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

The VPN management uses the included tunnelblick.zsh script for controlling Tunnelblick connections.

Contributing

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

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

Development Setup

# Clone the repository
git clone https://github.com/storizzi/hachack.git
cd hachack

# Install dependencies
pip install -r requirements.txt

# Generate SSL certificates
./generate_certificates.zsh

# Run the API server
python hac_api.py --port 8037

License

Hac Hack is released under the MIT License. This means you are free to use, modify, and distribute the software for both commercial and non-commercial purposes.

License Summary

✅ Commercial use
✅ Modification
✅ Distribution
✅ Private use
⚠️ Liability disclaimer
⚠️ Warranty disclaimer

For the full license text, see the LICENSE file in the repository.

Repository: github.com/storizzi/hachack
License: MIT
Python Version: 3.8+
Framework: FastAPI
Status: Active Development
Documentation: Interactive API Docs

Hac Hack provides a secure, flexible solution for automating SAP Commerce/Hybris HAC operations, enabling integration into modern development workflows and CI/CD pipelines.

Project Overview#

Key Features#

Core Functionality#

Integration Capabilities#

Security Features#

mTLS Authentication#

Environment Variable Configuration#

Installation and Setup#

Prerequisites#

Installation#

Basic Setup#

Usage Examples#

API Usage with curl#

Check API Health#

Login to HAC#

Execute Groovy Script#

Execute Impex Script#

Upload and Import Impex File#

Python Library Usage#

API Documentation#

Available Endpoints#

Certificate Generation#

Tunnelblick VPN Management#

VPN Control via API#

Contributing#

Development Setup#

License#

License Summary#