{"id":31618041,"url":"https://github.com/thalesgroup-cert/suspicious","last_synced_at":"2026-01-16T16:34:25.496Z","repository":{"id":317886062,"uuid":"1069106203","full_name":"thalesgroup-cert/suspicious","owner":"thalesgroup-cert","description":"AI-powered phishing \u0026 threat-analysis platform to automatically inspect, classify, and report suspicious emails, files, URLs, IPs, and hashes built for teams and organizations","archived":false,"fork":false,"pushed_at":"2026-01-08T13:55:07.000Z","size":16074,"stargazers_count":71,"open_issues_count":0,"forks_count":7,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-01-08T23:08:30.137Z","etag":null,"topics":["django","django-project","docker","docker-compose","javascript","mail","mail-analysis","python","security","tool"],"latest_commit_sha":null,"homepage":"","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thalesgroup-cert.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-03T12:14:34.000Z","updated_at":"2026-01-08T13:33:23.000Z","dependencies_parsed_at":"2025-10-03T18:26:07.161Z","dependency_job_id":"6a3011c4-5365-42a9-8312-9a0c52dc35f4","html_url":"https://github.com/thalesgroup-cert/suspicious","commit_stats":null,"previous_names":["thalesgroup-cert/suspicious"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/thalesgroup-cert/suspicious","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thalesgroup-cert%2Fsuspicious","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thalesgroup-cert%2Fsuspicious/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thalesgroup-cert%2Fsuspicious/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thalesgroup-cert%2Fsuspicious/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thalesgroup-cert","download_url":"https://codeload.github.com/thalesgroup-cert/suspicious/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thalesgroup-cert%2Fsuspicious/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28479938,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["django","django-project","docker","docker-compose","javascript","mail","mail-analysis","python","security","tool"],"created_at":"2025-10-06T13:45:09.790Z","updated_at":"2026-01-16T16:34:25.486Z","avatar_url":"https://github.com/thalesgroup-cert.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cstrong\u003eAI Phishing Threat Analysis Platform\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/thalesgroup-cert/suspicious/graphs/contributors\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/contributors/thalesgroup-cert/suspicious?style=for-the-badge\" alt=\"Contributors\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/thalesgroup-cert/suspicious\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/stars/thalesgroup-cert/suspicious?style=for-the-badge\u0026logo=opensourceinitiative\u0026logoColor=white\" alt=\"Stars\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/thalesgroup-cert/suspicious/issues?q=is%3Aissue+is%3Aclosed\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/issues-closed-raw/thalesgroup-cert/suspicious?style=for-the-badge\u0026logo=github\" alt=\"Closed Issues\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"./LICENSE\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/license/thalesgroup-cert/suspicious?style=for-the-badge\u0026logo=opensourceinitiative\u0026logoColor=white\" alt=\"License\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n# Suspicious 🛡️\n\nAn **AI-powered phishing \u0026 threat-analysis platform** to automatically inspect, classify, and report suspicious emails, files, URLs, IPs, and hashes built for teams and organizations.\n\n## Why Suspicious?\n\nPhishing and social-engineering attacks are becoming more sophisticated, combining deceptive emails, malware, credential theft, malicious links, and more.\n\nSuspicious offers a **scalable, automated, AI-augmented defense** that helps you:\n\n- 🔎 Analyze suspicious content: emails, documents, URLs, IPs, file hashes…\n- 🧠 Use deep analysis pipelines: YARA rules, sandboxing, metadata inspections, **AI-based classifier**, Cortex analyzers\n- ✅ Classify results into actionable categories (Safe / Inconclusive / Suspicious / Dangerous)\n- 📄 Provide full analysis reports and dashboards through an intuitive web interface\n- 📤 Automatically notify or alert users via email\n- 🔌 Integrate optionally with **TheHive**, **MISP**, **LDAP**, **MinIO**, **Elasticsearch**, and more\n\n## Getting Started (Quick Setup)\n\nWe recommend using Docker + Docker Compose v2. For full instructions, see **[SETUP.md](SETUP.md)** and **[CONFIG.md](CONFIG.md)**.\n\n```bash\n# 1. Clone the repo\ngit clone https://github.com/thalesgroup-cert/suspicious.git\ncd suspicious/deployment\n\n# 2. Initialize environment, configs \u0026 directory structure\nmake init\n\n# 3. Start the stack\nmake up\n\n# 4. On first run: run database migrations + create superuser\nmake migrate\nmake superuser\n\n# 5. Open the web UI\n#    http://localhost:9020  (or your configured domain/port)\n```\n\nAlternatively, you can use Docker Compose directly:\n\n```bash\ndocker compose up -d\n```\n\n## Configuration Overview\n\nSuspicious uses three main configuration files:\n\n| File                       | Purpose                                                                                                               |\n| -------------------------- | --------------------------------------------------------------------------------------------------------------------- |\n| `.env`                     | Environment variables for Docker services (versions, ports, paths, credentials)                                       |\n| `Suspicious/settings.json` | App-level config: branding, SMTP, LDAP, Cortex \u0026 MISP credentials, allowed domains, UI settings, etc.                 |\n| `email-feeder/config.json` | Email ingestion config: IMAP/IMAPS connectors, MinIO settings, polling, working directory, notification SMTP settings |\n\nFor full parameter documentation and examples, refer to **[CONFIG.md](CONFIG.md)**.\n\n## Key Features\n\n- **Multi-type submission support**\n  - Emails (`.eml`, `.msg`)\n  - Files (PDF, Office docs, archives, executable, HTML, ZIP, …)\n  - URLs, IP addresses, file hashes\n\n- **Automatic email ingestion**\n  - Forward suspicious emails to a monitored mailbox → ingested via Email Feeder → queued for automated analysis\n\n- **On-demand web submissions**\n  - Use the “Submit an Item” UI to send files, URLs, hashes, IPs, or email files for analysis\n\n- **Smart classification \u0026 reporting**\n  - Results are scored and categorized by risk\n  - Dashboards for overall statistics, phishing-campaign overviews, user submission history, detailed analyzer outputs\n\n- **Extensible integrations and stack support**\n  - **Cortex** for analyzer execution (YARA, AI, sandboxing, metadata analysis…)\n  - **Elasticsearch** for search capabilities\n  - **MinIO (S3-compatible)** for storage of artifacts\n  - Optional integration with **TheHive** / **MISP** for incident or threat-intel workflows\n  - Optional **LDAP authentication** for enterprise setups\n\n## AI Mail Analysis\n\nSuspicious includes a built-in AI module (via `Analyzers/AIMailAnalyzer`) that classifies emails by intent (phishing, malicious, suspicious, benign…) complementing static rules and analyzers to deliver smarter detection tailored to your organization.\n\n### What it does\n\n- Uses machine-learning to identify potentially malicious or suspicious email patterns beyond heuristic or rule-based detection.\n- Works alongside standard analyzers (YARA, sandbox, metadata) for a more robust analysis pipeline.\n- Supports organization-specific training allowing adaptation to your internal email norms, languages, and threat landscape.\n- Enables dashboards and KPIs: campaign summaries, volumes of suspicious vs safe emails, historical trends, detection stats.\n\n### Why it matters\n\n- Detects subtle or evolving threats which static rules may miss (e.g. social-engineering, unusual metadata)\n- Provides customization you can train the model on your own data to fit company-specific patterns\n- Gives visibility \u0026 analytics over time helpful for SOC, reporting, awareness, and improvement loops\n\n### How to get started\n\n1. Go to `Analyzers/AIMailAnalyzer/` there you’ll find training scripts and instructions.\n2. Collect a representative, labeled dataset (legitimate vs phishing emails).\n3. Train or retrain the model to suit your environment.\n4. Deploy the trained model in Cortex alongside other analyzers.\n5. Review classification results; monitor performance (precision, false-positives/negatives) and retrain periodically if needed.\n\n\u003e 💡 **Best practice:** Combine AI classification with other analyzers (YARA, sandbox, metadata). Never rely solely on AI for blocking/auto-response.\n\n## Architecture Overview\n\n| Component          | Role |\n|--------------------|------|\n| **Web (Django)**   | Core logic + UI – submission, analysis, reports |\n| **Database**       | Stores metadata, results, user settings |\n| **Elasticsearch**  | Search engine \u0026 indexing |\n| **Cortex**         | Analyzer engine (runs YARA, AI, sandbox, metadata analyzers) |\n| **MinIO (S3)**     | Stores uploaded files, extracted attachments, artifacts |\n| **Email Feeder**   | Monitors mailboxes, imports incoming emails automatically |\n| **Traefik (optional)** | Reverse-proxy, TLS/HTTPS termination, domain routing |\n\nThe AI analyzer (from `Analyzers/AIMailAnalyzer`) is fully compatible with this architecture, allowing ML-driven detection alongside traditional analyzers.\n\n## 🤝 Contributing\n\nWe welcome contributions! Please read **[CONTRIBUTING.md](CONTRIBUTING.md)** for coding standards, pull request flow, and guidelines.\n\nTypical workflow:\n\n```bash\ngit fork \u0026 clone\ngit checkout -b feature/YourFeature\n# make changes\ngit commit -m \"Add feature X\"\ngit push\n# open pull request\n```\n\nYou can also open [issues](https://github.com/thalesgroup-cert/suspicious/issues) if you encounter bugs or have ideas.\n\n## Screenshots\n\n### Home Page\n\n![Home page screenshot](https://github.com/user-attachments/assets/51a1a6cb-d58b-4175-996f-dc6cf2fc8345)\n\n### User Submissions\n\n![User Submissions](https://github.com/user-attachments/assets/23c61439-78d4-4aa3-aa54-db8fd21a028f)\n\n### Submit Page\n\n![Submit Page](https://github.com/user-attachments/assets/949d789b-b034-44e7-9a97-57361853c0a0)\n\n### Dashboard Classic\n\n![Dashboard Classic](https://github.com/user-attachments/assets/a9b6200a-c6b5-4114-b77d-c36f3214a6af)\n\n### Dashboard Phishing Campaigns\n\n![Dashboard Phishing Campaigns](https://github.com/user-attachments/assets/afabf61c-ba64-4b55-8343-e4df2c3061a0)\n\n## License\n\nSuspicious is released under the **GNU Affero General Public License v3 (AGPL-3.0)**.\n\nSee the [`LICENSE`](LICENSE) file for full details.\n\n## Contact \u0026 Support\n\nHave questions, ideas, or issues?\n\n👉 Open an [issue](https://github.com/thalesgroup-cert/suspicious/issues) feedback is very welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthalesgroup-cert%2Fsuspicious","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthalesgroup-cert%2Fsuspicious","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthalesgroup-cert%2Fsuspicious/lists"}