🛡️ QuishGuard AI - URL Phishing Detection Service

QuishGuard AI is a real-time, multi-signal phishing URL detection engine that aggregates multiple analyzers to assess the risk of a given URL. It features a simple frontend interface for interactive usage alongside a REST API for programmatic access, providing risk scores based on factors such as domain age, SSL status, Google Safe Browsing results, content analysis, and AI-powered semantic detection.

✨ Features

• Multi-Analyzer Approach: Combines results from 6 independent analyzers:

  • DNS/WHOIS (domain age, resolution, suspicious TLDs)
  • SSL Certificate (HTTPS, expiry, issuer validation)
  • Google Safe Browsing API (threat intelligence)
  • URLScan.io (community scan history)
  • HTML Content (link ratios, login forms, brand impersonation)
  • Gemini AI (LLM-powered typosquatting & brand mismatch detection)

• Weighted Scoring: Each analyzer contributes to a final risk score based on configurable weights with trust bonus for whitelisted domains

• Asynchronous Processing: Uses FastAPI and Motor for efficient handling of concurrent requests

• QR Code Scanning: Live camera scanning for quishing (QR code phishing) detection

• Extensible Design: New analyzers can be easily added by implementing the base interface

• Fully Containerized: Docker and Docker Compose support for easy deployment

🚀 Quick Start

API Endpoint

Method	Endpoint	Description
POST	/api/analyze	Submit URL for phishing analysis
GET	/api/health	Health check for container orchestration
GET	/docs	Interactive Swagger API documentation

Example Request

curl -X POST http://localhost:8000/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/login"}'

Example Response

Click to expand

{
  "url": "https://example.com/login",
  "final_url": "https://example.com/login",
  "verdict": "suspicious",
  "risk_score": 0.47,
  "risk_percent": "47%",
  "trust": {
    "bonus_applied": false,
    "trusted_domain": null,
    "base_score_before_bonus": 0.47
  },
  "pre_processor": {
    "short_link": false,
    "tunnel": false,
    "redirected": false,
    "redirect_count": 0
  },
  "breakdown": {
    "gemini": {"score": 0.9, "weight": 0.35, "flags": ["brand mismatch detected"]},
    "content": {"score": 0.55, "weight": 0.07, "flags": ["login form detected"]},
    "dns_whois": {"score": 0.1, "weight": 0.10, "flags": ["domain resolves OK"]},
    "ssl": {"score": 0.05, "weight": 0.08, "flags": ["SSL valid"]}
  },
  "analyzed_at": "2026-04-10T10:30:00Z"
}

📦 Installation

Option A) Using uv (Recommended)

git clone https://github.com/EnhancedProtection/quishguard-ai.git
cd quishguard-ai
uv sync
cp .env.example .env
# Edit .env with your API keys
uv run uvicorn app.main:app --reload

Option B) Using pip and venv

git clone https://github.com/EnhancedProtection/quishguard-ai.git
cd quishguard-ai
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your API keys
uvicorn app.main:app --reload

🐳 Docker Deployment

# Clone the repository
git clone https://github.com/EnhancedProtection/quishguard-ai.git
cd quishguard-ai

# Create environment configuration
cp .env.example .env
# Edit .env to add your API keys

# Build and run
docker build -t quishguard-ai .
docker run -d -p 8000:8000 --env-file .env quishguard-ai

📝 Note: See .env.example in the repository root for all available configuration options including API keys and analyzer weights.

Access the application at:

• Web Interface: http://localhost:8000/
• API Documentation: http://localhost:8000/docs

🛠️ Tech Stack

Category	Technologies
Backend	Python 3.11+, FastAPI, Uvicorn
Async HTTP	aiohttp
Database	MongoDB, Motor (async driver)
AI/ML	Google Gemini 2.5 Flash
Security APIs	Google Safe Browsing, URLScan.io
Parsing	BeautifulSoup4, dnspython, python-whois, tldextract
Frontend	HTML5, CSS3, JavaScript, html5-qrcode
Deployment	Docker

🤝 Contributing

Contributions are welcome! 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

Please ensure your code follows the existing style (ruff linting with line-length 92).

📄 License

Distributed under the MIT License. See LICENSE file for more information.

📧 Contact

Project Link: https://github.com/EnhancedProtection/quishguard-ai

---

Built with ❤️ for phishing detection