SentinelSwarm

SentinelSwarm is an autonomous DevSecOps orchestration project for Python code generation, test automation, security scanning, red-team simulation, patching, and GCP deployment. It now ships with a working frontend, wired to the backend API.

Project structure

sentinelswarm/
├── Dockerfile              # builds backend + frontend into one image
├── cloudbuild.yaml         # Cloud Build config
├── requirements.txt
├── .env.example            # copy to .env and fill in GROQ_API_KEY
├── backend/
│   ├── main.py              # FastAPI app - API routes + serves frontend/
│   ├── orchestrator.py       # pipeline: generate -> test -> scan -> policy -> red-team -> patch
│   ├── agents.py             # Coder, Tester, SecurityScanner, Policy, RedTeam, Patcher agents
│   ├── project_orchestrator.py
│   ├── multi_repo_orchestrator.py, multi_repo_demo.py
│   ├── attack_graph.py, vuln_mappings.py, verify_project_request.py
│   ├── test_orchestrator.py, test_project_orchestrator.py   # real pytest suite
│   └── manual_check_agent.py, manual_check_pipeline.py      # manual smoke scripts, NOT run by pytest
└── frontend/
    ├── index.html            # landing page
    ├── login.html            # no backend auth endpoint exists yet - just links through to the dashboard
    ├── dashboard.html        # dynamic stats, recent runs, pipeline overview for the latest active run
    ├── new-run.html          # creates a run, then hands off to live-run.html once it appears
    ├── live-run.html         # polls a single run's real status/history until it finishes
    ├── run-details.html      # full report for one run + approve/reject review
    ├── review-queue.html     # runs with status needs_human_review / scan_failed / policy_failed
    ├── run-history.html      # full run list with search + pagination
    ├── projects.html         # lists/creates projects
    ├── theme-config.js       # shared Tailwind color/type tokens (dark "mint" theme) used by every page
    ├── components.js         # shared sidebar + topbar, injected into every app page
    ├── api.js                # shared fetch client all pages use
    └── assets/logo.png

All pages share one dark visual theme via theme-config.js, and one sidebar/topbar via components.js (renderSidebar('page-key') / renderTopbar({...})) so nav links, the logo, and the Review Queue badge count stay consistent everywhere. Because POST /runs blocks until the whole pipeline finishes, new-run.html doesn't wait on that request directly — it polls GET /runs for the new row (which the orchestrator writes to the database as each stage completes) and redirects to live-run.html, which polls GET /runs/{id}/report for real progress. There is no fake/simulated data anywhere in the frontend now; every page that shows run data fetches it from the API.

Local setup (Windows CMD)

cd sentinelswarm
python -m venv venv
venv\Scripts\python.exe -m pip install --upgrade pip
venv\Scripts\python.exe -m pip install -r requirements.txt
copy .env.example .env

Open .env in a text editor and set GROQ_API_KEY (required for run creation to actually generate code). Then load it into your shell before running the server:

for /f "tokens=1,2 delims==" %A in (.env) do set %A=%B

Run locally

cd backend
..\venv\Scripts\python.exe -m uvicorn main:app --host 127.0.0.1 --port 8000

Then open http://127.0.0.1:8000/app/ in a browser — that's the SentinelSwarm frontend, served directly by the backend. No separate frontend server needed. (http://127.0.0.1:8000/ on its own just returns a small JSON status message — that's the API root, not the dashboard.)

• Swagger API docs: http://127.0.0.1:8000/docs

Run tests

cd backend
..\venv\Scripts\python.exe -m pytest -q

This runs the real automated suite (test_orchestrator.py, test_project_orchestrator.py). It does not run manual_check_agent.py / manual_check_pipeline.py — those make live Groq API calls and are meant to be run manually:

..\venv\Scripts\python.exe manual_check_agent.py

GCP Cloud Run deployment

Run these from the project root (where the Dockerfile is):

gcloud builds submit --tag gcr.io/%PROJECT_ID%/sentinelswarm:latest .
gcloud run deploy sentinelswarm ^
  --image gcr.io/%PROJECT_ID%/sentinelswarm:latest ^
  --platform managed ^
  --region YOUR_REGION ^
  --allow-unauthenticated ^
  --port 8000 ^
  --set-env-vars GROQ_API_KEY=your-key-here

Or trigger a build with cloudbuild.yaml directly:

gcloud builds submit --config cloudbuild.yaml .

After deploying, check it's actually live:

gcloud run services describe sentinelswarm --region YOUR_REGION --format="value(status.url)"
curl <that-url>/

You should get back {"message": "SentinelSwarm backend is alive"}, and opening the URL in a browser should show the SentinelSwarm dashboard, not a 404.

Environment variables

• GROQ_API_KEY — required for agents.py code generation and test generation. The server will still start without it, but creating a run will fail with a clear error until it's set.
• SANDBOX_BASE_URL — optional base URL for the sandbox target application
• SANDBOX_APP_PATH — optional path to the local sandbox app file

Notes

• The frontend (frontend/) is plain HTML + Tailwind (via CDN) + vanilla JS — no build step, no npm install needed. frontend/api.js is the only file that knows the backend URL; edit window.SENTINEL_API_BASE there if you ever host the frontend on a different origin from the backend.
• There is currently no real authentication endpoint on the backend. login.html just navigates to the dashboard — treat this as a placeholder until an auth API exists.