🛡️ CyberGPT - AI-Powered Cybersecurity Assessment Platform

A comprehensive cybersecurity platform combining AI-powered chat assistance with advanced vulnerability scanning, knowledge graph visualization, and interactive security analysis tools.

Features • Architecture • Installation • Documentation • Contributing

---

📋 Table of Contents

• Overview
• Key Features
• Architecture Overview
• Technology Stack
• Quick Start
• Configuration
• API Documentation
• Development
• Deployment
• Testing
• Contributing
• License

---

🌟 Overview

CyberGPT is an enterprise-grade cybersecurity assessment platform that leverages artificial intelligence to provide comprehensive security analysis, vulnerability detection, and actionable insights. Built with modern web technologies and integrated with industry-leading security tools, CyberGPT helps security professionals, developers, and organizations identify and mitigate security risks efficiently.

🎯 Mission

To democratize cybersecurity by making advanced security assessment tools accessible, intelligent, and actionable through AI-powered automation.

---

✨ Key Features

🤖 AI Security Assistant

Intelligent Conversational Interface

• Multi-Personality AI Modes

  • 👨‍🏫 Tutor Mode: Educational responses with detailed explanations
  • 🔍 Investigator Mode: Deep-dive analysis with evidence-based reasoning
  • 📊 Analyst Mode: Technical security analysis with actionable recommendations

• Advanced AI Capabilities

  • Real-time reasoning with step-by-step thought process visualization
  • Context-aware responses leveraging knowledge graphs
  • Streaming responses for immediate feedback
  • Human-in-the-loop approval for critical actions
  • Multi-turn conversation memory and context retention

• Intelligent Features

  • CVE database integration with real-time lookups
  • Jargon explanation with security terminology tooltips
  • Source link management with automatic reference tracking
  • Todo list generation from security recommendations
  • File upload support (code, logs, reports)

🔍 Vulnerability Scanning & Analysis

Comprehensive Security Assessment Tools

DAST (Dynamic Application Security Testing)

• Automated web application vulnerability scanning
• Real-time vulnerability detection

CVE Database Integration

• Real-time vulnerability database access
• NVD (National Vulnerability Database) integration
• CIRCL CVE Search API integration
• OSV (Open Source Vulnerabilities) database
• Automated CVE enrichment and correlation

📊 Knowledge Graph Visualization

Interactive Security Relationship Mapping

• Dynamic Graph Generation

  • Real-time knowledge graph creation from chat conversations
  • Automatic entity extraction (vulnerabilities, mitigations, CVEs)
  • Relationship mapping between security concepts
  • Interactive D3.js-powered visualizations

• Graph Features

  • Multiple node types (vulnerability, mitigation, source, CVE, problem, affected, risk)
  • Relationship types (mitigates, affects, references, causes, relates_to)
  • Zoom, pan, and drag interactions
  • Node and link detail panels
  • Severity-based color coding
  • Responsive design for mobile and desktop

• Knowledge Graph Database

  • Neo4j graph database integration
  • Semantic relationship storage
  • Complex cypher query support
  • Graph analytics and traversal

🎯 Interactive Task Management

Security Action Tracking

• Drag-and-drop todo list interface
• Task prioritization with severity levels
• Status tracking (Pending, In Progress, Completed)
• Real-time synchronization with Convex
• Integration with scan results
• Export to various formats
• Collaborative task assignment

🔐 Security & Authentication

Enterprise-Grade Security

• Authentication

  • JWT-based authentication
  • Password hashing with bcrypt
  • Session management

• Authorization

  • Protected API routes
  • Resource-level permissions
  • Secure token refresh

• Data Security

  • Encrypted data transmission (HTTPS)
  • Environment variable protection
  • SQL injection prevention
  • XSS protection
  • CSRF token implementation

---

🏗️ Architecture Overview

System Architecture Diagram

┌─────────────────────────────────────────────────────────────────────────┐
│                           CLIENT LAYER                                  │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                    React + TypeScript Frontend                  │    │
│  │  • Vite Build System    • Tailwind CSS    • Framer Motion       │    │
│  │  • React Router         • Zustand State   • Radix UI Components │    │
│  └─────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
                                    ↕
┌────────────────────────────────────────────────────────────────────────┐
│                       API GATEWAY / BACKEND                            │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │              Express.js REST API (Node.js/Bun)                  │   │
│  │  • JWT Authentication   • Rate Limiting    • Error Handling     │   │
│  │  • File Upload          • CORS             • Request Validation │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────────────────┘
                                    ↕
