Go - Go modules

Root Library Catalog supports Go modules. Patched modules are served through the GOPROXY protocol and consumed via replace directives in your go.mod file.

Prerequisites

The Root Patcher CLI (rootio_patcher) is required to analyze your dependencies and inject the necessary replace directives. Install it before configuring your Go environment.

# macOS (Apple Silicon)
curl -sL https://github.com/rootio-avr/rootio_patcher/releases/latest/download/rootio_patcher_darwin_arm64.tar.gz | tar xz
chmod +x rootio_patcher && sudo mv rootio_patcher /usr/local/bin/

# Linux (x86_64)
curl -sL https://github.com/rootio-avr/rootio_patcher/releases/latest/download/rootio_patcher_linux_x86_64.tar.gz | tar xz
chmod +x rootio_patcher && sudo mv rootio_patcher /usr/local/bin/

For macOS Intel and Windows, see the full installation instructions. Then set your API key:

export ROOTIO_API_KEY="your-api-key-here"

How Root Go modules work

Go modules are patched in a Docker build environment and published to pkg.root.io/go via the GOPROXY protocol. Patched modules keep their original module identity (e.g., module github.com/google/uuid) and are consumed using Go’s native replace directive in go.mod, requiring zero changes to application source code. Root publishes patched modules with the same version plus a -rootio.N suffix. For example:

golang.org/x/net v0.17.0 → pkg.root.io/golang/golang.org/x/net v0.17.0-rootio.1

The patcher analyzes your go.mod, queries Root’s API for available patches, and adds replace directives pointing to the Root-patched versions.

Only modules with pinned semver versions (e.g., v1.2.3) are analyzed. Modules using pseudo-versions (e.g., v0.0.0-20230101123456-abcdef012345) are skipped. If you have vulnerable pseudo-versioned dependencies, upgrade them to a pinned release first.

Authentication

Go’s module proxy system authenticates via the GOPROXY environment variable. This is the only environment variable you need to configure for regular builds:

export GOPROXY="https://:${ROOTIO_API_KEY}@pkg.root.io/gobinary,https://proxy.golang.org,direct"

This tells Go to:

Try resolving modules from pkg.root.io/gobinary first (with authentication)
Fall back to the public Go proxy at https://proxy.golang.org
Finally fall back to direct for modules not available through either proxy

You can also set this persistently:

# Add to ~/.bashrc or ~/.zshrc
export GOPROXY="https://:${ROOTIO_API_KEY}@pkg.root.io/gobinary,https://proxy.golang.org,direct"

No GONOSUMDB or GOPRIVATE needed! Once the patcher runs go mod tidy and generates your go.sum file, regular builds use the checksums from go.sum for verification. Go only queries the checksum database when adding new modules, which the patcher handles internally.

Patching your project

1. Preview available patches

Run the patcher in dry-run mode (no ROOTIO_API_KEY needed for discovery):

rootio_patcher go remediate

This shows which modules have Root-patched versions available and which CVEs they fix.

2. Apply patches

Run the patcher with --dry-run=false to update your go.mod:

rootio_patcher go remediate --dry-run=false

The patcher will:

Add replace directives to your go.mod
Automatically run go mod tidy to fetch the patched modules
Run go mod vendor if a vendor/ directory exists

3. Build your project

After patching, build as usual:

go build ./...

The build will use the patched modules from pkg.root.io/go via the replace directives.

Example workflow

# 1. Configure GOPROXY (only env var needed for builds)
export GOPROXY="https://:${ROOTIO_API_KEY}@pkg.root.io/gobinary,https://proxy.golang.org,direct"

# 2. Preview patches (dry-run)
rootio_patcher go remediate

# Output:
# === DRY-RUN MODE ===
# The following replace directives would be added to go.mod:
#
# 1. replace golang.org/x/net v0.17.0 => pkg.root.io/golang/golang.org/x/net v0.17.0-rootio.1
#    CVEs Fixed: [CVE-2024-12345]
#
# 2. replace github.com/golang-jwt/jwt/v4 v4.5.0 => pkg.root.io/golang/github.com/golang-jwt/jwt/v4 v4.5.0-rootio.1
#    CVEs Fixed: [CVE-2024-67890]

# 3. Apply patches
# The patcher automatically runs `go mod tidy` and updates go.sum
rootio_patcher go remediate --dry-run=false

