How m-sec-org/ez-ai-agent works
<explanation>
Below is a step‑by‑step guide to drawing an accurate, detailed system design diagram for the EZ AI Agent Demo project. The goal is to break the system into its core services, show how they interact, and highlight the key technologies and patterns in use.
1. Identify the Project Type and Purpose
- This is a multi‑service, full‑stack demo application showcasing an AI‑driven penetration‑testing orchestration framework.
- It bundles:
• A target web application (ez_target)
• A passive‑scanning toolset (ez_tools)
• An orchestration engine (ez_ai_agent_demo) that drives multiple AI “agents” via LLMs and browser automation
• A browser‑automation sandbox and API plus a React UI (steel-browser)
• All services are composed via Docker Compose.
2. Analyze the File Structure (High‑Level)
- Top‑level entries:
• docker-compose.yaml, .env, init.sql, pic/ (assets)
• ez_target/ – PHP target app + database init
• ez_tools/ – CLI passive‑scan binaries & config
• ez_ai_agent_demo/ – Python orchestration server + agent modules + LLM/config code
• steel-browser/
– api/ (Fastify TS backend driving ChromeDriver/Puppeteer & session services)
– ui/ (React/Vite frontend)
– Dockerfiles, nginx, render.yaml
- Notice the microservices pattern: each top‑level folder can be a separate container, networked together.
3. Pull Key Insights from README
- Core layers:
• Passive Scanning Engine (ez_tools)
• Browser‑Use Driver + Steel Sandbox (steel-browser/api + selenium/webdriver)
• AI Orchestrator (ez_ai_agent_demo) using DeepSeek/other LLMs
• Multi‑agent collaboration for testing, validation, reporting
- Entry points: UI at port 5173, target at port 8089, orchestrator started by start_server.py.
4. Main Components to Represent
a. Target Environment (“ez_target” service)
- PHP web app + MySQL (init.sql) behind Nginx/Apache
b. Passive‑Scan Toolset (“ez_tools” service)
- CLI binary listening on a port, driven by Docker container
c. AI Orchestration Service (“ez_ai_agent_demo”)
- Python server
- Modules: config, llm, orchestration, agent, task, tool adapters (calculator, faiss, file, GitHub, hack, langchain, web, Wikipedia)
- LLM integration (DeepSeek/Gemini via API)
d. Browser Automation Sandbox (steel-browser/api)
- Fastify TS API
- Selenium & Puppeteer patcher & driver
- Session management, cdp/selenium routes, plugins (browser-session, logger, proxy, etc.)
e. Frontend UI (steel-browser/ui)
- React/Vite application for triggering tests, showing logs & session consoles
f. External LLM Provider
- DeepSeek, Gemini (cloud API)
5. Relationships and Data Flows
- User → React UI (HTTP/WS)
- React UI → steel-browser API (HTTP/WS) to create browser sessions, view logs
- Orchestration Service ↔ LLM Provider (HTTPS API calls)
- Orchestration Service → Passive‑Scan Toolset (HTTP/CLI) for vulnerability scanning
- Orchestration Service → steel-browser API (HTTP) to drive browser‑use tasks
- Browser Sessions → Target Environment (HTTP) to simulate user interactions
- Toolset & Browser Automation → return scan & session data → Orchestration
- Orchestration → aggregates results → React UI (via its own API or push channel)
6. Highlight Architectural Patterns & Principles
- Microservices: each core capability runs in its own container & codebase
- Agent‑based orchestration: tasks are represented as Agent classes coordinated by an Orchestrator
- Layered design:
• Infrastructure layer (Docker, network)
• Service layer (target, tools, orchestration, browser API)
• Presentation layer (React UI)
• External services (LLM provider)
- Event‑driven / request‑response flows between services
- Separation of concerns: scanning, orchestration, automation, reporting
7. Technologies & Frameworks to Annotate
- Docker Compose, Dockerfiles
- Python (FastAPI or Flask–based orchestration)
- TypeScript + Fastify (steel-browser/api)
- Selenium & Puppeteer (browser automation)
- React + Vite (steel-browser/ui)
- LLM API (DeepSeek/Gemini)
- PHP + MySQL (target)
- CLI tools (ez_tools passive scanner)
8. Guidelines for Tailoring Your Diagram
- Group services into Swimlanes or Containers (Docker)
- Use distinct shapes or colors for:
• Internal services (containers)
• External services (LLM, GitHub, etc.)
• Data stores (MySQL)
• Users/Clients (browser)
- Show directional arrows for request/response, event notifications, data flow
- Label each arrow with protocol or API name (HTTP, WS, CLI)
- Include notes on key ports (5173, 8089, 9999, etc.) if space allows
9. Diagram Elements to Include
- Component boxes with clear names (e.g., “AI Orchestrator”, “Passive Scan Engine”, “Browser‑Automation API”, “UI”)
- Arrows showing:
• User → UI → Browser‑API → Target
• Orchestrator ↔ LLM
• Orchestrator → Passive‑Scan
• Orchestrator → Browser‑API
• Browser Sessions → Target
• Orchestrator → Reporting → UI
- Color coding:
• Blue for orchestration & agents
• Orange for automation & scanning tools
• Green for target & data store
• Purple for frontend & API
• Grey for external LLM service
- A legend explaining shapes/colors
By following these steps, you’ll produce a detailed, accurate architecture diagram that reflects every major service, data flow, and technology in the EZ AI Agent Demo. This will give stakeholders full visibility into how the multi‑agent pen‑testing framework is constructed and operates.
</explanation>