SentinelG3: Autonomous Self-Healing Security

An agentic security engineer powered by Gemini 3 that detects vulnerabilities and automatically opens verified, tested Pull Requests to fix them.

Comment

Sentinel-G3: Autonomous Self-Healing Security Auditor

Inspiration

Most security tools stop at finding problems. They hand you a long list of CVEs or findings and leave the rest to humans. We wanted something that closes the loop: an AI that doesn’t just detect vulnerabilities but reasons through them, fixes them, and proves that its reasoning actually happened—no black box, no “trust me.”

Three things pushed us toward Sentinel-G3:

  1. Transparency in AI security — If an AI suggests a code change, we should see why. Gemini 3’s chain-of-thought and thought_signature turn “the model said so” into a verifiable audit trail: reasoning depth and cryptographic proof in one pipeline.

  2. OWASP in practice — We’ve seen injection, broken auth, and hardcoded secrets over and over. We wanted a system that thinks in terms of attack vectors and context, not just regex, and that we could build with OWASP principles baked in (no prompt injection, no SSRF, no leaking tokens).

  3. Real workflows — Security fixes only matter if they land in code. Supporting GitHub repo scanning and automatic Pull Request creation meant the tool could slot into how teams already work: scan a repo, review the reasoning and diffs, merge the PR.

So we set out to build an autonomous, self-healing security auditor where Gemini 3’s reasoning is front and centre—and where every fix is explainable and verifiable.

What it does

Sentinel-G3 finds, fixes, and proves security issues in your codebase.

  • Scan — Point it at a local directory or paste a GitHub (or GitLab/Bitbucket) repo URL. The Auditor agent analyses every source file using Gemini 3 with high-level reasoning and returns a structured list of vulnerabilities: file, line, severity, and a short description. You see the Auditor’s chain-of-thought for each file.

  • Fix — For each finding, the Fixer agent generates a minimal, safe patch. Its reasoning streams live to the dashboard so you watch why it chose each change. Patches are applied on disk (with backups); for local scans you get modified files; for remote repos we work in a temporary clone.

  • Prove — Every reasoning step is backed by Gemini 3’s thought_signature. We extract and store these in the run manifest so you have a cryptographic audit trail that the reasoning really happened inside the model.

  • Integrate — For GitHub repos, you can optionally provide a token and check “Create PR.” After healing, Sentinel-G3 pushes a branch, commits the fixes, and opens a Pull Request with a summary table and per-finding status. You review and merge in your normal workflow.

The dashboard gives you a live terminal log, a collapsible chain-of-thought panel (vulnerable code + Fixer reasoning in markdown), and a Healing History table where each row expands to show Auditor/Fixer thoughts and a side-by-side code diff (original vs healed). So you’re never blindly applying patches—you see the reasoning and the exact code change every time.

How we built it

We structured the system in three layers: backend pipeline, real-time API, and dashboard.

Backend (Python + FastAPI)
The core pipeline is:

$$\text{Target (dir or repo)} \xrightarrow{\text{clone if URL}} \text{Auditor} \xrightarrow{\text{vulns}} \text{Fixer} \xrightarrow{\text{patches}} \text{Apply + optional PR}$$

  • Auditor — Sends each file to Gemini 3 with thinking_level="HIGH", include_thoughts=True, and response_schema=list[Vulnerability]. We accumulate thinking from every file so the UI can show the full audit chain-of-thought.

  • Fixer — For each vulnerability, sends the finding + original code. When the dashboard needs live reasoning, we use generate_content_stream and push thinking chunks into an asyncio.Queue; the SSE handler consumes the queue and emits thinking events. Patches are applied with backups; for remote repos we use a temp dir and tear it down after the run.

  • Orchestrator — Runs the pipeline, collects thought signatures from both agents, and writes run_manifest.json with the full audit trail.

We use the google-genai SDK (async), with configurable primary/fallback models (e.g. Flash → Pro on quota exhaustion). All agent I/O is Pydantic.

Real-time API (SSE)
The /api/v1/scan endpoint is one long-lived Server-Sent Events stream. It accepts directory or repo_url (and optional GitHub token + “Create PR”). Events: log, vuln, thinking, patch, summary, and pr (when a PR is created). The frontend subscribes and updates the terminal, stats, reasoning panel, and healing history in real time.

Dashboard (Next.js 15 + Tailwind)
“Cybersecurity war room” style: stats row (files scanned, threats found, healed), live terminal with semantic log colours and CRT-style scanlines, collapsible chain-of-thought (vulnerable snippet + markdown reasoning, auto-scroll), and Healing History with expandable rows and side-by-side code diffs. GitHub flow: paste repo URL and token, check “Create PR,” and get a branch + PR when the run finishes.

GitHub integration
We validate repo URLs (HTTPS, allowlisted hosts for SSRF protection), full-clone with auth when creating a PR, run the pipeline in a temp dir, then create branch sentinel-g3/fix-{run_id}, commit, push, and call the GitHub API to open a PR with a summary body. Temp dir is removed after the run.

