ua-spectral/botlensArtefatto di ricerca e server MCP che verifica problemi di sicurezza e privacy nei bot Discord di terze parti tramite analisi di recensioni su larga scala, etichettatura LLM e una tassonomia di 31 temi.
Paper: Kofi Ampomah e Tu Le. Measuring Users' Security and Privacy Concerns About Third-Party Community Bots on Discord. Network and Distributed System Security (NDSS) Symposium 2027. https://dx.doi.org/10.14722/ndss.2027.230535
Revisori dell'artefatto: iniziate da
ARTIFACT-EVALUATION.md. Mappa ogni affermazione del paper al comando esatto che la riproduce, elenca gli output e i tempi di esecuzione attesi e indica quali componenti sono fuori ambito.
Questo repository contiene il codice sorgente della pipeline BotLens, che analizza le problematiche di sicurezza e privacy (S&P) nei bot di comunità di terze parti su Discord attraverso l'analisi di recensioni su larga scala e l'auditing dei metadati. La pipeline elabora 183.142 recensioni utente relative a 23.102 bot raccolti da Top.gg, identifica 8.832 recensioni come rilevanti per S&P — una resa osservata della pipeline del 4,82% — e le mappa su una tassonomia S&P di 31 temi.
BotLens/
├── README.md # This file
├── ARTIFACT-EVALUATION.md # Claim → command → expected output
├── LICENSE # See License below
├── CITATION.cff # How to cite (also used by Zenodo)
├── botlens-ndss-data.zip # The data; unpack to data/ (see Data below)
├── requirements-lock.txt # Exact versions used for the paper
├── requirements.txt # Looser version bounds
│
├── config/ # Pipeline configuration
│ ├── __init__.py
│ ├── settings.py # Paths, model params, thresholds
│ └── taxonomy.py # 31-theme S&P taxonomy (single source of truth)
│
├── scrapers/ # Data collection scripts
│ ├── topgg_metadata_scraper.py # Bot metadata scraper (Top.gg pages)
│ ├── topgg_reviews_scraper.py # Bot review scraper (Top.gg reviews)
│ └── discord_server_scanner.py # Server bot scanner — OUT OF SCOPE, see below
│
├── scripts/ # Pipeline stages + analysis
│ ├── stage0_preprocess.py # Merge, clean, detect language, translate
│ ├── stage1_llm_labeling.py # Binary S&P classification via Ollama
│ ├── stage1b_active_learning.py # Active learning loop
│ ├── stage2_prepare_data.py # Train/val/test splits with balancing
│ ├── stage3_finetune_deberta.py # Fine-tune DeBERTa-v3-large classifier
│ ├── stage4_classify_all.py # Classify all 183K reviews
│ ├── stage5_theme_assignment.py # Assign 31-theme taxonomy themes
│ ├── stage6_emotion_classification.py # GoEmotions → Ekman-style groups
│ ├── stage7_analysis.py # Sec. IV-A: SPRR, TPR, per-tag/per-bot tables
│ ├── stage8_visualizations.py # Figs. 2–9
│ ├── rq3_permissions_metadata.py # RQ3 (Sec. IV-D): statistics + Figs. 10–14, 18
│ ├── language_affective_analysis.py # Appendix B: Fig. 17
│ ├── experiment_labeling_pct.py # Labeling-budget experiment (10–45%)
│ ├── create_irr_sheets.py # Inter-rater reliability labeling sheets
│ ├── compute_kappa.py # Cohen's kappa (Sec. III-C3)
│ ├── check_langs.py # Language distribution (Table IV; needs raw crawl)
│ └── prep_30pct_for_al.py # Prepare labels for active learning
│
├── tests/
│ └── test_smoke.py # Fast integrity checks, no data required
│
└── mcp_server/ # BotLens MCP server (Sec. V)
├── server.py # The six tools of Sec. V-B2 (+ internal helpers)
├── example_client.py # MCP SDK client reproducing Use Cases 1 and 2
└── benchmark_latency.py # Sec. V-D latency session
Ogni figura scritta dagli script è nominata in base al numero di figura del paper
(figures/fig02_sprr_over_time.png è la Fig. 2, e così via). Gli script producono
esattamente le figure del paper: Figg. 2–14, 17 e 18. La Fig. 1 è lo schema
della pipeline e le Figg. 15–16 sono screenshot dell'interfaccia del report di BotLens.
L'artifact è rilasciato su https://github.com/ua-spectral/BotLens. Ogni release GitHub è archiviata permanentemente su Zenodo con un DOI; il DOI è indicato nell'appendice dell'artifact del paper e nella pagina delle release del repository.
I dati sono distribuiti nel repository come botlens-ndss-data.zip (41 MB; un file
si scompatta a 515 MB, oltre il limite per file di GitHub). Scompattalo una volta, nella
radice del repository:
python -m zipfile -e botlens-ndss-data.zip .
Questo crea data/ accanto a config/; non serve scaricare nient'altro. La struttura è:
BotLens/
└── data/
├── processed/
│ ├── all_reviews_classified.csv # 183,142 rows — required by the MCP server
│ ├── privacy_reviews_full.csv # 8,832 S&P reviews w/ themes + affect
│ ├── bot_metadata_cleaned.csv # 23,102 bots (Table I, MCP fallback)
│ ├── train.csv / val.csv / test.csv
│ └── label_map.json
├── results/ # Tables behind the paper's numbers
├── reference_figures/ # Our output of every generated figure
└── irr/ # Annotator workbooks (Sec. III-C3)
Verifica l'integrità con sha256sum -c SHA256SUMS.txt dall'interno di data/.
data/README.md descrive ogni file.
| Fase | Script | Descrizione | Output principale |
|---|---|---|---|
| 0 | stage0_preprocess.py | Unione recensioni + metadati, rilevamento della lingua, Argos Translate | data/raw/reviews.csv |
| 1 | stage1_llm_labeling.py | Classificazione binaria S&P con Ollama/Llama 3 8B | phase1_binary_labels.csv |
| 1b | stage1b_active_learning.py | Campionamento per incertezza + etichette a maggioranza | Set di addestramento migliorato |
| 2 | stage2_prepare_data.py | Filtro per confidenza, sottocampionamento 5:1, split stratificati | train/val/test.csv |
| 3 | stage3_finetune_deberta.py | Fine-tuning di DeBERTa-v3-large (F1 = 0.938 al 30% di etichettatura) | best_model/ |
| 4 | stage4_classify_all.py | Inferenza batch su tutte le 183.142 recensioni | all_reviews_classified.csv |
| 5 | stage5_theme_assignment.py | Ollama assegna i temi della tassonomia a 31 temi | privacy_reviews_themed.csv |
| 6 | stage6_emotion_classification.py | GoEmotions (RoBERTa) → 8 gruppi di affetto | privacy_reviews_full.csv |
| 7 | stage7_analysis.py | SPRR, TPR, SPRR per tag e per bot, affetto per tema | data/results/analysis_summary.json |
| 8 | stage8_visualizations.py | Figg. 2–9, inclusa la tendenza OLS della Fig. 2 (R² = 0.35) | figures/fig02_* … fig09_* |
unassigned.La tassonomia S&P a 31 temi (Tabella V dell'articolo) comprende 20 temi ereditati da
Akgul et al. (USENIX Security 2024) e 11 temi sviluppati induttivamente in questo
studio — 2 temi aggiuntivi di Security & Safety e 9 temi specifici di Discord.
config/taxonomy.py è l'unica fonte di verità; stage8_visualizations.py
ne deriva i propri raggruppamenti.