ethan zhou 7223ea2c4a
feat(playscan): scan Android projects against Google Play policies (#17)
* feat(playscan): scan Android projects against Google Play policies

Adds a Google Play tier alongside the existing App Store checks. Android
projects are detected automatically, including the android/ directory of an
Expo or React Native app, so a cross-platform repo is checked against both
stores in one pass. Also available standalone as `greenlight playscan`.

Deadline checks, both landing 2026-08-31:
- Target API level: CRITICAL below API 35, HIGH below 36, with a live
  day countdown
- Play Billing Library 7 and below, which has no direct v7 to v9 path

Policy checks:
- Restricted permissions: SMS and Call Log (including the 2026-07-15 change
  dropping phone-call account verification), All files access,
  QUERY_ALL_PACKAGES, REQUEST_INSTALL_PACKAGES, background location, broad
  photo/video access, accessibility service, overlays, device admin, usage
  stats, contacts
- Foreground service types missing their FOREGROUND_SERVICE_* permission,
  which throws at startForeground() on Android 14+
- android:exported missing on components with an intent filter, debuggable,
  cleartext traffic
- Ads SDK without the AD_ID permission, which silently zeroes the ad ID
- Account creation without both in-app and web deletion paths

Every finding carries a Doc link to the policy page it comes from. Play
policies are named rather than numbered and change often, so the citation is
worth more than a section reference.

The Apple scanners now skip only when a project is unambiguously
Android-only. Previously every pure-Android repo led with a CRITICAL for a
missing PrivacyInfo.xcprivacy, an iOS-only requirement. iOS-only and
cross-platform projects are unaffected.

targetSdk is resolved from the app module, convention plugins, version
catalogs, gradle.properties, and named constants, since most real projects
reach it through a reference rather than a literal. lint.targetSdk and
testOptions.targetSdk are explicitly excluded. When it cannot be resolved the
scan says so rather than reporting a pass.

Scope is documented in the README and command help: this reads the pre-merge
manifest, so permissions contributed by library manifests are not visible
until the build merges them.

Validated against nowinandroid, AnkiDroid, Thunderbird, Pocket Casts,
DuckDuckGo, and Mattermost, with every finding checked against source.

* feat(playscan): scan built APKs and AABs, with 16 KB page size checks

Adds `greenlight playscan --apk` / `--aab`, closing the gap the source scan
documents: a repo's AndroidManifest.xml is the pre-merge manifest, so
permissions contributed by library manifests are invisible until build time.
A built artifact carries the merged manifest, so its permission list is
complete.

Every existing policy rule runs unchanged against the decoded manifest. The
archive scan adds the native code checks, which only exist at this layer:

- 16 KB page size: ELF LOAD segment alignment on arm64-v8a, 16 KB zip
  alignment of uncompressed libraries, and GNU_RELRO presence. Google Play
  requires apps targeting Android 15+ to support 16 KB memory pages; an
  unaligned library fails to load and crashes at startup on those devices.

Both container formats are decoded in pure Go with no new dependencies, so no
Android SDK, aapt2, or bundletool is required:

- APK: Android binary XML, including the string pool in both UTF-8 and UTF-16
  form and the resource ID map. aapt2 emits an empty string-pool entry for
  framework attributes and identifies them only by resource ID, so without the
  map every android:* attribute reads as unnamed.
- AAB: the protobuf-encoded manifest, walked directly off the wire format.

foregroundServiceType is a bitmask once compiled; it is rendered back to the
pipe-separated names the source manifest uses so the foreground service rule
needs no second code path.

Only arm64-v8a is assessed for 16 KB alignment. 16 KB page size devices are
64-bit ARM, so flagging a 32-bit library at 4 KB would be noise.

Verified against real APKs. Termux 0.118.3 decodes to exactly the 15
permissions in its published source manifest, and its 4 KB aligned libraries
are flagged; F-Droid's 16 KB aligned library is not. Alignment findings were
cross-checked by parsing the ELF program headers independently.

* fix(playscan): address code review findings

Two denial-of-service bugs in the binary parsers, both reachable through the
stated threat model of scanning an archive someone handed you, and both
reproduced before and after the fix:

- protoxml: the decoder recursed once per manifest nesting level with no
  bound. A deeply nested AAB drove a Go stack overflow, which is a process
  abort recover() cannot catch. An 8.9 MB file was enough. Now capped at 100
  levels, matching Android's own parser; the repro drops to 0.35s / 22 MB and
  reports an undecodable manifest.
- axml: attrCount is a uint16 read straight from the file and need not match
  the bytes present, but it was used directly to size an allocation. A 97 KB
  APK of 36-byte chunks each claiming 65535 attributes cost 65s CPU and
  1.46 GB RSS. Capped by the chunk's actual capacity; the repro drops to
  0.04s / 110 MB.

Correctness:

- protoxml decoded compiled values against a guessed schema. Primitive's oneof
  is non-contiguous in Resources.proto (float=3, int_decimal=6, int_hex=7,
  boolean=8), and the code treated field 3 as the boolean, so every compiled
  boolean in a bundle was misread and an AAB's debuggable=true was missed
  entirely. Now decodes Item.str and Item.prim against the real field numbers.
- The BIND_* permissions are never requested via <uses-permission>; the
  framework requires them as the bound component's android:permission. Those
  rules could therefore never fire. Component permissions are now inspected,
  and BIND_VPN_SERVICE is covered alongside accessibility and device admin.
- Every foreground service needs the base FOREGROUND_SERVICE permission from
  API 28 regardless of type. Only the type-specific permissions were checked,
  so an app missing the base one was reported clean.
- Gradle file ranking assumed the app module is named "app", the same
  assumption already fixed for manifest selection. Ranking is now tied to the
  module the selected manifest belongs to, so a library module's targetSdk
  cannot be reported as the app's.
- The Billing Library version had to be a literal, but most builds reach it
  through a variable or a version catalog version.ref, so the support-window
  check silently never fired on them. Both forms now resolve. This surfaces a
  real finding on Thunderbird, which ships Billing 7.1.1 via version.ref.
- detectIOS missed Objective-C sources and app.config.json, either of which
  could classify a cross-platform repo as Android-only and skip the Apple
  scanners.

Also drops GradleInfo.CompileSDK and .Dependencies, which were written or
declared but never read, and serializes an empty findings list as [] rather
than null.

---------

Co-authored-by: ethan zhou <231755529+ethanzhoucool@users.noreply.github.com>
2026-07-27 16:47:29 -07:00

67 lines
2.0 KiB
Go

package cli
import (
"errors"
"fmt"
"github.com/fatih/color"
"github.com/spf13/cobra"
)
var (
appVersion string
verbose bool
)
// ErrThreshold is returned by scan commands when --exit-code is set and the
// findings cross the failure threshold. main() maps it to a non-zero exit status
// without printing anything — the report is already the user-facing output.
var ErrThreshold = errors.New("findings exceeded --exit-code threshold")
var purple = color.New(color.FgHiMagenta)
var dim = color.New(color.Faint)
var rootCmd = &cobra.Command{
Use: "greenlight",
Short: "Pre-submission compliance scanner for the App Store and Google Play",
Long: fmt.Sprintf(`%s
Greenlight scans your app against Apple's App Store Review Guidelines and
Google Play's Developer Program Policies before you submit, catching
rejection risks so you ship with confidence.
Get started:
greenlight preflight . Run ALL checks — one command, zero uploads
greenlight preflight . --ipa X Include IPA binary analysis
greenlight playscan . Google Play policies + target API deadline
greenlight scan --app-id ID Check App Store Connect metadata (needs API key)
greenlight guidelines search Browse Apple's review guidelines`,
purple.Sprint("greenlight — know before you submit.")),
}
func SetVersion(v string) {
appVersion = v
// Enables `greenlight --version` (cobra auto-adds the flag when set).
rootCmd.Version = resolveVersion()
}
func Execute() error {
return rootCmd.Execute()
}
func init() {
// Errors are printed by main() (so --exit-code's sentinel can exit quietly);
// usage on a runtime error is just noise.
rootCmd.SilenceErrors = true
rootCmd.SilenceUsage = true
rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "verbose output")
// Match the `version` subcommand's wording ("greenlight <v>") for `--version`.
rootCmd.SetVersionTemplate("greenlight {{.Version}}\n")
rootCmd.AddCommand(scanCmd)
rootCmd.AddCommand(authCmd)
rootCmd.AddCommand(guidelinesCmd)
rootCmd.AddCommand(versionCmd)
}