Scanara AI

HIPAA compliance made simple — scan your code, fix issues, and stay secure.

Comment

As a team, we recognized that the healthcare industry is a sensitive and high-impact field in data privacy and security. Every day, hospitals and medical applications process vast amounts of confidential patient information, yet many non-specialized developers lack clarity on whether their systems meet HIPAA compliance standards. Our goal was to create a practical and reliable tool that allows teams to easily verify whether their products are HIPAA compliant and to prevent potential data leaks before they occur.

⚙️ What it does

Scanara AI helps developers and organizations quickly determine if their app or project is HIPAA compliant. Users can check their codebase in 3 ways:

Connecting a GitHub repo in the web app

Using the VS Code extension

Installing the npm package in their production server

The app scans the code base, detects missing security elements, and generates a detailed compliance report highlighting violations, missing safeguards, and recommended fixes — giving teams a clear path to HIPAA alignment.

🏗️ How we built it

We built Scanara AI using:

Frontend & User Interface

React with Vite for building the responsive web dashboard (audit results, app management, integrations).

React Router for navigation and protected routes.

Firebase Client SDK for frontend authentication.

Backend & API

Node.js with Express to handle REST API requests (authentication, audit processing, integrations).

Firebase Admin SDK for secure token verification and server-side authentication.

Firebase Firestore for storing audit results, configurations, and user data.

Google Gemini API for AI-powered compliance solutions and suggestions.

Developer Tools

VS Code Extension (scanara-ai): Integrates HIPAA auditing directly into the editor, enabling in-editor audits, reports, and insights.

NPM Package (hipaa-audit): CLI tool for CI/CD integration and automated terminal-based auditing workflows.

Architecture Highlights

Multi-platform access: Web dashboard, VS Code extension, and CLI tool connect to a shared backend API.

Secure authentication: Firebase Authentication with token-based verification ensures safety across all platforms.

AI-powered analysis: Combines HIPAA rule sets with AI-driven detection and remediation guidance.

Real-time updates: Firestore enables instant synchronization of audit results across.

Challenges we ran into

Large codebase processing and API token limits

Limited analysis to first 100 files and capped payloads at 500KB to stay within AI API limits

Inconsistent AI response parsing

AI sometimes returned malformed JSON; implemented regex extraction and fallback parsing

Unreliable AI scoring

AI occasionally returned invalid or identical scores; added fallback score calculation from component analysis

Gemini API integration

Added retry logic and graceful degradation for solution suggestions

Data structure normalization

Normalized data from different entry points (GitHub, VS Code, CLI) before storing in Firestore

VS Code extension authentication

Extension runs in Node.js, not browser; implemented Firebase Auth via REST APIs with token refresh

Token refresh and session management

Implemented token refresh logic and graceful handling of expired tokens across all platforms

Multi-platform integration complexity

Unified backend API to serve web, VS Code extension, and CLI with different authentication flows

File upload and processing limits

Added file filtering, size validation, and chunked processing to handle large projects

Real-time error handling across platforms

Standardized error response formats with platform-specific error display (notifications, modals, console)

🏅 Accomplishments that we're proud of

Weighted scoring algorithm — Implemented a fallback scoring system that calculates compliance scores from component analysis using weighted categories (45% technical, 30% administrative, 10% physical, 10% audit coverage, 5% data handling) when AI responses are invalid

GitHub OAuth integration with repository cloning — Built OAuth flow with state parameter encoding and repository cloning using isomorphic-git to extract code files while filtering out node_modules, .git, and build artifacts

VS Code extension workspace scanning — Implemented file discovery using VS Code's findFiles API with glob patterns for 19+ file types, async file reading with Promise.all, and progress reporting with cancellation support

AI response parsing with regex extraction — Built regex-based JSON extraction (/{[\s\S]*}/) to handle AI responses wrapped in text, with fallback error handling for malformed JSON

File processing and payload optimization — Implemented file limiting (100 files max), payload size capping (500KB), and byte length calculation using Buffer.byteLength to stay within API token limits

Firebase Auth REST API integration in Node.js — Implemented Firebase Authentication in VS Code extension using REST APIs (identitytoolkit.googleapis.com) with token refresh logic and secure storage using VS Code's secrets API

Gemini API integration for conversational AI — Built conversation history management with context injection, role-based message formatting (user/model), and error handling for the Gemini 2.5 Flash API

API key generation with crypto — Implemented secure API key generation using crypto.randomBytes(32) with base64url encoding and sk_ prefix for CLI authentication

Temp directory cleanup with retry logic — Built recursive directory removal with retry logic (3 attempts) and Windows-specific file handle release delays using fs.rmSync with retry options

Multi-platform authentication middleware — Created separate middleware (verifyToken for web/extension, verifyApiKey for CLI) with Firebase Admin SDK token verification and API key lookup in Firestore

Component-level scoring calculation — Implemented category score calculation that maps component status (compliant=100, partial=50, non-compliant/not_found=0) to weighted overall scores with 1 decimal precision

Data structure normalization — Built normalization layer that converts different input formats (GitHub clone, VS Code upload, CLI array/string) into unified Firestore document structure with file path, content, and size metadata

Conversation context management — Implemented context injection system for Gemini chat that includes component metadata, evidence, and remediation steps while maintaining conversation history across multiple API calls

File validation and error handling — Built comprehensive file structure validation with detailed error messages, index tracking for failed files, and graceful degradation when file reading fails

Express.js route architecture — Created modular Express router structure with separate routes for auth, apps, GitHub, audit, CLI, VSCode, and Gemini, all sharing unified error handling middleware

📚 What we learned

We learned how to interpret and apply regulatory frameworks like HIPAA to technical systems, and deepened our understanding of secure app design, API integrations, and scalable web architectures.

What's next for Scanara

We plan to:

Add continuous compliance monitoring for live projects.

Support more frameworks like GDPR and SOC 2.

Introduce AI-powered suggestions that automatically recommend fixes.

Develop a browser plugin to analyze web apps directly.

Built With

Share this project:

Updates