Attacco Black-Hole sul recupero da database vettoriali

Questo repository contiene l'implementazione che accompagna il paper Black-Hole Attack from Embedding Space Defects. L'attacco Black-Hole sfrutta un difetto geometrico negli spazi di embedding ad alta dimensionalità—la hubness guidata dalla centralità—per avvelenare i database vettoriali: un piccolo numero di vettori malevoli iniettati vicino ai centroidi dei cluster diventano i vicini più prossimi per una grande frazione delle query degli utenti, senza richiedere alcuna conoscenza di tali query.

Requisiti

• Python ≥ 3.10
• FAISS (GPU consigliata: faiss-gpu; CPU: faiss-cpu)
• NumPy, Pandas, PyArrow (per I/O parquet)
• scikit-learn, tqdm
• PyTorch e Transformers (necessari solo per scripts/encode_*.py; la pipeline dell'attacco stessa non importa torch)

Installa le dipendenze principali:

pip install numpy pandas pyarrow scikit-learn tqdm faiss-gpu

Avvio rapido

1. Scarica e prepara i dati

# Download BEIR datasets
bash scripts/download_data.sh

# Encode to vectors + build FAISS indexes
bash scripts/process_data.sh

Modifica gli array MODELS e DATASETS in ciascuno script per selezionare modelli o dataset specifici.

2. Esegui un attacco di base

# Full-Export Attack on HotpotQA with Contriever
python run.py --model contriever --src hotpotqa

Questo esegue l'intera pipeline: caricamento dei vettori → clustering → generazione di vettori avversariali → iniezione → costruzione dell'indice avvelenato → valutazione di MO@10, ASR, FPR.

3. Argomenti principali

Flag	Predefinito	Descrizione
--model / --src	contriever / hotpotqa	Modello di embedding e dataset di origine
--mode	default	default (stesso dataset) o transfer (cross-dataset)
--preprocess	default	default, query_trans o multi_query_transfer
--cluster	kmeans	kmeans, minibatch_kmeans, faiss_gpu
--num-copies / --epsilon	10 / 0.001	Numero di copie perturbate per centroide; entità della perturbazione
--eval-k / --sample-queries	10 / 3000	Valutazione top‑k; numero di query campionate
--eval-index-types	FlatIP	Tipi di indice da valutare: FlatIP, HNSW, IVF, IVFPQ
--eval-runners	evaluate	Passaggi di valutazione: evaluate, evaluate_recall, evaluate_defense, evaluate_defense_performance_loss, evaluate_mitigation_defense, evaluate_mitigation_performance_loss
--result-subdir	auto	Sottodirectory sotto data/result/ per il JSON di output

Percorsi di attacco

I quattro percorsi di attacco descritti nel paper corrispondono alle seguenti invocazioni:

Percorso	Comando
(1) Esportazione completa del database	python run.py --mode default --preprocess default
(2) Esportazione parziale del database	Esportare esternamente una frazione dei vettori prima del clustering; il resto della pipeline è identico a (1)
(3) Attacco con dataset surrogato	python run.py --mode transfer --preprocess multi_query_transfer --victim <dataset>
(4) Avvelenamento di dataset pubblici pre‑embedded	Modificare i file .npy di un dataset pre‑embedded e ricaricarlo su HuggingFace

Per (3), l'attaccante costruisce vettori malevoli dalle query di tutti gli altri dataset e li inietta nella vittima. I file .npy delle query per i dataset di origine surrogati devono essere presenti in data/vector/.

Valutazione delle difese

Per eseguire la difesa basata sul rilevamento:

python run.py --model contriever --src hotpotqa \
    --eval-runners evaluate_defense evaluate_defense_performance_loss

Per la difesa basata sulla mitigazione (uno o più metodi):

python run.py --model contriever --src hotpotqa \
    --eval-runners evaluate_mitigation_defense evaluate_mitigation_performance_loss \
    --mitigation-methods cl2 zn nohub

Demo

demo/ contiene un esempio minimale autonomo che costruisce una piccola knowledge base da un dataset BEIR, la codifica, inietta vettori malevoli e misura l'impatto a livello di retrieval. Utilizza il proprio requirements.txt e non dipende da src/. Consultare demo/src/main.py per i dettagli della CLI.

Dataset e modelli

config.json definisce i modelli supportati (contriever, bge, gte) e i dataset (14 benchmark BEIR). Per aggiungere un nuovo modello, estendere config.json e assicurarsi che i file vettoriali .npy esistano in data/vector/<model>_<dataset>.npy.

Citazione

@misc{li2026trustvectorsvectordatabase,
      title={Can You Trust the Vectors in Your Vector Database? Black-Hole Attack from Embedding Space Defects}, 
      author={Hanxi Li and Jianan Zhou and Jiale Lao and Yibo Wang and Zhengmao Ye and Yang Cao and Junfen Wang and Mingjie Tang},
      year={2026},
      eprint={2604.05480},
      archivePrefix={arXiv},
      primaryClass={cs.CR},
      url={https://arxiv.org/abs/2604.05480}, 
}