# tencent/ai-infra-guard architecture

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

- Interactive diagram: https://gitdiagram.com/tencent/ai-infra-guard
- Repository: https://github.com/tencent/ai-infra-guard

## Overview

Based on your review of the file tree and README, this project is an AI infrastructure security assessment tool called “AI Infra Guard.” Its purpose is to scan AI systems for security risks by matching web fingerprints and vulnerabilities using YAML rules. The tool supports both a command-line interface (CLI) and a web user interface (WEBUI), while its core engine processes various rules against target systems.

- Command-Line Interface (CLI): Represented by the “cmd/cli” package. This is the entry point when running in CLI mode.
- Web User Interface: Indicated by “common/websocket” which serves static files (index.html, bundle.js) to provide a web-based scan dashboard.
- Fingerprint & Vulnerability Processing Engine:
- Fingerprint Matching: Found in the “common/fingerprints” directory (with submodules for parsing, preloading, etc.) and the YAML definitions under “data/fingerprints.”
- Vulnerability Matching: Handled in part by the “pkg/vulstruct” package; YAML definitions for vulnerabilities are stored under “data/vuln.”
- Core Scanner & Runner: The “common/runner” package is responsible for scanning, executing HTTP requests, and aggregating results.
- HTTP Client Utilities: Provided by “pkg/httpx” for performing web requests during scan operations.
- External AI Integration: The README mentions AI analysis when using tokens (e.g. hunyuan token, deepseek token). The “pkg/openai” package (and similar integration points) are involved here.
- Logging & Configuration: Internal modules under “internal/gologger” and “internal/options” support logging, banner display, and configuration management.
- Data & YAML Rule Configuration: The “data” directory holds the external fingerprint and vulnerability YAML rules, which form the “knowledge base” that drives the scanner’s behavior.

##### Relationships and Interactions
- The user interacts either via the CLI (by providing flags like “-target” or “-localscan”) or via the WEBUI.
- In both modes, the system loads rule definitions (fingerprints & vulnerabilities) from the “data” folder.
- The scanning engine (in “common/runner”) uses utilities (in “pkg/httpx”) to send HTTP requests to target services.
- The fingerprint processing modules validate responses using the logic in “common/fingerprints” (parsers, matchers).
- When vulnerability checks are triggered, the “pkg/vulstruct” component processes those outcomes against vulnerability definitions.
- If running in WEBUI mode, the web server component in “common/websocket/server.go” serves static content and might push results via websockets.
- Optionally, if AI-based analysis is triggered, calls might be made through the AI integrations (e.g., “pkg/openai”).
- Logging and configuration are centrally handled by the “internal” packages, making sure that runtime parameters and output are managed cleanly.

##### Important Architectural Patterns and Technologies
- Modularity: Each major function (UI, fingerprint parsing, vulnerability matching, HTTP communications) is neatly separated across packages.
- YAML-Driven Configuration: The system uses external YAML files to define fingerprints and vulnerability matching rules, which allows for easy updates to security definitions.
- Lightweight and Efficient Design: Emphasized in the README – small binary, cross-platform support.
- Command Design: A clear separation between input interfaces (CLI vs. WEBUI) and the scanning engine.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Global User
    User("User"):::util

    %% UI Layer
    subgraph "UI Layer"
        CLI("Command-Line Interface (CLI)"):::ui
        WEBUI_Server("Web UI Server"):::ui
        WEBUI_Static("Web UI Static Files"):::ui
    end

    %% Core Engine
    subgraph "Core Engine"
        Runner("Core Scanner & Runner"):::core
        Fingerprint("Fingerprint Matching Engine"):::core
        Vulnerability("Vulnerability Matching Engine"):::core
    end

    %% Communication Modules
    subgraph "Communication Modules"
        HTTP("HTTP Client Utilities"):::util
        AI("External AI Integration"):::util
    end

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        Logger("Logging Module"):::util
        Config("Configuration Module"):::util
    end

    %% Data Repository
    subgraph "Data Repository"
        FP_YAML("Fingerprint YAML Definitions"):::data
        Vuln_YAML("Vulnerability YAML Definitions"):::data
        DataRepo("YAML Rule Configuration/Data Repository"):::data
    end

    %% External Target System (for HTTP communications)
    Target("Target Systems"):::util

    %% Relationships

    %% User interactions
    User --> CLI
    User --> WEBUI_Server

    %% UI to Core Engine
    CLI --> Runner
    WEBUI_Server --> Runner

    %% Core Engine interactions
    Runner --> HTTP
    Runner --> Fingerprint
    Runner --> Vulnerability
    Runner --> Logger
    Runner --> Config
    Runner --> AI

    %% HTTP communications to target systems
    HTTP -->|"HTTPRequests"| Target

    %% Data flow for Fingerprint Matching
    FP_YAML --> Fingerprint

    %% Data flow for Vulnerability Matching
    Vuln_YAML --> Vulnerability

    %% Link Data repository
    DataRepo --- FP_YAML
    DataRepo --- Vuln_YAML

    %% Click Events
    click CLI "https://github.com/tencent/ai-infra-guard/blob/main/cmd/cli/main.go"
    click WEBUI_Server "https://github.com/tencent/ai-infra-guard/blob/main/common/websocket/server.go"
    click WEBUI_Static "https://github.com/tencent/ai-infra-guard/tree/main/common/websocket/static"
    click Fingerprint "https://github.com/tencent/ai-infra-guard/tree/main/common/fingerprints"
    click FP_YAML "https://github.com/tencent/ai-infra-guard/tree/main/data/fingerprints"
    click Vulnerability "https://github.com/tencent/ai-infra-guard/tree/main/pkg/vulstruct"
    click Vuln_YAML "https://github.com/tencent/ai-infra-guard/tree/main/data/vuln"
    click Runner "https://github.com/tencent/ai-infra-guard/tree/main/common/runner"
    click HTTP "https://github.com/tencent/ai-infra-guard/tree/main/pkg/httpx"
    click AI "https://github.com/tencent/ai-infra-guard/tree/main/pkg/openai"
    click Logger "https://github.com/tencent/ai-infra-guard/tree/main/internal/gologger"
    click Config "https://github.com/tencent/ai-infra-guard/tree/main/internal/options"
    click DataRepo "https://github.com/tencent/ai-infra-guard/tree/main/data"

    %% Styles
    classDef ui fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef core fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef util fill:#ffa500,stroke:#000,stroke-width:2px;
    classDef data fill:#d3d3d3,stroke:#000,stroke-width:2px;
```
