final submit sudhanshu

Readme.md

@@ -1,101 +1,285 @@
-#  Stellaris Hackathon
+link: https://frontend-seven-steel-14.vercel.app
+# 🔐 Kubernetes Attack Path Visualizer
 
-> **Organized by:** ElixirTech Community  
-> **Repository:** [ElixirTechCommunity/Stellaris-Hackathon](https://github.com/ElixirTechCommunity/Stellaris-Hackathon)
+A full-stack security analysis engine that models Kubernetes RBAC as a graph and detects attack paths, privilege escalation, and vulnerabilities using graph algorithms.
 
+---
+
+## 🚀 Overview
 
-## How to Submit Your Project
+The Kubernetes Attack Path Visualizer is designed to help security engineers understand how an attacker can move inside a Kubernetes cluster.
 
-Follow these steps **carefully** to upload your project to this repository.
+It converts Kubernetes resources into a graph structure, enriches it with vulnerability data (CVEs), and applies graph algorithms to detect potential attack paths from entry points to critical assets like secrets and databases.
 
 ---
 
-###  Step 1 – Fork This Repository
+## 🧠 Key Features
+
+### 🔥 Attack Path Detection
 
-Click the **Fork** button at the top-right of this page to create your own copy of this repo.
+* Identifies all possible paths from **entry points → crown jewels**
+* Helps visualize how an attacker can compromise sensitive resources
 
 ---
 
-###  Step 2 – Clone Your Fork Locally
-```bash
-git clone https://github.com/<your-username>/Stellaris-Hackathon.git
-cd Stellaris-Hackathon
-```
+### 📊 Risk Scoring System
+
+* Assigns a risk score (0–10) to nodes and paths
+* Based on:
+
+  * CVEs
+  * RBAC permissions
+  * Access to sensitive resources
+
+---
+
+### ⚡ Shortest Attack Path (Dijkstra)
+
+* Finds the most efficient attack route
+* Simulates attacker behavior (least resistance path)
+
+---
+
+### 🌐 All Attack Paths (BFS)
+
+* Explores all possible attack routes
+* Ensures no hidden vulnerabilities are missed
+
+---
+
+### 💥 Blast Radius Analysis
+
+* Shows how far an attacker can spread from a compromised node
+* Helps measure impact of a breach
+
+---
+
+### 🔁 Privilege Escalation Detection
+
+* Detects loops where attacker gains increasing privileges
+* Example:
+
+  ```
+  Pod → ServiceAccount → Role → Pod (higher privilege)
+  ```
 
 ---
 
-### Step 3 – Create Your Project Folder
+### 🎯 Critical Node Detection
+
+* Identifies chokepoints in the graph
+* Securing these nodes blocks multiple attack paths
+
+---
+
+### 🧪 Attack Simulation
+
+* Simulates removing or securing a node
+* Shows:
+
+  * Attack paths eliminated
+  * Security improvement %
+
+---
+
+### ⚠️ Vulnerability Analysis
+
+* Lists risky nodes with:
+
+  * CVEs
+  * Risk score
+  * Explanation of risk
+
+---
+
+### 🧾 Human-Readable Explanations
+
+* Converts technical graph paths into simple attack stories
+* Example:
+
+  ```
+  Attacker enters via service → accesses pod → uses service account → reads secret
+  ```
+
+---
+
+### 📄 Report Generation
+
+* Generates a complete security report including:
+
+  * Attack paths
+  * Shortest paths
+  * Blast radius
+  * Cycles
+  * Critical nodes
+
+---
+
+## 🔄 Data Flow
 
-Inside the repo, create a new folder using the format:
 ```
-submissions/TeamName_ProjectName/
+Kubernetes Cluster / Mock Data
+        ↓
+Fetch (kubectl / JSON)
+        ↓
+Transform → Graph (Nodes + Edges)
+        ↓
+CVE Enrichment
+        ↓
+Validation (Zod Schema)
+        ↓
+cluster-graph.json
+        ↓
+Neo4j Database
+        ↓
+GDS Graph Projection
+        ↓
+Graph Algorithms (BFS, DFS, Dijkstra)
+        ↓
+API / CLI / Reports
 ```
 
-**Example:**
+---
+
+## 🏗️ Project Architecture
+
 ```
-submissions/TeamNova_SmartBridge/
+src/
+│
+├── cli/                # CLI commands (scan, ingest, report)
+├── core/               # Core logic (fetch, transform, CVE, attack-path)
+├── db/                 # Neo4j + GDS integration
+├── services/           # Business logic (ingestion, reporting)
+├── server/             # Express API
+├── schemas/            # Validation schemas
+├── data/               # Mock dataset
 ```
 
-Place all your project files inside this folder.
+---
+
+## 🧪 Technologies Used
+
+* **TypeScript / Node.js**
+* **Neo4j (Graph Database)**
+* **Neo4j Graph Data Science (GDS)**
+* **Express.js**
+* **Zod**
+* **Axios**
 
 ---
 
-###  Step 4 – Add a `README.md` Inside Your Folder
+## ⚙️ Installation & Setup
+
+### 1. Clone the repository
+
+```bash
+git clone <your-repo-url>
+cd project
+```
+
+---
+
+### 2. Install dependencies
+
+```bash
+npm install
+```
+
+---
+
+### 3. Start Neo4j (Docker)
+
+```bash
+cd docker
+docker-compose up -d
+```
 
-Your submission folder **must** include a `README.md` with the following structure:
-```markdown
-# Project Name
+---
 
-## 👥 Team Name
-<!-- Your team name -->
+### 4. Run the project
 
-## 🧑‍💻 Team Members
-| Name | Role | GitHub |
-|------|------|--------|
-| Name 1 | Frontend | @username |
-| Name 2 | Backend | @username |
+#### Scan (local pipeline)
 
-## 💡 Problem Statement
-<!-- What problem are you solving? -->
+```bash
+npx ts-node src/cli/index.ts scan --mock
+```
 
-## 🛠️ Tech Stack
-<!-- List the tools, frameworks, languages used -->
+#### Full ingestion
 
-## 🔗 Links
-- **Live Demo:** [link]
-- **Video Demo:** [link](if applicable)
-- **Presentation (PPT/PDF):** [link]
+```bash
+npx ts-node src/cli/index.ts ingest --source mock
+```
 
-## 📸 Screenshots
-<!-- Add screenshots or a GIF of your project -->
+#### Generate report
 
-## 🚀 How to Run Locally
-<!-- Step-by-step instructions to run your project -->
+```bash
+npx ts-node src/cli/index.ts report
 ```
 
 ---
 
-### Step 5 – Commit and Push Your Changes
+### 5. Start API server
+
 ```bash
-git add .
-git commit -m "Add submission: TeamName_ProjectName"
-git push origin main
+npx ts-node src/server/server.ts
 ```
 
 ---
 
-###  Step 6 – Open a Pull Request (PR)
+## 🌐 API Endpoints
+
+| Endpoint                 | Description        |
+| ------------------------ | ------------------ |
+| POST /api/ingest         | Run full pipeline  |
+| GET /api/graph           | Retrieve graph     |
+| GET /api/paths           | Attack paths       |
+| GET /api/vulnerabilities | Vulnerable nodes   |
+| GET /api/blast-radius    | Reachability       |
+| GET /api/cycles          | Privilege cycles   |
+| GET /api/critical-node   | Critical nodes     |
+| POST /api/simulate       | What-if simulation |
+| GET /api/report          | Full report        |
+
+---
+
+## 🎯 Real-World Use Cases
 
-1. Go to your forked repo on GitHub
-2. Click **"Compare & pull request"**
-3. Use this PR title format:  
-   `[Submission] TeamName – ProjectName`
-4. Fill in the PR description and click **"Create Pull Request"**
+* Kubernetes security auditing
+* DevSecOps pipelines
+* Threat modeling
+* Penetration testing
+* Cloud security analysis
 
-> ⚠️ **Only PRs following the correct format will be reviewed.**
+---
 
+## 🧠 Interview Explanation
 
+> This project converts Kubernetes RBAC into a graph and uses graph algorithms like BFS, DFS, and Dijkstra to detect attack paths, privilege escalation, and vulnerabilities. It enriches data with CVEs and generates human-readable security reports.
 
 ---
 
-<p align="center">Made with ❤️ by <strong>ElixirTech Community</strong></p>
+## 🚀 Future Improvements
+
+* Frontend graph visualization
+* Real-time monitoring
+* AI-based risk prediction
+* Multi-cluster support
+
+---
+
+## 👨‍💻 Author
+
+**Vardan Singhal**
+
+---
+
+## ⭐ Final Note
+
+This project demonstrates:
+
+* Graph theory
+* System design
+* Security analysis
+* Backend engineering
+
+A strong real-world project combining **DevOps + Security + Algorithms**.