Linux CLI Safety Advisor

A production-style hackathon app that analyzes Linux commands with deterministic risk logic and gives users actionable safety guidance before execution.

What it does

• Risk score (0-100) for each command
• Blast radius estimation (files affected, downtime, recovery)
• Human-readable explanation of command and flags
• Safer alternatives with one-click copy
• Decision output based on user level: ALLOW, WARN, BLOCK
• Real-time typing analysis preview
• Playground mode (same command in different directories)
• Command chain visualizer
• Learning mode with XP progression
• User auth and command history with Supabase
• Analytics dashboard with risk trends and heatmap

Tech Stack

• Frontend: React (Vite), Tailwind CSS, Framer Motion, Zustand, Recharts
• Backend: Node.js + Express
• Database/Auth/Realtime: Supabase

Project Structure

• frontend/ React app
• backend/ Express API
• supabase-schema.sql DB schema and RLS policies

Setup

1) Install dependencies

cd frontend
npm install

cd ../backend
npm install

2) Configure environment variables

copy .env.example .env

Fill these values:

• Shared root .env (used by both frontend and backend)
  • PORT
  • SUPABASE_URL
  • SUPABASE_SERVICE_ROLE_KEY
  • VITE_API_URL
  • VITE_SUPABASE_URL
  • VITE_SUPABASE_ANON_KEY

3) Create database table in Supabase

Run SQL from supabase-schema.sql in the Supabase SQL editor.

4) Run backend

cd backend
npm run dev

5) Run frontend

cd frontend
npm run dev

Open the frontend URL (default Vite: http://localhost:5173).

API Endpoints

• POST /api/analyze
  • body: { command, userLevel, currentDir }
• GET /api/history?userId=...
• POST /api/save-command
  • body: { userId, command, currentDir, analysis }

Deterministic Scoring System

The backend uses a deterministic rules engine only (no AI/ML):

• Base risk by command (rm, dd, mkfs, etc.)
• Additional risk by flags (-rf, --no-preserve-root, wildcard usage)
• Directory context weighting (/, /home, /tmp)
• User-level weighting (beginner, intermediate, expert)
• Decision tree:
  • BLOCK if risk >= 80
  • WARN if risk >= 50
  • ALLOW otherwise

Demo Scenarios

• rm -rf /
  • expected: very high risk, BLOCK, SYSTEM KILLER
• chmod -R 777 /etc
  • expected: high risk, WARN or BLOCK based on context
• ls -la /home
  • expected: low risk, ALLOW
• cd / && rm -rf *
  • expected: high chain risk and explicit chain visualization

Why this matters

Most severe infra incidents start with one dangerous command in the wrong context. This product acts like a CLI pre-flight safety layer for teams: deterministic, transparent, and fast enough for real workflows.

Judges talking points (3-minute demo)

• Start on landing page and live typing preview
• Run dangerous command in analyzer and show decision + alternatives
• Toggle playground mode and compare contexts
• Show command chain visualizer with multi-step command
• Sign in and open dashboard for trend charts and heatmap
• Show learning mode XP and command breakdown