|
|
|
|
# garble
|
|
|
|
|
|
|
|
|
|
go install mvdan.cc/garble@latest
|
|
|
|
|
|
|
|
|
|
Obfuscate Go code by wrapping the Go toolchain. Requires Go 1.16 or later.
|
|
|
|
|
|
|
|
|
|
garble build [build flags] [packages]
|
|
|
|
|
|
|
|
|
|
The tool also supports `garble test` to run tests with obfuscated code,
|
|
|
|
|
and `garble reverse` to de-obfuscate text such as stack traces.
|
|
|
|
|
See `garble -h` for up to date usage information.
|
|
|
|
|
|
|
|
|
|
### 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:
|
|
|
|
|
|
initial support for build caching (#142)
As per the discussion in https://github.com/golang/go/issues/41145, it
turns out that we don't need special support for build caching in
-toolexec. We can simply modify the behavior of "[...]/compile -V=full"
and "[...]/link -V=full" so that they include garble's own version and
options in the printed build ID.
The part of the build ID that matters is the last, since it's the
"content ID" which is used to work out whether there is a need to redo
the action (build) or not. Since cmd/go parses the last word in the
output as "buildID=...", we simply add "+garble buildID=_/_/_/${hash}".
The slashes let us imitate a full binary build ID, but we assume that
the other components such as the action ID are not necessary, since the
only reader here is cmd/go and it only consumes the content ID.
The reported content ID includes the tool's original content ID,
garble's own content ID from the built binary, and the garble options
which modify how we obfuscate code. If any of the three changes, we
should use a different build cache key. GOPRIVATE also affects caching,
since a different GOPRIVATE value means that we might have to garble a
different set of packages.
Include tests, which mainly check that 'garble build -v' prints package
lines when we expect to always need to rebuild packages, and that it
prints nothing when we should be reusing the build cache even when the
built binary is missing.
After this change, 'go test' on Go 1.15.2 stabilizes at about 8s on my
machine, whereas it used to be at around 25s before.
5 years ago
|
|
|
* Coupled with `cmd/go`, to support modules and build caching
|
|
|
|
|
* Deterministic and reproducible, given the same initial source code
|
|
|
|
|
* Reversible given the original source, to de-obfuscate panic stack traces
|
|
|
|
|
|
|
|
|
|
### Mechanism
|
|
|
|
|
|
|
|
|
|
The tool wraps calls to the Go compiler and linker to transform the Go build, in
|
|
|
|
|
order to:
|
|
|
|
|
|
|
|
|
|
* Replace as many useful identifiers as possible with short base64 hashes
|
|
|
|
|
* Replace package paths with short base64 hashes
|
|
|
|
|
* Remove all [build](https://golang.org/pkg/runtime/#Version) and [module](https://golang.org/pkg/runtime/debug/#ReadBuildInfo) information
|
|
|
|
|
* Strip filenames and shuffle position information
|
|
|
|
|
* Strip debugging information and symbol tables via `-ldflags="-w -s"`
|
|
|
|
|
* [Obfuscate literals](#literal-obfuscation), if the `-literals` flag is given
|
|
|
|
|
* Remove [extra information](#tiny-mode), if the `-tiny` flag is given
|
|
|
|
|
|
|
|
|
|
By default, the tool obfuscates the packages under the current module. If not
|
|
|
|
|
running in module mode, then only the main package is obfuscated. To specify
|
prepare for the first release (#264)
First, write a changelog file. We will use GitHub releases, but the
content in those is not stored in git nor is it portable or machine
readable. The canonical place for the changelog is here.
Second, disable 'garble test', as it is entirely broken. Issue #241
tracks fixing and re-enabling it, which will most likely happen for the
next release.
Third, disable the undocumented 'garble list'. This was added as part of
'garble reverse', but it never got used. I can't think of any reason why
any end user would prefer it over 'go list', either.
'garble reverse' remains enabled, but undocumented as it isn't fully
functional yet. Until it supports position information, it's not
particularly useful to end users. But it's not broken either, so it can
remain where it is.
Fourth, update the '-tiny' size reduction numbers in the README. Since
we removed the in-place modification of object files, we are no longer
able to do such an aggressive stripping of info. Garble itself drops in
size by 2%, so replace the old 6-10% estimate by 2-5%. We probably will
gain some of this back in the near future.
Finally, fix the indentation formatting of the README to consistently
use tabs.
4 years ago
|
|
|
what packages to obfuscate, set `GOPRIVATE`, documented at `go help private`.
|
|
|
|
|
|
|
|
|
|
Note that commands like `garble build` will use the `go` version found in your
|
|
|
|
|
`$PATH`. To use different versions of Go, you can
|
|
|
|
|
[install them](https://golang.org/doc/manage-install#installing-multiple)
|
|
|
|
|
and set up `$PATH` with them. For example, for Go 1.16.1:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
$ go install golang.org/dl/go1.16.1@latest
|
|
|
|
|
$ go1.16.1 download
|
|
|
|
|
$ PATH=$(go1.16.1 env GOROOT)/bin:${PATH} garble build
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Literal obfuscation
|
|
|
|
|
|
|
|
|
|
Using the `-literals` flag causes literal expressions such as strings to be
|
|
|
|
|
replaced with more complex variants, resolving to the same value at run-time.
|
|
|
|
|
This feature is opt-in, as it can cause slow-downs depending on the input code.
|
|
|
|
|
|
|
|
|
|
Literal expressions used as constants cannot be obfuscated, since they are
|
|
|
|
|
resolved at compile time. This includes any expressions part of a `const`
|
|
|
|
|
declaration.
|
|
|
|
|
|
|
|
|
|
### Tiny mode
|
|
|
|
|
|
|
|
|
|
When the `-tiny` flag is passed, extra information is stripped from the resulting
|
|
|
|
|
Go binary. This includes line numbers, filenames, and code in the runtime that
|
|
|
|
|
prints panics, fatal errors, and trace/debug info. All in all this can make binaries
|
|
|
|
|
2-5% smaller in our testing, as well as prevent extracting some more information.
|
|
|
|
|
|
|
|
|
|
With this flag, no panics or fatal runtime errors will ever be printed, but they
|
|
|
|
|
can still be handled internally with `recover` as normal. In addition, the
|
|
|
|
|
`GODEBUG` environmental variable will be ignored.
|
|
|
|
|
|
|
|
|
|
Note that this flag can make debugging crashes harder, as a panic will simply
|
|
|
|
|
exit the entire program without printing a stack trace, and all source code
|
|
|
|
|
positions are set to line 1. Similarly, `garble reverse` is generally not useful
|
|
|
|
|
in this mode.
|
|
|
|
|
|
|
|
|
|
### Speed
|
|
|
|
|
|
|
|
|
|
`garble build` should take about twice as long as `go build`, as it needs to
|
|
|
|
|
complete two builds. The original build, to be able to load and type-check the
|
|
|
|
|
input code, and finally the obfuscated build.
|
|
|
|
|
|
|
|
|
|
Go's build cache is fully supported; if a first `garble build` run is slow, a
|
|
|
|
|
second run should be significantly faster. This should offset the cost of the
|
|
|
|
|
double builds, as incremental builds in Go are fast.
|
|
|
|
|
|
|
|
|
|
### Determinism and seeds
|
|
|
|
|
|
|
|
|
|
Just like Go, garble builds are deterministic and reproducible if the inputs
|
|
|
|
|
remain the same: the version of Go, the version of Garble, and the input code.
|
|
|
|
|
This has significant benefits, such as caching builds or being able to use
|
|
|
|
|
`garble reverse` to de-obfuscate stack traces.
|
|
|
|
|
|
|
|
|
|
However, it also means that an input package will be obfuscated in exactly the
|
|
|
|
|
same way if none of those inputs change. If you want two builds of your program
|
|
|
|
|
to be entirely different, you can use `-seed` to provide a new seed for the
|
|
|
|
|
entire build, which will cause a full rebuild.
|
|
|
|
|
|
|
|
|
|
If any open source packages are being obfuscated, providing a custom seed can
|
|
|
|
|
also provide extra protection. It could be possible to guess the versions of Go
|
|
|
|
|
and garble given how a public package was obfuscated without a seed.
|
|
|
|
|
|
|
|
|
|
### Caveats
|
|
|
|
|
|
|
|
|
|
Most of these can improve with time and effort. The purpose of this section is
|
|
|
|
|
to document the current shortcomings of this tool.
|
|
|
|
|
|
|
|
|
|
* Exported methods are never obfuscated at the moment, since they could
|
detect more std API calls which use reflection
Before, we would just notice direct calls to reflect's TypeOf and
ValueOf. Any other uses of reflection, such as encoding/json or
google.golang.org/protobuf, would require hints as documented by the
README.
Issue #162 outlines some ways we could fix this issue in a general way,
automatically detecting what functions use reflection on their parameters,
even for third party API funcs.
However, that goal is pretty significant in terms of code and effort.
As a temporary improvement, we can expand the list of "known" reflection
APIs via a static table.
Since this table is keyed by "func full name" strings, we could
potentially include third party APIs, such as:
google.golang.org/protobuf/proto.Marshal
However, for now simply include all the std APIs we know about.
If we fail to do the proper fix for automatic detection in the future,
we can then fall back to expanding this global table for third parties.
Update the README's docs, to clarify that the hint is not always
necessary anymore.
Also update the reflect.txt test to stop using the hint for encoding/json,
and to also start testing text/template with a method call.
While at it, I noticed that we weren't testing the println outputs,
as they'd go to stderr - fix that too.
Updates #162.
4 years ago
|
|
|
be required by interfaces and reflection. This area is a work in progress; see
|
|
|
|
|
[#3](https://github.com/burrowers/garble/issues/3).
|
|
|
|
|
|
|
|
|
|
* If your program breaks due to an issue with reflection please [open an issue](https://github.com/burrowers/garble/issues/new),
|
|
|
|
|
we'll try to resolve new edge cases.
|
|
|
|
|
|
|
|
|
|
* Go declarations exported for cgo via `//export` are not obfuscated.
|
|
|
|
|
|
|
|
|
|
* Go plugins are not currently supported; see [#87](https://github.com/burrowers/garble/issues/87).
|
|
|
|
|
|
|
|
|
|
### Contributing
|
obfuscate unexported names like exported ones (#227)
In 90fa325da7, the obfuscation logic was changed to use hashes for
exported names, but incremental names starting at just one letter for
unexported names. Presumably, this was done for the sake of binary size.
I argue that this is not a good idea for the default mode for a number
of reasons:
1) It makes reversing of stack traces nearly impossible for unexported
names, since replacing an obfuscated name "c" with "originalName"
would trigger too many false positives by matching single characters.
2) Exported and unexported names aren't different. We need to know how
names were obfuscated at a later time in both cases, thanks to use
cases like -ldflags=-X. Using short names for one but not the other
doesn't make a lot of sense, and makes the logic inconsistent.
3) Shaving off three bytes for unexported names doesn't seem like a huge
deal for the default mode, when we already have -tiny to optimize for
size.
This saves us a bit of work, but most importantly, simplifies the
obfuscation state as we no longer need to carry privateNameMap between
the compile and link stages.
name old time/op new time/op delta
Build-8 153ms ± 2% 150ms ± 2% ~ (p=0.065 n=6+6)
name old bin-B new bin-B delta
Build-8 7.09M ± 0% 7.08M ± 0% -0.24% (p=0.002 n=6+6)
name old sys-time/op new sys-time/op delta
Build-8 296ms ± 5% 277ms ± 6% -6.50% (p=0.026 n=6+6)
name old user-time/op new user-time/op delta
Build-8 562ms ± 1% 558ms ± 3% ~ (p=0.329 n=5+6)
Note that I do not oppose using short names for both exported and
unexported names in the future for -tiny, since reversing of stack
traces will by design not work there. The code can be resurrected from
the git history if we want to improve -tiny that way in the future, as
we'd need to store state in header files again.
Another major cleanup we can do here is to no longer use the
garbledImports map. From a look at obfuscateImports, we hash a package's
import path with its action ID, much like exported names, so we can
simply re-do that hashing for the linker's -X flag.
garbledImports does have some logic to handle duplicate package names,
but it's worth noting that should not affect package paths, as they are
always unique. That area of code could probably do with some
simplification in the future, too.
While at it, make hashWith panic if either parameter is empty.
obfuscateImports was hashing the main package path without a salt due to
a bug, so we want to catch those in the future.
Finally, make some tiny spacing and typo tweaks to the README.
4 years ago
|
|
|
|
|
|
|
|
We welcome new contributors. If you would like to contribute, see
|
|
|
|
|
[CONTRIBUTING.md](CONTRIBUTING.md) as a starting point.
|
