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.

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}

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 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 57 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"

# 4. Critical files exist
test -f "ghunt/ghunt.py" \\
  && ok "ghunt/ghunt.py" \\
  || miss "missing critical file: ghunt/ghunt.py"
test -f "ghunt/cli.py" \\
  && ok "ghunt/cli.py" \\
  || miss "missing critical file: ghunt/cli.py"
test -f "ghunt/objects/session.py" \\
  && ok "ghunt/objects/session.py" \\
  || miss "missing critical file: ghunt/objects/session.py"
test -f "ghunt/helpers/auth.py" \\
  && ok "ghunt/helpers/auth.py" \\
  || miss "missing critical file: ghunt/helpers/auth.py"
test -f "ghunt/modules/email.py" \\
  && ok "ghunt/modules/email.py" \\
  || miss "missing critical file: ghunt/modules/email.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 57 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~27d)"
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).

GHunt is an offensive Google reconnaissance framework written in Python that performs OSINT against Google accounts and services by exploiting undocumented Google APIs. It enables investigators to extract detailed information from email addresses, Gaia IDs, Drive files, and geolocation data through async API calls to internal Google endpoints, with results exportable to JSON. Modular architecture: ghunt/apis/ contains individual Google API clients (accounts.py, drive.py, calendar.py, etc.), ghunt/helpers/ provides higher-level functionality wrappers (gmail.py, gmaps.py, playgames.py), ghunt/knowledge/ stores pre-computed API endpoint/service definitions, and ghunt/cli.py ties everything together. The ghunt/ghunt.py likely serves as the main orchestrator class.

Security researchers, bug bounty hunters, and OSINT investigators who need to extract intelligence from Google accounts and services. Also appeals to penetration testers who require a Python library for automated Google reconnaissance workflows.

Actively maintained and reasonably mature: Python 3.13 compatible, has a companion browser extension (Firefox/Chrome), documented on wiki, and includes examples. The codebase is substantial (~512KB Python) with structured modules, though no visible CI/CD pipelines (.github/workflows exists but only contains sponsors.yml). Appears production-ready for OSINT use but driven by a single maintainer.

Single-maintainer risk is significant (mxrch as sole contributor visible). Depends on undocumented Google APIs that are fragile targets for rate-limiting and account suspension; breaking changes could render entire modules non-functional overnight. No visible test coverage in file structure, and authentication relies on cookie extraction via browser extension, creating potential security surface for phishing or malware distribution.

No recent commit data visible in file structure, but README indicates active support for Python 3.13 and a maintained online version (osint.industries). The browser extension infrastructure (Companion) suggests ongoing UX iteration for login flows. No open issues or PRs visible in the provided data.

git clone https://github.com/mxrch/GHunt.git && cd GHunt && pip3 install -e . (for development) or pipx install ghunt (for CLI usage). Then run ghunt login to authenticate via the browser extension, and try ghunt email target@gmail.com to begin reconnaissance.

Daily commands: ghunt login (start auth listener), then ghunt email <email> / ghunt gaia <id> / ghunt drive <file_id> / ghunt geolocate <bssid> / ghunt spiderdal <domain>. For library usage: import ghunt and call module functions directly (see examples/email_registered.py, examples/get_people_name.py).

• ghunt/ghunt.py — Core GHunt class orchestrating all modules and API interactions; entry point for library usage
• ghunt/cli.py — Command-line interface and routing; defines all user-facing commands including login, email, and drive
• ghunt/objects/session.py — Session management and authentication state; handles cookie persistence and API authentication
• ghunt/helpers/auth.py — Login flow and credential acquisition; bridges CLI listener with cookie extraction mechanisms
• ghunt/modules/email.py — Email/OSINT module implementation; demonstrates pattern for building reconnaissance modules
• ghunt/knowledge/keys.py — API keys and constants for Google services; required for all downstream API calls

Add a New Google API Integration

