Phishing & threat-analysis platform

Suspicious

Documentation: https://thalesgroup-cert.github.io/suspicious/

Suspicious inspects, classifies, and reports suspicious emails, files, URLs, IPs, and file hashes. Submit an item from the web UI or forward an email to a monitored mailbox; Suspicious runs it through YARA rules, a sandbox, metadata checks, and a machine-learning email classifier, then returns a scored verdict and a full report.

Built and maintained by the Thales Group CERT.

What it does

• Analyzes emails (.eml, .msg), documents, archives, executables, URLs, IP addresses, and file hashes.
• Scores each submission as Safe, Inconclusive, Suspicious, or Dangerous.
• Reports results through a web UI with dashboards, per-analyzer output, and submission history.
• Ingests email automatically from IMAP/IMAPS mailboxes.
• Notifies reporters of the outcome by email.
• Integrates with Cortex, TheHive, MISP, LDAP, Elasticsearch, ChromaDB, and S3-compatible storage.

Quick start

Requires Docker and Docker Compose v2.

git clone https://github.com/thalesgroup-cert/suspicious.git
cd suspicious

# Example configs that run as-is for local development
cp docs/getting-started/examples/deployment-env.example          deployment/.env
cp docs/getting-started/examples/Suspicious-settings.example.json Suspicious/settings.json

cd deployment
docker network create suspicious_net
docker compose build suspicious
docker compose up -d db_suspicious redis_cache redis_broker
docker compose up -d --no-deps suspicious
make migrate
make seed-config
make createsuperuser

Open http://localhost:9020/admin/ and sign in.

The example configs use throwaway local credentials. Change every secret before exposing the app. Full guide, the complete stack (UI, HTTPS, Cortex), and configuration reference: INSTALL.md and CONFIG.md.

Configuration

Three files hold all configuration. Templates ship in the repo.

See CONFIG.md for every parameter.

Architecture

How an analysis runs

1. Django creates a Case. For each analyzer it writes an AnalyzerReport and a CaseAnalyzerJob row in one transaction, pinning the (case, cortex job) mapping at dispatch.
2. Cortex runs each analyzer and posts to the HMAC-signed webhook on completion.
3. The webhook looks up the case in CaseAnalyzerJob, then enqueues a Celery task that takes a per-case lock, updates the job, and calls finalise_case once the case has no pending jobs left.
4. finalise_case scores the case, pushes to TheHive/MISP if configured, queries ChromaDB for similar past cases, and emails the reporter.
5. Celery beat re-checks any webhook the platform missed (every 300 s) and fails jobs stuck past STALE_JOB_TIMEOUT_SECONDS (every 600 s), so cases never stall.

AI email classifier

Analyzers/AIMailAnalyzer classifies emails by intent (phishing, malicious, suspicious, benign) using a Sentence-Transformers embedding model and a custom classifier, with ChromaDB for similarity search. It runs as a Cortex analyzer alongside the static rules.

To train it on your own data:

1. Open Analyzers/AIMailAnalyzer/ for the training scripts.
2. Prepare a labeled dataset (legitimate vs phishing).
3. Train the model.
4. Deploy it in Cortex with the other analyzers.
5. Review precision and false-positive rates; retrain as needed.

Use it alongside YARA, sandbox, and metadata analyzers. Do not auto-block on the classifier alone.

Contributing

See CONTRIBUTING.md for coding standards and the pull request flow.

git checkout -b feature/your-feature
# make changes, commit, push
# open a pull request

Bug reports and ideas are welcome in issues.

Screenshots

Login Page

Home Page

User Submissions

Submit Page

Profile Page

Dashboard Classic

Dashboard Phishing Campaigns

CI/CD

GitHub Actions runs six workflows plus Dependabot under .github/.

Published images (GHCR)

Deployment is manual via deployment/Makefile (make deploy); CI never holds production credentials.

License

Released under the Apache License, Version 2.0. See LICENSE.

Contact

Questions, ideas, or bugs: open an issue.