PhishGuard AI

See the signals behind the verdict. Explainable phishing detection for URLs and email—offline by default, with no API key and no runtime dependencies.

PhishGuard AI turns structural URL signals and email indicators into a reviewable risk score, verdict, and feature-level explanation. Run it from a terminal, embed it in Python, add it to GitHub Actions, export JSON or SARIF, or use the browser demo.

Try the live demo · Install v0.5.1 · View on Marketplace · Review the evidence · Read the detection model

The image shows current CLI output from reserved, public-safe inputs. The latest validation completed 199 tests with 2 skips and 1 tracked expected failure. Reproduction commands and limitations are recorded in Project Evidence.

URL / email  →  local feature extraction  →  explainable risk score
                                                   ↓
                     CLI · JSON · SARIF · API · browser · GitHub Actions

PhishGuard is built for the moment after a scanner says “suspicious”: an engineer still needs to understand the signal, reproduce the result, and route the evidence into an existing workflow.

PhishGuard is designed as a lightweight supporting signal for security engineers, SOC analysts, developers, and educators. It is not a replacement for enterprise email security, threat-intelligence feeds, asset context, or a statistically trained production model.

Python 3.10 or later is required. Install the verified v0.5.1 wheel from GitHub Releases:

python -m pip install \
  https://github.com/omobolajiadeyan/phishguard-ai/releases/download/v0.5.1/phishguard_ai-0.5.1-py3-none-any.whl
phishguard --help

Run a safe example and a suspicious synthetic example:

phishguard url "https://www.example.com/account" --plain
phishguard url "http://192.0.2.10/secure-login/verify" --verbose --plain

Both inputs are reserved for documentation and do not contact live phishing infrastructure. See the one-minute demo or the five-minute evaluator guide for a guided review.

# URL with an explainable feature breakdown
phishguard url "http://paypa1-secure-login.xyz/verify" --verbose

# Email with authentication evidence from a trusted receiver
phishguard email \
  --subject "URGENT: Your account has been suspended" \
  --body "Click here immediately to verify your account." \
  --authentication-results "mx.example; spf=fail; dkim=fail; dmarc=fail"

# Saved email; trust only the named receiver's Authentication-Results header
phishguard eml suspicious.eml --trusted-authserv-id mx.example --verbose

SPF, DKIM, and DMARC failures are supporting evidence—not automatic proof of phishing. PhishGuard parses supplied results; it does not perform DNS policy validation or cryptographic signature verification.

phishguard batch data/urls.txt --output results.json
phishguard batch data/urls.txt --format sarif --output phishguard.sarif

See GitHub Code Scanning and the email output examples for integration-ready examples.

- name: Scan URL with PhishGuard AI
  uses: omobolajiadeyan/phishguard-ai@v0.5.1
  with:
    url: https://example.com
    sarif-output: phishguard-results.sarif

The Marketplace listing documents all inputs. Teams evaluating the action can follow the adoption guide.

from model import classify, score_url

probability, features = score_url("https://www.example.com/account")
print(classify(probability), probability, features)

See the Python API guide for supported URL, email, and extra-feature contracts.

The live browser demo runs the JavaScript scoring port entirely in the browser. Python/JavaScript parity tests guard against model drift. The Chromium extension prototype uses the same local scoring model and does not request browsing history.

For local service integrations:

phishguard serve --port 8765
curl http://127.0.0.1:8765/healthz
curl -X POST http://127.0.0.1:8765/v1/url \
  -H "Content-Type: application/json" \
  -d '{"url": "http://paypa1-secure-login.xyz/verify"}'

The server binds to 127.0.0.1 by default and has no authentication. Review the network controls before exposing it beyond the local machine.

PhishGuard applies a hand-tuned heuristic model to explainable URL and email features, including:

• hostname structure, entropy, IP literals, suspicious TLDs, and path depth;
• phishing keywords, typosquatting distance, IDN signals, and free hosting;
• email urgency, link density, attachment language, and capitalization;
• optional SPF, DKIM, and DMARC results supplied by a trusted receiver.

Default scoring is local. The opt-in --check-domain-age option performs an RDAP lookup through rdap.org; failures degrade to “no signal.” Redirect resolution also requires network access and includes SSRF protections.

Read Detection Model for weights, trust boundaries, known blind spots, and the requirements for scoring changes.

The checked-in regression fixture currently reports 7 true positives, 7 true negatives, 0 false positives, and 0 false negatives. A separate public-safe fixture reports 5 true positives and 5 true negatives. These small fixtures detect regressions; they are not population-level accuracy or calibration claims.

Realistic stress testing also preserves three known false-positive cases in an eight-case branded-path fixture. Those gaps are documented instead of hidden. For dated live-traffic results, methodology, and rerun commands, see:

• Project Evidence
• Benchmark
• Public Evidence and Adoption
• Detection Model

Run the local verification yourself:

python -m unittest discover -s tests -v
python tools/repository_policy.py
python tools/evaluate_url_benchmark.py
python tools/evaluate_url_benchmark.py data/public_benchmark_urls.jsonl

Contributions from security analysts, Python developers, students, researchers, and first-time open-source contributors are welcome.

Start with CONTRIBUTING.md, the first-contribution guide, and a scoped good first issue. Security issues should follow SECURITY.md, not a public issue.

Created and maintained by Omobolaji Adeyan, cybersecurity engineer.

GitHub · Website · LinkedIn · Security contact

A FreNiMi product, released under the MIT License. Citation metadata is available in CITATION.cff.