1. Create API wrapper in ghunt/apis/ folder following pattern of existing files like drive.py (ghunt/apis/newapi.py)
2. Add API class to object registry in ghunt/objects/apis.py (ghunt/objects/apis.py)
3. Create corresponding parser in ghunt/parsers/ to extract meaningful data (ghunt/parsers/newapi.py)
4. Import API key/signature constants in ghunt/knowledge/keys.py if needed (ghunt/knowledge/keys.py)

Add a New OSINT Module

1. Create module file in ghunt/modules/ (e.g., newmodule.py) with async functions (ghunt/modules/newmodule.py)
2. Add module reference to main GHunt class for CLI exposure (ghunt/ghunt.py)
3. Add CLI command handler in cli.py using pattern from existing commands (ghunt/cli.py)
4. Create helper functions in ghunt/helpers/ if module needs shared utilities (ghunt/helpers/newhelper.py)

Add Support for New Google Service

1. Define service metadata and endpoints in ghunt/knowledge/services.py (ghunt/knowledge/services.py)
2. Add API keys and signatures to ghunt/knowledge/keys.py (ghunt/knowledge/keys.py)
3. Create API wrapper in ghunt/apis/ using async httpx client from session (ghunt/apis/newservice.py)
4. Implement parser and module following established patterns (ghunt/modules/newservice.py)

Improve Authentication Flow

1. Update login methods in ghunt/helpers/auth.py (manual, listener, or base64) (ghunt/helpers/auth.py)
2. Modify listener HTTP handler in ghunt/helpers/listener.py for browser extension (ghunt/helpers/listener.py)
3. Update CLI login command in ghunt/cli.py to reflect new options (ghunt/cli.py)
4. Store cookies and session in ghunt/objects/session.py persistent storage (ghunt/objects/session.py)

• Python async/await (asyncio) — Enables concurrent Google API requests for faster reconnaissance across multiple targets
• httpx (async HTTP client) — Provides async-first HTTP client with cookie jar for session persistence across API calls
• Protocol Buffers — Required to serialize/deserialize binary responses from Google Play Games and other APIs
• Click (CLI framework) — Simplifies command-line argument parsing and multi-command routing (login, email, drive, etc.)

• Browser extension for login vs. manual cookie entry

  • Why: Browser extension reduces user friction but requires separate maintenance; manual entry is more portable
  • Consequence: Three login methods supported but adds complexity to auth.py and listener.py

• Library + CLI dual interface (ghunt.py + cli.py)

  • Why: Enables both programmatic use (examples/) and interactive command-line use
  • Consequence: Code duplication in command handlers but provides flexibility for different users

• Tight coupling to specific Google API keys/signatures in knowledge/

  • Why: Necessary to authenticate requests; keys may rotate or change
  • Consequence: Project requires maintenance whenever Google changes service endpoints or signatures

• Async-first architecture throughout

  • Why: Maximizes throughput for reconnaissance scanning
  • Consequence: Requires all helpers, modules, and APIs to use async functions; steeper learning curve for contributors

• Does not provide authentication for personal Google accounts beyond cookie extraction
• Not a general-purpose Google client library; focused exclusively on OSINT and reconnaissance
• Does not handle Google 2FA or complex challenge-response flows automatically
• Not designed for real-time monitoring or continuous updates
• Does not

Cookie expiration and Google rate-limiting are not visible in the file structure but will be critical at runtime. The browser extension (Companion) must be actively installed and accessible for the ghunt login listener to work. Python 3.10+ requirement is strict (no 3.9 backport). Undocumented Google APIs may break between versions without warning. No visible environment variable configuration (ghunt/config.py exists but contents unknown); check if API keys or session tokens must be manually provided.

