mathtechstudio/ohmyg0sh repository overview

⁠ohmyg0sh

ohmyg0sh is an APK security scanner that decompiles packages with jadx, applies a curated library of credential and secret patterns, filters false positives, and produces text or JSON reports.

⁠Table of Contents

• ohmyg0sh⁠
  • Table of Contents⁠
  • Features⁠
    • Recent Improvements (v1.71.0)⁠
  • Installation⁠
    • Global CLI (Recommended)⁠
    • Project Dependency⁠
    • Docker⁠
  • Requirements⁠
    • Installing jadx⁠
  • Quick Start⁠
    • CLI⁠
    • Programmatic API⁠
  • Configuration⁠
    • Custom Patterns (regexes.json)⁠
    • False Positive Filters (notkeyhacks.json)⁠
  • Built-in Patterns⁠
  • Output Examples⁠
    • Text⁠
    • JSON⁠
  • CLI Reference⁠
  • How It Works⁠
  • Troubleshooting⁠
    • jadx Not Found⁠
    • jadx Exits with Errors⁠
    • Custom Pattern Resolution⁠
  • Docker Usage⁠
  • Development⁠
  • Contributing⁠
  • Security Notes⁠
  • Acknowledments⁠
  • License⁠

⁠Features

• Scan Android APKs for hardcoded credentials before release
• 50+ bundled regex patterns covering major cloud, social, payment, and developer platforms
• Customizable detection rules and false-positive filters
• Human-readable text reports and machine-friendly JSON output
• Streamed CLI updates with noisy jadx error lines suppressed
• Programmatic API and Docker image for automation pipelines

⁠Recent Improvements (v1.71.0)

• Structured error types (ApkError, JadxError, ConfigurationError, ScanError)
• Configurable concurrency control (default: 16, adjustable via scanConcurrency)
• Progress reporting for long-running scans
• Enhanced enums and type-safe data models
• Modular architecture with utility classes
• Comprehensive API documentation with usage examples

⁠Installation

⁠Global CLI (Recommended)

dart pub global activate ohmyg0sh

# then
ohmyg0sh -f app-release.apk

⁠Project Dependency

dependencies:
  ohmyg0sh: ^1.70.0

dart pub get

⁠Docker

docker pull mathtechstudio/ohmyg0sh:latest
docker run -it --rm -v "$PWD":/work -w /work mathtechstudio/ohmyg0sh:latest -f /work/app-release.apk

⁠Requirements

• Dart SDK ^3.5
• Java 11 or newer (required by jadx)
• jadx installed and available on PATH, or passed with --jadx

⁠Installing jadx

# macOS
brew install jadx

# Linux / Windows
# Download from https://github.com/skylot/jadx/releases and add the binary to PATH

⁠Quick Start

⁠CLI

# Basic scan
ohmyg0sh -f app-release.apk

# JSON results
ohmyg0sh -f app-release.apk --json -o results.json

# Custom patterns & extra jadx flags
ohmyg0sh -f app-release.apk -p custom/regexes.json -a "--deobf --log-level INFO"

⁠Programmatic API

import 'package:ohmyg0sh/ohmyg0sh.dart';

Future<void> main() async {
  final scanner = OhMyG0sh(
    apkPath: './app-release.apk',
    outputJson: true,
    outputFile: 'results.json',
  );

  await scanner.run();
}

Advanced Usage with Error Handling:

import 'package:ohmyg0sh/ohmyg0sh.dart';

Future<void> main() async {
  final scanner = OhMyG0sh(
    apkPath: './app-release.apk',
    outputJson: true,
    outputFile: 'results.json',
    scanConcurrency: 32,        // Adjust for performance
    showProgress: true,          // Display progress
    continueOnJadxError: true,  // Continue on partial failures
  );

  try {
    await scanner.run();
    print('✓ Scan completed successfully');
  } on ApkError catch (e) {
    print('❌ APK Error: ${e.message}');
  } on JadxError catch (e) {
    print('❌ JADX Error: ${e.message}');
  } on ConfigurationError catch (e) {
    print('❌ Configuration Error: ${e.message}');
  } catch (e) {
    print('❌ Unexpected Error: $e');
  }
}

