From 522e0d83452c03c54d4a887ba0a1a5c733c3f2df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Mart=C3=AD?= Date: Mon, 9 Dec 2019 10:09:27 +0000 Subject: [PATCH] add README --- README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..e55ac7f --- /dev/null +++ b/README.md @@ -0,0 +1,45 @@ +# garble + +Obfuscate a Go build. + + garble build [build flags] [packages] + +which is equivalent to the longer: + + go build -a -trimpath -toolexec=garble [build flags] [packages] + +### Purpose + +Produce a binary that works as well as a regular build, but that has as little +information about the original source code as possible. + +The tool is designed to be: + +* Coupled with `cmd/go`, to support both `GOPATH` and modules with ease +* Deterministic, though the output is not yet reproducible +* eversible + +### Mechanism + +The tool wraps calls to the Go compiler to transform the Go source code, in +order to: + +* Replace as many useful identifiers as possible with short base64 hashes +* Remove [module build information](https://golang.org/pkg/runtime/debug/#ReadBuildInfo) +* Remove comments and empty lines, to make position info less useful + +It also wraps calls to the linker in order to: + +* Enforce the `-s` flag, to not include the symbol table +* Enforce the `-w` flag, to not include DWARF debugging data + +Finally, the tool requires the use of the `-trimpath` build flag, to ensure the +binary doesn't include paths from the current filesystem. + +### Caveats + +The `-a` flag for `go build` is required, since `-toolexec` doesn't work well +with the build cache; see [#27628](https://github.com/golang/go/issues/27628). + +Since no caching at all can take place right now (see the link above), builds +will be slower than `go build` - especially for large projects.