How m-sec-org/ez-ai-agent works
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.
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.
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.
Main Components
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)
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)
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
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)