Challenges we ran into

  1. Async stream → SSE — Gemini’s streaming API returns an async iterator; we had to run the Fixer in a task, feed thinking chunks into a queue, and have the SSE generator await queue.get() and emit thinking events until a “done” sentinel. Getting the concurrency right (one producer, one consumer, no dropped chunks) took several iterations.

  2. Thought extraction across files — The Auditor processes many files; we wanted the dashboard to show reasoning for all of them. We added an “accumulated thinking” buffer in the Auditor and append each response’s thought parts with a file header so the UI can display the full audit trail.

  3. Making the UI feel alive — During long Fixer runs the page felt stuck. We added a brainwave-style animation, a rotating status line (“Parsing AST…”, “Simulating attack vectors…”), and a blinking cursor in the terminal when a scan is active. We also made the reasoning panel auto-scroll to the bottom as new text streams in.

  4. Repo cloning and PR creation — We had to handle clone failures, missing tokens, and GitHub API errors without breaking the SSE stream. We run git via asyncio.to_thread for reliability on Windows and never log the auth URL.

  5. Security of the tool itself — We avoided plugging user input straight into prompts; we use structured fields and schemas. We validate and allowlist repo URLs and redact tokens from logs. Those rules are now in our project conventions and code.

Accomplishments that we're proud of

  • Real-time chain-of-thought — The Fixer’s reasoning streams live to the dashboard. You don’t wait until the end to see why a fix was chosen; you watch the model think step-by-step. That “glass box” experience is something we’re proud of.

  • End-to-end GitHub flow — Scan a repo by URL, watch the run in the dashboard, and get a single Pull Request with all fixes and a summary. No manual copy-paste; it fits how teams already work.

  • Verifiable reasoning — Every agent response contributes to thought signatures in the run manifest. We’re proud that the system doesn’t just say it reasoned; it leaves a cryptographic trail you can inspect.

  • Security-first build — We designed the pipeline with OWASP in mind: no prompt injection, SSRF protection on repo URLs, no secrets in logs, and typed Pydantic schemas for all agent I/O. The tool that finds and fixes vulnerabilities is itself built to resist common attacks.

  • Polished dashboard — From the CRT-style terminal and semantic log colours to the collapsible reasoning panel, markdown-rendered thoughts, and side-by-side code diffs, we’re proud of how usable and “war room” the UI feels.

What we learned

  • Streaming changes the product. Using generate_content_stream with include_thoughts=True let us show the Fixer’s reasoning live instead of one blob at the end. We learned to bridge Gemini’s async stream into Server-Sent Events so the Next.js UI could consume it in real time.

  • Structured output is non-negotiable. The Auditor’s response_schema=list[Vulnerability] and Pydantic models meant no brittle JSON parsing and a clean handoff to the Fixer. We now enforce schemas for every agent input and output.

  • Agentic design pays off. Two focused agents (Auditor and Fixer) with one orchestrator kept the pipeline clear. Coordinating async streams (fixer task + thinking queue + SSE) was one of the hardest and most rewarding parts.

  • Security of the tool itself. We learned to treat the builder as an attacker: validate and allowlist repo URLs, never interpolate user input into prompts, never log tokens, and use parameterised data. That mindset is encoded in our project rules and the codebase.

What's next for Sentinel-G3: Autonomous Self-Healing Security

  • More languages and frameworks — Extend the Auditor’s system prompt and file filters to better support JavaScript/TypeScript, Go, and other ecosystems, with framework-aware patterns (e.g. Express, Django).

  • Configurable rules and severity — Let users enable/disable categories (e.g. “only injection and secrets”) and set severity thresholds so teams can tune how noisy the tool is.

  • CI/CD integration — A “run on push” or “run on PR” mode so Sentinel-G3 can run as a GitHub Action or similar, comment on PRs with findings and optional suggested patches, and optionally open follow-up PRs for auto-fixable issues.

  • Better patch validation — Use Gemini’s code execution (or a sandboxed runner) to execute tests or lint after applying a patch and only report “healed” when the fix doesn’t break the build or tests.

  • Multi-repo and org-level runs — Support scanning multiple repos or an entire org (with appropriate auth and rate limiting) and a single dashboard or report aggregating findings and PR links.

We want Sentinel-G3 to become the go-to “reasoning-first” security auditor that teams run locally, in CI, or across repos—always with full transparency and verifiable reasoning.

Built With

  • aiohttp
  • fastapi
  • github-rest-api
  • google-gemini-3-api-(google-genai)
  • lucide-react
  • next.js-15
  • node.js-18+
  • pydantic
  • python-3.12
  • radix-ui
  • react-19
  • react-markdown
  • server-sent-events
  • shiki
  • tailwind-css-4
  • typescript
  • uvicorn
Share this project:

Updates