For detailed error scenarios and solutions, see ERROR_SCENARIOS.md⁠.

⁠Configuration

⁠Custom Patterns (regexes.json)

// your-fucking-rules.json
{
  "Google_API_Key": "AIza[0-9A-Za-z\\-_]{35}",
  "AWS_Access_Key": "AKIA[0-9A-Z]{16}",
  "Custom_Token": "myapp_[a-f0-9]{32}"
  // ...
}

Use via ohmyg0sh -f app.apk -p my-patterns.json.

⁠False Positive Filters (notkeyhacks.json)

{
  "patterns": ["example\\.com"],
  "contains": ["PLACEHOLDER"],
  "Google_API_Key": ["AIzaGRAPHIC_DESIGN"]
}

Use via ohmyg0sh -f app.apk -n my-filters.json.

⁠Built-in Patterns

Bundled rules detect secrets across:

• Cloud: AWS, Google Cloud, Azure, DigitalOcean
• Social & Comms: Facebook, Twitter, Slack, Discord
• Payments: Stripe, PayPal, Square, Braintree
• Developer Services: GitHub, GitLab, Mailgun, Cloudinary
• Databases & Keys: MongoDB, Postgres, private key blocks

Review the full list in config/regexes.json⁠.

⁠Output Examples

⁠Text

** Scanning against 'com.example.app'

[Google_API_Key]
- AIzaSyD...

** Results saved into 'results_1234567890.txt'.

⁠JSON

{
  "package": "com.example.app",
  "results": [
    {
      "name": "Google_API_Key",
      "matches": ["AIzaSyD..."]
    }
  ],
  "generated_at": "2025-10-07T14:00:00Z",
  "generated_by": "ohmyg0sh",
  "repository": "https://github.com/mathtechstudio/ohmyg0sh",
  "pub_dev": "https://pub.dev/packages/ohmyg0sh"
}

⁠CLI Reference

⁠How It Works

1. Decompile APK with jadx
2. Extract package metadata
3. Scan Java, Kotlin, Smali, XML, JS, and TXT sources
4. Match regex patterns against file contents
5. Filter via notkeyhacks rules
6. Report grouped matches to disk in the requested format

⁠Troubleshooting

⁠jadx Not Found

brew install jadx       # macOS
which jadx && jadx --version

Or run with --jadx /custom/path/to/jadx.

⁠jadx Exits with Errors

OhMyG0sh continues when usable artifacts exist and suppresses the noisy ERROR - finished with errors line. For verbose logs use:

ohmyg0sh -f app.apk -a "--log-level DEBUG"

⁠Custom Pattern Resolution

Search order:

1. --pattern path (if provided)
2. /app/config/regexes.json (Docker image)
3. package:ohmyg0sh/config/regexes.json (pub install)
4. ./config/regexes.json
5. Executable-relative fallback

⁠Docker Usage

alias ohmyg0sh='docker run --rm -it -v "$PWD":/work -w /work mathtechstudio/ohmyg0sh:latest'
ohmyg0sh -f app-release.apk

With custom patterns:

docker run -it --rm \
  -v "$PWD":/work \
  -v "$PWD/patterns.json":/patterns.json \
  -w /work \
  mathtechstudio/ohmyg0sh:latest \
  -f /work/app.apk -p /patterns.json

⁠Development

git clone https://github.com/mathtechstudio/ohmyg0sh.git
cd ohmyg0sh
dart pub get
dart run bin/ohmyg0sh.dart -f app-release.apk
dart test

⁠Contributing

1. Fork the repository
2. Create a feature branch
3. Implement and test your changes
4. Submit a pull request

⁠Security Notes

• Use only on APKs you are authorized to assess
• Review findings manually to confirm leaks
• Rotate exposed credentials immediately
• Report vulnerabilities responsibly

⁠Acknowledments

Since this tool includes some contributions, and I'm not an asshole, I'll publically thank the following users for their helps and resources:

Contributors

⁠License

Released under the MIT License - see the MIT License⁠ file for details.

Star on GitHub⁠ | View on pub.dev⁠ | Docker⁠ | Report Issues⁠