Template Security¶

The generator renders scaffolded project files from text/template using inputs collected via an interactive wizard, CLI flags, or a regenerate manifest. Because text/template performs no automatic escaping, an adversarial or accidentally-malformed input value can produce corrupted output (broken YAML, Markdown injection, path traversal) or disrupt downstream builds.

Two complementary layers of defence apply to every user-influenced field:

1. Input validation (internal/generator/validate.go) — a constrained character class per field rejects structurally dangerous values at the entry point. Most injection vectors collapse if the input never matches a template-active character.
2. Output escaping (internal/generator/template_escape.go) — context-aware escape functions pipe values through at non-code template sites, so even if validation ever widens or a new input field is added, the rendering layer remains safe.

Scope¶

This page covers the defence layers inside internal/generator/. Other generator inputs (command flags, manifest commands) follow their own conventions:

• Jennifer-generated Go (skeleton_root.go and friends) handles escaping via jen.Lit() — which produces correctly-escaped Go literals automatically. No additional template-escape helpers apply there.
• Shell and OS commands run by the generator use exec.Command (no shell) so argument quoting is not a concern.

Input Validation¶

Every user-influenced field has a dedicated validator in internal/generator/validate.go. Each validator:

• Normalises the input to Unicode NFC form before checking. Homoglyph attacks (ρaypal, hidden ZWJ) fail fast this way.
• Applies a strict, anchored regex or structural check (e.g. url.Parse + scheme allowlist for endpoints).
• Returns a cockroachdb/errors value wrapping the ErrInvalidInput sentinel so callers can distinguish validation failures via errors.Is.
• Produces a hint that names the field and the rule, and includes the offending input (truncated) only when doing so aids debugging. No hint reveals more than the first 32 runes of the input.

Field Rules¶

Where the Validators Fire¶

ValidateManifest is the gate for the regenerate path: it walks Properties, ReleaseSource (type, host, owner, and repo name), every command in the Commands tree — name, description, long description, and every flag (name, type, shorthand, description, and the code-default grammar when default_is_code: true) — and every rendered Signing field including the provenance-annotation fields (external_key_email, key_source). A tampered .gtb/manifest.yaml therefore cannot drive writes or deletes outside the project tree, inject YAML into CI-executed files, compile arbitrary Go through a flag default, or break out of the provenance comment.

The generate command CLI applies the same rules at its boundary: --short/--long run through ValidateDescription/ValidateLongDescription, and each colon-delimited --flag definition is validated field-by-field (including ValidateFlagDefaultCode when the definition marks its default as code).

The same rules apply at every entry point, with severity matched to the input's origin:

• CLI flags / interactive wizard (gtb generate command, gtb remove command, gtb generate project --signing-*, gtb enable signing) — an invalid value is a hard error: the user typed it and can correct it.
• Manifest entries (the regenerate path) — an invalid command or signing block is skipped, not fatal: the generator logs at ERROR level naming the entry and the rule it failed, and the remaining valid entries still regenerate. A skipped entry is never acted on, so the filepath.Join/RemoveAll sink is foreclosed. The on-disk manifest is left untouched for the user to fix.
• The join sink itself (getCommandPath) — independently of entry-point validation, every resolved command directory is checked (via filepath.Rel) to sit strictly under <project>/pkg/cmd.

AI Doc-Tool Containment¶

The AI documentation generator exposes read_file, list_dir, and go_doc tools to the model. All three are contained to the project root: model-supplied relative paths are joined to the absolute project root and rejected (filepath.Abs + filepath.Rel) if the result escapes it, so a model-supplied ../../etc/passwd cannot read or list outside the tree.

Output Escaping¶

The templateFuncMap in template_escape.go is registered on every text/template used by the generator. Call sites in non-code locations pipe their values through the appropriate helper:

# README.md — Markdown prose vs fenced code block
{{ .Name | escapeMarkdown }} is a tool built with [gtb](...).   # prose
    go install {{ .Repo | escapeMarkdownCodeBlock }}@latest     # inside ``` fence

# zensical.toml — TOML string values
site_name = "{{ .Name | escapeTOML }}"
site_description = "{{ .Description | escapeTOML }}"

