vulnerability-scanner

A SaaS B2B platform that automates vulnerability detection and remediation guidance for Linux servers at scale.

Architecture

• Frontend: React 18+ with TypeScript
• Backend: Ruby on Rails 7.1+ (API mode)
• Agent: Go 1.21+
• Database: MySQL 8.0+
• Background Jobs: Sidekiq with Redis
• Containerization: Docker & Docker Compose

Development Model

Local Coding, Remote VM Deployment

This project is set up for development where you:

• ✅ Code on your local machine (low resource usage)
• ✅ Deploy and run the application on a remote VM
• ✅ Sync code changes easily with provided scripts

See DEVELOPMENT-WORKFLOW.md for the complete workflow.

Prerequisites

Local Machine

• Code editor (VS Code, etc.)
• Git
• SSH access to remote VM
• rsync (for file syncing)
• Windows users: WSL (Windows Subsystem for Linux) recommended for using bash scripts
• macOS users: Scripts work natively - no additional setup needed

Remote VM

• Docker and Docker Compose installed
• SSH server running
• Sufficient resources (2+ CPU cores, 4GB+ RAM, 20GB+ disk)
• Ports accessible: 3000 (Backend), 5173 (Frontend)

Quick Start

1. Configure VM Access

Create config/.vm-config file:

cp config/.vm-config.example config/.vm-config
# Edit config/.vm-config with your VM details

2. Initial Deployment to VM

Deploy the application to your VM:

./scripts/deploy-to-vm.sh

This will:

• Sync code to VM
• Build Docker images
• Start all services
• Set up database

3. Access Application

• Frontend: http://VM_IP:5173
• Backend API: http://VM_IP:3000
• Health Check: http://VM_IP:3000/health

Manual Setup

1. Clone the repository

git clone <repository-url>
cd vulnerability-scanner

2. Set up environment variables

Create a .env file in the root directory:

cp .env.example .env
# Edit .env with your configuration

3. Initialize Rails application (if not already done)

cd backend
rails new . --api --database=mysql --skip-test --skip-git
cd ..

4. Start the development environment

cd config
docker-compose up -d
cd ..

This will start:

• MySQL database (port 3306)
• Redis (port 6379)
• Rails backend API (port 3000)
• Sidekiq worker
• React frontend (port 5173)

5. Set up the database

# Use docker-compose (with hyphen) or docker compose (with space)
cd config
docker-compose exec backend rails db:create
docker-compose exec backend rails db:migrate
docker-compose exec backend rails db:seed
cd ..

6. Access the application

• Frontend: http://localhost:5173
• Backend API: http://localhost:3000
• Health Check: http://localhost:3000/health
• Sidekiq Web UI: http://localhost:3000/sidekiq (development only)

Development on VM

Backend (Rails)

# Access Rails console
./scripts/vm-exec.sh backend rails console

# Run migrations
./scripts/vm-exec.sh backend rails db:migrate

# Run tests
./scripts/vm-exec.sh backend bundle exec rspec

# View logs
./scripts/view-vm-logs.sh backend

Frontend (React)

# Run tests
./scripts/vm-exec.sh frontend npm test

# Install dependencies
./scripts/vm-exec.sh frontend npm install

# View logs
./scripts/view-vm-logs.sh frontend

Database

# Access MySQL (via backend container)
./scripts/vm-exec.sh backend rails dbconsole

# Reset database
./scripts/vm-exec.sh backend rails db:reset

Project Structure

vulnerability-scanner/
├── backend/          # Rails API application
├── frontend/         # React application
├── agent/            # Go agent application
├── docs/            # Documentation
├── scripts/          # Deployment and VM management scripts
├── config/           # Configuration files (docker-compose.yml, .vm-config)
└── README.md         # This file

Documentation

Development

• Development Workflow - Local coding, remote VM deployment
• Remote VM Setup - Detailed VM setup guide
• Docker Commands - Docker Compose command reference
• Quick Start - Quick setup guide
• WSL Usage - Using bash scripts with WSL on Windows
• macOS Usage - Using bash scripts on macOS

Project Documentation

• Product Requirements Document
• System Architecture
• UX Design
• Epics and Stories
• Sprint Plan
• Test Design