# mxrch/ghunt architecture

> Architecture diagram of the GitHub repository mxrch/ghunt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mxrch/ghunt
- Repository: https://github.com/mxrch/ghunt

## Overview

GHunt is an async Google OSINT framework, exposed as CLI commands and a Python library. The main workflow is to authenticate, investigate a target through a domain module, query Google APIs, parse responses, and present or optionally export findings. The graph preserves the documented email, Gaia ID, Drive, geolocation, and Digital Assets Links capabilities, plus shared API, credential, and knowledge layers. Connections for unsampled modules rely on the README or SOURCE INDEX references; uncertain runtime details are omitted.

Main entry points: [`ghunt/cli.py`](https://github.com/mxrch/ghunt/blob/master/ghunt/cli.py) (CLI commands), [`ghunt/objects/apis.py`](https://github.com/mxrch/ghunt/blob/master/ghunt/objects/apis.py) (API request runtime), [`ghunt/modules/email.py`](https://github.com/mxrch/ghunt/blob/master/ghunt/modules/email.py) (Email lookup), [`ghunt/modules/drive.py`](https://github.com/mxrch/ghunt/blob/master/ghunt/modules/drive.py) (Drive lookup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_cli["CLI commands<br/>[cli.py]"]
end

subgraph group_auth["Authentication"]
  node_login["Login flow<br/>[login.py]"]
  node_auth_helpers["Credential auth<br/>[auth.py]"]
  node_credentials["Credential model<br/>[base.py]"]
end

subgraph group_investigation["Investigations"]
  node_email["Email lookup<br/>[email.py]"]
  node_gaia["Gaia lookup<br/>[gaia.py]"]
  node_drive["Drive lookup<br/>[drive.py]"]
  node_geolocate["BSSID geolocation<br/>[geolocate.py]"]
  node_spiderdal["Asset-link search<br/>[spiderdal.py]"]
  node_maps["Maps enrichment<br/>[gmaps.py]"]
end

subgraph group_api["Google API access"]
  node_drive_api["Drive API<br/>[drive.py]"]
  node_people_api["People API<br/>[peoplepa.py]"]
  node_vision_api["Vision API<br/>[vision.py]"]
  node_cac_api["Client auth config"]
  node_dal_api["Digital asset links"]
end

subgraph group_shared["Shared runtime"]
  node_api_runtime["API request runtime<br/>[apis.py]"]
  node_drive_parser["Drive parser<br/>[drive.py]"]
  node_knowledge["Reference knowledge<br/>[knowledge.py]"]
  node_http_client["Async HTTP client<br/>[httpx.py]"]
end

node_user(("Operator"))
node_google(("Google services"))

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches login"| node_login
node_cli -->|"dispatches lookup"| node_email
node_cli -->|"dispatches lookup"| node_gaia
node_cli -->|"dispatches lookup"| node_drive
node_cli -->|"dispatches lookup"| node_geolocate
node_cli -->|"dispatches search"| node_spiderdal
node_login -->|"loads authentication"| node_auth_helpers
node_auth_helpers -->|"updates credentials"| node_credentials
node_email -->|"authenticates"| node_auth_helpers
node_email -->|"looks up people"| node_people_api
node_email -->|"queries vision"| node_vision_api
node_email -->|"enriches with Maps"| node_maps
node_gaia -->|"queries profiles"| node_people_api
node_gaia -->|"enriches with Maps"| node_maps
node_drive -->|"authenticates"| node_auth_helpers
node_drive -->|"fetches Drive data"| node_drive_api
node_drive -->|"looks up app brand"| node_cac_api
node_spiderdal -->|"queries asset links"| node_dal_api
node_drive_api -->|"parses responses"| node_drive_parser
node_drive_api -->|"uses Drive knowledge"| node_knowledge
node_drive_api -->|"uses API runtime"| node_api_runtime
node_people_api -->|"uses API runtime"| node_api_runtime
node_vision_api -->|"uses API runtime"| node_api_runtime
node_cac_api -->|"uses API runtime"| node_api_runtime
node_api_runtime -->|"sends requests"| node_http_client
node_api_runtime -->|"calls Google APIs"| node_google

click node_cli "https://github.com/mxrch/ghunt/blob/master/ghunt/cli.py"
click node_login "https://github.com/mxrch/ghunt/blob/master/ghunt/modules/login.py"
click node_auth_helpers "https://github.com/mxrch/ghunt/blob/master/ghunt/helpers/auth.py"
click node_credentials "https://github.com/mxrch/ghunt/blob/master/ghunt/objects/base.py"
click node_email "https://github.com/mxrch/ghunt/blob/master/ghunt/modules/email.py"
click node_gaia "https://github.com/mxrch/ghunt/blob/master/ghunt/modules/gaia.py"
click node_drive "https://github.com/mxrch/ghunt/blob/master/ghunt/modules/drive.py"
click node_geolocate "https://github.com/mxrch/ghunt/blob/master/ghunt/modules/geolocate.py"
click node_spiderdal "https://github.com/mxrch/ghunt/blob/master/ghunt/modules/spiderdal.py"
click node_maps "https://github.com/mxrch/ghunt/blob/master/ghunt/helpers/gmaps.py"
click node_drive_api "https://github.com/mxrch/ghunt/blob/master/ghunt/apis/drive.py"
click node_people_api "https://github.com/mxrch/ghunt/blob/master/ghunt/apis/peoplepa.py"
click node_vision_api "https://github.com/mxrch/ghunt/blob/master/ghunt/apis/vision.py"
click node_cac_api "https://github.com/mxrch/ghunt/blob/master/ghunt/apis/clientauthconfig.py"
click node_dal_api "https://github.com/mxrch/ghunt/blob/master/ghunt/apis/digitalassetslinks.py"
click node_api_runtime "https://github.com/mxrch/ghunt/blob/master/ghunt/objects/apis.py"
click node_drive_parser "https://github.com/mxrch/ghunt/blob/master/ghunt/parsers/drive.py"
click node_knowledge "https://github.com/mxrch/ghunt/blob/master/ghunt/helpers/knowledge.py"
click node_http_client "https://github.com/mxrch/ghunt/blob/master/ghunt/lib/httpx.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli toneBlue
class node_login,node_auth_helpers,node_credentials toneAmber
class node_email,node_gaia,node_drive,node_geolocate,node_spiderdal,node_maps toneMint
class node_drive_api,node_people_api,node_vision_api,node_cac_api,node_dal_api toneRose
class node_api_runtime,node_drive_parser,node_knowledge,node_http_client,node_user,node_google toneIndigo
```

## Components

### User interface

- [CLI commands](https://github.com/mxrch/ghunt/blob/master/ghunt/cli.py): `ghunt/cli.py`

### Authentication

- [Login flow](https://github.com/mxrch/ghunt/blob/master/ghunt/modules/login.py): `ghunt/modules/login.py`
- [Credential auth](https://github.com/mxrch/ghunt/blob/master/ghunt/helpers/auth.py): `ghunt/helpers/auth.py`
- [Credential model](https://github.com/mxrch/ghunt/blob/master/ghunt/objects/base.py): `ghunt/objects/base.py`

### Investigations

- [Email lookup](https://github.com/mxrch/ghunt/blob/master/ghunt/modules/email.py): `ghunt/modules/email.py`
- [Gaia lookup](https://github.com/mxrch/ghunt/blob/master/ghunt/modules/gaia.py): `ghunt/modules/gaia.py`
- [Drive lookup](https://github.com/mxrch/ghunt/blob/master/ghunt/modules/drive.py): `ghunt/modules/drive.py`
- [BSSID geolocation](https://github.com/mxrch/ghunt/blob/master/ghunt/modules/geolocate.py): `ghunt/modules/geolocate.py`
- [Asset-link search](https://github.com/mxrch/ghunt/blob/master/ghunt/modules/spiderdal.py): `ghunt/modules/spiderdal.py`
- [Maps enrichment](https://github.com/mxrch/ghunt/blob/master/ghunt/helpers/gmaps.py): `ghunt/helpers/gmaps.py`

### Google API access

- [Drive API](https://github.com/mxrch/ghunt/blob/master/ghunt/apis/drive.py): `ghunt/apis/drive.py`
- [People API](https://github.com/mxrch/ghunt/blob/master/ghunt/apis/peoplepa.py): `ghunt/apis/peoplepa.py`
- [Vision API](https://github.com/mxrch/ghunt/blob/master/ghunt/apis/vision.py): `ghunt/apis/vision.py`
- [Client auth config](https://github.com/mxrch/ghunt/blob/master/ghunt/apis/clientauthconfig.py): `ghunt/apis/clientauthconfig.py`
- [Digital asset links](https://github.com/mxrch/ghunt/blob/master/ghunt/apis/digitalassetslinks.py): `ghunt/apis/digitalassetslinks.py`

### Shared runtime

- [API request runtime](https://github.com/mxrch/ghunt/blob/master/ghunt/objects/apis.py): `ghunt/objects/apis.py`
- [Drive parser](https://github.com/mxrch/ghunt/blob/master/ghunt/parsers/drive.py): `ghunt/parsers/drive.py`
- [Reference knowledge](https://github.com/mxrch/ghunt/blob/master/ghunt/helpers/knowledge.py): `ghunt/helpers/knowledge.py`
- [Async HTTP client](https://github.com/mxrch/ghunt/blob/master/ghunt/lib/httpx.py): `ghunt/lib/httpx.py`

### Other components

- **Operator**
- **Google services**

## Connections

- Operator → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Login flow: dispatches login (evidence: `ghunt/cli.py`)
- CLI commands → Email lookup: dispatches lookup (evidence: `ghunt/cli.py`)
- CLI commands → Gaia lookup: dispatches lookup (evidence: `ghunt/cli.py`)
- CLI commands → Drive lookup: dispatches lookup (evidence: `ghunt/cli.py`)
- CLI commands → BSSID geolocation: dispatches lookup (evidence: `ghunt/cli.py`)
- CLI commands → Asset-link search: dispatches search (evidence: `README.md`)
- Login flow → Credential auth: loads authentication (evidence: `ghunt/modules/login.py`)
- Credential auth → Credential model: updates credentials (evidence: `ghunt/helpers/auth.py`)
- Email lookup → Credential auth: authenticates (evidence: `ghunt/modules/email.py`)
- Email lookup → People API: looks up people (evidence: `ghunt/modules/email.py`)
- Email lookup → Vision API: queries vision (evidence: `ghunt/modules/email.py`)
- Email lookup → Maps enrichment: enriches with Maps (evidence: `ghunt/modules/email.py`)
- Gaia lookup → People API: queries profiles (evidence: `ghunt/modules/gaia.py`)
- Gaia lookup → Maps enrichment: enriches with Maps (evidence: `ghunt/modules/gaia.py`)
- Drive lookup → Credential auth: authenticates (evidence: `ghunt/modules/drive.py`)
- Drive lookup → Drive API: fetches Drive data (evidence: `ghunt/modules/drive.py`)
- Drive lookup → Client auth config: looks up app brand (evidence: `ghunt/modules/drive.py`)
- Asset-link search → Digital asset links: queries asset links (evidence: `ghunt/modules/spiderdal.py`)
- Drive API → Drive parser: parses responses (evidence: `ghunt/apis/drive.py`)
- Drive API → Reference knowledge: uses Drive knowledge (evidence: `ghunt/apis/drive.py`)
- Drive API → API request runtime: uses API runtime (evidence: `ghunt/apis/drive.py`)
- People API → API request runtime: uses API runtime (evidence: `ghunt/apis/peoplepa.py`)
- Vision API → API request runtime: uses API runtime (evidence: `ghunt/apis/vision.py`)
- Client auth config → API request runtime: uses API runtime (evidence: `ghunt/apis/clientauthconfig.py`)
- API request runtime → Async HTTP client: sends requests (evidence: `ghunt/objects/apis.py`)
- API request runtime → Google services: calls Google APIs (evidence: `ghunt/objects/apis.py`)
