SPOT - Spear-Phishing Overwatching Tool¶
SPOT is an open-source email-security platform that decides whether each incoming message is a spear-phishing or business-email-compromise attempt and helps the operator act on the verdict. It runs a chosen set of classifiers against every email, enriches the analysis with organisational context, and exposes the result through a dashboard and an API.
Where to start¶
The documentation is split by audience:
| You are … | Start with |
|---|---|
| Trying SPOT for the first time | Getting Started, then How SPOT works |
| Installing SPOT for production | Deployment, then the Admin guide |
| Using SPOT day to day | Web UI → Operator guide |
| Building a plugin | SDK |
| Reporting a vulnerability | SECURITY.md |
| Contributing | CONTRIBUTING.md |
What SPOT does¶
SPOT receives email through a mail retriever of your choice (SMTP, IMAP, ...), enriches it with organisational facts deposited by context providers (employee directory, partner-domain list, policy wiki, ...), runs it through one or more analyzers (NLP, LLM, rule-based, threat-intelligence, classical ML, ...), and produces a verdict: phishing yes/no, threat level, confidence, indicators, and a recommended action.
Operators see the verdict, the original email, and the contributing analyzers in a dashboard. They can adjust the policies that govern how analyzers combine, install or update plugins, browse the knowledge that providers have deposited, and inspect every analysis SPOT has ever produced.
The platform¶
If this is your first encounter with SPOT, the concepts pages explain what the platform does and how the pieces fit together without expecting you to know its internals. Read them in order or jump to the one that answers your question:
- How SPOT works - the journey of one email through SPOT, from arrival to verdict.
- Plugins - analyzers, context providers, and mail retrievers.
- Workflows - the policies that decide which analyzers run and how their verdicts combine.
- Knowledge store - the shared memory of organisational facts that analyzers consult.
Getting Started walks through bringing the platform up on a fresh machine, submitting your first email, and reading the verdict.
Guides¶
When you know what SPOT is, the guides cover the recurring tasks:
- Admin guide - deployment, configuration, backups, scaling.
- Core developer guide - contributing to the SPOT platform.
- Plugin developer guide - building or contributing to plugins.
- Knowledge store guide - operating the knowledge store.
- Context providers guide - what context providers are and how to use them.
The operator's day-to-day playbook (reviewing flagged messages, adjusting workflows, installing plugins through the dashboard) lives in the Web UI section.
Reference¶
- API reference - every HTTP endpoint exposed by the platform.
- Configuration reference - every setting in
spot.yamland the.envfile. - Environments -
APP_ENVand the development stack's modes. - Database schema - tables, columns, and retention policies.
- Architecture decisions - the ADRs that record why the platform is shaped the way it is.
Operations¶
- Testing - how to run the test suites.
- CI/CD - how the platform is built and released.
- Benchmarking - measuring phishing-detection accuracy against labeled datasets.
Links¶
| Resource | Where |
|---|---|
| Source code (all repositories) | codeberg.org/SPOT_Project |
| Container images | hub.docker.com/u/spotproject |
| Python SDK | pypi.org/project/spot-sdk-python |
| TypeScript SDK | npmjs.com/package/spot-sdk-typescript |
| Models library | huggingface.co/spotproject |
Report issues on Codeberg.
About this site¶
The platform, deployment and web UI pages are in the docs/ directory of the spot repository. The SDK's pages are imported from its own repository when the site is built. The site is published at https://spot-project.codeberg.page/documentation/.
License¶
SPOT is published under the Apache License 2.0. See LICENSE.