RobertoDeLaCamara/Cognitive-Intrusion-Detection-System
GitHub: RobertoDeLaCamara/Cognitive-Intrusion-Detection-System
基于多机器学习引擎与威胁情报融合的实时网络入侵检测系统，通过加权集成模型对异常流量进行自动化识别与告警。
Stars: 2 | Forks: 1
# 认知网络防御系统
**CNDS** 是一个实时网络入侵检测系统，它将**五个**检测引擎——有监督 ML、无监督异常检测、时序序列建模、基于规则的启发式算法以及**外部威胁情报源**——融合为一个单一的加权集成模型。Scapy 捕获循环将数据包送入并行的特征流水线；告警通过由 SQLite（或 PostgreSQL）支持的 FastAPI REST 接口对外暴露。
## 架构
```
[Network Interface]
│ Scapy packet capture
▼
[PacketProcessor] ── async queue ──► Worker threads (×4)
│
▼
[Dispatcher] ── flow expiry ──► on_flow_complete()
├─ FlowExtractor → 76 CICFlowMeter flow features
├─ HostExtractor → 18 per-IP host features
├─ PayloadAnalyzer → regex pattern matches + 10 numeric payload features
└─ JA3 Extractor → TLS ClientHello fingerprint (hash + raw string)
│
├─► [Supervised Engine] FT-Transformer (preferred, 76 flow features, UNSW-NB15 schema)
│ ↳ falls back to Random Forest if no checkpoint
├─► [Isolation Forest] Novelty score (18 host features)
├─► [LSTM Autoencoder] Sequence score (18 host features)
├─► [Rules Engine] Threshold + pattern + JA3 rules
└─► [Threat Intelligence] External IOC feeds (AbuseIPDB, JA3, MISP)
│
▼
[Ensemble Scorer]
weighted confidence fusion + TI boost
│
┌───────┴────────┐
│ Alert fired │ → MITRE ATT&CK mapping
└───────┬────────┘ → logger + SQLite → FastAPI
│
├─► SIEM (Splunk / Elastic / Syslog-CEF)
└─► Webhook / Telegram notifications
```
### 检测引擎
| 引擎 | 输入 | 模型 | 检测内容 |
|---|---|---|---|
| **有监督模型（首选）** | 76 个 CICFlowMeter 流特征 | FT-Transformer (PyTorch, ~2.4M 参数) — Optuna 调优，在 UNSW-NB15 测试集划分上 F1 macro 为 0.6197 | 10 种攻击类别：Benign, Analysis, Backdoor, DoS, Exploits, Fuzzers, Generic, Reconnaissance, Shellcode, Worms |
| **有监督模型（后备）** | 76 个 CICFlowMeter 流特征（如果重新训练则 + 10 个 payload 特征） | Random Forest (sklearn Pipeline) | 相同的 10 种攻击类别；仅在不存在 FT-T 检查点时激活 |
| **Isolation Forest** | 18 个基于单 IP 的主机特征 | IsolationForest + StandardScaler | 新型 / 零日体积异常 |
| **LSTM Autoencoder** | 基于单 IP 的 18 特征时间序列 | PyTorch 序列 AE | 慢速攻击、时序行为漂移 |
| **规则** | 流元数据 + payload 字节 + JA3 哈希 | 阈值规则 | ICMP 泛洪、SYN 扫描、SQLi、XSS、LFI、大型 payload、非对称上传、恶意 TLS 指纹 |
| **威胁情报** | IP、JA3 哈希、域名 | 外部源 (AbuseIPDB, JA3 黑名单, MISP) | 已知的恶意 IP、恶意 JA3 指纹、威胁情报域名 |
默认集成权重：有监督模型 35 %，Isolation Forest 25 %，LSTM 15 %，规则 5 %，Baseline 20 %。
任何缺失的引擎，其权重都会按比例重新分配给处于激活状态的引擎。
### 无监督 Baseline 训练
CNDS 持续收集实时网络特征向量，并自主训练 Baseline 异常模型——无需标注数据。当观测到足够的流量多样性后，后台线程会在收集的窗口数据上拟合一个新的 **IsolationForest** 和 **LSTM Autoencoder**，并将产出物持久化到 MLflow。
**触发条件**（必须同时满足以下所有四个条件）：
| 条件 | 默认值 |
|---|---|
| 收集的最小特征向量数 | 50,000 |
| 最小独立源 IP 数 | 20 |
| 最小流逝时间 | 30 分钟 |
| 最小目标端口 Shannon 熵 | 2.5 bits |
500,000 个向量的硬上限将无视其他条件直接覆盖上述复合触发机制。
**产出物结构**（记录在 MLflow 实验 `cnds-unsupervised-baseline` 下，注册为 `cnds-unsupervised-baseline`）：
```
unsupervised_baseline/
scaler.joblib # StandardScaler fitted on training split
iforest.joblib # IsolationForest (200 estimators, contamination 0.01)
lstm_autoencoder.pt # LSTM Autoencoder weights (PyTorch .pt)
threshold.txt # 99th-percentile reconstruction error threshold
provenance.json # Window metadata: time range, fire reason, port/protocol histograms
```
如果未配置 MLflow，模型仍会被拟合，但不会被持久化；系统将记录一条警告。
**启用 / 禁用：** 设置 `BASELINE_COLLECTION_ENABLED=false` 可完全禁用收集。默认值为 `true`。
**丢弃计数器警告：** 当训练运行正在进行时，传入的样本会被静默丢弃并计数。当运行完成时，将记录一条包含总丢弃计数的 `WARNING` 日志。持续偏高的丢弃计数意味着训练耗时超过了一个窗口间隔——建议考虑减小 `min_total_vectors` 或将训练工作负载转移到专用进程中。
完整的开发者参考文档请参阅 [`doc/unsupervised.md`](doc/unsupervised.md)。
### MITRE ATT&CK 映射
每条告警都会自动关联 [MITRE ATT&CK](https://attack.mitre.org/) 技术 ID。映射涵盖了有监督模型标签（14 种攻击类型）和规则触发器（11 种规则，包括 `malicious_ja3`）。当多个来源映射到同一个 ID 时，技术 ID 会被去重。
告警 payload 示例：
```
{
"attack_type": "DoS Hulk",
"mitre_techniques": [
{"id": "T1498", "name": "Network Denial of Service", "tactic": "Impact"}
]
}
```
### JA3 TLS 指纹识别
CNDS 实时从 TLS ClientHello 消息中提取 [JA3](https://github.com/salesforce/ja3) 指纹。JA3 哈希（TLS 版本、密码套件、扩展、椭圆曲线和点格式的 MD5）会：
- 存储在每一条告警中（`ja3_hash`、`ja3_string` 列）
- 与可配置的已知恶意哈希列表（`MALICIOUS_JA3_FILE`）进行比对
- 被规则引擎标记为 `malicious_ja3` → 映射到 MITRE T1071 + T1573
GREASE 值 (RFC 8701) 会在哈希计算前被过滤。
### 威胁情报源集成
CNDS 可以利用来自外部威胁情报源的妥协指标 (IOC) 来增强检测能力。当流量的源/目的 IP 或 JA3 哈希与已知的恶意指标匹配时，集成得分将获得 **+0.30 的提升**，并且告警会被打上 `threat_intel_malicious_ip` 或 `threat_intel_malicious_ja3` 标签。
**支持的情报源：**
| 情报源 | 环境变量 | 描述 |
|------|---------------------|-------------|
| [AbuseIPDB](https://www.abuseipdb.com/) | `ABUSEIPDB_URL`, `ABUSEIPDB_API_KEY` | 恶意 IP 的 CSV 黑名单 |
| JA3 哈希列表 | `MALICIOUS_JA3_URL` | 原始 URL，每行包含一个恶意 JA3 哈希 |
| [MISP](https://www.misp-project.org/) | `MISP_URL`, `MISP_API_KEY` | 从您的 MISP 实例中拉取 IP/域名指标 |
情报源会在后台线程中每 `THREAT_INTEL_REFRESH_MINUTES`（默认：60）分钟刷新一次。在检测热路径上不会发起任何网络调用——所有查找均命中内存集合。如果某个情报源无法访问，则保留现有数据并记录一条警告。
**配置示例：**
```
# .env
ABUSEIPDB_URL=https://api.abuseipdb.com/api/v2/blacklist
ABUSEIPDB_API_KEY=your-key-here
MALICIOUS_JA3_URL=https://raw.githubusercontent.com/strangerealintel/ja3-fingerprints/main/ja3-hashes.txt
THREAT_INTEL_REFRESH_MINUTES=60
```
### SIEM 集成
预置的集成模板位于 `siem/` 目录下：
| 平台 | 文件 | 方法 |
|---|---|---|
| **Splunk** | `siem/splunk/inputs.conf`, `props.conf`, `savedsearches.conf` | 通过 `WEBHOOK_URLS` 推送 HEC 或通过 HTTP 轮询 |
| **Elastic / OpenSearch** | `siem/elastic/index_template.json`, `logstash_cnds.conf`, `filebeat_cnds.yml` | Logstash 轮询/webhook，Filebeat 日志追踪 |
| **Syslog / CEF** (QRadar, ArcSight, Sentinel) | `siem/syslog/forwarder.py` | 基于 UDP/TCP 的独立 CEF 转发器 |
快速开始：
```
# 推送告警到 Splunk HEC
WEBHOOK_URLS=https://splunk.example.com:8088/services/collector/event
# 或者运行 CEF syslog forwarder
python siem/syslog/forwarder.py --syslog-host 10.0.0.50 --syslog-port 514
```
完整的设置说明请参阅 `siem/README.md`。
## 快速开始
### 1. 安装
```
git clone https://github.com/RobertoDeLaCamara/Cognitive-Intrusion-Detection-System.git
cd Cognitive-Intrusion-Detection-System
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
```
### 2. 添加模型
有监督引擎会自动选择以下两种检查点之一：
1. **首选 — 统一 FT-Transformer** (`models/unified/unified_ft_transformer.pt`, ~6.5 MB，已被 gitignore)。基于 UNSW-NB15 训练，并在 MLflow 中注册为 `ml-ids-unified-ft-transformer/1`。优先从 MLflow 加载，如果失败则回退到本地文件。完整的设置与实机测试操作手册请参阅 [`doc/UNIFIED_FT_LIVE_RUNBOOK.md`](doc/UNIFIED_FT_LIVE_RUNBOOK.md)。
2. **后备 — Random Forest lite** (`models/rf_lite_model.joblib`, 1.6 MB，已提交)。如果不存在 FT-T 检查点，则自动激活。开箱即用，提供具备基本功能的检测能力（在 CIC-UNSW-NB15 上达到 91% 的准确率）。
```
# 拉取统一的 FT-Transformer（推荐）——从 ML-IDS 复制或从 MLflow 下载
mkdir -p models/unified
cp /path/to/ML-IDS/models/unified/unified_ft_transformer.pt models/unified/
cp /path/to/ML-IDS/models/unified/unified_scaler.pkl models/unified/
cp /path/to/ML-IDS/models/unified/unified_metadata.json models/unified/
# 或者训练传统的完整 Random Forest（需要 CIC-UNSW-NB15 数据集，约24秒）
python scripts/train_rf.py --data-dir /path/to/CIC-UNSW-NB15
# Isolation Forest + scaler（可选）
cp /path/to/isolation_forest.joblib models/
cp /path/to/if_scaler.joblib models/
# LSTM Autoencoder（可选）
cp /path/to/lstm_autoencoder.pt models/
cp /path/to/lstm_config.json models/ # tracked in git
```
CNDS 可以使用任意模型子集正常运行——缺失的引擎会被平滑跳过。
#### Docker 镜像中包含的内容
`Dockerfile` 构建上下文包含（通过 `.dockerignore` 白名单规则）：
| 文件 | 适用时机 | 用途 |
|---|---|---|
| `models/rf_lite_model.joblib` | 总是包含（已提交） | RF 后备方案——即使没有 MLflow 和 FT 检查点，也能保持有监督槽位处于激活状态 |
| `models/unified/unified_ft_transformer.pt` | 如果构建主机上存在 | 首选 FT-Transformer；优先于 RF 后备方案加载 |
| `models/unified/unified_scaler.pkl` | 同上 | 与 FT 检查点匹配的 StandardScaler |
| `models/unified/unified_metadata.json` | 同上 | 特征名称 + 类元数据 |
| `models/lstm_config.json` | 总是包含（已提交） | LSTM 架构配置（模型权重在运行时拉取） |
运行时的行为矩阵：
| 场景 | 有监督引擎 |
|---|---|
| 无 MLflow，且构建主机上没有 `models/unified/` | Random Forest lite (内置) |
| 无 MLflow，构建时填充了 `models/unified/` | FT-Transformer (从本地检查点加载) |
| 容器可访问 MLflow | FT-Transformer (从 `models:/ml-ids-unified-ft-transformer/` 加载)；如果对注册中心的调用失败，本地文件依然是热后备方案 |
### 3. 运行
```
# 数据包捕获 + 检测（需要 root 权限以使用 raw sockets）
sudo venv/bin/python main.py
# 指定网络接口
sudo venv/bin/python main.py --iface eth0
# 在 :8000 上进行捕获 + REST API
sudo venv/bin/python main.py --api
# 仅 API —— 无实时捕获（用于测试）
uvicorn src.api.main:app --host 0.0.0.0 --port 8000
# N 秒后自动停止
sudo venv/bin/python main.py --duration 60
# Docker Compose（API + detector + Streamlit dashboard）
# 注意：默认的 SQLite backend 不支持并发写入。
# 在 docker-compose 中，只有 API 服务会写入数据库。
# 对于生产环境的多容器设置，请使用 PostgreSQL：
# DATABASE_URL=postgresql+asyncpg://user:pass@db:5432/cnds
docker-compose up -d
# API: http://localhost:8000
# Dashboard: http://localhost:8501
```
## REST API
基础 URL: `http://localhost:8000`
| Endpoint | Method | 描述 |
|---|---|---|
| `/health` | GET | 引擎可用性 + 捕获统计 |
| `/api/predict` | POST | 对提供的特征运行所有引擎 |
| `/api/alerts` | GET | 列出告警（过滤项：`severity`, `src_ip`, `acknowledged`） |
| `/api/alerts/export` | GET | 导出告警为 CSV/JSON（过滤项：`format`, `severity`, `hours`） |
| `/api/alerts/trends` | GET | 按小时/天分桶的告警计数（过滤项：`hours`, `bucket`） |
| `/api/alerts/{alert_id}` | GET | 根据 ID 获取单条告警 |
| `/api/alerts/{alert_id}` | PATCH | 确认告警、添加备注、关联至事件 |
| `/api/incidents` | GET / POST | 事件管理（POST 需要管理员/分析师权限） |
| `/api/stats` | GET | 按严重程度分组的告警计数 |
| `/api/suppression-rules` | GET / POST | 列出或创建抑制规则（POST 需要管理员/分析师权限） |
| `/api/suppression-rules/{rule_id}` | DELETE | 移除抑制规则（需要管理员权限） |
| `/api/adaptive-weights` | GET | 基于反馈计算自适应引擎权重 |
| `/api/dns-log` | GET | DNS 查询日志（过滤项：`src_ip`） |
| `/api/auth/token` | POST | 签发 JWT token（设置了 `JWT_SECRET` 时有效） |
| `/api/auth/users` | GET / POST | 用户管理（需要管理员权限） |
| `/api/auth/users/{user_id}` | DELETE | 删除用户（需要管理员权限） |
| `/ws/alerts` | WebSocket | 实时告警流（启用认证后使用 `?token=JWT`） |
| `/metrics` | GET | Monitoring Service 指标（当 `Monitoring Service_ENABLED=true` 时有效） |
| `/docs` | GET | Swagger UI (自动生成) |
### 示例：手动预测
```
curl -X POST http://localhost:8000/api/predict \
-H "Content-Type: application/json" \
-d '{
"src_ip": "[CLIENT_IP]",
"dst_ip": "10.0.0.1",
"dst_port": 80,
"protocol": 6,
"host_features": [45.2, 5200.0, 115.0, 800.0, 452, 52000,
0.02, 0.005, 12.0, 10.0, 0.9, 0.1, 0.0,
3.0, 0.2, 3.5, 80.0, 200.0]
}'
```
### 示例：列出高严重性告警
```
curl "http://localhost:8000/api/alerts?severity=high&limit=20"
```
### 示例：导出告警为 CSV
```
curl "http://localhost:8000/api/alerts/export?format=csv&severity=high&hours=24" -o alerts.csv
```
### 示例：重放 PCAP 进行模型评估
```
python scripts/pcap_replay.py data/test.pcap --labels data/labels.csv --output results.json
```
## 数据库迁移
CNDS 使用 [Alembic](https://alembic.sqlalchemy.org/) 进行 schema 版本控制。在启动时，API 会自动运行挂起的迁移（对于内存测试数据库，则回退到 `create_all`）。
```
# 修改 models 后生成新的 migration
alembic revision --autogenerate -m "describe your change"
# 应用所有待处理的 migration
alembic upgrade head
# 回退一步
alembic downgrade -1
# 查看当前 revision
alembic current
```
迁移文件位于 `alembic/versions/` 目录下，并由 git 进行版本跟踪。
## 测试
```
# 运行所有测试
pytest tests/ -v
# 带有覆盖率报告
pytest tests/ --cov=src --cov-report=term-missing
# 单个 module
pytest tests/test_flow_extractor.py -v
```
## 配置
将 `.env.example` 复制为 `.env` 并根据需要进行调整。
**注意：** 配置在启动时会被验证。无效的设置（例如，权重总和不为 .0）将引发 `ConfigurationError`。
| 变量 | 默认值 | 描述 |
|---|---|---|
| `CAPTURE_INTERFACE` | auto | 网络接口（例如 `eth0`） |
| `PACKET_WORKERS` | `4` | 异步工作线程数 |
| `PACKET_QUEUE_SIZE` | `20000` | 内部数据包队列大小 |
| `FLOW_TIMEOUT` | `120` | 空闲流被清除前的秒数 |
| `MAX_ACTIVE_FLOWS` | `50000` | 最大同时追踪流数 |
| `ACTIVE_IDLE_THRESH` | `1.0` | 将流标记为空闲所需的非活动状态秒数 |
| `HOST_WINDOW_SIZE` | `100` | 用于主机特征的每个 IP 的数据包历史记录窗口 |
| `MAX_TRACKED_IPS` | `5000` | 主机特征提取器 / LSTM 缓冲区追踪的最大 IP 数 |
| `MIN_PACKETS_FOR_ML` | `10` | ML 引擎激活前的最小数据包数 |
| `ENSEMBLE_THRESHOLD` | `0.55` | 触发告警的得分阈值 |
| `WEIGHT_SUPERVISED` | `0.35` | 有监督引擎权重 |
| `WEIGHT_IFOREST` | `0.25` | Isolation Forest 权重 |
| `WEIGHT_LSTM` | `0.15` | LSTM 权重 |
| `WEIGHT_RULES` | `0.05` | 规则权重 |
| `WEIGHT_BASELINE` | `0.20` | 无监督 Baseline 引擎权重 |
| `LARGE_PAYLOAD_BYTES` | `10000` | 触发大 payload 规则的转发 payload 大小（字节） |
| `MAX_PAYLOAD_SAMPLES` | `50` | 为特征提取而每个流存储的最大 payload 样本数 |
| `PAYLOAD_SAMPLE_BYTES` | `4096` | 每个 payload 样本保留的最大字节数 |
| `RATE_SPIKE_MULTIPLIER` | `2.0` | 速率剧增规则检测的乘数 |
| `ICMP_FLOOD_THRESHOLD` | `50` | 触发 ICMP 泛洪规则的包数 |
| `PORT_SCAN_THRESHOLD` | `20` | 用于扫描检测的 SYN 计数阈值 |
| `ALERT_COOLDOWN_SECS` | `60` | 同一重复告警再次触发前的冷却秒数 |
| `DEDUP_WINDOW_SECS` | `300` | 告警去重窗口（秒） |
| `MODELS_DIR` | `models` | 包含模型文件的目录 |
| `RF_MODEL_FILE` | `rf_model.joblib` | 完整 RF 模型（已被 gitignore，仅作为后备） |
| `RF_LITE_MODEL_FILE` | `rf_lite_model.joblib` | 内置的轻量级 RF 模型（已提交，第二级后备） |
| `RF_SCORE_THRESHOLD` | `0.90` | 避免误报的最小 RF 异常得分 |
| `FT_MODEL_FILE` | `unified/unified_ft_transformer.pt` | FT-Transformer 检查点（已被 gitignore，首选方案） |
| `FT_SCALER_FILE` | `unified/unified_scaler.pkl` | 与 FT 检查点匹配的 StandardScaler |
| `FT_USE_GPU` | `false` | 在可用时于 CUDA 上运行 FT-T 推理 |
| `FT_SCORE_THRESHOLD` | `0.50` | 参与贡献的最小 FT 异常得分 (1 − P(Benign)) |
| `MLFLOW_FT_REGISTRY_NAME` | `ml-ids-unified-ft-transformer` | 从 MLflow 加载 FT 时使用的已注册模型名称 |
| `MLFLOW_FT_STAGE` | `None` | 指定的 MLflow 阶段（默认为最新版本） |
| `IF_MODEL_FILE` | `isolation_forest.joblib` | Isolation Forest 模型文件名 |
| `IF_SCALER_FILE` | `if_scaler.joblib` | IF scaler 文件名 |
| `LSTM_MODEL_FILE` | `lstm_autoencoder.pt` | LSTM 模型文件名 |
| `LSTM_CONFIG_FILE` | `lstm_config.json` | LSTM 配置文件名 |
| `DATABASE_URL` | `sqlite+aiosqlite:///./cnds.db` | SQLite 或 PostgreSQL URL |
| `API_HOST` | `0.0.0.0` | API 绑定地址 |
| `API_PORT` | `8000` | API 监听端口 |
| `API_KEY` | _(空)_ | Bearer token；留空则禁用认证 |
| `CORS_ORIGINS` | _(空)_ | 逗号分隔的允许源；默认为 `http://localhost:3000` |
| `ATTACK_TYPE_WEIGHTS` | `{}` | JSON：按攻击类型覆盖的引擎权重 |
| `CALIBRATION_TEMPERATURE` | `1.0` | Platt 缩放温度（>1 变软，<1 变硬） |
| `ML Tracking_TRACKING_URI` | `http://[MAIN_NODE_IP]:5050` | ML Tracking 服务器 URL；留空则禁用 ML Tracking |
| `ML Tracking_REGISTRY_NAME` | `cnds` | ML Tracking 模型注册表名称 |
| `AWS_ACCESS_KEY_ID` | — | 用于 ML Tracking 产出物存储的 S3 兼容存储访问密钥 |
| `AWS_SECRET_ACCESS_KEY` | — | 用于 ML Tracking 产出物存储的 S3 兼容存储密钥 |
| `ML Tracking_S3_ENDPOINT_URL` | `http://[BACKUP_SERVER_IP]:9000` | 用于 ML Tracking 产出物的 S3 兼容存储 S3 endpoint |
| `JWT_SECRET` | _(空)_ | JWT 签名密钥；留空则禁用 JWT 认证 |
| `JWT_ALGORITHM` | `HS256` | JWT 签名算法 |
| `JWT_EXPIRE_MINUTES` | `60` | JWT token 过期时间（分钟） |
| `Monitoring Service_ENABLED` | `false` | 在 `/metrics` 启用 Monitoring Service 指标 |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | _(空)_ | OpenTelemetry OTLP endpoint |
| `GEOIP_DB_PATH` | _(空)_ | GeoLite2-City.mmdb 路径；留空则禁用 GeoIP |
| `CORRELATION_WINDOW_SECS` | `300` | 告警关联的时间窗口（秒） |
| `CORRELATION_THRESHOLD` | `5` | 来自同一 IP 自动创建事件前的告警数 |
| `ADAPTIVE_WEIGHTS_ENABLED` | `false` | 启用自适应引擎权重计算 |
| `ADAPTIVE_MIN_SAMPLES` | `100` | 调整权重前需确认的最小告警数 |
| `WEBHOOK_URLS` | _(空)_ | 逗号分隔的 webhook/Slack 通知 URL |
| `NOTIFY_MIN_SEVERITY` | `high` | 触发 webhook 通知的最低严重性 |
| `TELEGRAM_BOT_TOKEN` | _(空)_ | 来自 @BotFather 的 Telegram bot token；留空则禁用 |
| `TELEGRAM_CHAT_ID` | _(空)_ | 用于发送告警的 Telegram 聊天/群组 ID |
| `RATE_LIMIT_REQUESTS` | `60` | 每个 IP 每个时间窗口的最大 API 请求数 |
| `RATE_LIMIT_WINDOW` | `60` | 速率限制时间窗口（秒） |
| `DNS_LOGGING_ENABLED` | `false` | 启用对捕获流量的 DNS 查询日志记录 |
| `CONFIDENCE_DECAY_FACTOR` | `0.9` | 同一 IP 重复告警的得分乘数 |
| `CONFIDENCE_DECAY_WINDOW` | `300` | 追踪重复告警以进行衰减的秒数 |
| `IP_ALLOWLIST` | _(空)_ | 逗号分隔的 IP 或 CIDR 范围，将其完全跳过检测 |
| `IP_BLOCKLIST` | _(空)_ | 逗号分隔的 IP 或 CIDR 范围，将其自动标记为关键 |
| `LOG_FORMAT` | `text` | 日志输出格式：`text` 或 `json` (结构化) |
| `JA3_ENABLED` | `true` | 从 TLS ClientHello 中提取 JA3 指纹 |
| `MALICIOUS_JA3_FILE` | _(空)_ | 已知恶意 JA3 哈希的路径（每行一个）；留空则禁用 |
| `BASELINE_COLLECTION_ENABLED` | `true` | 启用无监督 Baseline 收集与训练 |
| `ABUSEIPDB_URL` | _(空)_ | AbuseIPDB 黑名单 URL；留空则禁用 IP 源 |
| `ABUSEIPDB_API_KEY` | _(空)_ | AbuseIPDB API 密钥 |
| `MALICIOUS_JA3_URL` | _(空)_ | 用于拉取已知恶意 JA3 哈希的 URL（每行一个） |
| `MISP_URL` | _(空)_ | MISP 实例 URL；留空则禁用 MISP 源 |
| `MISP_API_KEY` | _(空)_ | MISP API 密钥 |
| `THREAT_INTEL_REFRESH_MINUTES` | `60` | 刷新威胁情报源的频率（分钟） |
## 项目结构
```
├── main.py # Entry point: capture + CLI
├── docker-compose.yml
├── Dockerfile
├── CI/CDfile # CI/CD: build → lint → test → Quality Analysis → push
├── sonar-project.properties
├── requirements.txt
├── .env.example
├── alembic/ # Database migrations
│ ├── env.py # Alembic config wired to CNDS models
│ └── versions/ # Auto-generated migration scripts
├── scripts/
│ ├── retrain_with_payload.py # Retrain RF with 86 features (76 flow + 10 payload)
│ ├── pcap_replay.py # PCAP replay for offline threat hunting / model eval
│ └── smoke_test_ft_unified.py # Reproduce FT-Transformer F1 macro on the held-out test split
├── siem/ # SIEM integration templates
│ ├── README.md # Setup guide for all platforms
│ ├── splunk/
│ │ ├── inputs.conf # HEC input configuration
│ │ ├── props.conf # Field extraction + CIM mapping
│ │ └── savedsearches.conf # Pre-built alert searches
│ ├── elastic/
│ │ ├── index_template.json # Typed mappings (geo_point, nested MITRE)
│ │ ├── logstash_cnds.conf # Logstash pipeline (poll + webhook)
│ │ └── filebeat_cnds.yml # Filebeat log tail config
│ └── syslog/
│ └── forwarder.py # CEF syslog forwarder (QRadar, ArcSight, Sentinel)
├── dashboard/
│ └── app.py # Streamlit real-time dashboard
├── models/ # ML model files
│ ├── unified/
│ │ ├── unified_ft_transformer.pt # Preferred supervised model (gitignored)
│ │ ├── unified_scaler.pkl # StandardScaler matched to the FT checkpoint
│ │ └── unified_metadata.json # Feature names, class counts, training metrics
│ ├── rf_lite_model.joblib # Bundled lite RF (1.6MB, committed — fallback)
│ ├── rf_model.joblib # Full RF pipeline (gitignored — fallback only)
│ ├── isolation_forest.joblib # Isolation Forest (gitignored)
│ ├── if_scaler.joblib # StandardScaler for IF (gitignored)
│ ├── lstm_autoencoder.pt # LSTM Autoencoder weights (gitignored)
│ └── lstm_config.json # LSTM architecture config (committed)
├── src/
│ ├── config.py # All settings (env-var driven)
│ ├── pipeline.py # Detection pipeline callback (flow → engines → alert)
│ ├── mlflow_registry.py # Unified MLflow model registry
│ ├── models/
│ │ └── ft_transformer.py # FTTransformer class + load/build helpers + UNIFIED_CLASS_LABELS
│ ├── capture/
│ │ ├── packet_capture.py # Scapy capture + async worker queue
│ │ └── dispatcher.py # Fan-out to feature pipelines on flow expiry
│ ├── features/
│ │ ├── flow_extractor.py # 76 CICFlowMeter-compatible features per flow
│ │ ├── host_extractor.py # 18 per-IP host features
│ │ ├── payload_analyzer.py # Regex pattern matching + numeric payload features
│ │ ├── ja3.py # JA3 TLS fingerprint extraction
│ │ └── utils.py # Shared utilities (byte entropy, etc.)
│ ├── engines/
│ │ ├── protocol.py # DetectionEngine interface (Protocol)
│ │ ├── registry.py # Shared engine singletons (FT preferred, RF fallback)
│ │ ├── supervised.py # Random Forest wrapper (legacy fallback)
│ │ ├── ft_transformer_engine.py # FT-Transformer engine (MLflow → local fallback)
│ │ ├── isolation_forest.py # Isolation Forest wrapper
│ │ ├── lstm_autoencoder.py # LSTM Autoencoder wrapper
│ │ ├── lstm_model.py # LSTM Autoencoder architecture (nn.Module)
│ │ └── rules.py # Rule-based engine (incl. JA3 rules)
│ ├── unsupervised/
│ │ ├── collector.py # Thread-safe ring-capped feature vector buffer
│ │ ├── triggers.py # CompositeTrigger: four-condition window trigger
│ │ ├── window_trainer.py # IsolationForest + LSTM Autoencoder training + MLflow logging
│ │ ├── artifact_schema.py # Canonical MLflow artifact path constants
│ │ └── provenance.py # ProvenanceMetadata: window statistics snapshot
│ ├── ensemble/
│ │ └── scorer.py # Weighted confidence fusion → EnsembleResult
│ ├── enrichment/
│ │ ├── mitre.py # MITRE ATT&CK technique mapping
│ │ ├── geoip.py # GeoIP enrichment (MaxMind)
│ │ ├── correlation.py # Auto-group alerts into incidents
│ │ ├── adaptive_weights.py # Feedback-driven engine weight tuning
│ │ ├── suppression.py # Temporary alert suppression rules
│ │ ├── notifications.py # Webhook/Slack alert notifications
│ │ ├── confidence_decay.py # Exponential score decay for repeat alerts
│ │ ├── ip_lists.py # IP allowlist / blocklist
│ │ ├── threat_intel.py # Threat intelligence feed integration (AbuseIPDB, JA3, MISP)
│ │ └── dns_logger.py # DNS query logging from captured traffic
│ └── api/
│ ├── main.py # FastAPI application
│ ├── models.py # SQLAlchemy ORM (Alert, Incident)
│ ├── schemas.py # Pydantic request/response schemas
│ ├── database.py # Async SQLAlchemy session setup
│ ├── auth.py # JWT authentication and RBAC
│ ├── metrics.py # Monitoring Service metrics + OpenTelemetry
│ ├── rate_limit.py # Per-IP rate limiting middleware
│ └── routers/
│ ├── predict.py # POST /api/predict
│ ├── alerts.py # Alert + incident CRUD
│ ├── auth.py # POST /api/auth/token
│ └── websocket.py # WebSocket /ws/alerts
└── tests/
├── conftest.py # Shared fixtures (in-memory DB, mock features)
├── test_api.py # API integration tests
├── test_auth.py # JWT authentication and RBAC tests
├── test_config.py # Configuration validation tests
├── test_engines.py # Engine unit tests
├── test_enrichment.py # Enrichment module tests
├── test_ensemble.py # Ensemble scorer tests
├── test_flow_extractor.py
├── test_host_extractor.py
├── test_ja3.py # JA3 fingerprint extraction tests
├── test_mitre.py # MITRE ATT&CK mapping tests
├── test_payload_features.py
├── test_ip_lists.py # IP allowlist/blocklist tests
├── test_threat_intel.py # Threat intelligence feed tests (31 tests, 98% cov)
├── test_rules_engine.py
├── test_siem.py # CEF syslog forwarder tests
├── test_ft_transformer_engine.py # FT-Transformer integration tests (load + predict + dataset checks)
└── unsupervised/
└── test_collector.py # BaselineCollector, CompositeTrigger, ProvenanceMetadata unit tests
```
## 路线图
请查看 [待办问题](https://github.com/RobertoDeLaCamara/Cognitive-Intrusion-Detection-System/issues) 以了解计划中的功能和已知漏洞。欢迎贡献代码——请查阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。
标签：Apex, AV绕过, CISA项目, FastAPI, IP 地址批量处理, Scapy, 入侵检测系统, 凭据扫描, 威胁情报, 安全数据湖, 开发者工具, 异常检测, 机器学习, 测试用例, 网络安全, 请求拦截, 逆向工具, 防御绕过, 隐私保护