Automatically discover adversarial failures in AI APIs before users exploit them.

Built for the DigitalOcean Gradient AI Hackathon 🎉

Adversarial testing platform powered by DigitalOcean Gradient™ AI for attack generation, deep vulnerability analysis, iterative refinement, and developer-friendly fix suggestions.

🌐 Live app: https://shadowlab-h9yu6.ondigitalocean.app/
(Gradient AI is pre-configured — scans use AI-generated attacks and AI-powered analysis)

# 1. Clone and configure
git clone https://github.com/prabhakaran-jm/shadowlab-ai.git
cd shadowlab-ai

# 2. Backend: set GRADIENT_MODEL_ACCESS_KEY in backend/.env (see docs/GRADIENT_SETUP.md)
cd backend
pip install -r requirements.txt
cp .env.example .env
# Edit .env: GRADIENT_MODEL_ACCESS_KEY=<your key>, ALLOW_LOCALHOST_TARGET=1 for local demo
uvicorn app.main:app --reload

# 3. Frontend (new terminal)
cd frontend
npm install
npm run dev

4. Open http://localhost:3000

5. Try the mock vulnerable API:

• API Endpoint: http://localhost:8000/mock-vulnerable-api
• Ensure ALLOW_LOCALHOST_TARGET=1 in backend/.env
• Click Start Scan — you’ll see failures, a lower safety score, and AI-generated fix suggestions

AI APIs often fail under adversarial or edge-case inputs. Common failure modes include:

Developers lack tools to proactively test these vulnerabilities before they are exploited in production.

ShadowLab is an adversarial testing platform that:

• Generates adversarial prompts via DigitalOcean Gradient AI or a curated seed set (15 payloads)
• Runs automated red-team scans against HTTP AI APIs (POST with JSON: message or OpenAI-style messages)
• Detects vulnerabilities using heuristic rules and Gradient AI–powered deep analysis on every response
• Iteratively refines attacks — when a target defends successfully, Gradient generates follow-up bypass attempts
• Suggests fixes with developer-friendly remediation (including Gradient-generated suggestions)
• Computes a safety score (0–100) so you can track and compare API robustness over time

ShadowLab uses DigitalOcean Gradient™ AI in four distinct ways:

This two-model design optimizes performance and cost. Without a Model Access Key, the app falls back to seed attacks and heuristic-only judging.

📖 Setup: docs/GRADIENT_SETUP.md for GRADIENT_MODEL_ACCESS_KEY and optional overrides.

• Attack generation — Gradient AI–generated or seed-based (15 payloads: prompt injection, system prompt extraction, policy bypass, encoding bypass, multi-language, and more)
• AI-powered detection — Gradient AI analyzes all responses, not only heuristic matches (subtle leakage, compliance, tone)
• Iterative refinement — Multi-round adaptive testing that learns from the target’s defenses

• Safety score — 0–100 derived from severity of findings
• Developer-friendly fix recommendations — Actionable suggestions (including Gradient AI–enhanced)
• Security report dashboard — Summary, vulnerability counts, filterable/sortable results table, recommended fixes
• Gradient connectivity indicator — Real-time badge showing whether Gradient AI is connected
• Honest loading state — Real scan progress with status indicator (no fake logs)

• Persistent data — Targets and recent reports stored in SQLite (not in-memory only)
• Target URL guard — Private and localhost URLs rejected unless ALLOW_LOCALHOST_TARGET=1 (for local demo)

cd backend && pip install -r requirements.txt && cp .env.example .env && uvicorn app.main:app --reload
# In another terminal:
cd frontend && npm install && npm run dev

Then open http://localhost:3000.

• Optional: Set GRADIENT_MODEL_ACCESS_KEY (or GRADIENT_API_KEY) in backend/.env for Gradient AI → docs/GRADIENT_SETUP.md
• Local mock demo: Set ALLOW_LOCALHOST_TARGET=1 in backend/.env and use target http://localhost:8000/mock-vulnerable-api

cd backend
pip install -r requirements.txt
cp .env.example .env   # then set GRADIENT_MODEL_ACCESS_KEY or GRADIENT_API_KEY for Gradient AI
uvicorn app.main:app --reload

• API: http://localhost:8000
• Docs: http://localhost:8000/docs

Target URL guard: Private and localhost URLs are rejected unless ALLOW_LOCALHOST_TARGET=1 (use for the mock-vulnerable-api demo).

cd frontend
npm install
npm run dev

• Dashboard: http://localhost:3000
• Production: Set NEXT_PUBLIC_API_URL to your backend URL.
• Production build locally: npm run build then npm start (port 3000 unless PORT is set).

Backend (pytest):

cd backend
pip install -r requirements.txt
pytest tests/ -v
# CI: pytest tests/ -v --timeout=10

Frontend (Jest + React Testing Library):

cd frontend
npm install
npm run test

1. Push this repo to GitHub and connect it in the Apps dashboard (or use doctl apps create --spec .do/app.yaml after setting your repo in .do/app.yaml).
2. Add two services: backend (source dir backend, run sh run.sh, port 8080) and frontend (source dir frontend, npm run build / npm start, port 8080).
3. Backend env: CORS_ORIGINS = your frontend Live URL; optionally GRADIENT_MODEL_ACCESS_KEY.
4. Frontend env: NEXT_PUBLIC_API_URL = your backend Live URL, then redeploy the frontend.

📖 Full guide: docs/DEPLOYMENT.md

1. Start the stack — run backend (uvicorn) and frontend (npm run dev).
2. Open the dashboard — go to the frontend URL (e.g. http://localhost:3000).
3. Check Gradient status — scan form shows whether Gradient AI is connected.
4. Enter a target — API endpoint URL and optional target description.
5. Start scan — click Start Scan; status indicator shows real progress. With Gradient configured, attacks are generated by DigitalOcean Gradient AI and responses are analyzed by Gradient AI.
6. View report — Safety Score (with round count if refinement ran), vulnerability summary, filterable results table, and recommended fixes.
7. Filter findings — use severity filter (All / High / Medium / Low) to focus on issues.
8. Optional — try GET /scan/demo for a quick scan against a mock endpoint.

Built for the DigitalOcean Gradient AI Hackathon. The app integrates Gradient AI for attack generation, deep vulnerability detection, iterative refinement, and fix suggestions as described above.

Before submitting:

• Demo video: https://youtu.be/kv1Ye9RTBD8
• Live demo: https://shadowlab-h9yu6.ondigitalocean.app/

For judges: Set GRADIENT_MODEL_ACCESS_KEY in the backend (docs/GRADIENT_SETUP.md) so scans use Gradient. Without it, the app uses seed attacks and heuristic-only judging; the report should show "Adversarial attacks generated by DigitalOcean Gradient™ AI."

Note: Targets and reports are persisted in SQLite (backend/shadowlab.db by default; SHADOWLAB_DB_PATH). Up to 50 recent reports are retained automatically.

• Real-time attack streaming — stream attack events and judge results as they complete
• CI/CD integration — fail builds or block deploys when safety score or critical findings exceed thresholds
• Advanced adversarial mutation — multi-generation attack evolution for broader coverage
• Comparative reporting — track safety score trends across scan history

Built with ❤️ for the DigitalOcean Gradient AI Hackathon

Chaos engineering for AI APIs — find vulnerabilities before attackers do.