tianxuan/docs/workflow.md

天璇 TLS 流量分析工作流

工具总览（27 个 MCP 工具）

⚡ 核心工具（7个）— 执行实际分析，可修改数据

工具	输入	输出	何时调用
profile_data	dataset_id	列类型/统计/空值率	第一步，了解数据
build_entity_profiles	dataset_id, [entity_column]	实体画像数据集	确定实体列后
compute_scores	dataset_id	proxy_score/risk_level/threat_score	实体画像完成后
run_clustering	dataset_id, cluster_columns, algorithm	聚类结果	需要行为分组时
extract_features	dataset_id, cluster_result_id	各组区分特征	聚类完成后
detect_anomalies	dataset_id, [contamination]	异常实体列表	评分完成后
visualize_anomalies	dataset_id	PCA散点数据	评分/检测完成后

🔍 分析工具（5个）— 只读，安全可随时调用

工具	功能	典型场景
analyze_patterns	热门IP/端口/TLS版本分布	快速了解流量结构
analyze_tls_health	TLS安全评估（旧版比例/弱加密）	安全审计
analyze_geo_distribution	地理分布/不可能旅行	检测跨国代理
analyze_entity_detail	单实体深度调查	可疑实体深入分析
analyze_temporal	时间维度流量模式	理解流量周期性

🩺 诊断工具（7个）— 排查问题

工具	解决什么问题
validate_data	数据质量：空列、常量列、schema不一致
explore_distributions	查看列分布统计，理解数据
find_outliers	发现极端值
diagnose_clustering	聚类效果差时诊断原因
compare_datasets	对比处理前后的数据差异
export_debug_sample	导出JSON供人工检查
repair_schema	修复列名不一致

其他（8个）

load_data, filter_data, preprocess_data, evaluate_clustering, export_results, list_datasets, drop_dataset, clone_dataset

---

标准分析流程

load_data → profile_data → build_entity_profiles → compute_scores → run_clustering → extract_features

完整步骤

1. 加载数据

工具: load_data
参数: csv_glob="data/*.csv"
说明: 支持glob模式，自动合并同结构多文件

2. 了解数据

工具: profile_data
参数: dataset_id="..."
说明: 查看列数、类型、空值率、统计摘要

可选: 调用 analyze_patterns 查看更多流量结构信息

3. 构建实体画像

工具: build_entity_profiles
参数: dataset_id="...", auto_detect=true
说明: 自动检测实体列(IP/SNI等)，聚合流数据为实体特征

如果自动检测失败 → 调用 explore_distributions 查看候选列

4. 计算异常分数

工具: compute_scores
参数: dataset_id="<entity_dataset_id>"
说明: PCA自动学习权重，输出 proxy_score / risk_level / threat_score

5. 检测异常（可选）

工具: detect_anomalies
参数: dataset_id="...", contamination=0.05
说明: Isolation Forest 找出异常实体

6. 聚类分析

工具: run_clustering
参数: dataset_id="...", cluster_columns=[...], algorithm="hdbscan"
说明: 实体行为分组

如果聚类效果差 → 调用 diagnose_clustering 诊断

7. 提取特征

工具: extract_features
参数: dataset_id="...", cluster_result_id="...", method="zscore"
说明: 找出每组区分特征

8. 可视化

工具: visualize_anomalies
参数: dataset_id="..."
说明: PCA降维，散点图数据

---

异常排查流程

数据加载失败

load_data 报错
  → validate_data: 检查 schema 问题
  → repair_schema: 修复列名不一致
  → 重试 load_data

实体检测失败

build_entity_profiles 返回无实体列
  → explore_distributions: 检查各列unique值
  → 手动指定 entity_column 重试

聚类效果差

run_clustering 返回 1 个簇或全噪声
  → diagnose_clustering: 诊断原因
  → 根据诊断调整参数重试
  → 或用 analyze_tls_health 检查 TLS 质量

分数异常

compute_scores 后多数实体分数极高/低
  → explore_distributions: 检查各特征分布
  → find_outliers: 找出极端值
  → analyze_entity_detail: 深入调查可疑实体

---

LLM自动模式

在配置页面设置 LLM 后，LLM分析 页面会自动编排工具链。LLM 的策略：

1. 先 profile_data 了解数据
2. 根据 profile 决定下一步
3. 失败时自动调用诊断工具
4. 分析过程中随时调用只读分析工具深入了解
5. 中文总结分析结果

可通过配置文件调整 LLM 参数 (config.yaml → llm)