• Undocumented API Exploitation — GHunt's core strength and fragility: it reverse-engineers and abuses internal Google endpoints not in the public API docs, so understanding how APIs evolve and block scrapers is critical to maintaining this tool
• OAuth Cookie Extraction & Session Hijacking — The browser extension authentication model relies on capturing session cookies without full OAuth flows; contributors must understand cookie management, SameSite/Secure flags, and Google's anti-scraping measures
• Async/Await Rate-Limited Concurrency — GHunt processes multiple API calls concurrently with async patterns; understanding how to manage rate limits, backoff strategies, and connection pooling across undocumented endpoints is essential for scaling reconnaissance
• Gaia ID Enumeration & Account Linking — Google's internal Gaia system uniquely identifies accounts; GHunt exploits cross-service linking to enumerate data. Understanding Gaia's role in tying Gmail, Drive, Calendar, etc. together is central to the reconnaissance model
• Digital Assets Links & App-to-Domain Binding — The spiderdal module leverages DAL to find associated apps and services; this cryptographic linking mechanism is a powerful reconnaissance vector for asset discovery
• Browser Extension Security & IPC (Inter-Process Communication) — The Companion extension communicates session tokens to the CLI listener; understanding extension sandbox isolation, message passing, and CORS is critical to secure credential handling
• OSINT Methodology & Target Enrichment — GHunt is a tool in the OSINT workflow; understanding how to pivot from email → Gaia ID → Drive → Calendar and chain intelligence is essential for effective reconnaissance

• maigret/maigret — Complementary OSINT framework for username/email enumeration across platforms; both are Python-async and focus on reconnaissance
• sherlock-project/sherlock — Similar social-media OSINT tool using parallel requests; shares target-enumeration philosophy but covers non-Google surfaces
• Ekultek/BlueKeep — Offensive security framework with modular vulnerability/API exploitation; architectural parallel for how GHunt structures API clients
• securitytxt/securitytxt — Companion tool for web reconnaissance; complements GHunt by finding security policy files on targets' domains
• gchq/CyberChef — Data transformation and encoding/decoding tool useful for preparing payloads and analyzing API responses in GHunt workflows

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/modules/ with pytest coverage

The repo lacks unit tests for core modules (email.py, gaia.py, login.py, drive.py, spiderdal.py, geolocate.py). Given this is an async framework with complex API interactions, adding pytest fixtures and mocks for these modules would catch regressions and help new contributors understand the module behavior. Currently there's no tests/ directory visible.

• [ ] Create tests/ directory with conftest.py for shared async fixtures
• [ ] Add unit tests for ghunt/modules/email.py covering email validation and OSINT flows
• [ ] Add unit tests for ghunt/modules/login.py mocking authentication flows
• [ ] Add unit tests for ghunt/modules/drive.py mocking Google Drive API responses
• [ ] Configure pytest in pyproject.toml or setup.cfg with coverage targets

Add GitHub Actions workflow for Python 3.10-3.13 compatibility testing

The README advertises Python 3.10+ and 3.13 compatibility, but there's no visible CI workflow (only sponsors.yml exists). Add a matrix test workflow to catch breaking changes across supported versions before releases, especially important given the async codebase.

• [ ] Create .github/workflows/tests.yml with Python 3.10, 3.11, 3.12, 3.13 matrix
• [ ] Include pip install and pytest execution steps
• [ ] Add linting checks (flake8 or ruff) for code quality
• [ ] Configure coverage reporting to codecov or similar service

Enhance ghunt/knowledge/ with docstrings and type hints for API signature knowledge

Files like ghunt/knowledge/sig.py, services.py, and keys.py appear to store critical Google API signatures and service mappings, but lack documentation. Adding comprehensive docstrings, type hints, and a README explaining how to update these when Google APIs change would help maintainers and contributors keep the framework current.

