This is not an officially supported Google product.

Safe-by-construction libraries for producing formats like YAML, to replace syntax-unaware libraries like text/template and sprintf that are at risk of injection vulnerabilities.

Since text/template is not syntax-aware of the formats it produces, it does not offer any protection against injection vulnerabilities.

Consider the following produceConfig function which uses text/template to generate YAML:

package main

import (
        "bytes"
        "fmt"
        "text/template"
)

func produceConfig(params any) (error, string) {
        tmpl, _ := template.New("test").Parse("{ hello: {{ .addressee }} }")

        var buf bytes.Buffer
        err := tmpl.Execute(&buf, params)
        if err != nil {
                return err, ""
        }

        return nil, buf.String()
}

func main() {
        goodReplacements := map[string]interface{}{
                "addressee": "safe",
        }

        err, config := produceConfig(goodReplacements)

        if err == nil {
                fmt.Println(config)
        } else {
                fmt.Printf("Error: %v\n", err)
        }

        badReplacements := map[string]interface{}{
                "addressee": "world, oops: true",
        }

        err, config = produceConfig(badReplacements)

        if err == nil {
                fmt.Println(config)
        } else {
                fmt.Printf("Error: %v\n", err)
        }
}

This program demonstrates how a malicious addressee input can cause injection of new YAML keys in the template execution result.

With text/template, no errors will be encountered when this happens, and the program output will be:

{ hello: safe }
{ hello: world, oops: true }

By instead switching from text/templateto safetext/yamltemplate, the injection would have been prevented, with the output instead being:

{ hello: safe }
Error: YAML Injection Detected

Injection detection is automatically applied when accessing input data fields.

• It can also be manually enabled on the result of any function call:

  {{ RetrieveUntrustedData | ApplyInjectionDetection }}
  

• The injection logic can be disabled on certain fields by applying the StructuralData annotation:

  {{ (StructuralData .x) }}
  

• The StructuralData annotation is also needed when passing an input to a function where the input should not be mutated, such as a performing some kind of lookup:

  name: {{ readFile (StructuralData .pathToName) | ApplyInjectionDetection }}
  

• It is recommended to make full use of text/template features like conditional expressions, range loops, etc to avoid the StructuralData annotation where possible. For example, instead of:

  properties:
      {{ (StructuralData .PropertiesYaml) }}
  

  Consider:

  properties:{{ range .Properties }}
      - {{ . }}{{ end }}
  

The intention of yamltemplate is to ensure that by-default none of the strings in the input data affect the structure of the resultant YAML (just the values).

• For example, the below template would be compatible with yamltemplate as-is, whilst automatically preventing any injections from the Name input:

  name: {{.Name}}
  

• However, any template nodes that are expected to change the resultant YAML structure, such as inserting arbitrary YAML config, would need to be annotated explicitly as StructuralData:

  config: {{ (StructuralData .Config) }}
  

• Another case of needing the StructuralData annotation would be where you need to include a complete map into the yaml structure. Using StructuralData alone may let injections pass through via the key so we need an extra layer of validation here:

  labels:
  {{- range $key, $value := .Labels }}
      {{ (StructuralData $key | MapKey) }}: {{ $value }}
  {{- end }}
   ```
  
  The corresponding golang side could look like this:
  
  

  func mapKeyFunc(data any) (string, error) { if v, ok := data.(string); ok { matched, err := regexp.MatchString(^[a-zA-Z0-9/\-.]+$, v) if err != nil { return "", err } if !matched { return "", fmt.Errorf("invalid characters in the key: %v", v) } return v, nil }

  return "", errors.New("invalid input")
  

  } ...

  tmp:= template.New("something") tmp.Funcs(map[string]any{"MapKey": mapKeyFunc}) tmpl := template.Must(tmp.Parse(yamlTemplate)) ```

• You can combine yamltemplate with shprintf. Consider the following cloud-init yaml template:

  ---
  write_files:
  - path: /etc/nginx/refresh.sh
    owner: root:root
    permissions: 0755  # Don't forget the 0 (you are probably using octal...)
    content: |
      #!/bin/bash
      set -euo pipefail
  
      {{ shprintf `curl %s > /tmp/something` .userInput }}
  

  Evaluating this template with safetext/yamltemplate, both shell command and YAML injections will be prevented.

  To do this, you need to setup the golang side like this:

  tmp:= addons.WithShsprintf(template.New("something"))
  tmpl := template.Must(tmp.Parse(yamlTemplate))
  

• YAML with duplicate keys. Duplicate keys are non-standard YAML, and not supported by this library. Please refactor your YAML template to remove duplicate keys. For example:

  - project:
     members: member-a
     members: member-b
  

  To:

  - project:
    members: member-b
  

shtemplate is designed to allow you to generate shell scripts with the guarantee that none of the input data strings will be able to inject new commands or flags, without explicit annotation.

• For example, a template script designed to just print one string will fail to render if that string injects a new command `./evil`:

  echo "{{ .addressee }}"
  

• To explicitly allow an input string to contain new commands not from the template string, the StructuralData annotation can be used:

  {{ (StructuralData .commands) }}
  

• Flags (arguments starting with -) are also forbidden by-default. For example, the below template will fail to render if Filename is --interactive:

  git add {{ .Filename }}
  

• To explicitly allow an input string passed as a command argument to be a flag, the AllowFlags annotation can be used:

  git add {{ (AllowFlags .FilenameOrGitAddFlag) }}
  

• Multiple arguments from a single input string is also forbidden by-default. This construct should instead be implemented using an array and range expression:

  ls {{ range .Paths }}{{.}} {{end}}
  

• Escaping logic outside of the templating system. Instead, you should annotate the escaping logic into your template (EG: .UntrustedField | escape).

• Partial formats. The libraries are designed to be used for generating complete files. If you generate segments and then concatenate them together, you should instead move this logic into the templating system itself (using constructs like if or range).

• Functions with side effects. The libraries work by performing multiple template executions, so if you register functions that have side effects, this could cause unexpected behaviour (EG: id: {{ AllocateID }}).

shsprintf is designed to allow you to generate shell scripts with the guarantee that none of the input data strings will be able to inject new commands or flags regardless of potentially incorrect escaping. See the below example, which will return the error shsprintf.ErrShInjection instead of the script with an injected command:

message := "`whoami`"
result, err := shsprintf.Sprintf("git commit -m %s", message)

shsprintf.Sprintf adds an error return value compared to fmt.Sprintf, but the API is otherwise the same. shsprintf.MustSprintf is available for cases where panic is acceptable.

shsprintf comes with an escaping function that is recommended for use:

message := "`whoami`"
result := shsprintf.MustSprintf("git commit -m %s", shsprintf.EscapeDefaultContext(message))

Unlike with text/template there are no special annotations. If you need to pass multiple arguments for example, this should be done by altering the format string:

files := []any{ "file1", "file2", "file3" }
result, err := shsprintf.Sprintf("cat" + strings.Repeat(" %s", len(files)), files...)