WAIT — Single-maintainer risk — review before adopting

• Last commit 4w ago
• 16 active contributors
• Other licensed
• CI configured
• ⚠ Single-maintainer risk — top contributor 82% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

GHunt is an offensive Google OSINT framework written in Python that extracts intelligence from Google services (Gmail, Drive, Calendar, Play Games, etc.) by leveraging authenticated Google accounts. It provides both a CLI tool and Python library API for reconnaissance on email addresses, Gaia IDs, and Drive files, with fully async operations and JSON export capabilities. Modular plugin architecture: ghunt/apis/ contains 14 Google service modules (accounts.py, drive.py, calendar.py, etc.), ghunt/helpers/ provides higher-level wrappers (auth.py, drive.py, gmail.py), and ghunt/knowledge/ holds data structures and service metadata. CLI entry point in ghunt/cli.py routes to specific commands, with examples/ containing runnable demos.

OSINT researchers, penetration testers, and security professionals who need to gather intelligence on Google account holders and their associated data. Developers building OSINT automation workflows who want a Python library abstraction over Google's undocumented APIs.

Actively maintained—explicitly Python 3.13 compatible with recent updates noted in README. No test suite visible in file structure suggests experimental/prototype stage. Single maintainer (mxrch) with AGPL licensing indicates serious project but limited peer review. Likely production-capable for specific OSINT use cases but with stability risks.

Single maintainer (mxrch) with no visible CI/CD pipeline (.github/workflows only contain sponsors.yml, no test runs). Reverse-engineered Google API endpoints are fragile and subject to breakage on Google's side. No dependency version pinning visible in file list. AGPL licensing creates compliance burden for commercial users.

No commit history visible in file structure, but README indicates recent Python 3.13 compatibility work. Companion browser extension (Firefox/Chrome) for streamlined authentication is actively maintained with separate distribution. Wiki documentation is being built at docs level.

pip3 install pipx
pipx ensurepath
pipx install ghunt
ghunt login

Or for library usage: pip3 install ghunt then import ghunt in your Python scripts (see examples/ for starting points).

Daily commands:

ghunt login                           # Start auth listener
ghunt email <email_address>           # Query email info
ghunt email <email_address> --json out.json  # Export as JSON
ghunt gaia <gaia_id>                  # Query Gaia profile
ghunt drive <file_id>                 # Query Drive file
ghunt geolocate <bssid>               # Geolocate wireless
ghunt spiderdal <domain>              # Digital Assets Links reconnaissance

• ghunt/cli.py: Main CLI entry point—defines all subcommands (login, email, gaia, drive, geolocate, spiderdal) and argument parsing
• ghunt/helpers/auth.py: Central authentication handler for Google cookie management, login listener mode, and base64 cookie parsing
• ghunt/apis/accounts.py: Core Google Accounts API reverse-engineering—handles Gaia ID lookup, email enumeration, and account verification
• ghunt/helpers/gmail.py: Gmail OSINT extraction—retrieves email metadata, labels, threads without official API
• ghunt/helpers/drive.py: Drive file/folder enumeration and metadata extraction for OSINT on shared files
• ghunt/knowledge/services.py: Service registry and metadata—defines which Google services are available and their capabilities
• ghunt/globals.py: Global state management—handles session cookies, HTTP client pooling, and configuration

