CyberGuard 🛡️

A Django-based cybersecurity assistant that uses an AI agent + Model Context Protocol (MCP) to help elderly users identify scams, phishing links, deepfakes, and suspicious emails.

---

What It Does

Users paste a suspicious message, URL, or image into the chat interface. An AI agent (GPT-4o) then automatically decides which of the following security tools to call:

Tool	What It Scans	Method
scan_url_reputation	URL safety	VirusTotal API (90+ vendor consensus)
scan_domain_dns	Domain legitimacy & email spoofing	DNS A / MX / TXT (SPF) lookups
scan_url_phishing	Phishing probability	22-feature KNN ML model
check_deepfake_image	Uploaded image authenticity	Reality Defender API

Results are synthesised by GPT-4o into plain-English advice designed for non-technical users.

---

Architecture Summary

Browser → Django (async view) → LLM Agent → GPT-4o
                                          ↕  stdio (MCP)
                                     MCP Server (mcp_server.py)
                                          ↕
                          VirusTotal / DNS / WHOIS / Reality Defender

The MCP server runs as a subprocess with stdio transport. The agent discovers its tools at runtime and converts them to OpenAI's function-calling schema. See ARCHITECTURE.md for the full technical breakdown.

---

Prerequisites

• Python 3.11+
• A virtual environment (venv recommended)
• API keys (see .env setup below)

---

Setup

1. Clone & Install

git clone https://github.com/your-org/cyberguard.git
cd cyberguard
python -m venv venv

# Windows
.\venv\Scripts\Activate

# Mac / Linux
source venv/bin/activate

pip install -r requirements.txt

2. Configure Environment Variables

Copy the example file and fill in your keys:

cp .env.example .env

Edit .env:

# Required: LLM (GPT-4o via GitHub Models / Azure Inference)
GITHUB_TOKEN=your_github_pat_or_azure_key

# Required: URL reputation scanning
VIRUSTOTAL_API_KEY=your_virustotal_key

# Required: Deepfake detection
REALITY_DEFENDER_API_KEY=your_reality_defender_key

# Required: Email verification (MFA)
MAILGUN_API_KEY=your_mailgun_key
MAILGUN_DOMAIN=mg.yourdomain.com
MAILGUN_ENDPOINT=https://api.mailgun.net/v3/mg.yourdomain.com/messages
MAILGUN_FROM=CyberGuard <noreply@mg.yourdomain.com>

3. Place the ML Model Files

The phishing classifier requires two files in core/services/phishing_models/:

core/
  services/
    phishing_models/
      knn_model.pkl   ← trained KNeighborsClassifier
      scaler.pkl      ← fitted StandardScaler

If these files are absent the scan_url_phishing tool still works — it falls back to returning the raw URL risk features so the LLM can still reason about the URL.

4. Run Migrations & Start

python manage.py migrate
python manage.py runserver

Open http://localhost:8000 in your browser.

---

Project Structure

cyberguard/
├── mcp_server.py                  # MCP tool server (URL scanner, deepfake, DNS)
├── manage.py                      # Django entry point
├── requirements.txt
├── .env.example
│
├── cyberguard_project/
│   ├── settings.py                # Django configuration
│   ├── urls.py                    # Root URL routing
│   └── wsgi.py
│
└── core/
    ├── models.py                  # CyberGuardUser, ChatSession, ChatMessage
    ├── views.py                   # Async Django views & auth
    ├── urls.py                    # App-level URL patterns
    ├── services/
    │   ├── llm_agent.py           # Agent loop: OpenAI + MCP orchestration
    │   ├── phishing_detection.py  # 22-feature URL extractor (HTTP + WHOIS)
    │   ├── email_service.py       # MFA code store/send via Mailgun
    │   └── phishing_models/       # knn_model.pkl + scaler.pkl (not in repo)
    └── templates/
        ├── base.html              # Shared layout + global scanner widget
        ├── index.html             # Main chat SPA
        ├── knowledge_hub.html     # Educational content
        ├── quizzes.html           # Scam-awareness quizzes
        ├── login.html / signup.html / verify_code.html
        ├── about.html / support.html
        └── 404.html

---

Authentication Flow

CyberGuard uses two-factor authentication for all logins and sign-ups:

1. User submits email + password.
2. A 6-digit code is generated and stored in Django's cache (15-minute TTL).
3. The code is emailed via Mailgun.
4. User enters the code on the /verify/ page to complete login.

A Guest Mode is available for development. Set ENABLE_GUEST_MODE = False in views.py and uncomment @login_required on the index view to enforce real logins.

---

Adding a New Security Tool

Add a decorated function to mcp_server.py — FastMCP auto-registers it:

@mcp.tool()
def check_email_breach(email_address: str) -> str:
    """
    Check if an email appears in known data breaches.
    Use this whenever the user asks about the safety of an email address.
    """
    # your implementation here
    return result

The agent discovers the new tool automatically on the next request. See ARCHITECTURE.md → Extension Points for more detail.

---

Known Security Gaps

Issue	Risk	Recommended Fix
No SSRF protection	phishing_detection.py fetches user-supplied URLs; internal IPs could be probed	Validate resolved IP against blocklist before fetch
Redirects not validated	requests.get(allow_redirects=True) may follow a chain ending at an internal host	Manually follow redirects with per-hop IP validation
No API rate limiting	/api/analyze/ has no per-user throttle	Add django-ratelimit
Hardcoded SECRET_KEY	Exposed in settings.py	Load from .env; regenerate before deployment
DEBUG = True	Full stack traces exposed to browser	Set to False; restrict ALLOWED_HOSTS before deployment

---

Windows Note

On Windows, asyncio requires the Proactor event loop for subprocess support. This is already handled in manage.py:

if sys.platform == 'win32':
    asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())

---

License

This project is for educational and research purposes.