┌───────────────────────────────────────────────────────────────────────┐
│                        SERVICE LAYER                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────┐   │
│  │   Chat       │  │  Scanning    │  │  Knowledge   │  │  Report  │   │
│  │  Service     │  │  Services    │  │    Graph     │  │ Service  │   │
│  │              │  │              │  │   Service    │  │          │   │
│  │ • OpenAI     │  │              │  │ • Neo4j      │  │ • HTML   │   │
│  │ • RAG        │  │              │  │ • Cypher     │  │ • MDX    │   |
│  │ • Streaming  │  │              │  │ • Analytics  │  │          │   │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────┘   │
└───────────────────────────────────────────────────────────────────────┘
                                    ↕
┌───────────────────────────────────────────────────────┐
│                        DATA LAYER                     │
│  ┌──────────────┐  ┌──────────────┐    ┌──────────┐   │
│  │  PostgreSQL  │  │    Neo4j     │    │ Supabase │   │
│  │  (Prisma)    │  │  Graph DB    │    │ Storage  │   │
│  │              │  │              │    │          │   │
│  │ • Users      │  │ • Entities   │    │ • Files  │   │
│  │ • Scans      │  │ • Relations  │    │ • Reports│   │
│  │ • Reports    │  │ • CVEs       │    │ • Assets │   │
│  └──────────────┘  └──────────────┘    └──────────┘   │
└───────────────────────────────────────────────────────┘
                                    ↕
┌──────────────────────────────────────────────────────────────────────┐
│                    EXTERNAL SERVICES                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                |
│  │   OpenAI     │  │              │  │              │                │
│  │   GPT-4      │  │   Scanner    │  │   Analysis   │                │
│  └──────────────┘  └──────────────┘  └──────────────┘                |
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────┐  │
│  │     NVD      │  │    CIRCL     │  │     OSV      │  │  Convex  │  │
│  │  CVE Data    │  │  CVE Search  │  │  Vulns DB    │  │ Real-time│  │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────┘  │
└──────────────────────────────────────────────────────────────────────┘

Data Flow Architecture

1. Chat Interaction Flow

User Input → Frontend → API Gateway → Chat Service
                                           ↓
                                    OpenAI GPT-4
                                           ↓
                                    graphRAG Service
                                           ↓
                                Neo4j Knowledge Graph
                                           ↓
                                    Response Stream
                                           ↓
                            Frontend (Real-time Update)
                                           ↓
                                    Convex Storage

#### **2. Knowledge Graph Generation Flow**

AI Response → Entity Extraction → Relationship Mapping ↓ Neo4j Storage ↓ Graph Visualization (D3.js) ↓ Interactive Frontend Display

---

## 🚀 Technology Stack

### **Frontend**

| Technology | Version | Purpose |
|-----------|---------|---------|
| **React** | 18.3.1 | UI framework |
| **TypeScript** | 5.6.2 | Type safety |
| **Vite** | 5.4.10 | Build tool & dev server |
| **Tailwind CSS** | 3.4.15 | Styling framework |
| **Framer Motion** | 11.18.2 | Animations |
| **D3.js** | 7.9.0 | Data visualization |
| **Radix UI** | Latest | Accessible components |
| **Zustand** | 5.0.1 | State management |
| **React Router** | 7.0.1 | Routing |
| **Axios** | 1.7.8 | HTTP client |
| **Convex** | 1.17.4 | Real-time database |

### **Backend**

| Technology | Version | Purpose |
|-----------|---------|---------|
| **Node.js** | 18+ | Runtime environment |
| **Bun** | 1.1+ | JavaScript runtime & bundler |
| **Express.js** | 4.x | Web framework |
| **TypeScript** | 5.6.2 | Type safety |
| **Prisma** | Latest | ORM for PostgreSQL |
| **PostgreSQL** | 14+ | Primary database |
| **Neo4j** | 5.x | Graph database |
| **JWT** | Latest | Authentication |

### **AI & ML Services**

| Service | Purpose |
|---------|---------|
| **OpenAI GPT-4** | Conversational AI & reasoning |
| **Neo4j** | Knowledge graph database |
| **Langchain** | LLM orchestration |

### **Security Tools**

