Metadata-Version: 2.4
Name: phishguard
Version: 1.0.0
Summary: Email phishing and spam detection library with built-in REST API
Author-email: Atharva Kulkarni <atharva.kulkarni678@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/atharvakulkarni/phishdetect
Project-URL: Issues, https://github.com/atharvakulkarni/phishdetect/issues
Keywords: phishing,spam,email,security,detection,levenshtein
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Security
Classifier: Topic :: Communications :: Email :: Filters
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Requires-Dist: python-whois>=0.9
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.29
Requires-Dist: pydantic>=2.0

# phishdetect

Email phishing and spam detection library — drop it into any Python project or run it as a standalone REST API on your mail server.

## Install

```bash
pip install phishdetect
```

## Use as a Python library

```python
from phishdetect import PhishingDetector

detector = PhishingDetector()

result = detector.analyze({
    "sender":   "support@paypa1.com",
    "subject":  "Urgent: verify your account NOW!!",
    "content":  "Click here to reset your password immediately.",
    "reply_to": "",   # optional
})

print(result["risk_score"])   # "HIGH", "MEDIUM", or "LOW"
print(result["risk_level"])   # 0–100 numeric score
print(result["warnings"])     # detailed list of every signal found
```

### Integrate with your mail server

```python
from phishdetect import PhishingDetector

detector = PhishingDetector()

def on_email_received(email):
    result = detector.analyze({
        "sender":  email.from_address,
        "subject": email.subject,
        "content": email.body,
    })

    if result["risk_score"] == "HIGH":
        quarantine(email)
    elif result["risk_score"] == "MEDIUM":
        add_warning_banner(email)
    else:
        deliver(email)
```

## Run as a REST API server

```bash
phishdetect-server
# Server starts at http://0.0.0.0:5000
```

### API endpoints

| Method | Endpoint   | Description                        |
|--------|------------|------------------------------------|
| POST   | /analyze   | Analyze an email for phishing      |
| GET    | /health    | Health check                       |
| GET    | /status    | Domain intelligence database info  |
| POST   | /update    | Refresh the Tranco domain list     |

### Example API call

```bash
curl -X POST http://localhost:5000/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "sender":  "support@paypa1.com",
    "subject": "Urgent: verify your account",
    "content": "Click here to reset your password."
  }'
```

## What it detects

- **Lookalike domains** — `paypa1.com` vs `paypal.com` (Levenshtein distance)
- **Homoglyph attacks** — Unicode characters that look like Latin letters (е, о, а)
- **Subdomain abuse** — `paypal.attacker.com` pretending to be PayPal
- **Suspicious keywords** — urgency, financial fraud, prize/lottery patterns
- **Deceptive links** — visible URL differs from actual href destination
- **Reply-To mismatch** — replies routed to a different domain
- **New domains** — recently registered domains flagged via WHOIS
- **Spam signals** — ALL CAPS subjects, excessive exclamation marks, bulk patterns

## How the domain database works

On first run, phishdetect automatically downloads the [Tranco top-1M domain list](https://tranco-list.eu) and stores the top 50,000 domains in a local SQLite database at `~/.phishdetect/phishing.db`. This refreshes weekly. No API key required.

## License

MIT
