// extensão companion

GHunt Companion, explicada

A GHunt Companion é uma extensão para Chrome e Firefox. Seu único papel é capturar uma sessão Google e entregar os tokens à ferramenta de linha de comando do GHunt para que o CLI possa autenticar. É um contorno para o fato de que o CLI não consegue logar no Google sozinho. Se você usa ghunt.sh no navegador, não precisa dela.

O que a extensão Companion faz, na prática

Quando você instala o CLI do GHunt, a própria ferramenta não tem como fazer login em uma conta Google. O fluxo de login do Google foi feito para rodar dentro de um navegador real, não dentro de um script Python. Para contornar isso, a extensão Companion foi criada. Você instala no Chrome ou Firefox, faz login no Google nesse navegador, e a extensão exporta um payload em base64 contendo os cookies e tokens que o CLI precisa. Você então cola esse payload no comando de login do CLI e o CLI passa a se comportar como se fosse o usuário logado.

É um contorno inteligente. Também é frágil por construção, porque depende de um alvo móvel: o formato de sessão do Google.

Por que as pessoas travam com ela

É mais uma instalação. Você já instalou Python, o CLI do GHunt, montou um virtualenv. Agora também precisa adicionar uma extensão ao navegador e descobrir onde o payload vai.
Quebra em atualizações do Google. Toda vez que o Google muda como armazena cookies de sessão, a Companion precisa ser ajustada. Existem trechos longos em que a extensão produz um payload mas o CLI o rejeita.
Nem sempre está nas lojas oficiais. Análises na loja de extensões podem atrasar. Versões aparecem, são removidas, são reenviadas sob nomes ligeiramente diferentes. As pessoas acabam fazendo sideload da extensão, o que as deixa, com razão, nervosas.
O token expira. Mesmo quando tudo funciona, a sessão capturada não dura para sempre. Você reexporta o payload, refaz o login pelo CLI, e torce para continuar funcionando.
Políticas de navegador atrapalham. Perfis Chrome ou Firefox gerenciados corporativamente frequentemente recusam instalar extensões fora de uma allowlist, o que bloqueia a Companion totalmente em máquinas de trabalho.

A Companion é o ponto de fricção onde muita gente que tentaria usar o GHunt desiste.

Você precisa da Companion para usar o ghunt.sh?

Não. O ghunt.sh cuida da autenticação internamente. Você não instala extensão, não captura tokens, não cola payload base64 em lugar nenhum. Da perspectiva do visitante, o que existe é uma caixa de busca e um relatório. Esse é exatamente o ponto de rodar o GHunt como um serviço web hospedado: as partes frágeis ficam do nosso lado, você recebe a saída.

Quando você realmente precisa da Companion

Você precisa da Companion se todos os seguintes forem verdadeiros ao mesmo tempo:

Você instalou o CLI do GHunt na sua própria máquina.
Você quer que as consultas venham da sessão da sua própria conta Google.
Você ainda não capturou um token de sessão válido por outros meios.

Fora desse cenário, a Companion não acrescenta nada ao seu fluxo. É encanamento exclusivo do CLI.

Se você está lendo isso porque a Companion está quebrada para você

Você tem duas opções. Pode esperar o próximo fix da Companion, repetir a dança da instalação, capturar um payload novo, e torcer para durar. Ou pode colar o email que você queria investigar no ghunt.sh e receber o relatório em segundos. A segunda opção é para o que construímos o ghunt.sh.