| Tool | Purpose |
|------|---------|
| **NVD API** | CVE vulnerability data |
| **CIRCL CVE** | CVE search API |
| **OSV** | Open source vulnerabilities |

### **Infrastructure**

| Technology | Purpose |
|-----------|---------|
| **Docker** | Containerization |
| **Docker Compose** | Multi-container orchestration |
| **Vercel** | Frontend hosting |
| **Supabase** | File storage & additional DB |
| **Nodemailer** | Email service |

---

## 🚀 Quick Start

### **Prerequisites**

Ensure you have the following installed:

- **Node.js** >= 18.0.0
- **Bun** >= 1.1.0 (for backend)
- **PostgreSQL** >= 14.0
- **Neo4j** >= 5.0
- **Docker** (optional, for containerized deployment)

### **Required API Keys**

- OpenAI API Key (GPT-4 access)
- Supabase credentials
- Convex deployment URL

### **Installation Steps**

#### **1. Clone the Repository**

```bash
git clone https://github.com/your-org/cybergpt.git
cd cybergpt

2. Install Dependencies

Frontend:

cd frontend
npm install

Backend:

cd backend
bun install

3. Environment Configuration

Backend .env:

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/cybergpt_db"
SHADOW_DATABASE_URL="postgresql://user:password@localhost:5432/cybergpt_shadow"

# Neo4j
NEO4J_URI="bolt://localhost:7687"
NEO4J_USER="neo4j"
NEO4J_PASSWORD="your-neo4j-password"

# OpenAI
OPENAI_API_KEY="sk-your-openai-api-key"
OPENAI_MODEL="gpt-4"

# JWT
JWT_SECRET="your-super-secret-jwt-key"
JWT_EXPIRES_IN="7d"

# Stripe
STRIPE_SECRET_KEY="sk_test_your-stripe-key"
STRIPE_WEBHOOK_SECRET="whsec_your-webhook-secret"

# Supabase
SUPABASE_URL="https://your-project.supabase.co"
SUPABASE_ANON_KEY="your-supabase-anon-key"
SUPABASE_SERVICE_ROLE_KEY="your-service-role-key"

# Email
EMAIL_HOST="smtp.gmail.com"
EMAIL_PORT=587
EMAIL_USER="your-email@gmail.com"
EMAIL_PASSWORD="your-app-password"


# Application
PORT=8000
NODE_ENV="development"
FRONTEND_URL="http://localhost:3000"

Frontend .env:

# Backend API
VITE_API_URL="http://localhost:8000"

# Convex
VITE_CONVEX_URL="https://your-convex-deployment.convex.cloud"

# Stripe (Public Key)
VITE_STRIPE_PUBLIC_KEY="pk_test_your-stripe-public-key"

# Application
VITE_APP_NAME="CyberGPT"
VITE_APP_URL="http://localhost:3000"

4. Database Setup

PostgreSQL:

# Create database
createdb cybergpt_db
createdb cybergpt_shadow

# Run Prisma migrations
cd backend
bunx prisma migrate dev
bunx prisma generate

Neo4j:

# Using Docker
docker run \
  --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -d \
  -e NEO4J_AUTH=neo4j/your-password \
  neo4j:latest

# Or install Neo4j Desktop from https://neo4j.com/download/

5. Seed Data (Optional)

cd backend
bun run src/scripts/ingestAll.ts

This will ingest CVE data from NVD and CISA into your Neo4j database.

6. Start the Application

Development Mode:

Terminal 1 (Backend):

cd backend
bun run dev
# Backend runs on http://localhost:8000

Terminal 2 (Frontend):

cd frontend
npm run dev
# Frontend runs on http://localhost:3000

Production Mode with Docker:

# From project root
docker-compose up --build

# Frontend: http://localhost:3000
# Backend: http://localhost:8000

7. Access the Application

Open your browser and navigate to:

http://localhost:3000

Default test credentials (if seeded):

• Email: admin@example.com
• Password: Admin@123

---

⚙️ Configuration

Backend Configuration

Prisma Schema

Located at backend/src/prisma/schema.prisma

model User {
  id            String   @id @default(uuid())
  email         String   @unique
  password      String
  name          String?
  role          String   @default("user")
  subscription  String   @default("free")
  createdAt     DateTime @default(now())
  updatedAt     DateTime @updatedAt
}

CORS Configuration

In backend/src/app.ts:

app.use(cors({
  origin: process.env.FRONTEND_URL || 'http://localhost:3000',
  credentials: true,
}));

Frontend Configuration

API Client

Located at frontend/src/api/axios.ts

const api = axios.create({
  baseURL: import.meta.env.VITE_API_URL,
  timeout: 30000,
  headers: {
    'Content-Type': 'application/json',
  },
});

Route Protection

Protected routes use authentication middleware:

<ProtectedRoute>
  <Dashboard />
</ProtectedRoute>

---

📚 API Documentation

Authentication Endpoints

Register User

POST /api/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "name": "John Doe"
}

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}

Get Profile

GET /api/auth/profile
Authorization: Bearer <jwt_token>

Chat Endpoints

Send Message

POST /api/chat/message
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "message": "What is SQL injection?",
  "chatId": "chat-uuid",
  "mode": "tutor"
}

Stream Response

POST /api/chat/stream
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "message": "Explain XSS vulnerabilities",
  "chatId": "chat-uuid"
}

Knowledge Graph Endpoints

Generate Graph

POST /api/graph/generate
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "messageId": "msg-uuid",
  "chatId": "chat-uuid",
  "question": "What are the vulnerabilities in OWASP Top 10?"
}

Get Graph Visualization

GET /api/graph/visualization/:messageId
Authorization: Bearer <jwt_token>

---

🛠️ Development

Project Structure

CyberGPT/
├── frontend/                  # React frontend application
│   ├── src/
│   │   ├── api/              # API client configurations
│   │   ├── components/       # Reusable React components
│   │   │   ├── chat/        # Chat-related components
│   │   │   ├── dashboard/   # Dashboard components
│   │   │   ├── graph-visualization/  # Graph components
│   │   │   ├── reports/     # Report components
│   │   │   └── ui/          # Base UI components
│   │   ├── hooks/           # Custom React hooks
│   │   ├── lib/             # Utility libraries
│   │   ├── pages/           # Page components
│   │   ├── store/           # Zustand state management
│   │   ├── types/           # TypeScript type definitions
│   │   └── utils/           # Utility functions
│   ├── public/              # Static assets
│   ├── package.json
│   └── vite.config.ts
│
├── backend/                   # Express backend application
│   ├── src/
│   │   ├── config/          # Configuration files
│   │   ├── controllers/     # Route controllers
│   │   ├── middlewares/     # Express middlewares
│   │   ├── models/          # Database models
│   │   ├── routes/          # API routes
│   │   ├── services/        # Business logic services
│   │   ├── utils/           # Utility functions
│   │   ├── prisma/          # Prisma schema & migrations
│   │   ├── scripts/         # Utility scripts
│   │   └── index.ts         # Application entry point
│   ├── package.json
│   └── tsconfig.json
│
├── convex/                    # Convex backend functions
│   ├── chats.ts
│   ├── graphVisualizations.ts
│   ├── reports.ts
│   ├── todoLists.ts
│   └── schema.ts
│
├── docker-compose.yml        # Docker Compose configuration
├── backend.Dockerfile        # Backend Dockerfile
├── frontend.Dockerfile       # Frontend Dockerfile
└── README.md                 # Project documentation

Available Scripts

Frontend

npm run dev          # Start development server (port 3000)
npm run build        # Build for production
npm run preview      # Preview production build
npm run lint         # Run Biome linter
npm run lint:fix     # Fix linting issues
npm run format       # Check code formatting
npm run format:fix   # Fix formatting issues
npm run test         # Run tests
npm run test:ui      # Run tests with UI
npm run test:coverage # Generate coverage report
npm run type-check   # TypeScript type checking

Backend

bun run dev          # Start development server (port 8000)
bun run build        # Build for production
bun run start        # Start production server
bun run check        # Run Biome checks
bun run check:fix    # Fix Biome issues
bunx prisma studio   # Open Prisma Studio
bunx prisma migrate dev  # Run database migrations

Code Style & Linting

This project uses Biome for linting and formatting:

# Check code quality
npm run check

# Auto-fix issues
npm run check:fix

Configuration: biome.json in frontend and backend directories

Testing

Frontend Tests

Using Vitest and React Testing Library:

# Run tests
npm run test

# Run tests with UI
npm run test:ui

# Generate coverage
npm run test:coverage

Backend Tests

# Run tests
bun run test

Database Migrations

# Create a new migration
bunx prisma migrate dev --name migration_name

# Apply migrations
bunx prisma migrate deploy

# Reset database (development only)
bunx prisma migrate reset

Debugging

Frontend

Use React DevTools and Redux DevTools:

# Enable verbose logging
VITE_LOG_LEVEL=debug npm run dev

Backend

# Enable debug mode
DEBUG=* bun run dev

---

🚢 Deployment

Docker Deployment

Build and Run

# Build images
docker-compose build

# Start services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Environment Variables

Create .env files for production:

cp backend/.env.example backend/.env.production
cp frontend/.env.example frontend/.env.production

Manual Deployment

Frontend (Vercel)

cd frontend
npm run build

# Deploy to Vercel
vercel --prod

Backend (Traditional Server)

cd backend
bun run build

# Set environment to production
export NODE_ENV=production

# Start with PM2
pm2 start dist/index.js --name CyberGPT-backend

Database Deployment

PostgreSQL

Use managed PostgreSQL services:

• Railway

Neo4j

Use Neo4j AuraDB (managed cloud service) or self-host:

docker run \
  --name neo4j-prod \
  -p 7474:7474 -p 7687:7687 \
  -v $HOME/neo4j/data:/data \
  -e NEO4J_AUTH=neo4j/production-password \
  neo4j:latest

Environment-Specific Configurations

Development:

• Hot reload enabled
• Debug logging
• Local databases
• Mock external services

Production:

• Minified builds
• Error tracking (Sentry)
• Production databases
• CDN for static assets
• Rate limiting
• Security headers

---

🧪 Testing

Test Coverage

# Frontend coverage
cd frontend
npm run test:coverage

# Backend coverage
cd backend
bun run test:coverage

E2E Testing

# Install Playwright
npm install -D @playwright/test

# Run E2E tests
npx playwright test

Load Testing

# Install k6
brew install k6

# Run load test
k6 run tests/load/chat-api.js

---

🤝 Contributing

We welcome contributions! Please follow these guidelines:

Development Workflow

1. Fork the repository

gh repo fork your-org/CyberGPT --clone

2. Create a feature branch

git checkout -b feature/amazing-feature

3. Make your changes

# Follow code style guidelines
# Add tests for new features
# Update documentation

4. Run quality checks

npm run check:fix
npm run test
npm run type-check

5. Commit your changes

git commit -m "feat: add amazing feature"

Follow Conventional Commits:

• feat: New feature
• fix: Bug fix
• docs: Documentation
• style: Formatting
• refactor: Code restructuring
• test: Adding tests
• chore: Maintenance

6. Push and create PR

git push origin feature/amazing-feature
# Create Pull Request on GitHub

Code Review Process

• All PRs require at least one review
• CI/CD checks must pass
• Code coverage should not decrease
• Documentation must be updated

Reporting Issues

Use GitHub Issues with appropriate labels:

• bug - Something isn't working
• enhancement - New feature request
• documentation - Documentation improvements
• security - Security vulnerabilities

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2024 CyberGPT

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

🙏 Acknowledgments

Technologies

• OpenAI - GPT-4 AI capabilities
• Neo4j - Graph database technology
• React - Frontend framework
• Tailwind CSS - Styling framework

Inspirations

• OWASP Foundation for security standards
• Cybersecurity community for best practices
• Open-source contributors worldwide

---

📞 Support & Contact

Support Channels

• 📧 Email: support@cybergpt.com
• 🐛 Issues: GitHub Issues
• 📚 Documentation: docs.cybergpt.com

---

📝 Changelog

See CHANGELOG.md for detailed version history.

Latest Release (v1.0.0)

Added

✨ Responsive graph visualization for mobile devices
✨ Enhanced knowledge graph with D3.js
✨ Multi-personality AI modes
✨ Comprehensive vulnerability scanning
✨ Interactive todo list management
✨ PDF report generation

Fixed

🐛 Graph modal responsiveness issues
🐛 Chat alignment problems
🐛 Authentication edge cases
🐛 File upload handling

Changed

♻️ Improved API error handling
♻️ Optimized database queries
♻️ Enhanced UI/UX across platform
♻️ Updated dependencies

---

CyberGPT - AI-Powered Cybersecurity Assessment Platform

Documentation • GitHub

©️ 2024 CyberGPT. All rights reserved.