laugiov/scambusterLaboratorio di ricerca per l'engagement difensivo e il threat intelligence. Converte le email di truffa in arrivo in IOC utilizzabili attraverso un engagement AI controllato e guidato da policy. Architettura LLM multi-agente con selezione adattiva delle strategie.
Piattaforma automatizzata di honeypot per scambaiting e threat intelligence
Sito web: scambuster.ai · Demo live: demo.scambuster.ai
Comunità: GitHub Discussions | Segnala problemi di sicurezza
Guidato dalla community: valutalo tu stesso -- esegui la demo, leggi il codice, fatti la tua opinione.
Prova la demo (nessuna installazione): demo.scambuster.ai -- accesso:
[email protected]/Un1que$trongPassword2024(stesso dataset della demo localemake demo-up).Installazione locale in 5 minuti: Guida rapida --
cp .env.dist .env-> modifica 4 valori ->make quickstart-> fatto.Esegui la demo localmente (nessuna chiave API necessaria): Guida alla demo --
make demo-up-> http://localhost:3002
ScamBuster trasforma le email di truffa in arrivo in threat intelligence utilizzabile attraverso engagement controllato e guidato da policy. Estrae IOC, profila gli attori delle minacce, misura l'efficacia dell'engagement ed esporta l'intelligence nei formati STIX 2.1 / MISP / TAXII -- tutto protetto da safety gate, consapevole dei costi e completamente auditabile.
Le truffe via email operano su scala massiccia. La maggior parte dei programmi di sicurezza blocca e dimentica: il messaggio viene rimosso, ma l'infrastruttura dell'attaccante, i canali finanziari e i segnali delle campagne rimangono inosservati. C'è poca attribuzione, visibilità limitata sulle TTP in evoluzione e nessuna intelligence generata dall'interazione reale con gli attori delle minacce.
ScamBuster esplora questa lacuna convertendo le email di truffa in intelligence delle minacce misurabile, in modo sicuro e su larga scala. Vedi Dichiarazione del problema.
Ogni risposta passa attraverso simulazione del ritardo umano (cadenza configurabile, tempi randomizzati, consapevolezza dell'ora del giorno) per imitare pattern di risposta realistici.
ScamBuster usa epsilon-greedy con esplorazione UCB1 per apprendere quale persona massimizza il rendimento dell'intelligence per tipo di truffa. L'efficacia della persona viene appresa per categoria dai risultati reali, piuttosto che fissata a mano.
I truffatori operano in molte lingue, quindi anche ScamBuster lo fa. Le regole di rilevamento (minacce, impersonificazione dell'autorità, segnali di urgenza), i system prompt delle persona e le linee guida delle strategie includono contenuti non in inglese di proposito — sono dati operativi che permettono all'honeypot di interagire con i truffatori nella loro lingua. Il codice stesso (identificatori, commenti, log) è in inglese; le stringhe non inglesi che vedi nei dati seed e nei prompt sono intenzionali, non codice non tradotto. Aggiungi o adatta le lingue modificando i dati seed delle persona e del rilevamento — nessuna modifica al codice.
Ogni conversazione produce IOC deduplicati (email, domini, IP, IBAN, wallet crypto, telefoni, username Telegram, hash di file...) arricchiti con contesto semantico: il ruolo di ogni IOC nella narrazione della truffa (destinazione di pagamento, esca di phishing, canale di contatto), tipo di stimolo, punteggio di urgenza e un estratto di contesto senza PII.
Ogni conversazione produce un threat actor STIX 2.1 con profilazione comportamentale:```json { "type": "threat-actor", "name": "ScamBuster Actor - INVESTMENT #02114290", "sophistication": "minimal", "goals": ["financial-theft"], "primary_motivation": "personal-gain", "threat_actor_types": ["criminal"], "description": "Criminal actor operating investment scam." }
Threat actors include MITRE ATT&CK technique mapping, `indicates` relationships to all IOCs, and a custom `x_scambuster_actor` extension with engagement metrics. Bundles are validated for import into **OpenCTI**.
### Threat-Actor Intelligence
First-party intelligence *about the actor*, built from the honeypot's own interactions (no external enrichment) — see the [Threat-Actor Profiling guide](https://github.com/laugiov/scambuster/blob/HEAD/docs/21_threat_actor_profiling.md):
- **Psychological profiling** — a durable per-actor fingerprint: dominant + secondary **Cialdini influence levers** (Authority, Urgency, Scarcity, Secrecy, Reciprocity, Liking, SocialProof), a behavioural narrative, escalation pattern, and victim targeting. Generated offline, surfaced on the cluster detail page, the API, and a `x_scambuster_actor_psych` STIX extension.
- **Fuzzy actor clustering** — conversations link on *canonically equivalent* financial/contact IOCs (ETH wallet case, IBAN/card/phone separators), not just identical values — while genuinely different values (one digit apart) stay separate.
- **Analyst feedback loop** — analysts mark an IOC confirmed / false-positive (`POST /iocs/{id}/feedback`); the verdict overrides export confidence (confirmed → high, false-positive → near-zero).
- **Explicit STIX evidence** — each indicator carries a `sighting` SDO (count, first/last seen, where-sighted), and standard observables also emit `observed-data` + Cyber Observable Objects.
### Scammer TTP Intelligence
ScamBuster also tags the **scammer's tactics, techniques and procedures (TTPs)** on inbound
messages against a closed, 27-entry taxonomy spanning a six-phase scam kill chain (hook,
trust-building, payment-request, escalation, channel-switch, exit). A stimulus is something
**our persona** does; a TTP is something **the scammer** does — the two are kept strictly
separate, and the analytical value is the crossing **stimulus → TTP → IOC**.
- **Inbound-only LLM tagging** — our own replies are never analysed. Each observation carries
a confidence, a `confirmed` / `review` status (below a configurable threshold, nothing is
silently dropped), a verbatim evidence quote (**stored internally only**, never in any API
response or export — consumers see character offsets), and model/prompt provenance.
- **Read APIs** — `GET /conversations/{id}/ttps`, `/clusters/{id}/ttps`, `/ttps`,
`/ttps/cluster-matrix`, `/ttps/{code}/iocs`, `/iocs/{id}/ttps`; a manual
`POST /communication/message/{msgId}/extract-ttps` remains as an ops/test surface.
- **Analyst UI** — a cluster TTP panel, a per-conversation stimulus → TTP → IOC elicitation
timeline with neutral stimulus/causality chips, and a tabbed **TTP Explorer**
(taxonomy with per-TTP detail pages, phase analytics with an 8-week trend, the
cluster-overlap playbook matrix, and a read-only review queue with on-demand,
masked-by-default evidence).
- **CTI export** — one stable STIX 2.1 attack-pattern per TTP (with `kill_chain_phases`),
`threat-actor uses attack-pattern` relationships and sightings from cluster aggregates, and
`scambuster:ttp` + MITRE ATT&CK galaxy MISP tags. Evidence text is never exported.
- **Operator tooling** — `scambuster:ttp:backfill` (historical extraction, preview by default,
budget-capped, idempotent) and `scambuster:ttp:audit-sample` (random-sample CSV for a manual
precision audit — the only path by which evidence text leaves the database).
- The whole module sits behind the **`TTP_EXTRACTION_ENABLED`** feature flag (default on) and
fails safe: disabled or failing, it never affects ingestion, IOC extraction or replies.
> **Note on metrics.** The TTP module was added **after** the nine-month production window
> covered by the white paper, so **no published metric applies to it**. Its extraction
> precision is to be established by the manual audit (`scambuster:ttp:audit-sample`); no
> precision figure is claimed until that audit exists.
### Automated Intelligence Feeds
- **STIX 2.1 export** per conversation (indicators + threat-actor + sightings + observed-data + attack-pattern + relationships)
- **TAXII 2.1 server** with delta sync -- IOC indicators enriched with threat-actor attribution
- **MISP Event JSON** export
- **SIEM export** in CEF, ECS or JSON, over file or syslog
Standards, not per-vendor connectors: any platform that consumes STIX 2.1, TAXII
2.1, MISP Event JSON or CEF/ECS syslog can read these. **Verified end to end
against OpenCTI** -- see the [OpenCTI Integration guide](https://github.com/laugiov/scambuster/blob/HEAD/docs/11_opencti_integration.md)
for what lands where. The other paths follow the same standards but have not been
exercised against a live instance.
See [TAXII Server Guide](https://github.com/laugiov/scambuster/blob/HEAD/docs/16_taxii_server.md) and [API Reference](https://github.com/laugiov/scambuster/blob/HEAD/docs/12_api_quick_reference.md).
---
## Tech Stack
| Layer | Technology |
|-------|------------|
| **Backend** | PHP 8.3, Symfony 7.4, DDD architecture |
| **Database** | PostgreSQL 15, Redis 7 |
| **Frontend** | React 19, TypeScript, TailwindCSS, i18n (EN/FR) |
| **LLM** | Multi-provider: OpenAI, Anthropic, Ollama (full local), Mock (dev) |
| **Orchestration** | n8n (self-hosted) |
| **Secrets** | Environment variables / Docker secrets |
| **Monitoring** | Prometheus metrics, LLM cost tracking, pipeline tracing |
| **Infrastructure** | Docker Compose, GitHub Actions CI |
| **SIEM** | CEF, ECS, JSON -- pluggable connector |
> **Data sovereignty**: Deploy with `LLM_PROVIDER=ollama` for 100% on-premise processing. No data leaves your infrastructure.
---
## Quick Start```bash
git clone https://github.com/laugiov/scambuster.git
cd scambuster
cp .env.dist .env # then EDIT it (see below) BEFORE the next step for real use
make quickstart # one command: build, start, migrate, seed, JWT keys, n8n
make test # optional: run the test suite
Configura
.envprima dimake quickstart. L'installazione registra la tua casella honeypot e crea la credenziale IMAP di n8n da.envdurante l'installazione. Se eseguimake quickstartcon i segnaposto predefiniti, si avvia in modalità demo — la cattura delle email in tempo reale e le risposte non funzioneranno finché non compiliHONEYPOT_IMAP_*,MAILER_DSNeLLM_API_KEYe non lo riesegui. (make quickstartti avvisa se rileva segnaposto.)
make quickstart compila e avvia l'intero stack, crea e migra il
database, inserisce fixture e dati demo, genera le chiavi JWT e configura
n8n — nessun passaggio manuale. Consulta QUICKSTART.md per la guida completa.
Due modi per distribuire — fallo manualmente con QUICKSTART.md, oppure affidalo a un agente IA (Claude Code, Cursor, Copilot, …) con AI_DEPLOYMENT.md, un runbook indipendente dallo strumento con la gestione dei segreti e le protezioni di cui un agente ha bisogno.
In produzione?
make quickstartè il percorso locale/per sviluppatori (server di sviluppo, dati demo). Per una distribuzione reale usa l'immagine di produzione autonoma e il file compose: Runbook di distribuzione in produzione (docker compose -f docker-compose.prod.yml up -d --build— nginx + php-fpm, nessun dato demo, migrazioni eseguite automaticamente). Un agente può seguire la sezione Produzione di AI_DEPLOYMENT.md.
Prima di un uso reale (non demo), modifica questi 4 in .env (gli stessi 4 indicati dal
blocco >>> EDIT THESE 4 FIRST <<< all'inizio di .env.dist, e che
make quickstart verifica per i segnaposto):
Per rafforzare la sicurezza in produzione, cambia anche POSTGRES_PASSWORD (e DATABASE_URL di
conseguenza) e JWT_PASSPHRASE (openssl rand -hex 32) — consulta il
runbook di distribuzione in produzione.
Provider LLM (si cambia con una variabile d'ambiente):
Credenziali predefinite (create dalle fixture):
| Password | Ruolo | |
|---|---|---|
[email protected] | Un1que$trongPassword2024 | ROLE_USER |
[email protected] | Un1que$trongPassword2024 | ROLE_ADMIN |
Guida completa all'installazione: Getting Started
scambuster/ backend-symfony/ # PHP/Symfony backend (DDD) src/ Domain/ # Entities, value objects, enums, events Application/ # Handlers, services, orchestrators Infrastructure/ # Doctrine repos, external APIs, listeners UI/Http/ # Controllers (single __invoke) tests/ # PHPUnit (unit, integration, E2E) frontend-react/ # React 19 dashboard n8n/ # Workflow definitions infra/ # Docker configs docs/ # Documentation guides
---
## Sicurezza ed etica
ScamBuster è uno **strumento di ricerca difensivo**, non un'arma offensiva.
- **Solo in entrata**: interagisce solo dopo che il truffatore ha avviato il contatto
- **Nessun accesso non autorizzato**: non accede mai ai sistemi dell'attaccante
- **Filtro dei contenuti**: PolicyGuard blocca minacce, contenuti illegali e dati personali reali
- **Limitazione della frequenza**: limiti rigidi su conversazioni, messaggi e chiamate LLM
- **Interruttore di emergenza**: arresto immediato a livello di workflow, API, database o infrastruttura
- **GDPR**: minimizzazione dei dati, policy di conservazione, crittografia a riposo
> **L'uso responsabile è responsabilità dell'operatore.** Verifica che la tua distribuzione sia legale nel luogo in cui operi, mantienila solo in entrata e non usarla mai per avviare contatti, prendere di mira individui, molestare o fare doxxing. Leggi la **[Dichiarazione di esclusione di responsabilità e uso responsabile](https://github.com/laugiov/scambuster/blob/HEAD/DISCLAIMER.md)** prima della distribuzione.
Vedi [Sicurezza e protezioni](https://github.com/laugiov/scambuster/blob/HEAD/docs/04_security_guardrails.md), [SECURITY.md](https://github.com/laugiov/scambuster/blob/HEAD/SECURITY.md) e [DISCLAIMER.md](https://github.com/laugiov/scambuster/blob/HEAD/DISCLAIMER.md).
---
## Stato del progetto
| Fase | Stato |
|-------|--------|
| Architettura LLM multi-agente | Completa |
| Coinvolgimento adattivo (epsilon-greedy) | Completo |
| Scalabilità, dashboard e osservabilità | Completa |
| Garanzia di qualità e validazione | Completa |
| Arricchimento contestuale avanzato degli IOC | Completo |
| Esportazione degli attori delle minacce in STIX e integrazione OpenCTI (sightings + observed-data) | Completa |
| Clustering degli attori delle minacce (Union-Find su IOC finanziari, corrispondenza canonica fuzzy) | Completo |
| Profilazione psicologica degli attori delle minacce (leve di Cialdini) | Completa |
| Ciclo di feedback IOC degli analisti (confermato / falso positivo → confidenza) | Completo |
| Estrazione e intelligence dei TTP dei truffatori (tassonomia della kill-chain, attack-pattern STIX) | Completa (post-studio — nessuna metrica pubblicata) |
| Thompson Sampling (algoritmo bandit v2) | Pianificato |
Vedi [Roadmap](https://github.com/laugiov/scambuster/blob/HEAD/docs/06_roadmap.md) e [Changelog](https://github.com/laugiov/scambuster/blob/HEAD/CHANGELOG.md).
---
## Documentazione
| Documento | Descrizione |
|----------|-------------|
| [Dichiarazione del problema](https://github.com/laugiov/scambuster/blob/HEAD/docs/01_problem_statement.md) | Il problema delle truffe via email |
| [Proposta di valore](https://github.com/laugiov/scambuster/blob/HEAD/docs/02_value_proposition.md) | Elementi di differenziazione tecnica |
| [Architettura](https://github.com/laugiov/scambuster/blob/HEAD/docs/03_high_level_architecture.md) | Progettazione del sistema |
| [Sicurezza ed etica](https://github.com/laugiov/scambuster/blob/HEAD/docs/04_security_guardrails.md) | Principi difensivi, GDPR |
| [Valutazione](https://github.com/laugiov/scambuster/blob/HEAD/docs/05_evaluation_methodology.md) | Metriche e validazione |
| [Roadmap](https://github.com/laugiov/scambuster/blob/HEAD/docs/06_roadmap.md) | Cronologia e traguardi |
| [FAQ](https://github.com/laugiov/scambuster/blob/HEAD/docs/07_faq.md) | Domande frequenti |
| [Per iniziare](https://github.com/laugiov/scambuster/blob/HEAD/docs/08_getting_started.md) | Tutorial completo di configurazione |
| [Distribuzione in produzione](https://github.com/laugiov/scambuster/blob/HEAD/docs/runbooks/production-deployment.md) | Immagine di produzione auto-contenuta + compose, testata end-to-end |
| [Riferimento API](https://github.com/laugiov/scambuster/blob/HEAD/docs/12_api_quick_reference.md) | Tutti gli endpoint |
| [Server TAXII](https://github.com/laugiov/scambuster/blob/HEAD/docs/16_taxii_server.md) | Guida al feed CTI automatizzato |
| [Integrazione OpenCTI](https://github.com/laugiov/scambuster/blob/HEAD/docs/11_opencti_integration.md) | Collega OpenCTI al feed: cosa finisce dove e le insidie |
| [Integrazione SIEM](https://github.com/laugiov/scambuster/blob/HEAD/docs/15_siem_integration.md) | Connettore SIEM aziendale |
| [Integrazione MISP](https://github.com/laugiov/scambuster/blob/HEAD/docs/13_misp_integration.md) | Mappatura dell'esportazione MISP |
| [SSO aziendale](https://github.com/laugiov/scambuster/blob/HEAD/docs/20_enterprise_sso.md) | Single sign-on OIDC |
| [Catalogo delle metriche](https://github.com/laugiov/scambuster/blob/HEAD/docs/22_metrics_catalog.md) | Definizioni delle metriche e provenienza |
| [Validazione dei dati](https://github.com/laugiov/scambuster/blob/HEAD/docs/18_data_validation.md) | Comandi di audit per la qualità di IOC, cluster e classificazione |
| [Audit della qualità dei dati](https://github.com/laugiov/scambuster/blob/HEAD/docs/19_data_quality_audit.md) | Auditor di qualità LLM, audit approfondito manuale e guida alla correzione |
| [Profilazione degli attori delle minacce](https://github.com/laugiov/scambuster/blob/HEAD/docs/21_threat_actor_profiling.md) | Impronta psicologica e comportamentale per attore (leve di Cialdini) |
| [Leggere la schermata dell'attore delle minacce](https://github.com/laugiov/scambuster/blob/HEAD/docs/23_reading_the_threat_actor_screen.md) | Guida pratica alla pagina Cluster Detail — ogni indicatore spiegato, con spunti di discussione per la demo |
| [Leggere le schermate TTP](https://github.com/laugiov/scambuster/blob/HEAD/docs/26_reading_the_ttp_screens.md) | Guida pratica alle schede di TTP Explorer, alle pagine di dettaglio per TTP, alla coda di revisione e ai chip di causalità della conversazione |
| [Feedback degli analisti](https://github.com/laugiov/scambuster/blob/HEAD/docs/24_analyst_feedback.md) | Verdetti umani di conferma / falso positivo che diventano confidenza autorevole nei feed STIX, TAXII, MISP e CSV |
---
## Licenza
- **Codice**: [Licenza MIT](https://github.com/laugiov/scambuster/blob/HEAD/LICENSE)
- **Documentazione**: CC BY-NC-SA 4.0
- **Dataset** (quando pubblicato): CC BY-NC-SA 4.0
---
## Come contribuire
Vedi [CONTRIBUTING.md](https://github.com/laugiov/scambuster/blob/HEAD/CONTRIBUTING.md) per le linee guida.
---
## Contatti
| | |
|---|---|
| **Sito web** | [scambuster.ai](https://scambuster.ai) |
| **Demo dal vivo** | [demo.scambuster.ai](https://demo.scambuster.ai) |
| **Manutentore** | Laurent Giovannoni |
| **LinkedIn** | [linkedin.com/in/giovannonilaurent](https://linkedin.com/in/giovannonilaurent) |
| **Contesto** | Black Hat USA 2026 |
| **Problemi** | [Problemi su GitHub](https://raw.githubusercontent.com/laugiov/issues) |
| **Sicurezza** | Vedi [SECURITY.md](https://github.com/laugiov/scambuster/blob/HEAD/SECURITY.md) |
---
<p align="center">
<a href="docs/01_problem_statement.md">Per saperne di più</a> •
<a href="docs/03_high_level_architecture.md">Architettura</a> •
<a href="docs/06_roadmap.md">Roadmap</a> •
<a href="docs/07_faq.md">FAQ</a>
</p>
| Agente | Ruolo |
|---|
| ScamClassifier | Classifica le truffe in arrivo (13 tipi di truffa + fallback UNKNOWN) + rileva la lingua |
| IocExtractor | Estrae gli indicatori di minaccia (36 tipi di IOC) con arricchimento contestuale |
| Generator | Crea risposte basate su persona che massimizzano il rendimento dell'intelligence |
| Validator | Garantisce sicurezza e qualità (PolicyGuard + doppia validazione LLM) |
| ConversationDirector | Ragiona sull'intero thread a ogni turno e guida il Generator (tiene traccia delle intelligence già fornite, deduce l'obiettivo, segnala quando fermarsi) |
| Orchestrator | Coordina la pipeline, ottimizza i costi, tiene traccia delle tracce per risposta |
| InjectionDetector | Analisi dell'iniezione di prompt a due livelli (pattern + LLM-as-judge) |
| TtpExtractor | Tagga le tattiche dei truffatori (TTP) sui messaggi in arrivo rispetto a una tassonomia chiusa (solo in ingresso, abilitato da feature flag) |
| Variable | Cosa fare |
|---|
LLM_API_KEY | La tua chiave API OpenAI (oppure mantieni LLM_PROVIDER=mock per una demo senza chiave) |
HONEYPOT_IMAP_USER | La casella di posta honeypot (IMAP — riceve le email truffa) |
HONEYPOT_IMAP_PASSWORD | La relativa password per app (NON la password normale dell'account) |
MAILER_DSN | SMTP per l'invio delle risposte — stessa casella, @ scritto come %40 |
| Provider | LLM_PROVIDER= | Posizione dei dati | Ideale per |
|---|
| OpenAI | openai | Cloud | Qualità migliore (GPT-4o) |
| Anthropic | anthropic | Cloud | Alternativa (Claude) |
| Ollama | ollama | 100% locale | Distribuzione sovrana |
| Mock | mock | Locale | Demo (senza chiave API, senza costi) |