# 4. Commit the changes
# IMPORTANT: Commit both go.mod and go.sum
git add go.mod go.sum
git commit -m "Apply Root patches for Go modules"

# 5. Build (go.sum provides checksum verification)
go build ./...

Working with go.mod

After running the patcher, your go.mod will contain replace directives like:

module github.com/myorg/myapp

go 1.21

require (
    golang.org/x/net v0.17.0
    github.com/golang-jwt/jwt/v4 v4.5.0
)

// Root patches
replace golang.org/x/net v0.17.0 => pkg.root.io/golang/golang.org/x/net v0.17.0-rootio.1
replace github.com/golang-jwt/jwt/v4 v4.5.0 => pkg.root.io/golang/github.com/golang-jwt/jwt/v4 v4.5.0-rootio.1

Your import statements remain unchanged:

import (
    "golang.org/x/net/http2"
    "github.com/golang-jwt/jwt/v4"
)

The replace directives transparently redirect module resolution to Root’s patched versions at build time.

CI/CD Configuration

In CI/CD environments, you only need to set GOPROXY - the committed go.sum file provides checksum verification.

GitHub Actions

name: Build

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-go@v5
        with:
          go-version: '1.21'
      
      - name: Configure GOPROXY
        run: echo "GOPROXY=https://:${{ secrets.ROOTIO_API_KEY }}@pkg.root.io/gobinary,https://proxy.golang.org,direct" >> $GITHUB_ENV
      
      - name: Build
        run: go build ./...

No GONOSUMDB needed! The go.sum file committed in your repo contains all the checksums. Go uses those for verification during builds.

GitLab CI

build:
  image: golang:1.21
  before_script:
    - export GOPROXY="https://:${ROOTIO_API_KEY}@pkg.root.io/gobinary,https://proxy.golang.org,direct"
  script:
    - go build ./...

Docker builds

FROM golang:1.21-alpine

WORKDIR /app

# Copy go.mod, go.sum (contains checksums)
COPY go.mod go.sum ./

# Set GOPROXY - no GONOSUMDB needed
ARG ROOTIO_API_KEY
ENV GOPROXY="https://:${ROOTIO_API_KEY}@pkg.root.io/gobinary,https://proxy.golang.org,direct"

# Download dependencies (verified against go.sum)
RUN go mod download

# Copy source and build
COPY . .
RUN go build -o myapp ./cmd/myapp

CMD ["./myapp"]

Checksum verification and go.sum

Go’s module system uses checksums for security. Here’s how it works with Root patches:

How go.sum provides security

When the Root Patcher runs go mod tidy, it:

Downloads the patched modules from pkg.root.io/gobinary
Calculates their checksums
Writes those checksums to your go.sum file

During regular builds (go build, go test, Docker builds):

Go reads the checksums from your committed go.sum file
Go downloads modules and verifies them against go.sum
Go does not query the checksum database (sum.golang.org)
Your go.sum is the source of truth

This means:

✅ Cryptographic verification is still active via go.sum
✅ No environment variables needed beyond GOPROXY
✅ Reproducible builds across all environments
✅ Git tracks the checksums (commit go.sum with your code)

When GONOSUMDB is used

The Root Patcher sets GONOSUMDB=pkg.root.io internally when it runs go mod tidy. This allows it to download patched modules from Root’s registry without querying the public checksum database. You don’t need to set this yourself - the patcher handles it automatically.

If you manually run go mod tidy

If you need to run go mod tidy manually after the patcher has added replace directives:

export GOPROXY="https://:${ROOTIO_API_KEY}@pkg.root.io/gobinary,https://proxy.golang.org,direct"
export GONOSUMDB="pkg.root.io"
go mod tidy

But this is rarely needed - the patcher runs go mod tidy automatically after updating your go.mod.

Troubleshooting

Issue	Solution
`401 Unauthorized`	Verify `GOPROXY` includes your `ROOTIO_API_KEY` and the token is valid
Module not found	Confirm the patched module exists at `pkg.root.io/gobinary` or check the dry-run output
Checksum mismatch during build	Ensure `go.sum` is committed and up-to-date - the patcher generates this automatically
Checksum mismatch during manual `go mod tidy`	Set `GONOSUMDB="pkg.root.io"` before running `go mod tidy`
Pseudo-version dependencies	Upgrade to a pinned semver version - the patcher only supports semver
`replace` not working	Ensure `go mod tidy` has been run and `GOPROXY` is configured before building

