Skip to content

Go API

hemlock exposes its full functionality as a Go library. Import the packages directly to integrate poisoned document generation, payload management, and framework validation into your own security tooling, CI pipelines, or custom test harnesses.

Import Path

import "github.com/professor-moody/hemlock/pkg/craft"

The primary entry point is the craft package. For finer control, import the sub-packages directly.

Quick Example

package main

import (
    "fmt"
    "log"
    "os"

    "github.com/professor-moody/hemlock/pkg/craft"
    "github.com/professor-moody/hemlock/pkg/validate"
)

func main() {
    // Generate DOCX documents with fontzero technique
    docs, err := craft.Craft(craft.CraftOptions{
        Format:    "docx",
        Technique: "fontzero",
        Payload:   "override",
        Topic:     "IT security policy",
        Count:     3,
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, doc := range docs {
        // Write to disk
        if err := os.WriteFile(doc.Filename, doc.Content, 0o644); err != nil {
            log.Fatal(err)
        }

        // Validate against LangChain
        result, err := validate.Validate(
            doc.Content, doc.Payload, doc.Format, "langchain",
        )
        if err != nil {
            log.Fatal(err)
        }

        fmt.Printf("%s: payload_found=%t stealth=%d\n",
            doc.Filename, result.PayloadFound, doc.StealthScore)
    }
}

Package Overview

Package Import Path Description
craft pkg/craft High-level API for generating poisoned documents. Orchestrates format generators, payload resolution, and optimization.
payloads pkg/payloads Payload registry with 6 categories and 70 preset variants. Handles custom payloads and template rendering.
validate pkg/validate Simulates text extraction by LangChain, LlamaIndex, Unstructured.io, and Haystack. Returns structured validation results.
formats/html pkg/formats/html HTML document generation with 9 hiding techniques.
formats/docx pkg/formats/docx DOCX document generation with 8 hiding techniques.
formats/pdf pkg/formats/pdf PDF document generation with 7 hiding techniques.
formats/txt pkg/formats/txt Plain text generation with 4 hiding techniques.
formats/markdown pkg/formats/markdown Markdown generation with 5 hiding techniques.
formats/rtf pkg/formats/rtf RTF document generation with 3 hiding techniques.
formats/epub pkg/formats/epub EPUB document generation with 6 hiding techniques.
formats/csv pkg/formats/csv CSV file generation with 3 hiding techniques.
formats/jsonf pkg/formats/jsonf JSON file generation with 2 hiding techniques.
formats/xlsx pkg/formats/xlsx XLSX spreadsheet generation with 4 hiding techniques.
formats/image pkg/formats/image PNG image generation with 4 hiding techniques.
embed pkg/embed Embedding generation via Ollama and OpenAI for semantic optimization.

Design Philosophy

Clean, minimal API. The craft.Craft() function handles the common case. For advanced use, the format packages expose Generate() directly.

Near-zero external dependencies. hemlock depends only on:

All HTML, DOCX, TXT, and Markdown generation is implemented with Go's standard library. The validation engine uses pure Go string processing and archive/zip for DOCX handling---no Python or external extraction libraries required.

Deterministic output. Given the same inputs, hemlock produces identical documents. This makes it suitable for CI integration where reproducible test artifacts are needed.

Package Reference

  • craft --- Craft(), CraftOptions, Document, TechniqueInfo, ListTechniques(), ListPayloads()
  • payloads --- PayloadInfo, ListPayloads(), GetPayload(), ResolvePayload()
  • validate --- ValidationResult, Validate(), ValidateFile()
  • formats --- Per-format Techniques() and Generate() functions