# ed1s0nz/privhunterai architecture

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

- Interactive diagram: https://gitdiagram.com/ed1s0nz/privhunterai
- Repository: https://github.com/ed1s0nz/privhunterai

## Overview

##### Project Type and Purpose
- PrivHunterAI is a Go-based security tool that passively intercepts HTTP(S) traffic (via a built-in MITM proxy), analyzes request/response pairs using AI engines (e.g., GPT, DeepSeek) to detect authorization bypass vulnerabilities, and exposes both a CLI interface and a lightweight web dashboard.

##### File Structure Analysis
- Top-level files:
- main.go – CLI entrypoint that initializes modules (config, proxy, scanner, web).
- mitmproxy.go – Sets up an HTTP/HTTPS proxy (listening on 9080) to capture traffic.
- scan.go – Core scanning orchestration: feeding intercepted requests to AI logic.
- AIAPIS/aiapis.go – Adapter for different AI providers’ HTTP APIs.
- config/config.go & config.json – Configuration loader for AI model, API keys, headers, filters.
- tools.go – Common utilities (e.g., JSON diff, dynamic-field filtering).
- index.go + index.html + img/ – Web server handlers and static assets (dashboard on port 8222).
- go.mod/go.sum – Module declarations and dependencies.

##### Key Components
a. Proxy Layer:
- MITM Proxy (mitmproxy.go) intercepts client → server HTTP(S) traffic.
b. Scanner Core:
- scan.go orchestrates preprocessing, invokes tools.go utilities, calls AIAPIS adapter.
c. AI Engine Integration:
- AIAPIS module relays formatted prompts to external AI services (GPT, Kimi, etc.) and returns analysis.
d. Configuration Module:
- config module loads config.json (API keys, filters, header rules).
e. Persistence/State (In-Memory):
- Scanner holds transient request/response records; no external DB is defined.
f. Web Dashboard:
- index.go serves REST endpoints and UI (index.html + img assets) for real-time results on port 8222.
g. CLI Interface:
- main.go CLI flags to start proxy, scan workflows, and optionally launch web server.

##### Component Interactions & Data Flow
1. User configures config.json → runs `privhunterai` binary.
2. main.go reads config → starts MITM proxy and scanner loop.
3. Client (e.g., browser or BurpSuite) routes traffic through proxy.
4. mitmproxy captures Request A, forwards to real server, captures Response A; then modifies credentials (Request B) as per headers2, captures Response B.
5. scan.go passes reqA, respA, respB to preprocessing (tools filter dynamic fields, identify read/write) → invokes AIAPIS with a JSON prompt.
6. AIAPIS sends HTTP request to external AI provider → receives analysis JSON.
7. scan.go applies decision tree → constructs result object (res, reason, confidence).
8. Results are stored in memory and forwarded to:
- CLI stdout renderer
- Web server endpoint (index.go)
9. User views results in terminal or navigates to 127.0.0.1:8222 in browser to see dashboard.

##### Architectural Patterns & Principles
- Modular Separation: proxy, scanner logic, AI adapter, config, web server are cleanly separated.
- Adapter Pattern: AIAPIS abstracts multiple AI providers under a common interface.
- Pipeline/Chain of Responsibility: scan.go steps through preprocessing, quick channel, deep analysis.
- Inversion of Control: main.go wires components based on config.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        Browser["Browser/BurpSuite"]:::external
    end

    subgraph "Proxy Layer"
        Proxy["MITM Proxy\n(mitmproxy.go)"]:::internal
    end

    subgraph "Scanner & AI Integration"
        Scanner["Scanner Core\n(scan.go)"]:::internal
        Tools["Utilities\n(tools.go)"]:::internal
        AIAPIS["AIAPIS Adapter\n(AIAPIS/aiapis.go)"]:::internal
        AIProvider["External AI Provider"]:::external
        TargetServer["Target Web Server"]:::external
    end

    subgraph "Configuration"
        ConfigModule["Config Loader\n(config/config.go)"]:::config
        ConfigJSON["config.json"]:::config
    end

    subgraph "Presentation Layer"
        CLI["CLI Interface\n(main.go)"]:::internal
        WebServer["Web Dashboard\n(index.go)"]:::internal
        UIHTML["UI Static\n(index.html)"]:::internal
        ImgAssets["Image Assets\n(img/)"]:::internal
    end

    subgraph "Project Metadata"
        GoMod["go.mod"]:::docs
        GoSum["go.sum"]:::docs
        README["README.md"]:::docs
    end

    Browser -->|"Intercept HTTP(S)"| Proxy
    Proxy -->|"Forward to Target"| TargetServer
    Proxy -->|"Capture reqA,respA,reqB,respB"| Scanner
    ConfigJSON -->|"Load settings"| ConfigModule
    ConfigModule -->|"Provide proxy rules"| Proxy
    ConfigModule -->|"Provide AI settings"| AIAPIS
    Scanner -->|"Preprocess pipeline"| Tools
    Tools -->|"Return filtered data"| Scanner
    Scanner -->|"JSON prompt"| AIAPIS
    AIAPIS -->|"HTTPS request/response"| AIProvider
    AIAPIS -->|"Return analysis"| Scanner
    Scanner -->|"Result(res,reason,confidence)"| CLI
    Scanner -->|"Result(res,reason,confidence)"| WebServer
    WebServer -->|"Serve UI"| UIHTML
    UIHTML -->|"Load assets"| ImgAssets

    click Proxy "https://github.com/ed1s0nz/privhunterai/blob/main/mitmproxy.go"
    click Scanner "https://github.com/ed1s0nz/privhunterai/blob/main/scan.go"
    click Tools "https://github.com/ed1s0nz/privhunterai/blob/main/tools.go"
    click AIAPIS "https://github.com/ed1s0nz/privhunterai/blob/main/AIAPIS/aiapis.go"
    click ConfigModule "https://github.com/ed1s0nz/privhunterai/blob/main/config/config.go"
    click ConfigJSON "https://github.com/ed1s0nz/privhunterai/blob/main/config.json"
    click CLI "https://github.com/ed1s0nz/privhunterai/blob/main/main.go"
    click WebServer "https://github.com/ed1s0nz/privhunterai/blob/main/index.go"
    click UIHTML "https://github.com/ed1s0nz/privhunterai/blob/main/index.html"
    click ImgAssets "https://github.com/ed1s0nz/privhunterai/tree/main/img/"
    click GoMod "https://github.com/ed1s0nz/privhunterai/blob/main/go.mod"
    click GoSum "https://github.com/ed1s0nz/privhunterai/blob/main/go.sum"
    click README "https://github.com/ed1s0nz/privhunterai/blob/main/README.md"

    classDef internal fill:#add8e6,stroke:#000
    classDef external fill:#90ee90,stroke:#000
    classDef config fill:#fffacd,stroke:#000
    classDef docs fill:#dda0dd,stroke:#000
```