# .goreleaser.yaml — mixed contexts
project_name: {{ .Name | escapeYAML }}   # YAML value (non-code)
    main: cmd/{{ .Name }}/main.go        # code path (no escape)

# justfile — mixed contexts
# Build the {{ .Name | escapeComment }} binary               # comment (non-code)
build: go build -o bin/{{ .Name | escapeShellArg }} ...      # sh recipe body (shell arg)

Both escapeShellArg (justfile recipe bodies) and escapeMarkdownCodeBlock (fenced README/docs blocks) are wired at the render sites above as defence-in-depth: ValidateName/ValidateRepo already restrict the inputs to a shell- and fence-safe character class, so clean projects see no diff, but the pipe keeps the output safe if a validator is ever widened. The TestEscape_HelpersWiredAtDocumentedSites test asserts the pipes stay in place.

Not every render site is a text/template: the boilerplate docs builder (internal/generator/docs.go) assembles Markdown with fmt.Fprintf on a strings.Builder, so the FuncMap pipes never apply there. Its sites call the helpers directly — escapeMarkdown for the description/long-description prose and escapeMarkdownTableCell (composed with escapeMarkdown) for every flags- and subcommands-table cell. When adding a Go-side render site, call the helper explicitly; the two-layer rule (validate at the gate, escape at the sink) applies regardless of the rendering mechanism.

Helper Contract¶

Every escape function is:

• Pure. Same input → same output; no side effects; safe for concurrent use.
• Infallible. Invalid UTF-8 is replaced with U+FFFD; every other input produces well-formed output.
• Identity on the safe class. For inputs matching ^[a-zA-Z0-9 _.,/-]*$, the output equals the input. Clean projects see no diff after piping values through the helpers.
• Syntactically valid in the target format. escapeYAML output parses as a YAML scalar; escapeTOML output parses as a TOML basic string; escapeMarkdownCodeBlock output contains no ``` fence sequence.

Helpers Available¶

Adding a New User-Input Field¶

When you add a new field that flows from the wizard/flags/manifest into skeleton templates:

1. Add a validator in validate.go with a rule as tight as reasonable. Prefer a strict character class over a permissive one; start narrow and relax only with a clear use case.
2. Test the validator with representative accepting and rejecting inputs, including Unicode adversarial cases (NUL, RTL override, zero-width joiner, CJK homoglyphs).
3. Audit the template call sites for the new field. For each non-code site, pipe the field through the appropriate escape helper. Code sites (paths, identifiers, Go source strings) must not be piped.
4. Decide whether the field is required or optional and wire that into ValidateManifest accordingly: required fields hard-fail on empty; optional fields short-circuit to nil.
5. Run the existing fuzz and regression tests. No golden-hash drift should occur for existing clean fixtures — the escape functions are identity on the safe class.

See docs/development/specs/2026-04-02-generator-template-escaping.md for the full rationale and the complete audit of template locations.

Custom Template Overlays — A Different Threat Model¶

The escape-at-known-sites model above protects GTB's own templates: GTB authors every template and escapes the user-supplied field values it interpolates. Custom template overlays (docs/development/specs/2026-06-15-generator-custom-partial-templates.md) deliberately step outside that perimeter — the generator renders text/template content GTB did not author, fetched (for git sources) over the network from a repository the framework does not control. The template author controls the output directly, so the escape helpers cannot guarantee a custom template's output is well-formed; that correctness is the template author's responsibility.

GTB's guarantees for custom overlays are therefore confined to where output may land and what data a template may see — not the bytes emitted. The posture is trusted-source with bounded blast radius, not a sandbox (a true sandbox is out of scope). Adding a source is the trust decision; the SHA pin records exactly what was trusted.

Hard controls (always on)¶

Output escaping reality¶

GTB cannot guarantee a custom template emits valid YAML/Markdown/etc., and a malicious .gitlab-ci.yml or justfile it renders could run attacker code when CI/just later runs. That downstream-injection risk is inherent to running an operator-chosen template and is out of scope for GTB to neutralise — it is the same trust the operator extends to a Makefile or a pre-commit hook they chose to run. The controls above bound the blast radius at generate time; they do not vet the semantics of the emitted bytes.