Multi-module projects

For projects with multiple Go modules (e.g., monorepos), run the patcher from the root and specify each module:

# Patch the root module
rootio_patcher go remediate --go-mod=./go.mod --dry-run=false

# Patch a submodule
rootio_patcher go remediate --go-mod=./services/api/go.mod --dry-run=false

Or iterate over all modules:

find . -name "go.mod" -execdir rootio_patcher go remediate --dry-run=false \;

Version pinning

Root patches are tied to specific upstream versions. If you upgrade a dependency to a newer version, run the patcher again to check if a Root patch is available for the new version:

# After upgrading dependencies
go get -u github.com/some/module@v2.0.0

# Check for patches
rootio_patcher go remediate

Go Standard Library (stdlib) Limitations

Root Library Catalog does not support patching Go’s standard library packages (e.g., net/http, crypto/tls, encoding/json). Stdlib packages are part of the Go toolchain itself and cannot be patched using the replace directive mechanism that Root uses for external modules.

Why stdlib patching is not supported

Unlike external Go modules where Root can publish patched versions and use replace directives in go.mod to redirect module resolution, the Go standard library is:

Embedded in the toolchain - stdlib packages are compiled from sources bundled with the Go binary itself
Not replaceable via go.mod - Go’s module system does not support replace directives for stdlib packages
Tied to the Go version - The stdlib version is determined by the go directive at the top of go.mod (e.g., go 1.22.3)

Recommended approach for stdlib vulnerabilities

Keep your Go version up to date. Unlike third-party packages where version upgrades may introduce breaking changes, Go’s standard library maintains exceptional backwards compatibility. The Go team at Google maintains stdlib with:

Strong backwards compatibility guarantees
Rapid security response times
Regular patch releases for security issues
Comprehensive test coverage

When a stdlib CVE is announced:

Upgrade to the latest patch version of your current Go minor version:
```
# If on Go 1.22.x, upgrade to latest 1.22.y
go get go@1.22
```
Update your go.mod:
```
go 1.22.5  // Updated from 1.22.3
```

For Dockerfile-based builds, update your base image:

# Before
FROM golang:1.22.3-alpine

# After
FROM golang:1.22.5-alpine

This approach provides the most reliable security posture for stdlib vulnerabilities without compromising build reproducibility.

Getting Started

Root Image Catalog

Platform

Integrations

AI Integrations

Root Library Catalog

Core Concepts

Reports & Insights

Reference

Trust & Compliance

Go - Go modules

Prerequisites

How Root Go modules work

Authentication

Patching your project

1. Preview available patches

2. Apply patches

3. Build your project

Example workflow

Working with go.mod

CI/CD Configuration

GitHub Actions

GitLab CI

Docker builds

Checksum verification and go.sum

How go.sum provides security

When GONOSUMDB is used

If you manually run go mod tidy

Troubleshooting

Multi-module projects

Version pinning

Go Standard Library (stdlib) Limitations

Why stdlib patching is not supported

Recommended approach for stdlib vulnerabilities

Getting Started

Root Image Catalog

Platform

Integrations

AI Integrations

Root Library Catalog

Core Concepts

Reports & Insights

Reference

Trust & Compliance

Documentation Index

​Prerequisites

​How Root Go modules work

​Authentication

​Patching your project

​1. Preview available patches

​2. Apply patches

​3. Build your project

​Example workflow

​Working with go.mod

​CI/CD Configuration

​GitHub Actions

​GitLab CI

​Docker builds

​Checksum verification and go.sum

​How go.sum provides security

​When GONOSUMDB is used

​If you manually run go mod tidy

​Troubleshooting

​Multi-module projects

​Version pinning

​Go Standard Library (stdlib) Limitations

​Why stdlib patching is not supported

​Recommended approach for stdlib vulnerabilities

Prerequisites

How Root Go modules work

Authentication

Patching your project

1. Preview available patches

2. Apply patches

3. Build your project

Example workflow

Working with go.mod

CI/CD Configuration

GitHub Actions

GitLab CI

Docker builds

Checksum verification and go.sum

How go.sum provides security

When GONOSUMDB is used

If you manually run go mod tidy

Troubleshooting

Multi-module projects

Version pinning

Go Standard Library (stdlib) Limitations

Why stdlib patching is not supported

Recommended approach for stdlib vulnerabilities