🛡️ PhishGuard

Stellar Blockchain Phishing Protection System

📋 Overview

PhishGuard is an advanced phishing detection system specifically designed for the Stellar blockchain ecosystem. It analyzes URLs and Stellar wallet addresses to provide real-time security risk assessments, protecting users from malicious websites and fraudulent addresses.

✨ Features

• 🔍 Real-time Analysis: Instant security scanning of URLs and Stellar addresses
• 🚫 Blacklist Detection: Comprehensive database of known malicious domains
• 🎯 Similarity Analysis: Advanced typosquatting detection using string similarity algorithms
• 📊 Risk Scoring: 0-100 risk score with detailed explanations
• 📱 Responsive Design: Beautiful, mobile-friendly interface
• 📈 Scan History: Track and review previous security checks
• ⚡ Fast Performance: Sub-100ms response times
• 🌐 API Access: RESTful API for integration with other applications

🚀 Live Demo

Visit the live application: PhishGuard on Vercel

🛠️ Technology Stack

Backend

• Node.js - Runtime environment
• Express.js - Web framework
• string-similarity - Levenshtein distance algorithm for domain comparison
• fs-extra - Enhanced file system operations
• cors - Cross-origin resource sharing

Frontend

• Vanilla JavaScript - No frameworks, pure performance
• Modern CSS - Gradient backgrounds, animations, responsive design
• HTML5 - Semantic markup

Deployment

• Vercel - Serverless deployment platform
• JSON Database - Lightweight data storage

📦 Installation

Prerequisites

• Node.js 18+
• npm or yarn

Local Development

1. Clone the repository

   git clone https://github.com/yourusername/PhishGuard.git
   cd PhishGuard

2. Install dependencies

   npm install

3. Start development server

   npm run dev

4. Open in browser

   http://localhost:3000
   

Production Deployment

1. Deploy to Vercel

   npm install -g vercel
   vercel --prod

2. Or use Vercel GitHub integration

   • Connect your GitHub repository to Vercel
   • Automatic deployments on push

🔧 API Documentation

POST /check

Analyze a URL or Stellar address for security risks.

Request Body:

{
  "url": "stellar.org",           // For URLs/domains
  "address": "GAHK7EEG..."       // For Stellar addresses
}

Response:

{
  "risk_score": 5,
  "status": "safe",
  "details": {
    "input_type": "url_or_domain",
    "blacklisted": false,
    "similarity_check": {
      "similarity": 1.0,
      "domain": "stellar.org"
    },
    "valid_stellar_address": false
  }
}

GET /history

Retrieve recent scan history.

Response:

{
  "total_checks": 150,
  "recent_checks": [...]
}

GET /health

System health check.

Response:

{
  "status": "healthy",
  "timestamp": "2025-10-10T16:29:42.020Z",
  "version": "1.0.0"
}

🎯 Risk Assessment Algorithm

PhishGuard uses a multi-layered approach to assess security risks:

1. Blacklist Check

• Risk Score: 100 (Malicious)
• Trigger: Domain found in known malicious list
• Action: Immediate warning to user

2. Similarity Analysis

• High Similarity (80%+): Risk 70-100 (Suspicious - Typosquatting)
• Medium Similarity (60-80%): Risk 40-70 (Suspicious)
• Low Similarity (<60%): Risk 0-20 (Safe)

3. Stellar Address Validation

• Valid Format: Risk 10 (Safe)
• Invalid Format: Treated as URL/domain

4. Legitimate Domain Database

Protected domains include:

• stellar.org
• stellarx.com
• stellarterm.com
• lobstr.co
• stellarport.io
• And more...

📊 Example Use Cases

Safe Domain

Input: stellar.org
Output: Risk 5, Status: Safe
Reason: Exact match with legitimate domain

Typosquatting Detection

Input: stellr.org
Output: Risk 95, Status: Suspicious  
Reason: 84% similarity to stellar.org (missing 'a')

Blacklisted Domain

Input: scamstellar.io
Output: Risk 100, Status: Malicious
Reason: Found in blacklist database

Valid Stellar Address

Input: GAHK7EEG2WWHVKDNT4CEQFZGKF2LGDSW2IVM4S5DP42RBW3K6BTODB4A
Output: Risk 10, Status: Safe
Reason: Valid Stellar address format

🏗️ Project Structure

PhishGuard/
├── public/
│   ├── index.html          # Main HTML file
│   ├── script.js           # Frontend JavaScript
│   ├── styles.css          # CSS styling
│   └── logo.jpg            # PhishGuard logo
├── server.js               # Express server
├── results.json            # Scan history database
├── package.json            # Dependencies
├── vercel.json            # Vercel configuration
└── README.md              # This file

🔒 Security Features

• Input Validation: Comprehensive input sanitization
• Rate Limiting: Protection against abuse
• CORS Configuration: Secure cross-origin requests
• Error Handling: Graceful error management
• Data Privacy: No sensitive data logging

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow existing code style
• Add tests for new features
• Update documentation
• Ensure all tests pass

📝 License

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

👥 Team

• PhishGuard Team - Initial work and maintenance

🙏 Acknowledgments

• Stellar Development Foundation for the amazing blockchain platform
• String-similarity library for efficient text comparison
• Vercel for seamless deployment platform
• The open-source community for inspiration and tools

📞 Support

• Issues: GitHub Issues
• Documentation: This README and inline code comments
• Community: Join our discussions

🔮 Roadmap

• Machine learning-based threat detection
• Browser extension
• Mobile app
• Integration with popular Stellar wallets
• Real-time threat intelligence feeds
• Multi-language support

---

Protecting the Stellar ecosystem, one scan at a time.

Made with ❤️ by the PhishGuard Team