An AI-powered blackbox penetration testing framework that uses LangGraph, Google Gemini, and Reinforcement Learning to automatically discover and exploit vulnerabilities in web applications.
- 🤖 Autonomous Web Navigation: Uses Playwright to interact with web applications like a real user
- 🔍 Intelligent Vulnerability Discovery: AI-driven approach to finding security issues
- 💉 SQL Injection Detection: Automatically tests for and exploits SQL injection vulnerabilities
- 📊 Real-time Dashboard: React-based UI showing pipeline progress, logs, and reports
- 📝 Comprehensive Reporting: Generates detailed reports with screenshots and executive summaries
- 🧠 Reinforcement Learning: Learns from successful exploits to improve future performance
The fastest way to see everything in action:
echo 'GOOGLE_API_KEY=your-key-here' > .env./run_demo.shThis single command:
- ✅ Installs all dependencies (npm + pip)
- ✅ Starts the buggy-vibe vulnerable test app (ports 3001, 5173)
- ✅ Starts the API server (port 8000)
- ✅ Starts the Dashboard (port 3000)
Navigate to http://localhost:3000 and click "🚀 Run Full Pipeline"
Watch the AI:
- Discover the application structure
- Find vulnerable endpoints
- Exploit SQL injection flaws
- Extract sensitive data
- Generate an executive report
- Python 3.8+
- Node.js 16+
- Google API Key(s) for Gemini
If you prefer manual setup over the demo script:
git clone https://github.com/enturesting/blackbox-rl-agent.git
cd blackbox-rl-agentpip install -r requirements.txt
playwright install chromiumcd frontend && npm install && cd ..
cd target-apps/buggy-vibe && npm install && cd ../..cp .env.example .envEdit .env and add your Google API key(s):
GOOGLE_API_KEY=your-api-key-here
# For higher rate limits, add multiple keys:
GOOGLE_API_KEY_2=another-api-key
GOOGLE_API_KEY_3=yet-another-key
# ... up to GOOGLE_API_KEY_9Note: Each API key provides ~10 requests per minute. Multiple keys increase throughput.
- Start everything:
./run_demo.sh - Open http://localhost:3000
- Set target URL (default:
http://localhost:5173) - Click "🚀 Run Full Pipeline" for automated scan
- Or run individual phases:
- Recon - Discover the application
- Plan - Generate attack strategy
- Attack - Execute exploits
- Analyze - Review findings
- Report - Generate executive summary
# Set target URL and run full pipeline
export TARGET_URL=http://localhost:5173
./run_all_agents.shOr run individual agents:
python qa_agent_v1.py # Reconnaissance
python exploit_planner.py # Attack planning
python attack.py # Exploitation
python gemini_coderabbit_analyzer.py # Analysis
python executive_report_generator.py # Reportingblackbox-rl-agent/
├── run_demo.sh # 🚀 One-command demo launcher
├── run_all_agents.sh # CLI pipeline runner
├── server.py # FastAPI backend for dashboard
│
├── qa_agent_v1.py # Phase 1: Reconnaissance agent
├── exploit_planner.py # Phase 2: Attack planning
├── attack.py # Phase 3: Exploitation
├── gemini_coderabbit_analyzer.py # Phase 4: Analysis
├── executive_report_generator.py # Phase 5: Reporting
│
├── frontend/ # React dashboard
│ ├── src/App.jsx # Main UI component
│ └── package.json
│
├── target-apps/
│ └── buggy-vibe/ # Vulnerable test application
│ ├── src/ # React frontend
│ ├── server-vulnerable.cjs # Intentionally vulnerable API
│ └── pw_db.json # Mock database
│
├── requirements.txt # Python dependencies
├── .env # Environment variables
├── qa_screenshots/ # Screenshot outputs
├── qa_reports/ # Generated reports
└── rl_training_data.json # RL training data
| Phase | Agent | Description |
|---|---|---|
| 1. Recon | qa_agent_v1.py |
Navigate app, discover endpoints, identify attack surfaces |
| 2. Plan | exploit_planner.py |
Generate attack strategies based on findings |
| 3. Attack | attack.py |
Execute planned exploits (SQL injection, XSS, etc.) |
| 4. Analyze | gemini_coderabbit_analyzer.py |
Review and categorize vulnerabilities |
| 5. Report | executive_report_generator.py |
Generate HTML executive summary |
After running the pipeline:
qa_screenshots/- Screenshots of each action takenqa_reports/- Detailed markdown reports per phaseexecutive_report_*.html- Final executive summaryrl_training_data.json- RL training data for improvement
- Ensure
.envfile exists:echo 'GOOGLE_API_KEY=your-key' > .env - Check that python-dotenv is installed:
pip install python-dotenv
- Add more Google API keys to increase rate limit (up to 9 keys)
- The agent automatically rotates between available keys
- The demo script automatically kills existing processes on required ports
- Manual cleanup:
lsof -ti:3000,3001,5173,8000 | xargs kill
- Ensure Playwright is installed:
playwright install chromium - Check for headless mode issues: set
headless=Truein agent code
This tool is designed for authorized security testing only. Never use it against applications you don't own or have explicit permission to test.
Important: do NOT commit your local .env containing real API keys.
- Use
.env.exampleas a template and keep real keys local only. - Verify before committing:
git status --porcelainand ensure.envis not listed. - If you accidentally added
.envto the repo, remove it from the index:git rm --cached .env && git commit -m "chore: remove local .env from repo".
- Create a feature branch:
git checkout -b feature/your-feature - Make your changes
- Test with the buggy-vibe application
- Submit a pull request
MIT License - See LICENSE file