SentinelScan: AI-Powered Code Risk Radar

SentinelScan analyzes repos and uploads in minutes, flags real security risks with clear fixes, and tracks scan history so teams ship safer code faster.

Comment

SentinelScan: AI-Powered Code Risk Radar

About the Project

SentinelScan is a full-stack vulnerability scanner that helps developers spot risky code before it ships. Users can scan either a GitHub repository URL or uploaded source files, receive line-level findings, and review suggested fixes with severity context.

We built it to feel practical for real engineering workflows: fast enough for iteration, transparent enough for debugging, and structured enough for future CI/CD integration.

Inspiration

Our inspiration came from a common pain point in hackathons and startup teams: security checks usually happen too late. By the time code reaches review or deployment, teams are already racing the clock. We wanted a "security radar" that could run early, summarize risk clearly, and make remediation less intimidating.

We were also inspired by the gap between static security tools and modern AI workflows. Traditional scanners are great at deterministic rules, while LLMs are strong at reasoning over context and suggesting human-readable fixes. SentinelScan combines both strengths.

What We Built

SentinelScan is a monorepo with:

  • Backend: Express + TypeScript scanning API
  • Frontend: React + TypeScript interface with focused scan and results flows
  • AI layer: Gemini-powered vulnerability analysis and fix suggestions
  • Storage: Local scan history persistence for report lookup
  • Operations: Queueing, metrics, dead-letter tracking, and request tracing

Core product capabilities

  • Scan by GitHub URL, PR URL, commit URL, or direct file uploads
  • Return findings with severity, explanation, and fix guidance
  • Deduplicate overlapping findings before presenting results
  • Save and retrieve past scan reports
  • Run synchronous or asynchronous scanning modes
  • Show observability signals such as latency, error rate, queue depth, and cache behavior

How We Built It

Architecture

  1. Frontend sends scan requests with API key + trace ID.
  2. Backend validates auth and request schema.
  3. For GitHub scans, repository/PR/commit files are fetched through Octokit.
  4. Files are batched by character budget and passed to the LLM scanner.
  5. Findings are normalized, deduplicated, scored, and persisted.
  6. The API returns a detailed scan report to the UI.

Technology stack

  • Node.js, Express, TypeScript
  • React, Vite, Testing Library
  • Google Generative AI SDK (Gemini)
  • Jest + Supertest for backend testing
  • Structured telemetry and queue persistence for resilience

Simple risk model (LaTeX)

For reporting and triage, we frame scan risk using a weighted score:

$$ \text{RiskScore} = \sum_{i=1}^{n} w_i \cdot s_i $$

where $s_i$ is the severity score of finding $i$ and $w_i$ is a weight based on exploitability and confidence.

This helped us communicate risk in a consistent way during testing and debugging.

Challenges We Faced

1. Model/API compatibility and quota limits

We hit multiple model-name mismatches and quota/rate-limit errors while integrating Gemini. Some model IDs looked valid but were not callable for our key/version combination at runtime. We solved this by:

  • Listing available models programmatically
  • Pinning to a verified working model
  • Improving fallback behavior in the LLM client
  • Adding safer retry/backoff behavior for transient failures

2. Port conflicts in local development

Backend dev startup occasionally failed with EADDRINUSE on port 3001. This was caused by lingering Node processes and restart timing during nodemon cycles. We stabilized local runs by explicitly identifying and stopping the owning PID before restart.

3. Error clarity across the stack

Early on, frontend error surfaces were too generic. We improved error extraction and propagation so users see meaningful messages (auth, validation, model, or rate-limit issues) instead of vague failures.

4. Balancing speed with output quality

Scanning large repositories quickly while preserving useful findings required batching, char budgets, and caching. We tuned concurrency and cache policies to reduce latency without sacrificing report quality.

What We Learned

  • AI-assisted security tools need strong operational discipline, not just clever prompts.
  • Model selection and quota behavior can dominate reliability in production-like conditions.
  • Good observability (request IDs, structured logs, metrics) dramatically reduces debugging time.
  • UX matters as much as detection quality: clear errors and readable findings build user trust.
  • Shipping fast is possible when architecture is modular (scanner, queue, persistence, UI) and testable.

What's Next

  • Convert downloads to fully corrected code instead of AI prompts
  • Add CI-native scanning with pull request annotations
  • Expand rule packs and language coverage
  • Add organization-level dashboards and policy thresholds
  • Introduce automated fix PR drafts with human approval gates
  • Harden multi-tenant auth and role-based access control

Why This Matters

Developers should not need a security team just to catch obvious risks early. SentinelScan aims to make secure coding workflows accessible, fast, and actionable for every builder.

Built With

  • anthropic-sdk
  • aws-sdk-(bedrock-runtime)
  • cors
  • dotenv
  • express.js
  • github-rest-api-(octokit)
  • google-gemini-api-(@google/generative-ai)
  • helmet
  • jest
  • json
  • multer
  • node.js
  • openai-sdk
  • react
  • supertest
  • typescript
  • uuid
  • vite
Share this project:

Updates