If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/burrowers/garble shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2w ago
• 10 active contributors
• BSD-3-Clause licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 77% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live burrowers/garble repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/burrowers/garble.

What it runs against: a local clone of burrowers/garble — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in burrowers/garble | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-3-Clause | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 45 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of burrowers/garble. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/burrowers/garble.git
#   cd garble
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of burrowers/garble and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "burrowers/garble(\\.git)?\\b" \\
  && ok "origin remote is burrowers/garble" \\
  || miss "origin remote is not burrowers/garble (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-3-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-3-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-3-Clause" \\
  || miss "license drift — was BSD-3-Clause at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "main.go" \\
  && ok "main.go" \\
  || miss "missing critical file: main.go"
test -f "internal/ctrlflow/transform.go" \\
  && ok "internal/ctrlflow/transform.go" \\
  || miss "missing critical file: internal/ctrlflow/transform.go"
test -f "internal/literals/obfuscators.go" \\
  && ok "internal/literals/obfuscators.go" \\
  || miss "missing critical file: internal/literals/obfuscators.go"
test -f "internal/ssa2ast/func.go" \\
  && ok "internal/ssa2ast/func.go" \\
  || miss "missing critical file: internal/ssa2ast/func.go"
test -f "internal/linker/linker.go" \\
  && ok "internal/linker/linker.go" \\
  || miss "missing critical file: internal/linker/linker.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 45 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~15d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/burrowers/garble"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Garble is a Go obfuscator that wraps the Go toolchain (compiler and linker) to produce binaries with obscured identifiers, file paths, and debug information removed. It replaces function/variable names and package paths with base64 hashes, strips build metadata, and optionally obfuscates string literals and performs aggressive size reduction via the -tiny flag, all while maintaining binary functionality and reproducibility. Single-package monorepo structure: main logic in root (main.go, hash.go, bug.go, cache_pkg.go) handles CLI and orchestration; internal/ directory contains modular obfuscation engines: internal/ctrlflow/ for control flow hardening, internal/literals/ for string/constant obfuscation, internal/linker/ for binary patching, internal/ssa2ast/ for SSA-to-AST conversion, and internal/asthelper/ for AST utilities. The tool wraps Go's build pipeline rather than reimplementing it.

