pranavstormer17/AcoustiGuard
GitHub: pranavstormer17/AcoustiGuard
基于自适应 1/f 粉红噪声掩蔽技术防御物理键盘声学侧信道攻击的概念验证与评估框架，覆盖从数据采集、噪声注入到多模型对抗评估和实时演示的完整流水线。
Stars: 0 | Forks: 0
# AcoustiGuard：声学侧信道攻击防御
AcoustiGuard 是一个受控的概念验证项目，旨在针对物理键盘的声学侧信道攻击（ASCA）提供一种响应式、与硬件无关的防御机制。本仓库演示了如何通过动态缩放的 $1/f$ 粉红噪声掩蔽，在数学上削弱最先进神经架构的特征提取能力。
本项目从零开始构建，以定制的单会话数据集为基础。为了捕捉单个按键的精确瞬态声学特征，我们单独记录了 52 个特定物理键（包括字母数字键、修饰键和系统键）。此数据收集工作在两种截然不同的声学环境中进行：一是受控、安静的“Home”环境，用于建立高保真基线；二是“Classroom”环境，用于模拟现实世界的环境噪声和声学域偏移。该数据集原生包含 Zipfian 分布，反映了英语按键的自然频率，从而确保评估器不会因猜测高概率按键而人为夸大准确率。
标准的 ASCA 文献通常将声学数据归一化为有损的 8 位 `.png` 图像，与此不同，AcoustiGuard 严格将所有音频作为未压缩的 `Float32` 张量进行处理。这确保了神经评估器基于绝对的声学物理特性（范围从 -80 dB 到 0 dB）运行，而不是基于视觉压缩伪影。在掩蔽阶段，$1/f$ 粉红噪声在数学上被精确缩放至环境 RMS 噪声底的 $2.5\times$，然后再与按键瞬态混合。混合后应用线性边界缩放，以防止数字削波，同时严格保留波形几何结构。
该防御措施的有效性以纯卷积架构（EfficientNet-V2-S）为基准进行了测试，并进一步针对混合注意力模型和纯 Transformer 模型进行了探索性沙盒分析。
**关于泛化能力的说明：** 本仓库代表了一个基础原型。当前的评估依赖于在特定笔记本电脑机箱和麦克风阵列上录制的单会话数据集。尽管攻击者模型的数学崩塌在这种受限环境中是绝对的，但要建立真正的跨会话、多设备泛化能力，仍需进行大量未来的工作。
## 项目结构与输出
本仓库在执行期间会自动将所有生成的工件路由到专用目录中：
- `figures/`：混淆矩阵（`conf_matrix_*.png`）和单次打击视觉证明（`defense_proof.png`）。
- `results/`：评估指标（`results_*.json`），包括 F1 分数、置信区间和等级分数。
- `logs/`：执行遥测（`pipeline_log_*.json` 和 `.log`），用于延迟跟踪和调试。
- `models/`：神经网络权重检查点（`.pth`）、映射数据以及用于比较模型训练（ViT、CoAtNet）的 `sandbox/` 目录。
## 完整流水线执行指南
以下命令记录了从头到尾复现此论文实验所需的确切步骤。
**前置条件：**
* **操作系统：** 严格针对 Linux（例如 CachyOS、Arch、Ubuntu）进行了优化。不支持 macOS。
* **硬件：** 支持 CUDA 加速的 NVIDIA GPU。
* **网络：** 步骤 1（下载 PyTorch/CUDA 二进制文件）和步骤 5（下载 Hugging Face 架构权重）需要稳定的互联网连接。
## 外部资产：数据集与预训练模型
由于 GitHub 的文件大小限制，庞大的声学数据集和神经网络权重托管在外部。
* **[下载原始声学数据集](https://drive.google.com/file/d/19rVKCxq-1CxT2PDhDqhNO6jS8eLtsfjc/view?usp=drive_link)**：此压缩包包含 `data/` 目录结构。将此文件直接解压到本仓库的根目录中。它会自动合并并将原始录音放入 `data/raw/home/` 和 `data/raw/classroom/` 中。
* **[下载预训练模型权重](https://drive.google.com/file/d/1HEWiOCCEMl-bKJe0nAwAI2oIbnVNLbR9/view?usp=drive_link)**：此压缩包包含 `models/` 目录结构。将此文件直接解压到本仓库的根目录中。它会自动用 `efficientnet.pth` 文件填充主目录，并用 `vit` 和 `coatnet` 权重填充 `models/sandbox/` 目录。
## 实时演示视频
[](https://www.youtube.com/watch?v=0DB4WZswFkQ)
### 步骤 1：环境与依赖项
首先，验证您当前的活动 shell，创建一个新的 Python 虚拟环境，并安装所需的依赖项。
```
# 1. 确定你的活动 Shell (输出 /bin/bash, /usr/bin/zsh 或 /usr/bin/fish)
echo $SHELL
# 2. 创建 Python 虚拟环境
python3 -m venv venv
# 3. 根据你的 Shell 激活环境:
# ---> 如果使用标准 Linux Bash/Zsh:
source venv/bin/activate
# ---> 如果使用 Fish Shell:
source venv/bin/activate.fish
# 4. 安装所有必需的机器学习和信号处理框架
pip install -r requirements.txt
# 5. 验证你的 GPU 已被检测且 CUDA 已启用
python gpu.py
```
### 步骤 2：“干净状态”初始化
*首次运行者的注意事项：强烈建议执行此步骤以保证无菌环境。它只会严格清除生成的数组和日志，而不会触及 `data/raw/` 源音频。*
```
# 清除已处理的 Float32 数组
rm -rf data/processed/home/* 2>/dev/null
rm -rf data/processed/classroom/* 2>/dev/null
rm -rf data/processed/home_masked/* 2>/dev/null
rm -rf data/processed/masked/* 2>/dev/null
# 清除动态生成的粉红噪声音频
rm -f data/raw/classroom_masked/*.wav 2>/dev/null
rm -f data/raw/home_masked/*.wav 2>/dev/null
# 清除旧版模型、日志和图表
rm -f models/*.pth 2>/dev/null
rm -f models/sandbox/*.pth 2>/dev/null
rm -f logs/* 2>/dev/null
rm -f results/* 2>/dev/null
rm -f figures/* 2>/dev/null
echo "Clean slate confirmed. Environment ready for execution."
```
### 步骤 3：验证原始数据完整性
在预处理之前，验证原始音频目录中是否存在这 52 个物理键类。
```
echo "=== HOME RAW AUDIO ===" && ls data/raw/home/ | wc -l
echo "=== CLASSROOM RAW AUDIO ===" && ls data/raw/classroom/ | wc -l
```
### 步骤 4：核心自动流水线
针对两种声学环境，执行主要的训练、掩蔽和评估流水线。
**选项 A：如果您使用的是 Fish Shell（原生脚本）**
```
# 1. 执行 Classroom Pipeline (Baseline & Masked)
./run_pipeline.fish
# 2. 执行 Home Pipeline (Baseline & Masked)
./run_home_pipeline.fish
```
**选项 B：如果您使用的是标准 Linux Bash/Zsh（手动执行）**
*（由于自动化脚本使用 Fish 语法，Bash 用户可以使用原生的 `sed` 命令更新配置来顺序复现流水线。）*
```
# 1. 执行 Classroom Pipeline
sed -i 's/^MODE = .*/MODE = "classroom"/' config.py
python -m src.preprocess_data && python sanity_check.py && python -m src.train_models && python -m src.evaluate_models
python -m src.masker
sed -i 's/^MODE = .*/MODE = "masked"/' config.py
python -m src.preprocess_data && python sanity_check.py && python -m src.evaluate_models
# 2. 执行 Home Pipeline
sed -i 's/^MODE = .*/MODE = "home"/' config.py
python -m src.preprocess_data && python sanity_check.py && python -m src.train_models && python -m src.evaluate_models
python -m src.masker
sed -i 's/^MODE = .*/MODE = "home_masked"/' config.py
python -m src.preprocess_data && python sanity_check.py && python -m src.evaluate_models
```
### 步骤 5：比较架构沙盒
训练并评估混合注意力模型（CoAtNet-0）和纯 Transformer（ViT-B/16），将它们与基线卷积进行比较。
```
python -m src.train_coatnet_sandbox
python -m src.train_vit_sandbox
python -m src.evaluate_all
```
### 步骤 6：实时硬件演示
通过 PipeWire/ALSA 后端原生执行实时声学演示。
```
# 一次性设置：将类别映射同步到训练好的模型索引
python src/generate_mapping.py
# 1. 视觉防御证明 (在 figures/ 目录下生成 defense_proof.png)
python demo_defense_comparison.py
# 2. 实时 ASCA 窃听模拟
python demo_live_attack.py
# (在笔记本电脑键盘上输入目标键，然后按 Ctrl+C 终止流)
```
### 步骤 7：NLP 语义重建
演示使用 SymSpell 算法（最大编辑距离 = 2）将被泄露的按键重建成连贯的英语语法的威胁升级过程。
```
python -m src.nlp_postprocess
```
### 步骤 8：最终结果摘要
打印综合数据摘要，证明攻击者能力的数学崩塌。
```
python3 -c "
import json
with open('results/results_classroom_efficientnet.json') as f: c = json.load(f)
with open('results/results_masked_efficientnet.json') as f: m = json.load(f)
print('\n==========================================')
print('ACOUSTIGUARD FINAL RESULTS SUMMARY')
print('==========================================')
print('\n--- CLASSROOM BASELINE vs MASKED ---')
print(f'Classroom Baseline F1: {c[\"macro_f1\"]*100:.2f}%')
print(f'Classroom Masked F1: {m[\"macro_f1\"]*100:.2f}%')
print(f'Defense Effectiveness: -{(c[\"macro_f1\"]-m[\"macro_f1\"])*100:.2f} percentage points')
print(f'Attack collapsed to near-random chance: {m[\"macro_f1\"]*100:.2f}%')
with open('results/results_home_efficientnet.json') as f: h = json.load(f)
print('\n--- HOME BASELINE ---')
print(f'Home Baseline F1: {h[\"macro_f1\"]*100:.2f}%')
print(f'95% CI: [{h[\"ci_low\"]*100:.2f}%, {h[\"ci_high\"]*100:.2f}%]')
print('==========================================\n')
"
```
标签：1/f噪声, ASCA, CoAtNet, EfficientNet, meg, Vectored Exception Handling, ViT, 人机交互安全, 侧信道攻击, 信号处理, 信息安全, 凭据扫描, 击键声识别, 声学侧信道攻击, 声学特征提取, 声音掩蔽, 对抗样本, 数据集构建, 深度学习, 物理键盘, 神经网络, 粉红噪声, 网络安全, 网络安全, 逆向工具, 防御机制, 防御概念验证, 隐私保护, 隐私保护, 音频处理