# praveenk8051/agentic_security architecture

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

- Interactive diagram: https://gitdiagram.com/praveenk8051/agentic_security
- Repository: https://github.com/praveenk8051/agentic_security

## Overview

##### Project Type and Purpose
- This is a full-stack, open-source vulnerability scanner ("Agentic Security") for AI/LLM workflows.
- Backend: Python package (`agentic_security/…`) exposing HTTP endpoints (via FastAPI/Uvicorn).
- Frontend: Vue.js Single-Page Application in `ui/`, served as static assets.
- CLI: Entry-point `agentic_security` for command-line scanning and CI checks.
- Features: multimodal attacks (text, image, audio), multi-step jailbreaks, fuzzing, RL-based probes, plugin modules, dataset registry.

##### File Structure Analysis
- Top-level:
- `.github/workflows`, CI/CD config (Docker build, tests, security scans, releases)
- `Dockerfile`, `.dockerignore`, `pyproject.toml`
- `agentic_security/`: backend code
- `ui/`: frontend SPA (Vue, Tailwind CSS)
- `docs/`: markdown docs and MkDocs config
- `tests/`, `tests/routes/`, `tests/probe_actor/`, etc.
- Backend substructure:
- `app.py`, `core/`, `routes/`, `middleware/`, `agents/`, `probe_actor/`, `probe_data/`, `refusal_classifier/`, `integrations/`, `mcp/`
- Config & dependencies (`config.py`, `dependencies.py`, `http_spec.py`)
- Static file handlers (`routes/static.py`) serving frontend assets
- Frontend:
- `ui/src/`: Vue components (`App.vue`, page components)
- `ui/public/`: compiled assets, `index.html`, telemetry scripts
- Build config: `vue.config.js`, `tailwind.config.js`, ESLint, Babel

##### README Insights
- Defines core use cases: vulnerability probing, dataset extensions, CI integration, CLI usage.
- Lists HTTP spec for LLM calls, custom self-probe endpoints for text/image/audio.
- Shows modular design: dataset registry, dynamic mutation modules (stenography), plugin integrations (Garak, InspectAI, etc.).
- Mentions MCP micro-client (`agentic_security/mcp`) for service orchestration.

a. Main Components
- **Browser (Client-Side SPA)**
- Vue.js application (UI components, telemetry scripts)
- **API Gateway / HTTP Server**
- FastAPI application (`agentic_security/app.py`) hosted on Uvicorn
- Middleware layers: CORS, logging
- Routers: `/probe`, `/scan`, `/report`, `/static`, `/telemetry`, `/v1/self-probe`
- **Scanning Engine / Core Services**
- Probe Data Loader (`probe_data/`): dataset registry, local CSV, HF datasets, dynamic generators
- Probe Actor (`probe_actor/`): fuzzers, cost modules, stateful multi-step actor, refusal logic
- Agents (`agents/`): higher-level orchestration classes (`operator_crew`, `operator_pydantic`)
- Refusal Classifier (`refusal_classifier/`): model artifacts for post-processing
- Integrations (`integrations/`): external tools and libraries (Garak, InspectAI, RL-attacks)
- MCP Client & Server (`mcp/`): optional microservice orchestrator
- **External Services**
- LLM Providers (OpenAI API, custom self-probe endpoints)
- Hugging Face Datasets, local CSV storage
- **Reporting & Storage**
- In-memory or file-based results aggregator (`report_chart.py`, JSON/CSV)
- CI/CD pipeline integration (GitHub Actions, Docker registry)
- **CLI Interface**
- Entry point via `agentic_security` script
- Config loader (`agesec.toml`), commands: `init`, `ls`, `ci`

b. Relationships and Interactions
- Browser ↔ HTTP Server: REST/HTTP calls for scans, reports, telemetry
- HTTP Server → Scanning Engine: dependency injection launches pipeline
- Scanning Engine ↔ External LLMs: HTTP calls per `http_spec` for each probe
- Probe Data Loader → Probe Actor: feeds prompts into actor modules
- Probe Actor → Refusal Classifier: decides pass/fail of each response
- MCP Client ↔ MCP Server: optional RPC for distributed scanning
- CLI ↔ Scanning Engine: same code paths as HTTP endpoints for headless scans
- CI/CD Pipeline ↔ CLI: automated security scans during pre-commit or GitHub Actions

c. Architectural Patterns & Principles
- Modular plugin architecture: datasets, actors, integrations register through registries
- Layered design: HTTP layer, service layer, data layer
- Dependency Injection: FastAPI dependencies for config and modules
- Microservice support: MCP sub-system for distributed tasks
- Single-Page Application front/back separation

