1 line
6.1 KiB
JSON
1 line
6.1 KiB
JSON
{"repo": "adnan-najjar/undomalware", "files": {"README.md": {"72dfe95d0b9c2dbd4e08b6d2eb0c3382a6f67206": {"t": 1785674377.3957582, "n": 5766, "h": "68c0c62a8b27ceb9", "c": "# UndoMalware - Malware detection\n\nA full-stack web application for malware detection using VirusTotal API with an extra local malware database.\n\n## Quick Setup\n\n```bash\n# Development (runs both frontend and backend)\nmake dev\n\n# Production (builds, deploys, and starts servers)\nmake prod\n```\n\nFor manual setup, see the sections below.\n\n## Features\n\n### Core Functionality\n- **File Scanning**: Upload files to scan via VirusTotal API (32MB limit for free API)\n- **Hash Lookup**: Check file hashes against local malware database and VirusTotal\n- **Malware Database**: Browse known threats with search and filtering\n- **Scan History**: View and manage your previous scans\n- **Admin Dashboard**: Manage users, malware entries, and view all scans\n- **AI Chatbot**: Get help navigating the application, understanding features, and interpreting scan results\n\n### Security Features\n- JWT-based authentication\n- Role-based access control (user/admin)\n- File size validation (32MB max)\n- Public hash lookup (no auth required)\n\n## Tech Stack\n\n**Frontend:**\n- React + Vite\n- React Router DOM\n- Custom CSS (dark theme with matrix rain effect)\n\n**Backend:**\n- Node.js + Express\n- MongoDB (Mongoose)\n- VirusTotal API v2 integration\n- JWT authentication\n- Bcrypt.js for password hashing\n\n## Project Structure\n\n```\nmain/\n├── frontend/ # React frontend\n│ ├── src/\n│ │ ├── pages/ # Login, Dashboard, Scan, History, etc.\n│ │ ├── components/ # Navbar, Chatbot, DropTriangle\n│ │ └── api.js # API integration\n│ └── package.json\n│\n└── backend/ # Express backend\n ├── routes/ # auth, scan, malware, history, admin\n ├── models/ # User, Scan, Malware\n ├── middleware/ # auth, admin\n ├── seeds/ # Database seed scripts\n └── package.json\n```\n\n## Setup Instructions\n\n### Prerequisites\n- Node.js (v16+)\n- MongoDB (local or Atlas)\n- VirusTotal API key (free tier available)\n\n### Backend Setup\n\n1. Navigate to backend directory:\n```bash\ncd backend\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Create `.env` file:\n```env\nMONGODB_URI=mongodb://localhost:27017/malware_db\nJWT_SECRET=your_jwt_secret_key\nVT_API=your_virustotal_api_key\nPORT=5000\n\n# OpenAI/Groq API (for AI chatbot)\nOPENAI_API_KEY=your_openai_or_groq_api_key\nOPENAI_BASE_URL=https://api.groq.com/openai/v1\nOPENAI_MODEL=llama-3.1-8b-instant\n```\n\n4. Seed the database:\n```bash\nnpm run seed:malware # Adds sample malware entries\nnpm run seed:admin # Creates admin user\n```\n\n5. Start the backend:\n```bash\nnpm start # Production\nnpm run dev # Development with nodemon\n```\n\n### Frontend Setup\n\n1. Navigate to frontend directory:\n```bash\ncd frontend\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Start the development server:\n```bash\nnpm run dev\n```\n\n## API Endpoints\n\n### Authentication (Public)\n- `POST /api/auth/register` - Register new user\n- `POST /api/auth/login` - Login user\n\n### File Scanning (Protected)\n- `POST /api/scan` - Upload and scan file (32MB limit)\n- `GET /api/scan/:hash` - Get scan result by hash\n\n### Hash Lookup (Public)\n- `GET /api/malware/check/:hash` - Check hash against local DB + VirusTotal\n\n### Malware Database (Public Read)\n- `GET /api/malware` - List malware (paginated, with search/filter)\n- `GET /api/malware/:id` - Get single malware entry\n\n### Scan History (Protected)\n- `GET /api/history` - Get user's scan history\n- `DELETE /api/history/:id` - Delete single scan\n- `DELETE /api/history` - Delete all history\n\n### Admin Routes (Admin Only)\n- `GET /api/admin/users` - List all users\n- `DELETE /api/admin/users/:id` - Delete user\n- `GET /api/admin/scans` - View all scans\n- `POST /api/admin/malware` - Add malware entry\n- `PUT /api/admin/malware/:id` - Update malware entry\n- `DELETE /api/admin/malware/:id` - Delete malware entry\n\n### Chatbot (Protected)\n- `POST /api/chat/message` - Send message and get AI response\n- `GET /api/chat/history` - Get chat history\n- `DELETE /api/chat/clear` - Clear chat history\n\n## Default Admin Account\n\nAfter running the admin seed script:\n- **Email**: `admin@admin`\n- **Username**: `admin`\n- **Password**: `admin123`\n\nAccess admin dashboard at `/admin` after login.\n\n## Usage\n\n1. **Register/Login** at `/register` or `/login`\n2. **Scan Files** - Drag & drop files on the home page or visit `/dashboard`\n3. **Lookup Hashes** - Enter MD5/SHA-1/SHA-256 hashes at `/hash`\n4. **Browse Malware DB** - View known threats at `/samples`\n5. **View History** - Check past scans at `/history`\n6. **AI Chatbot** - Click the chat icon in bottom-right for help\n7. **Admin Panel** - Manage everything at `/admin` (admin only)\n\n## File Size Limits\n\n- **VirusTotal Free API**: 32MB maximum file size\n- Files larger than 32MB will be rejected with a clear error message\n- Use Hash Lookup feature for larger files (scan hash without uploading)\n\n## Error Handling\n\n- **413 Payload Too Large**: File exceeds 32MB limit\n- **403 Forbidden**: Invalid/missing VirusTotal API key\n- **400 Bad Request**: Invalid hash format (must be valid MD5/SHA-1/SHA-256)\n\n## Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| MONGODB_URI | MongoDB connection string | Yes |\n| JWT_SECRET | Secret key for JWT tokens | Yes |\n| VT_API | VirusTotal API key | Yes (for scanning) |\n| PORT | Backend server port | No (default: 5000) |\n| OPENAI_API_KEY | OpenAI/Groq API key | Yes (for chatbot) |\n| OPENAI_BASE_URL | OpenAI API base URL | No |\n| OPENAI_MODEL | Model to use (e.g., gpt-3.5-turbo, llama-3.1-8b-instant) | No |\n\n### OpenAI/Groq Setup\nThe chatbot supports both OpenAI and Groq (free tier available). Example Groq setup:\n```\nOPENAI_API_KEY=gsk_...\nOPENAI_BASE_URL=https://api.groq.com/openai/v1\nOPENAI_MODEL=llama-3.1-8b-instant\n```\n\n"}}}} |