ghunt/sh

// companion extension

GHunt Companion, explained

The GHunt Companion is a Chrome and Firefox extension. Its only job is to capture a Google session and hand the tokens to the GHunt command-line tool so that the CLI can authenticate. It is a workaround for the fact that the CLI cannot log into Google by itself. If you use ghunt.sh in your browser, you do not need it.

What the Companion extension actually does

When you install the GHunt CLI, the tool itself has no way to log into a Google account. Google's sign-in flow is built to run inside a real browser, not a Python script. To get around that, the Companion extension was created. You install it in Chrome or Firefox, log into Google in that browser, and the extension exports a base64 payload containing the cookies and tokens the CLI needs. You then paste that payload into the CLI's login command and the CLI starts behaving as if it were the logged-in user.

It is a clever workaround. It is also brittle by design, because it depends on a moving target: Google's session format.

Why people get stuck with it

  • It is one more install. You already installed Python, the GHunt CLI, set up a virtualenv. Now you also need to add an extension to your browser and figure out where the payload goes.
  • It breaks on Google updates. Every time Google changes the way they store session cookies, the Companion has to be patched. There are long stretches where the extension produces a payload but the CLI rejects it.
  • It is not always in the official stores. Browser extension store reviews can fall behind. Versions appear, get pulled, get reuploaded under slightly different names. People end up sideloading the extension, which makes them rightly nervous.
  • The token expires. Even when everything works, the captured session does not last forever. You re-export the payload, re-login through the CLI, and hope it still works.
  • Browser policies fight back. Corporate-managed Chrome or Firefox profiles often refuse to install extensions outside of an allowlist, which blocks the Companion entirely on work machines.

The Companion is the friction point where a lot of would-be GHunt users give up.

Do you need the Companion to use ghunt.sh?

No. ghunt.sh handles the authentication side internally. You do not install an extension, you do not capture tokens, you do not paste a base64 payload anywhere. From the visitor's perspective, the only thing that exists is a search box and a report. That is the entire point of running GHunt as a hosted web service: the brittle parts stay on our side, you get the output.

When you actually need the Companion

You need the Companion if all of these are true at the same time:

  • You have installed the GHunt CLI on your own machine.
  • You want lookups to come from your own Google account's session.
  • You have not yet captured a working session token through any other means.

Outside of that scenario, the Companion adds nothing to your workflow. It is a CLI-only piece of plumbing.

If you are reading this because the Companion is broken for you

You have two options. You can wait for the next Companion fix, repeat the install dance, capture a fresh payload, and hope it lasts. Or you can paste the email you wanted to investigate into ghunt.sh and get the report in seconds. The second option is what we built ghunt.sh for.

Related reading