# GHunt: an async Google OSINT framework that lives or dies by your cookies

> GHunt v2 turns a logged-in Google session into a queryable OSINT tool for email addresses, Gaia IDs, Drive links and BSSIDs. It is a Python 3.10+ CLI and library under AGPL-3.0, and the whole thing depends on you supplying valid Google cookies.

**mxrch/GHunt** — 🕵️‍♂️ Offensive Google framework.

- Repository: https://github.com/mxrch/GHunt
- Stars: 19,645 · Forks: 1,727
- Language: Python
- License: NOASSERTION
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/mxrch-ghunt

## What GHunt actually queries, and who needs it

GHunt is not a scraper that reads public search results. It is a client for Google's own internal endpoints, and the module list tells you which ones: email for an address, gaia for a Gaia ID, drive for a file or folder, geolocate for a BSSID, and spiderdal for assets found through Digital Assets Links. The README describes the project as an "offensive Google framework" that is currently focused on OSINT but could support "any use related with Google".

The audience follows from that design. Someone running a missing-person investigation, a red team doing pre-engagement reconnaissance, or a researcher studying what Google exposes around an account can use a single command to pivot from an email address to a Gaia ID and then to a Drive object. A general web scraper cannot do that, because the interesting responses are not on pages a scraper can reach.

The trade-off is that GHunt is useless without an authenticated session. Every module that returns anything interesting is talking to Google as you. That is also why the README carries two disclaimers rather than one: the first is the usual educational-purposes notice, and the second states that the project is under the AGPL and that you should "use it only in personal, criminal investigations, pentesting, or open-source projects".

## Async HTTP, protobuf responses and a cookie jar as the engine

The dependency list in pyproject.toml is the clearest description of the architecture. httpx is pulled in with the http2 extra, which is what the asynchronous request layer runs on. protobuf is a direct dependency, which fits the pattern of an internal Google API: the responses are not tidy JSON documents, they are binary payloads that have to be decoded against a schema. jsonpickle and autoslot handle object serialisation, and rich plus beautifultable and alive-progress render the terminal output.

Data flow is a straight line. You authenticate once, GHunt stores the cookies, and each module builds a request against the relevant Google endpoint, decodes the protobuf or HTML response, and hands back a structured object. Because it is fully async, a module can issue several requests concurrently rather than walking through them one at a time. The imagehash and pillow dependencies suggest that some modules compare or hash images rather than only parsing text.

The library path is deliberate, not incidental. The README points developers at a wiki and an examples directory, and pyproject.toml exposes a console script entry point, ghunt = "ghunt.ghunt:main". The two example files shipped in the repository, email_registered.py and get_people_name.py, are the intended starting points for anyone who wants to call the framework from their own code instead of the terminal.

## Installing GHunt with pipx and running a first email lookup

The README recommends pipx so that GHunt lives in its own virtual environment and does not fight with the dependencies of your other projects. You need Python 3.10 or newer. The three commands below install pipx, make its shims available on your PATH, and then install GHunt itself.

```bash
$ pip3 install pipx
$ pipx ensurepath
$ pipx install ghunt
```

After that, authentication is the next step, and it is interactive. Running ghunt login presents a menu with three options: put GHunt in listening mode for the Companion extension, paste base64-encoded cookies, or enter all cookies manually. The README notes that the listening mode is currently not compatible with Docker.

```bash
$ ghunt login

[1] (Companion) Put GHunt on listening mode (currently not compatible with docker)
[2] (Companion) Paste base64-encoded cookies
[3] Enter manually all cookies

Choice =>
```

The GHunt Companion browser extension, published for Firefox and Chrome, is what completes the login flow. Once the session is stored, the module list is the whole interface: login, email, gaia, drive, geolocate and spiderdal. A first real lookup is a single command, and adding --json writes the result to a file rather than only to the terminal.

```bash
$ ghunt email <email_address> --json user_data.json
```

If you want GHunt as a library rather than a CLI, the README is explicit that pipx will not work, because it isolates the package inside a virtual environment. Install it with pip instead, then import ghunt in your own project and start from the files in examples/.

## The cookie dependency is the real failure mode

The most common way GHunt stops working is not a bug in GHunt. It is an expired or invalidated Google session. Because every module authenticates as you, a cookie set that Google has rotated, a session that has been signed out, or a login flow that was interrupted all produce the same outcome: requests that fail or return nothing useful. The README does not document any automatic refresh, and it does not document rollback or recovery beyond running ghunt login again.

There is a second constraint that is easy to miss. Listening mode, which is the smoothest of the three login methods, is documented as not compatible with Docker. Anyone who wants to containerise GHunt is pushed toward the base64 or manual cookie options, which are less convenient and easier to get wrong.

