-
-
Notifications
You must be signed in to change notification settings - Fork 11.1k
[stealth 06/11] Add garble obfuscation targets #8780
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
reflog
wants to merge
10
commits into
main
Choose a base branch
from
stealth/8768-garble-go
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
10 commits
Select commit
Hold shift + click to select a range
20b6efb
Add garble obfuscation targets
reflog f13ed64
Address review feedback for garble builds
reflog b9cca55
Ensure obfuscated desktop lib output dir
reflog 225475c
Simplify obfuscated Android target wiring
reflog f8660fa
fix: parse garble flags without globbing
reflog 4b7e000
fix: scope garble to local packages
reflog f957bb8
fix: pin garble version
reflog 3f88651
fix: centralize garble workflow version
reflog 999310f
fix: declare android workflow secrets
reflog 4e0635a
fix: rely on makefile garble version
reflog File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,110 @@ | ||
| # Stealth Go/native obfuscation | ||
|
|
||
| Stealth Go/native builds are opt-in. Normal Makefile targets continue to use | ||
| `go build` and `gomobile bind` directly. | ||
|
|
||
| ## Inputs | ||
|
|
||
| - `GARBLE_SEED` or `STEALTH_GARBLE_SEED` is required for every obfuscated | ||
| target. Use a base64-encoded seed from the stealth profile so support can | ||
| reproduce the build and use `garble reverse` when needed. | ||
| `GARBLE_SEED=random` is acceptable only for local, unreproducible smoke | ||
| builds. | ||
| - `GARBLE_FLAGS` defaults to `-literals`. Add `-tiny` only after accepting the | ||
| loss of useful panic and stack trace output. | ||
| - `GARBLE_LDFLAGS` defaults to `-w -s -buildid=` to strip symbol/debug tables | ||
| and the Go build ID from obfuscated artifacts. | ||
| - `GARBLE_GOGARBLE` defaults to `github.com/getlantern/lantern` so release | ||
| builds obfuscate local Go packages without forcing garble through every | ||
| dependency. Full dependency obfuscation can be attempted with | ||
| `GARBLE_GOGARBLE=*`, but dependency compatibility should be validated before | ||
| using that scope for a shipped artifact. | ||
|
|
||
| Treat release seeds as private support material. The Makefile suppresses command | ||
| echo for seed-bearing garble invocations, but release automation should still | ||
| keep the profile seed in a secret store alongside any private release metadata | ||
| needed for `garble reverse`. Record the exact `GARBLE_VERSION` and Go toolchain | ||
| version with each release. The Makefile defaults `GARBLE_VERSION` to `v0.16.0` | ||
| so CI and support builds use a reproducible tool version unless explicitly | ||
| overridden. | ||
|
|
||
| Install garble: | ||
|
|
||
| ```sh | ||
| make install-garble | ||
| ``` | ||
|
|
||
| ## Android | ||
|
|
||
| Build the Android AAR with garble and then produce the APK/AAB: | ||
|
|
||
| ```sh | ||
| STEALTH_GARBLE_SEED="$PROFILE_GARBLE_SEED" make android-release-ci-obfuscated | ||
| ``` | ||
|
|
||
| `gomobile bind` invokes `go build` internally, so the obfuscated target prepends | ||
| `scripts/garble-go` to `PATH`. That wrapper delegates non-build commands to the | ||
| real Go binary and runs only gomobile's internal `go build` through `garble`. | ||
|
|
||
| Reusable workflow callers can opt in without changing normal Android releases: | ||
|
|
||
| ```yaml | ||
| jobs: | ||
| build-android-stealth: | ||
| uses: ./.github/workflows/build-android.yml | ||
| secrets: inherit | ||
| with: | ||
| version: ${{ needs.set-metadata.outputs.version }} | ||
| build_type: stealth | ||
| installer_base_name: lantern-installer | ||
| obfuscate_go: true | ||
| ``` | ||
|
|
||
| The workflow consumes `secrets.STEALTH_GARBLE_SEED` when `obfuscate_go` is true. | ||
| This workflow does not generate Android app identities or stealth profiles. | ||
|
|
||
| ## Other native targets | ||
|
|
||
| Linux shared library: | ||
|
|
||
| ```sh | ||
| STEALTH_GARBLE_SEED="$PROFILE_GARBLE_SEED" make linux-obfuscated | ||
| ``` | ||
|
|
||
| Linux daemon: | ||
|
|
||
| ```sh | ||
| STEALTH_GARBLE_SEED="$PROFILE_GARBLE_SEED" make lanternd-linux-amd64-obfuscated | ||
| STEALTH_GARBLE_SEED="$PROFILE_GARBLE_SEED" make lanternd-linux-arm64-obfuscated | ||
| ``` | ||
|
|
||
| Desktop C shared library for a specific platform: | ||
|
|
||
| ```sh | ||
| STEALTH_GARBLE_SEED="$PROFILE_GARBLE_SEED" \ | ||
| GOOS=darwin GOARCH=arm64 LIB_NAME=bin/macos-arm64/liblantern.dylib \ | ||
| make desktop-lib-obfuscated | ||
| ``` | ||
|
|
||
| ## ABI and support constraints | ||
|
|
||
| These boundaries are externally visible and their public names cannot be | ||
| obfuscated without breaking consumers: | ||
|
|
||
| - Gomobile binding packages in `GOMOBILE_REPOS`: | ||
| `github.com/sagernet/sing-box/experimental/libbox`, | ||
| `./lantern-core/mobile`, and `./lantern-core/utils`. Java/Kotlin bindings | ||
| are generated from exported Go APIs, and garble currently keeps exported | ||
| methods/functions visible. | ||
| - Desktop FFI package `./lantern-core/ffi`. Every `//export` function in | ||
| `lantern-core/ffi/ffi.go` is a C ABI symbol used by Flutter FFI and generated | ||
| headers; examples include `setup`, `startVPN`, `stopVPN`, `login`, `logout`, | ||
| and `freeCString`. | ||
| - Crash and support tooling. `lantern-core/utils.RunOffCgoStack` records | ||
| `runtime/debug.Stack`; garble `-tiny` removes runtime panic and trace output, | ||
| so it should not be the default for supportable builds. | ||
|
|
||
| Validation before shipping a stealth artifact should include Android connect, | ||
| auth, config fetch, and proxy/no-VPN smoke tests, plus a check that protobuf | ||
| marshal/unmarshal paths and gomobile exported calls still work with the selected | ||
| `GARBLE_GOGARBLE` scope. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,52 @@ | ||
| #!/usr/bin/env bash | ||
| set -euo pipefail | ||
|
|
||
| real_go="${GARBLE_REAL_GO:-}" | ||
| garble_bin="${GARBLE_BIN:-garble}" | ||
| seed="${GARBLE_SEED:-}" | ||
|
|
||
| if [[ -z "$real_go" ]]; then | ||
| echo "garble go wrapper: GARBLE_REAL_GO is not set" >&2 | ||
| exit 2 | ||
| fi | ||
|
|
||
| if [[ ! -x "$real_go" ]]; then | ||
| echo "garble go wrapper: GARBLE_REAL_GO is not executable: $real_go" >&2 | ||
| exit 2 | ||
| fi | ||
|
|
||
| if [[ $# -eq 0 ]]; then | ||
| exec "$real_go" | ||
| fi | ||
|
|
||
| case "$1" in | ||
| build) | ||
| if [[ -z "$seed" ]]; then | ||
| echo "garble go wrapper: GARBLE_SEED is required for obfuscated go build" >&2 | ||
| exit 2 | ||
| fi | ||
| if ! command -v "$garble_bin" >/dev/null 2>&1; then | ||
| echo "garble go wrapper: garble not found. Set GARBLE_BIN or run 'make install-garble'." >&2 | ||
| exit 2 | ||
| fi | ||
|
|
||
| if [[ -n "${GARBLE_GOGARBLE:-}" ]]; then | ||
| export GOGARBLE="$GARBLE_GOGARBLE" | ||
| else | ||
| unset GOGARBLE | ||
| fi | ||
|
|
||
| garble_flags=() | ||
| if [[ -n "${GARBLE_FLAGS:-}" ]]; then | ||
| # GARBLE_FLAGS is intentionally simple make/CI input such as "-literals -tiny". | ||
| # Split on shell whitespace without pathname expansion. | ||
| read -r -a garble_flags <<< "${GARBLE_FLAGS}" | ||
| fi | ||
|
|
||
| real_go_dir="$(dirname "$real_go")" | ||
| exec env PATH="$real_go_dir:$PATH" "$garble_bin" "${garble_flags[@]}" -seed="$seed" "$@" | ||
| ;; | ||
| *) | ||
| exec "$real_go" "$@" | ||
| ;; | ||
| esac |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.