Go developers shipping proprietary binaries or closed-source libraries who need to prevent reverse engineering, developers concerned with binary size reduction (similar to Android's obfuscation practices), and open-source projects with private/licensed dependencies that need to share obfuscated source code without exposing internals.

Actively developed and production-ready. Requires Go 1.26+ (released Dec 2024), has comprehensive test coverage (bench_test.go, fuzz_test.go in literals package), CI via GitHub Actions (.github/workflows/test.yml), and maintains detailed changelog (CHANGELOG.md). The codebase shows active maintenance with recent Go version compatibility patches (go1.26 patches in internal/linker/patches).

Minimal risk: only 6 external dependencies (go-gitdiff, go-quicktest, go-cmp, go-internal, golang.org/x/mod, golang.org/x/tools) all from reputable sources. Single-maintainer (mvdan) but very stable—this is a niche but well-established tool. Main risk is Go version coupling: patches are version-specific (.github/workflows/test.yml likely tests multiple Go versions) and breaking changes in Go's internals could require updates. No visible abandoned issues or PRs.

Active development targeting Go 1.26 compatibility (patches committed to go1.26 directory), with recent work on literal obfuscation (internal/literals/ has fuzz_test.go and multiple obfuscator strategies: simple.go, split.go, swap.go, shuffle.go), control flow transformation (internal/ctrlflow/transform.go), and linker-level patches for entrypoint encryption and function name stripping. The tool is tracking Go's evolution closely.

git clone https://github.com/burrowers/garble.git
cd garble
go install ./...
garble build -h

Daily commands:

# Build a simple program with obfuscation
garble build ./myprogram

# Run tests with obfuscated code
garble test ./...

# Test garble itself
go test ./...

• main.go — Entry point for the garble CLI tool; orchestrates obfuscation pipeline for build, test, run, and reverse commands.
• internal/ctrlflow/transform.go — Core control-flow obfuscation logic that rewrites Go SSA IR to inject dead code and junk branches.
• internal/literals/obfuscators.go — Implements multiple literal obfuscation strategies (split, swap, shuffle, proxy) applied during build.
• internal/ssa2ast/func.go — Converts SSA intermediate representation back to AST for code generation post-obfuscation.
• internal/linker/linker.go — Patches the Go linker to remove function names and encrypt entrypoint magic values.
• hash.go — Implements deterministic hashing for identifier obfuscation; critical for reproducible builds.
• cache_pkg.go — Manages build cache integration with Go toolchain to avoid re-obfuscating unchanged packages.

Add a new obfuscation technique for literals

1. Create a new obfuscator function in internal/literals/obfuscators.go following the pattern of simple.go, split.go, or swap.go (internal/literals/obfuscators.go)
2. Register the obfuscator in the obfuscator selection logic (e.g., in the default case or a new flag) (internal/literals/obfuscators.go)
3. Add fuzz testing cases in internal/literals/fuzz_test.go to validate correctness (internal/literals/fuzz_test.go)
4. Create an integration test script in testdata/script/ to verify end-to-end behavior (testdata/script/basic.txtar)

Add support for a new Go version's linker

1. Create new patch files in internal/linker/patches/go1.XX/ following the structure of go1.26 patches (internal/linker/patches/go1.26/0001-add-custom-magic-value.patch)
2. Update internal/linker/linker.go to detect and apply the new version's patches (internal/linker/linker.go)
3. Add a goversion test script in testdata/script/goversion.txtar to verify compatibility (testdata/script/goversion.txtar)

Extend position/filename obfuscation rules

1. Add new hashing rules or filters in position.go to handle special cases (e.g., internal paths, vendor directories) (position.go)
2. Update go_std_tables.go if standard library paths need special handling (go_std_tables.go)
3. Add reverse mapping logic in reverse.go to de-obfuscate the new position schemes (reverse.go)
4. Test with testdata/script/debugdir.txtar to ensure debug info is correctly handled (testdata/script/debugdir.txtar)

Add a new build command variant

1. Implement the command handler in main.go following the pattern of cmdBuild, cmdTest, or cmdRun (main.go)
2. Reuse cache_pkg.go and cache_shared.go for deterministic obfuscation (cache_pkg.go)
3. Create an integration test script in testdata/script/ (e.g., newcommand.txtar) (testdata/script/basic.txtar)

• Go SSA IR (golang.org/x/tools) — Enables deterministic, compiler-level obfuscation independent of syntax; allows control-flow analysis and dead-code injection without fragile AST manipulation.
• Linker patches (internal/linker) — Strips function names and encrypts entry-point magic values at link time, preventing symbol recovery from binaries without source.
• Build cache integration (cache_pkg.go, cache_shared.go) — Preserves Go's build cache semantics; obfuscation is deterministic and reproducible, avoiding re-obfuscation of unchanged packages.
• Base64 hashing (hash.go) — Deterministic, compact, and reversible given source; enables stack-trace de-obfuscation via reverse.go.
• Multiple literal encoders (internal/literals) — Diverse obfuscation strategies (split, swap, shuffle, proxy) prevent pattern-based attacks on constant reconstruction.

• Wraps Go toolchain instead of replacing it

  • Why: Reuses Go's build cache, module system, and compiler—no need to fork or reimplement.
  • Consequence: Adds small overhead per build; limited to transformations compatible with standard Go build flow.

• Deterministic hashing for all identifiers

  • Why: Ensures reproducible, reversible obfuscation; enables binary caching and stack-trace de-obfuscation.
  • Consequence: Attackers with source code can regenerate the same hashes; requires keeping original source secret.

• SSA-level obfuscation with SSA-to-AST conversion (ssa2ast/)

  • Why: More robust than AST-only transforms; survives compiler optimization; avoids syntax errors.
  • Consequence: Complex bidirectional IR conversion; higher maintenance burden; limited to Go 1.26+.

• Reverse mapping file (debugdir) for stack-trace de-obfuscation

  • Why: Allows developers to map panic traces back to original source without distributing original code.
  • Consequence: Debug file is sensitive (contains mapping); must be kept secure or distributed separately from binary.

• Control-flow hardening (internal/ctrlflow) as optional feature

  • Why: Adds anti-tampering and anti-analysis measures beyond basic obfuscation.
  • Consequence: Increases binary size and runtime overhead; must be explicitly enabled; not all Go patterns supported.

• Does not provide cryptographic key derivation or encrypted binary execution.
• Does not obfuscate assembly or C code (via cgo); only transforms Go source and IR.
• Does not prevent reverse-engineering if original source code is compromised.
• Does not protect against runtime introspection via reflect or unsafe at deployment time.
• Does not obfuscate test binaries by default; garble test is separate from production builds.
• Not a code packer or runtime encryption tool

Go version coupling: Garble requires exact Go version matches for linker patches; mismatched Go version will fail silently. GOGARBLE env var: Obfuscation only applies to packages matching GOGARBLE patterns (comma-separated globs like GOPRIVATE); omitting this obfuscates everything, which may break reflection-dependent code. Determinism requires stable seed: hash.go uses go.mod hash as seed; changed dependencies change all hashes, breaking reproducibility. Linker patches are fragile: internal/linker/patches/ are Go version-specific (.patch files); upgrading Go can require new patches. No CGO support: Control flow hardening and some obfuscations don't work with cgo binaries. Test output obfuscation: garble test obfuscates test names, making failure attribution harder.

• Static Single Assignment (SSA) Form — Garble converts Go code to SSA (via golang.org/x/tools) to analyze and transform control flow; understanding SSA is critical for modifying internal/ctrlflow/ and internal/ssa2ast/
• Deterministic Hashing for Obfuscation — Garble uses content-addressed hashing (hash.go) to ensure the same source always produces the same obfuscated binary; this is non-obvious but essential for reproducible builds and debugging
• Polymorphic Obfuscation (Literal Pooling) — Multiple obfuscation strategies (split.go, swap.go, shuffle.go) are randomly selected per-literal to prevent pattern recognition; understanding this randomized-but-deterministic approach is key to internal/literals/
• Linker Patching and Binary Rewriting — Garble post-processes compiled binaries via internal/linker/ to strip metadata and inject custom patches; this low-level manipulation is Go-version-specific and requires understanding of ELF/Mach-O formats
• AST (Abstract Syntax Tree) Transformation — Garble transforms Go ASTs to rewrite identifiers and function signatures; internal/asthelper/ and internal/ssa2ast/ do this work; understanding Go's ast package is prerequisite
• Build Cache Integration — Garble wraps cmd/go to leverage Go's existing build cache (cache_pkg.go, cache_shared.go); this allows incremental obfuscation without recompiling unchanged packages, critical for usability
• Control Flow Graph (CFG) Flattening and Junk Code Injection — internal/ctrlflow/transform.go adds opaque predicates and unreachable blocks to complicate reverse engineering; understanding CFG analysis is necessary to extend this feature

• golang/go — Garble wraps Go's compiler and linker; understanding cmd/go and runtime internals is essential to extend garble
• rogpeppe/go-internal — Direct dependency (go.mod) for internal Go APIs and testing utilities; garble uses this to interact with Go's module system and build cache
• golang/tools — Dependency for golang.org/x/tools packages (SSA, type utilities); garble bundles typeutil.go and typeparams.go from this repo
• obfuscator-io/javascript-obfuscator — Conceptual parallel in the JavaScript ecosystem; demonstrates polymorphic obfuscation strategies (literal splitting, control flow hardening) applicable to Go
• yottadb/YottaDB — Example of a project using garble for source protection; demonstrates real-world usage pattern for proprietary Go binaries

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive tests for internal/literals obfuscators

The internal/literals package contains multiple obfuscation strategies (simple.go, split.go, swap.go, shuffle.go, proxy.go) but only has fuzz_test.go and random_testing.go. These obfuscators lack unit tests verifying correctness of each strategy independently. Adding targeted tests would catch regressions when modifying obfuscation logic and help new contributors understand expected behavior.

• [ ] Create internal/literals/simple_test.go with tests for literal splitting edge cases
• [ ] Create internal/literals/swap_test.go verifying byte/value swapping preserves semantics
• [ ] Create internal/literals/shuffle_test.go testing shuffle determinism and correctness
• [ ] Add tests for proxy.go verifying proxy function calls are properly obfuscated
• [ ] Document expected behavior for each obfuscator in docs or test comments

Add integration tests for Go version compatibility patches

The internal/linker/patches directory contains version-specific patches (go1.26) that modify the Go toolchain, but there's no CI workflow or test suite verifying these patches apply correctly and don't break the build across Go versions. This is critical for a tool that wraps the Go toolchain.

• [ ] Create .github/workflows/test-patches.yml to test patch application across Go 1.26+
• [ ] Add scripts/test_patches.sh to verify patches apply cleanly to each supported Go version
• [ ] Test in main_test.go that garble builds successfully with patched Go versions
• [ ] Document supported Go versions and patch application process in CONTRIBUTING.md

Add unit tests for SSA-to-AST conversion edge cases

The internal/ssa2ast package converts SSA IR back to Go AST (func.go, type.go) with existing test files (func_test.go, type_test.go, helpers_test.go), but coverage appears limited. Missing tests for type parameter handling, generic functions, and complex type conversions could cause subtle obfuscation failures.

• [ ] Review existing ssa2ast/*_test.go files and identify untested code paths
• [ ] Add tests in internal/ssa2ast/func_test.go for generic function conversion (leveraging bundled_typeparams.go)
• [ ] Add tests in internal/ssa2ast/type_test.go for complex types (interfaces, type params, constraints)
• [ ] Add tests for edge cases: empty structs, recursive types, unnamed function parameters
• [ ] Document SSA-to-AST conversion assumptions in docs/CONTROLFLOW.md or inline comments

• Add comprehensive tests for internal/ssa2ast/func.go—currently only func_test.go exists with limited cases; new contributor should add tests for edge cases like closures, deferred calls, and type switches
• Extend internal/literals/ with a new obfuscator strategy (e.g., XOR-based or base64-rotation); all obfuscators inherit from Obfuscator interface in obfuscators.go, so adding one is isolated and well-constrained
• Add missing documentation to docs/ for the -tiny flag behavior and its interaction with other obfuscation modes; currently only CONTROLFLOW.md exists, but -tiny is mentioned in README without design docs

The garble codebase demonstrates good security practices overall. It is a build tool focused on obfuscation rather than a security-critical system. The main risks are related to: (1) use of experimental golang.org/x/tools packages, (2) bundling of internal Go packages not part of the public API, (3) potential edge cases in code transformation logic, and (4) runtime patching of the Go toolchain. No hardcoded secrets, injection vulnerabilities, or misconfigured infrastructure were identified. Dependencies are well-maintained and appropriately scoped. The project maintains good practices with test coverage and documentation.

• Low · Potential Dependency Vulnerability - golang.org/x/tools — go.mod - golang.org/x/tools v0.44.0. The codebase depends on golang.org/x/tools v0.44.0, which is an experimental/development tool package. While this is typical for development, golang.org/x/tools packages can have lower stability guarantees than standard library packages. The bundled_typeutil.go and bundled_typeparams.go files suggest potential vendoring of experimental Go internals. Fix: Monitor golang.org/x/tools for security advisories. Consider regular updates and review any bundled/vendored code from this package for stability and security implications.
• Low · Use of Experimental/Internal Go Packages — bundled_typeutil.go, bundled_typeparams.go, internal/ssa2ast/*, go.mod. The codebase bundles and uses internal Go toolchain packages (visible in bundled_typeutil.go, bundled_typeparams.go, and internal/ssa2ast). These internal packages are not part of Go's public API and may change without notice, potentially introducing security or stability issues. Fix: Review bundled internal packages for security implications. Document why internal packages are necessary. Monitor Go release notes for breaking changes to internal APIs that could affect obfuscation correctness.
• Low · Potential Code Injection via Obfuscation Process — internal/ctrlflow/transform.go, internal/ssa2ast/, internal/literals/. The tool performs AST manipulation and code transformation (visible in internal/ctrlflow/transform.go, internal/ssa2ast/). While this is the tool's intended purpose, improper handling of user input during the obfuscation process could theoretically introduce security vulnerabilities in the generated binaries. Fix: Ensure all user-provided build flags and source code paths are properly validated. Review AST transformation logic for potential injection vectors. Maintain comprehensive test coverage for edge cases in code transformation.
• Low · Runtime Patching of Go Internals — runtime_patch.go, internal/linker/patches/, internal/linker/linker.go. The codebase patches the Go runtime and linker (visible in runtime_patch.go and internal/linker/patches/). These patches modify critical Go toolchain components, which could introduce security or stability issues if not properly reviewed and maintained across Go versions. Fix: Maintain comprehensive documentation of all runtime patches. Ensure patches are thoroughly tested with each supported Go version. Review patches for security implications and potential attack vectors. Keep patches minimal and focused.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.