• [ ] Add module-level docstrings to ghunt/knowledge/*.py explaining data structures
• [ ] Add type hints to ghunt/knowledge/sig.py and ghunt/knowledge/services.py
• [ ] Create ghunt/knowledge/README.md documenting how signatures are discovered and updated
• [ ] Add comments explaining the relationship between sig.py, keys.py, and the APIs they support

• Add unit tests for ghunt/apis/accounts.py and ghunt/apis/drive.py covering successful API responses and error handling; currently no test directory is visible in the file list
• Expand ghunt/knowledge/ with additional service endpoint definitions (e.g., YouTube, Google Photos, Google Takeout) and document the format in the wiki to enable community contributions
• Create a troubleshooting guide in the wiki documenting common rate-limit errors, authentication failures, and API deprecations for each ghunt/apis/ module

• Critical · Offensive Security Tool Without Clear Authorization Framework — ghunt/modules (email.py, login.py, gaia.py, drive.py), examples/. GHunt is explicitly designed as an 'offensive Google framework' for OSINT and Google-related activities. The codebase includes modules for unauthorized account enumeration (email_registered.py), calendar access, drive access, geolocation, and authentication bypass. There is no built-in authorization or consent mechanism visible. This tool could be used for unauthorized access to Google accounts and personal data. Fix: Implement strict authorization checks, user consent mechanisms, and clear terms of service. Add logging and audit trails for all data access. Consider implementing rate limiting and detection evasion protections to prevent abuse.
• High · Authentication Bypass and Credential Handling — ghunt/helpers/auth.py, ghunt/modules/login.py, ghunt/objects/session.py. The ghunt/helpers/auth.py and ghunt/modules/login.py modules appear to handle authentication token extraction and session management. The README mentions cookie extraction via 'Paste base64-encoded cookies' method, suggesting direct credential handling without proper validation. Fix: Implement secure credential storage with encryption. Never store plaintext credentials. Use OAuth 2.0 flows instead of direct cookie extraction. Implement credential rotation and expiration policies.
• High · Missing Input Validation in API Modules — ghunt/apis/*.py (all API modules). Multiple API modules (accounts.py, calendar.py, drive.py, vision.py, etc.) interact with Google services without visible input validation or sanitization. This could enable injection attacks or malformed request exploitation. Fix: Implement comprehensive input validation for all API parameters. Use type hints and runtime validation. Sanitize all user-supplied inputs before passing to API calls.
• High · Insecure HTTP Library Wrapper — ghunt/lib/httpx.py. Custom HTTP library wrapper at ghunt/lib/httpx.py suggests custom HTTP handling which may bypass security checks or introduce vulnerabilities. httpx is used without visible certificate validation or security headers enforcement. Fix: Use standard httpx security features. Enable certificate verification. Add security headers (HSTS, CSP, etc.). Implement request/response validation.
• High · Unvalidated API Key/Secret Storage in Knowledge Base — ghunt/knowledge/keys.py. ghunt/knowledge/keys.py suggests hardcoded API keys or secrets may be present in the knowledge base for various Google services. Hardcoded credentials pose critical security risk. Fix: Never hardcode API keys. Move all credentials to environment variables or secure configuration management. Use key rotation. Implement secret scanning in CI/CD.
• Medium · Protobuf Message Handling Without Validation — ghunt/protos/playgatewaypa/. ghunt/protos/ contains .proto files for PlayGateway services. Deserialization of untrusted protobuf messages without validation could lead to code execution or DoS attacks. Fix: Implement strict protobuf message validation. Use type-safe deserialization. Validate message sizes and nested depth. Implement error handling for malformed messages.
• Medium · Potential Data Exfiltration via JSON Export — ghunt/objects/encoders.py, ghunt/modules/. The README mentions 'JSON export' capability. Exporting sensitive data (calendar, drive contents, personal information) without encryption or access controls could lead to data exposure. Fix: Encrypt JSON exports at rest. Implement access controls for exported data. Add warnings about sensitive data. Log all data exports with audit trails.
• Medium · Async Operations Without Proper Error Handling — ghunt/ghunt.py, ghunt/helpers/. The codebase is 'fully async' but without visible comprehensive error handling for concurrent operations. This could lead to information disclosure through error messages or race conditions. Fix: Implement proper exception handling for all async operations. Use try-catch blocks with specific exception types. Implement timeout mechanisms. Log errors securely without exposing sensitive information.
• Medium · No Visible Rate Limiting or Abuse Prevention — undefined. The tool performs enumeration 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

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