Add new Google service: create ghunt/apis/newservice.py with async methods, add corresponding helper in ghunt/helpers/newservice.py, register in ghunt/knowledge/services.py. Extend CLI: modify ghunt/cli.py argument parser and add subcommand handler. Add reconnaissance logic: extend ghunt/helpers/*.py with new query patterns. All auth flows go through ghunt/helpers/auth.py.

Browser extension companion required for streamlined login (ghunt login method [1]); manual cookie entry fallback exists but fragile. Google APIs are undocumented and reverse-engineered—endpoints break without warning on Google's infrastructure changes. No visible environment variable configuration; relies on ~/.ghunt/ or system config directory. Async operations require event loop awareness in library usage. AGPL license requires source disclosure for derivative works.

• Reverse-Engineered API Endpoints — GHunt bypasses official Google APIs entirely by analyzing and mimicking browser requests to undocumented internal endpoints—critical to understand why breakage happens and how to debug failed requests
• Async/Await Pattern (asyncio) — Entire codebase uses Python async/await for concurrent Google API calls; essential to understand for extending the framework or using it as a library
• Browser Cookie Injection & Session Spoofing — GHunt authenticates by extracting and replaying Google session cookies rather than using OAuth—understand this for security implications and how the companion extension works
• Gaia ID / Google Account Enumeration — Core OSINT technique in ghunt/knowledge/people.py that maps emails to Gaia IDs (Google's internal user identifier)—foundational concept for all profile lookups
• Digital Assets Links (DAL) Crawling — ghunt/apis/digitalassetslinks.py leverages Google's public DAL metadata to discover app/domain ownership relationships—useful for attribution in OSINT
• AGPL License Compliance — Project uses AGPL v3, which requires source code disclosure for network service modifications—critical for commercial or closed-source deployments

• twintproject/twint — Twitter OSINT framework with similar modular API-scraping architecture and JSON export, now archived but conceptual predecessor
• sherlock-project/sherlock — Username enumeration across platforms—complementary OSINT tool that works alongside GHunt for cross-platform reconnaissance
• TheHarvester/theHarvester — Email and subdomain harvesting tool; often used in same OSINT workflows as GHunt for initial reconnaissance
• mxrch/GHunt-Companion — Official Firefox/Chrome extension companion for cookie-based authentication into GHunt; required for streamlined login flow
• Eun1c0rn/Google-Play-Store-API — Reverse-engineered Google Play Store API library—similar methodology to GHunt's Google service reverse-engineering

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for ghunt/apis modules

The repo has 13 API modules (accounts.py, calendar.py, drive.py, vision.py, etc.) in ghunt/apis/ but no visible test directory. Given the async nature and API interaction criticality, unit tests for these modules would catch regressions, validate API response parsing, and ensure the framework remains stable across Google API changes.

• [ ] Create tests/ directory with tests/apis/ subdirectory
• [ ] Add test_accounts.py, test_calendar.py, test_drive.py with mocked httpx responses
• [ ] Add test_vision.py and test_identitytoolkit.py (sensitive modules)
• [ ] Set up pytest with async fixtures for async function testing
• [ ] Integrate tests into GitHub Actions workflow (create .github/workflows/tests.yml)

Add integration tests for ghunt/modules and their helpers

The ghunt/modules/ contain core functionality (email.py, gaia.py, login.py, drive.py, geolocate.py, spiderdal.py) that rely on helpers (ghunt/helpers/auth.py, gmail.py, drive.py, etc.). Without tests, changes to authentication flows or session handling risk breaking critical features. Integration tests would validate end-to-end workflows.

• [ ] Create tests/modules/ directory
• [ ] Add test_login.py validating ghunt/modules/login.py with mocked auth flow
• [ ] Add test_email.py for email module with ghunt/helpers/gmail.py integration
• [ ] Add test_drive.py validating ghunt/modules/drive.py with ghunt/helpers/drive.py
• [ ] Create fixtures in tests/conftest.py for mock sessions (ghunt/objects/session.py)

Add type hints and mypy validation for core async functions

The codebase is async-first (README mentions 'Fully async') with modules like ghunt/lib/httpx.py and helpers using async/await, but type hints appear incomplete. Adding comprehensive type hints to async function signatures and enabling mypy in CI would catch type errors and improve IDE support for users.

• [ ] Add type hints to ghunt/lib/httpx.py async functions (Awaitable, Coroutine types)
• [ ] Add return type hints to async functions in ghunt/helpers/auth.py and ghunt/objects/session.py
• [ ] Create setup.cfg or pyproject.toml with mypy configuration
• [ ] Add GitHub Action workflow (.github/workflows/mypy.yml) to validate types on PRs
• [ ] Document typing patterns in CONTRIBUTING.md for contributors

• Add unit tests for ghunt/helpers/utils.py utility functions—currently untested, critical for reliability of data parsing across all modules
• Document the Gaia ID reverse-engineering process in ghunt/knowledge/people.py with inline examples—currently opaque to new contributors trying to extend people lookups
• Implement missing fields in Vision API wrapper (ghunt/apis/vision.py)—file exists but only partial Google Vision API coverage for image OSINT

• Critical · Offensive Google Framework - Unauthorized Account Access — ghunt/modules/, ghunt/helpers/, ghunt/apis/. GHunt is explicitly designed as an 'offensive Google framework' for OSINT purposes. The codebase contains modules for unauthorized access to Google accounts including: email enumeration (email.py), drive access (drive.py), calendar access (calendar.py), Gmail access (gmail.py), and geolocation tracking (geolocate.py). The framework appears designed to bypass authentication and extract sensitive user data. Fix: This tool appears to be designed for unauthorized access to Google services. Verify compliance with Google's Terms of Service and applicable laws (CFAA, GDPR, etc.). Consider: 1) Adding explicit legal disclaimers, 2) Implementing OAuth2 properly instead of cookie-based auth, 3) Requiring explicit user consent, 4) Adding audit logging.
• Critical · Insecure Authentication Handling — ghunt/helpers/auth.py, ghunt/modules/login.py, ghunt/cli.py. The login mechanism (ghunt/helpers/auth.py, ghunt/modules/login.py) uses cookie-based authentication and base64-encoded cookie pasting. This method bypasses standard OAuth2 flows and allows direct cookie extraction/reuse, which violates Google's ToS and enables session hijacking. Fix: Implement proper OAuth2 with PKCE flow. Never allow raw cookie extraction or pasting. Use secure token storage with encryption. Implement token refresh mechanisms and expiration.
• High · Sensitive API Keys and Endpoints Hardcoded — ghunt/knowledge/keys.py, ghunt/knowledge/sig.py, ghunt/config.py, ghunt/globals.py. The file structure indicates API keys and credentials are likely stored in: ghunt/knowledge/keys.py, ghunt/knowledge/sig.py, ghunt/config.py, and ghunt/globals.py. These files typically contain hardcoded API signatures, service keys, or authentication tokens. Fix: Move all credentials to environment variables or secure vaults. Never commit API keys to version control. Use GCP Secret Manager or similar. Implement secret scanning in CI/CD pipeline.
• High · Unrestricted Data Extraction from Google Services — ghunt/helpers/drive.py, ghunt/helpers/calendar.py, ghunt/helpers/geolocation.py, ghunt/helpers/gmaps.py, ghunt/apis/. Multiple modules allow extraction of sensitive user data: drive files (drive.py), calendar events (calendar.py), location data (geolocation.py, gmaps.py), play games profile (playgames.py), and vision/image analysis (vision.py). No rate limiting, consent mechanisms, or access controls are evident. Fix: Implement: 1) Rate limiting to prevent abuse, 2) Explicit user consent dialogs, 3) Access scope restrictions, 4) Audit logging of data access, 5) Data minimization principles.
• High · Custom HTTP Library May Bypass Security Controls — ghunt/lib/httpx.py. The codebase includes a custom httpx wrapper (ghunt/lib/httpx.py) which may implement certificate pinning bypass, header manipulation, or other techniques to circumvent Google's anti-bot protections. Fix: Review the custom HTTP library for security-relevant modifications. Use standard httpx without modifications. Implement proper rate limiting and respect robots.txt.
• High · Protobuf Messages Without Validation — ghunt/protos/. Custom protobuf definitions (ghunt/protos/playgatewaypa/) are used for API communication. Lack of input validation on deserialized protobuf messages could lead to injection attacks or unexpected behavior. Fix: Implement strict protobuf validation schemas. Sanitize all deserialized data before use. Use type-safe protobuf parsing with version constraints.
• Medium · Missing Input Validation in Parsers — ghunt/parsers/. Multiple parser modules (ghunt/parsers/) parse API responses without visible validation. Malicious or malformed API responses could trigger injection attacks or code execution. Fix: Implement strict input validation and schema validation for all API responses. Use typed parsers with explicit error handling. Implement response size limits.
• **** · undefined — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/mxrch/GHunt shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live mxrch/GHunt repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mxrch/GHunt.

What it runs against: a local clone of mxrch/GHunt — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in mxrch/GHunt | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 59 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mxrch/GHunt. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mxrch/GHunt.git
#   cd GHunt
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of mxrch/GHunt and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mxrch/GHunt(\\.git)?\\b" \\
  && ok "origin remote is mxrch/GHunt" \\
  || miss "origin remote is not mxrch/GHunt (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 59 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~29d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/mxrch/GHunt"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.