A third limitation is scope. GHunt answers questions about what Google exposes around an account or an asset. It is not a general people-search engine, it does not cover other providers, and the spiderdal module is aimed at asset discovery through Digital Assets Links rather than at broad internet scanning. If your question is not ultimately a question about Google's data, this is the wrong tool, and no amount of configuration will change that.

## GHunt versus a general OSINT framework such as Sherlock

The natural comparison is with username and account enumeration tools, Sherlock being the familiar example. The difference is not the output format, it is the mechanism. Sherlock-style tools work unauthenticated: they send requests to public profile URLs across many sites and report which ones respond with a hit. That makes them broad but shallow, and it also means they only see what a site chooses to show an anonymous visitor.

GHunt inverts both properties. It covers one provider, Google, and goes deep inside it, which is only possible because you are authenticated. The result is data an anonymous request cannot retrieve: account metadata keyed to an email or Gaia ID, Drive objects, and geolocation tied to a BSSID. It also means GHunt cannot be pointed at a target outside Google, and it inherits the fragility of a session that can expire at any moment.

There is also a licensing difference worth noting. GHunt is AGPL-3.0, which the README stresses and which the pyproject.toml confirms. If you build a service on top of it, the AGPL's network clause is the part that matters, and that is a question for a lawyer rather than for this article.

## Version, licence and what upgrades cost you

The repository's pyproject.toml declares version 2.3.4, while the most recent tagged release listed is v2.2.0 from 2024-06-06. The last push to the default branch was on 2026-04-10, so work on the repository has continued between tags. The README also notes that the project is now Python 3.13 compatible, alongside a Python 3.10+ minimum.

That version split is the upgrade detail to watch. The README's requirement is Python >= 3.10, but the Poetry section of pyproject.toml pins python = "^3.11". Anyone installing through Poetry is on 3.11 or later; anyone following the pipx path is told 3.10 is enough. The dependencies themselves are pinned with caret ranges, so a fresh install resolves to the newest compatible minor version rather than a frozen set, which is normal for a library but does mean an upstream release can change behaviour under you.

The licence is AGPL-3.0, stated both in the README and in the project metadata. The README frames permitted use as personal work, criminal investigations, pentesting or open-source projects. Whether your particular deployment fits that framing is a legal question, not a technical one, and the repository does not answer it for you.

## Conclusion

GHunt fits investigators, pentesters and researchers who already have a legitimate reason to query Google's own endpoints and can keep a cookie set alive. It does not fit anyone looking for a zero-auth lookup tool, and it does not fit Windows users who want the container route, since the README says listening mode is not compatible with Docker. Before adopting it, verify three things: that your Python is 3.10 or newer, that you can complete the ghunt login flow with the GHunt Companion extension, and that your use falls inside the licence's stated scope of personal, criminal investigation, pentesting or open-source work. The pyproject.toml pins Python to ^3.11 for Poetry installs while the README advertises 3.10+, so check which path you are on before filing a version bug.

## FAQ

### How do I install GHunt?

Install pipx first with pip3 install pipx, run pipx ensurepath, then run pipx install ghunt. You need Python 3.10 or newer. If you want to use GHunt as a library rather than a CLI, the README says to install it with pip instead, because pipx isolates the package in a virtual environment.

### How do I use GHunt?

Run ghunt login first and pick one of the three authentication methods, completing the flow with the GHunt Companion extension. After that, the modules are login, email, gaia, drive, geolocate and spiderdal. For example, ghunt email <email_address> --json user_data.json writes the result to a JSON file.

### What is GHunt?

GHunt is described in its README as an offensive Google framework, currently focused on OSINT. It offers CLI usage and modules, Python library usage, fully async operation, JSON export, and a browser extension to ease login.

### How do I set up GHunt?

Setup is the login step. Run ghunt login and choose between listening mode with the Companion extension, pasting base64-encoded cookies, or entering all cookies manually. The README notes that listening mode is currently not compatible with Docker.

### Is there a GHunt alternative?

The repository does not name a competing tool, but the design difference is worth stating: GHunt queries Google's own endpoints with your authenticated session, so it goes deeper on one provider than an unauthenticated username-enumeration tool that checks many sites at once. If your target is not on Google, GHunt is the wrong tool.

### Is GHunt free?

The repository does not list a price. It is published under AGPL-3.0, and the README states that you should use it only in personal work, criminal investigations, pentesting, or open-source projects.

## Sources

- [Issues](https://github.com/mxrch/GHunt/issues)
- [mxrch/GHunt on GitHub](https://github.com/mxrch/GHunt)
- [README](https://github.com/mxrch/GHunt/blob/master/README.md)
- [Releases](https://github.com/mxrch/GHunt/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mxrch-ghunt