d. Key Technologies & Frameworks
- Python 3, FastAPI, Uvicorn, Pydantic
- Vue.js, Tailwind CSS, Babel
- Hugging Face Datasets, joblib for model artifacts
- Docker, GitHub Actions, MkDocs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend
    subgraph "Frontend (Browser)"
        Browser["SPA (Vue.js)"]:::frontend
    end

    %% Backend
    subgraph "Backend"
        subgraph "HTTP Server & API Gateway"
            APIGateway["FastAPI Uvicorn"]:::api
            CoreApp["Core App"]:::api
        end

        subgraph "Middleware"
            CORS["CORS"]:::middleware
            LoggingMW["Logging"]:::middleware
        end

        subgraph "Routers"
            ProbeAPI["/probe, /scan, /report, /telemetry, /static"]:::router
        end

        subgraph "Service / Engine"
            ProbeData["Probe Data Loader"]:::service
            ProbeActor["Probe Actor"]:::service
            Agents["Agents Orchestration"]:::service
            Refusal["Refusal Classifier"]:::service
            Integrations["Integrations"]:::service
            MCP["MCP Client/Server"]:::service
        end

        Config["Config & DI"]:::utility
        StaticServe["Static File Serving"]:::service
        Reporting["Reporting & Storage"]:::service
        CoreUtils["Core Utils & Logging"]:::utility
    end

    %% CLI and CI
    CLI["CLI Interface"]:::cli
    CI["CI/CD Pipeline"]:::ci

    %% External Services
    subgraph "External Services"
        LLM["LLM Providers"]:::external
        HFData["HF Datasets / CSV"]:::external
    end

    %% Connections
    Browser -->|HTTP| APIGateway
    APIGateway --> CoreApp
    CoreApp --> CORS
    CoreApp --> LoggingMW
    CoreApp --> ProbeAPI
    ProbeAPI --> ProbeData
    ProbeAPI --> ProbeActor
    ProbeAPI --> Reporting
    ProbeData --> HFData
    ProbeData --> Integrations
    ProbeData --> Agents
    ProbeActor --> Refusal
    ProbeActor --> Integrations
    ProbeActor --> LLM
    Agents --> ProbeActor
    MCP --> ProbeActor
    CLI --> ProbeAPI
    CLI --> CoreApp
    CI --> CLI

    %% Click Events
    click Browser "https://github.com/praveenk8051/agentic_security/tree/main/ui/src/"
    click APIGateway "https://github.com/praveenk8051/agentic_security/blob/main/agentic_security/app.py"
    click CoreApp "https://github.com/praveenk8051/agentic_security/blob/main/agentic_security/core/app.py"
    click CORS "https://github.com/praveenk8051/agentic_security/blob/main/agentic_security/middleware/cors.py"
    click LoggingMW "https://github.com/praveenk8051/agentic_security/blob/main/agentic_security/middleware/logging.py"
    click ProbeAPI "https://github.com/praveenk8051/agentic_security/tree/main/agentic_security/routes/"
    click ProbeData "https://github.com/praveenk8051/agentic_security/tree/main/agentic_security/probe_data/"
    click ProbeActor "https://github.com/praveenk8051/agentic_security/tree/main/agentic_security/probe_actor/"
    click Agents "https://github.com/praveenk8051/agentic_security/tree/main/agentic_security/agents/"
    click Refusal "https://github.com/praveenk8051/agentic_security/blob/main/agentic_security/refusal_classifier/model.py"
    click Integrations "https://github.com/praveenk8051/agentic_security/tree/main/agentic_security/integrations/"
    click MCP "https://github.com/praveenk8051/agentic_security/blob/main/agentic_security/mcp/client.py"
    click CLI "https://github.com/praveenk8051/agentic_security/blob/main/agentic_security/__main__.py"
    click Config "https://github.com/praveenk8051/agentic_security/blob/main/agentic_security/config.py"
    click StaticServe "https://github.com/praveenk8051/agentic_security/blob/main/agentic_security/routes/static.py"
    click Reporting "https://github.com/praveenk8051/agentic_security/blob/main/agentic_security/report_chart.py"
    click CoreUtils "https://github.com/praveenk8051/agentic_security/blob/main/agentic_security/core/logging.py"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef api fill:#90CAF9,stroke:#1565C0,color:#1565C0
    classDef middleware fill:#E3F2FD,stroke:#64B5F6,color:#1565C0
    classDef router fill:#E1F5FE,stroke:#42A5F5,color:#1565C0
    classDef service fill:#C8E6C9,stroke:#2E7D32,color:#1B5E20
    classDef utility fill:#F0F4C3,stroke:#9E9D24,color:#827717
    classDef cli fill:#CFD8DC,stroke:#607D8B,color:#455A64
    classDef ci fill:#ECEFF1,stroke:#90A4AE,color:#455A64
    classDef external fill:#FFE0B2,stroke:#FB8C00,color:#E65100
```
