简介：基于Python机器学习朴素贝叶斯（NB）算法实现的WebShell检测工具，适合具有一定Python基础、希望入门文本分类与安全检测的学习者，也可作为毕设、课程设计或工程实训的参考项目。资源共14个文件，以Python脚本和txt数据文件为主，包含check.py检测入口、train_asp.py、train_php.py、train_jsp.py三个训练脚本及README说明，整体仅32KB，轻量易读。已有234人学习浏览。项目采用词袋模型结合TF-IDF进行特征提取，利用NB算法对文本内容分类，能识别php、asp、jsp三类WebShell；Data目录按正常样本和WebShell子目录组织，便于理解数据预处理与模型训练流程。代码结构清晰，适合在真实项目中参考改造成自定义检测流程，也可据此扩展更多脚本类型或优化特征工程。
1. 基于文本的WebShell检测：NB算法工具能解决什么
拿到一个被人上传过WebShell的站点目录，几百个PHP文件堆在那里，手工翻一遍能翻到眼冒金星。这个基于python机器学习NB算法的WebShell检测工具，把朴素贝叶斯分类直接用在文件内容上：读入文本、TF-IDF提取特征、模型预测类别，一条龙跑完，支持PHP、ASP、JSP三种后端语言。它解决的不是“能不能查出已知木马”的问题，而是“面对一堆没有明显特征的代码，怎么快速缩小人工排查范围”的问题。
它的用法也足够简单：训练阶段往Data目录里分别填充黑白样本，依次执行train_jsp.py、train_asp.py、train_php.py；检测阶段把可疑文件丢进Data/check，跑一条python check.py命令就能得到预测结果。所以适合三类人：想用机器学习做安全方向课程设计或毕设的学生、需要快速批量排查服务器文件的运维、以及刚接触文本分类想找个真实场景练手的Python学习者。这篇文章会从算法原理拆到参数设置，再落到底层踩坑，尽量让你照着能跑出一份可信的检测结果。
2. 朴素贝叶斯和TF-IDF：这套检测工具能在文本里站稳的依据
2.1 朴素贝叶斯为什么适合做“文本分类”
WebShell检测本质上是个二分类问题：同样一段PHP代码，要么是正常业务逻辑，要么是恶意脚本。朴素贝叶斯解决这个问题的思路很直接，它计算“给定这段文本，它属于WebShell类别的概率”和“属于正常类别的概率”，哪个大就判给哪个。公式核心是贝叶斯定理，P(类别|文本)=P(类别)×P(文本|类别)/P(文本)，计算时对文本里的每个特征求条件概率再连乘。这个过程非常快，训练一个模型只要几秒到几分钟，推理时更是毫秒级。
它有一个“朴素”假设：特征之间相互独立。明眼人都知道代码里“eval”和“$_POST”经常同时出现，谈不上独立，但工程上这个假设反而成了优势，它让概率计算变得极其简单，而且在样本量只有几百到几千的小型文本分类任务里，效果并不比复杂模型差。具体到实现，sklearn里的MultinomialNB是首选，因为TF-IDF特征是非负稀疏向量，符合多项式分布；如果误用了GaussianNB，它假设特征服从正态分布，拿稀疏矩阵去拟合，predict_proba输出往往非常奇怪。
还有一个容易被忽略的参数叫alpha，也就是拉普拉斯平滑。它解决的是“某个词在某类样本里没出现过导致概率为0”的问题，加了平滑后各项概率都保留一个极小底数，避免整个连乘被清零。默认alpha=1，调小到0.5或0.1会让模型更贴近训练数据，但也会放大噪声。我一般会先用默认值跑通，再看误报情况决定要不要动它。简单说，alpha是这套工具里最值得试的第一个旋钮。
2.2 TF-IDF：从文件文本到特征向量的完整过程
原始PHP文件是一串字符串，计算机没法直接算概率，必须转成向量。词袋模型先做的是把文件内容拆成token，统计每个token出现次数，但纯词频有个问题，“if”“echo”“function”这类词到处都是，它们会淹没真正的信号。TF-IDF在词频基础上加了逆文档频率：某个词在当前文件里出现次数多，同时在训练语料其他文件里很少出现，它的权重就会被拉高。放到WebShell场景里，“eval”“base64_decode”“assert”这些危险函数几乎不会出现在正常业务代码里，IDF值很高，自然成为模型的强特征。
下面这一段是训练前最核心的特征提取逻辑，几乎所有的train脚本都绕不开它：
from sklearn.feature_extraction.text import TfidfVectorizer corpus = [ "<?php @eval($_POST['pass']); ?>", "<?php echo 'hello world'; ?>", ] vectorizer = TfidfVectorizer( analyzer="char_wb", # 按字符切分，且窗口不跨空格 ngram_range=(1, 3), # 单字符到三字符组合都作为特征 min_df=2, # 只保留至少在2个文件中出现的特征 max_features=5000 # 限制特征总数，防止高维稀疏 ) X = vectorizer.fit_transform(corpus) print(X.shape) # (2, 特征数) print(vectorizer.get_feature_names_out()[:5])这里几个参数不是随手填的。analyzer="char_wb"表示按字符级切分，PHP、ASP、JSP这类代码没有天然的空格分词结构，字符级n-gram能捕捉“$_”这种危险写法；ngram_range=(1,3)把单个字符、相邻两个、三个字符都作为特征，对混淆代码的容错更好；min_df=2过滤掉只在极个别文件里出现的噪声片段，避免模型记住随机字符串；max_features限制维度，否则字符级特征会膨胀到几十万维，内存和训练时间都不可控。
训练和检测阶段最容易出问题的地方也在这：fit_transform是在训练集上拟合词表，检测新文件时必须复用同一个vectorizer去transform，绝对不能再fit一次。一旦重新fit，词表、特征维度全变，模型要么直接报错，要么静默地给出错误预测。这也是为什么我拆这类工具时，第一步永远是找到vectorizer保存和加载的代码，确认训练和预测用的是同一个对象。
2.3 为什么词袋+TF-IDF对WebShell检测够用
选择朴素贝叶斯而不是CNN、LSTM这类深度模型，最直接的原因是样本量。WebShell的黑白样本通常只有几百到几千个文件，深度学习在这个数据量下很容易过拟合，调参成本还高。NB训练快、内存占用小，特征维度高一点也能扛住，而且每个特征都有明确的字面含义，模型把哪个文件判成恶意后，你可以把贡献最大的几个token打印出来，这就是可解释性。对安全检测场景来说，能解释远比能说“模型很准”重要。
用Pipeline把特征提取和分类器串起来是常见做法，代码可以长这样：
from sklearn.pipeline import Pipeline from sklearn.naive_bayes import MultinomialNB model = Pipeline([ ("tfidf", TfidfVectorizer(analyzer="char_wb", ngram_range=(1, 3))), ("clf", MultinomialNB(alpha=0.5)) ]) model.fit(X_train, y_train)Pipeline的好处是网格搜索、交叉验证时不用分开传参数，比如想试不同alpha，直接写model.set_params(clf__alpha=0.1)。alpha=0.5是我在类似项目里比较常用的起点，比默认1更敏感，适合黑样本特征比较明显的场景；如果误报高就退回1。不过也要说清楚边界：TF-IDF看到的是统计规律，遇到硬编码的加密载荷、完全随机字符串拼出来的混淆变种，文本特征几乎没有信号。所以这套工具的定位是“快速初筛”，不是“最终裁决”，高危文件必须有人工复核兜底。
3. 训练三套检测模型：样本目录、执行顺序与超参数调优
3.1 先理清Data目录结构：黑白样本放哪里才算对
下载解压后第一件事不是跑脚本，而是检查Data目录。项目里Data下面横向分normal和WebShell两大类，纵向分asp、jsp、php三种语言，check是检测阶段专用目录。训练时真正起作用的是normal和WebShell，下面各自有asp/jsp/php三个子目录，分别存放对应语言的正常文件和恶意文件。
| 目录路径 | 角色 | 说明 |
|---|---|---|
| Data/normal/php | 白样本 | 正常PHP文件，尽量覆盖常见框架写法 |
| Data/normal/asp | 白样本 | 正常ASP/ASPX文件 |
| Data/normal/jsp | 白样本 | 正常JSP文件 |
| Data/WebShell/php | 黑样本 | 各种PHP WebShell，包含一句话、变形 |
| Data/WebShell/asp | 黑样本 | 各种ASP WebShell |
| Data/WebShell/jsp | 黑样本 | 各种JSP WebShell |
| Data/check | 待检 | 检测时把可疑文件放这里 |
特别注意训练脚本按语言分开执行，三个脚本各读各的目录。PHP的黑样本只会影响PHP模型，不会混进ASP模型。如果目录层级不对，脚本会在读取阶段直接抛FileNotFoundError；如果在Windows上解压后目录大小写变了，或者把WebShell整个文件夹误放进normal，训练出来的模型基本是废的。这个目录结构是整个工具的地基，先花五分钟核对它，比后面调试两小时都值。
3.2 训练脚本执行顺序：先准备样本，再跑三个train脚本
目录确认无误后，按顺序执行训练脚本。项目命名已经很明确：train_php.py训练PHP模型，train_asp.py训练ASP模型，train_jsp.py训练JSP模型。这三个脚本之间没有依赖关系，真正有意义的是“先补数据、再跑脚本、最后确认模型文件生成”。下面是一套完整的操作流程：
# 进入项目根目录 cd WebShell-AIHunter-master # 确认训练目录存在，不存在就创建 mkdir -p Data/normal/php Data/normal/asp Data/normal/jsp mkdir -p Data/WebShell/php Data/WebShell/asp Data/WebShell/jsp mkdir -p Data/check # 依次训练三种模型 python train_php.py python train_asp.py python train_jsp.py三个脚本内部做的事情是同构的：遍历对应样本目录，逐个读取文件内容，用TfidfVectorizer做特征提取，喂给MultinomialNB训练，最后把模型序列化保存。模型保存格式一般是joblib或pickle，文件名带语言标识，比如model_php.pkl，具体以脚本最后几行的print输出为准。如果训练过程没有任何输出，先怀疑样本目录为空，再怀疑路径拼接用了相对路径而当前终端所在目录不对。
我习惯在训练前手动统计一下每个目录的文件数量，比如用ls Data/WebShell/php | wc -l确认黑样本不是0。这个动作看起来多余，但实际项目里我见过太多次“训练了一晚上，最后发现读入的是空列表”的翻车现场。脚本不报错不代表读到了数据，定向输出几个文件路径出来看一眼最稳。
3.3 超参数该怎么调：alpha、ngram_range、min_df的影响
训练脚本能跑通只是第一步，真正决定检测效果的是TfidfVectorizer和MultinomialNB那几组参数。字符级TF-IDF下，最常用的可调参数有四个：alpha、ngram_range、min_df和max_features。它们对结果的影响差别很大，下面这张表可以直接当调参速查。
| 参数 | 常见取值 | 对结果的影响 |
|---|---|---|
| alpha | 0.1 / 0.5 / 1.0 | 平滑强度，越小越敏感，越容易过拟合 |
| ngram_range | (1,2) / (1,3) / (1,4) | 特征粒度，范围越大特征数量越多 |
| min_df | 1 / 2 / 5 | 过滤低频词，太大丢特征，太小噪声大 |
| max_features | 3000 / 5000 / 10000 | 限制特征维度，防止内存爆炸 |
这些参数不是拍脑袋定的。我一般先用交叉验证看一轮趋势：alpha依次试1、0.5、0.1，ngram_range在字符级下常用(1,3)起步，如果误报高再放到(1,4)。min_df在样本量小的时候不要设太高，黑白样本各只有两三百个文件时设min_df=5，会把很多只在恶意代码里出现的危险片段直接过滤掉。选参的判断标准也很简单：先看验证集F1，再看被误报的正常文件长什么样，而不是只盯一个平均值。
# 用 5 折交叉验证快速比较不同 alpha from sklearn.model_selection import cross_val_score for alpha in (1.0, 0.5, 0.1): model.set_params(clf__alpha=alpha) scores = cross_val_score(model, X, y, cv=5, scoring="f1_macro") print(f"alpha={alpha}, F1均值={scores.mean():.4f}")cross_val_score返回每一折的F1值，取均值做对比。之所以用f1_macro而不是accuracy，是因为正常样本通常占多数，模型就算把所有文件都判成normal，准确率也可能很高，掩盖掉漏报问题。F1同时惩罚误报和漏报，更能反映真实水平。这一步在样本量少时尤其重要，能提前暴露数据分布的问题，而不是等部署到服务器上才被发现。
3.4 黑白样本质量比数量更重要
训练数据的质量直接决定模型上限。黑样本不要只收集最经典的“一句话木马”，至少要覆盖：原始一句话、base64加密载荷、字符串拼接绕过、回调函数、文件操作类马。白样本同样要有代表性，用一行“hello world”当正常PHP文件没有意义，真正的正常业务代码会大量出现$_GET、$_POST、include、require这些操作，模型需要见过它们，才能在特征里把它们和危险函数区分开。
样本比例上，我见过最翻车的配置是白样本2000个、黑样本50个，模型学出来几乎只会说“正常”。社区常规做法是每种语言至少准备白黑各100到300个，比例不要超过3:1。如果黑样本实在不够，可以把已有样本做轻微改写再扩充，改文件名、加注释、调整换行，但不要用同一个文件复制500份，那样模型会对该样本的个性噪声过拟合，换一个真实变种立刻失效。训练集是这部工具的弹药库，宁可少而精，不要多而脏。
4. 实战检测：check.py 的调用方式与结果解读
4.1 待检测文件放进Data/check：目录约定与递归扫描
训练完成后，检测流程被刻意做得简单：把可疑文件复制到Data/check文件夹，执行python check.py。这个设计对应急响应场景很友好，拿到一批未知文件，不用逐个改名，直接批量丢进去。check.py一般会按扩展名自动选择对应模型，PHP文件走PHP模型，ASP走ASP模型，JSP走JSP模型。以下是拷贝和执行的标准动作：
# 把可疑目录整体拷入待检测目录，保留子目录结构 cp -r /tmp/suspect_site/* Data/check/ # 执行检测 python check.py拷贝时我建议保留原始目录结构，因为check.py输出结果时如果能带上相对路径，你能快速定位“到底是哪个目录下的哪个文件有问题”。如果脚本不支持递归扫描子目录，那就只能把所有文件平铺到Data/check下，这时文件名重名会互相覆盖，这是检测阶段最容易踩的第一个坑。跑起来后，几百个文件几秒扫完是正常速度，因为模型和向量化对象都放在内存里，不需要反复加载。
4.2 检测输出解读：预测标签、概率与危险文件定位
check.py的典型输出一般是每行一个文件路径加一个预测结果，比如“webshell: Data/check/upload.php”或者“normal: Data/check/index.php”。有些版本还会打印预测概率，这是判断可信度的关键。只看标签不看概率，等于只知道模型“觉得”可疑，不知道它能确定到什么程度。一个概率0.99的webshell和一个概率0.51的webshell，处理优先级完全不同。
# 伪代码：check.py 内部预测逻辑，核心就三步 def predict_file(path, model, vectorizer): with open(path, "r", encoding="utf-8", errors="ignore") as f: text = f.read() vec = vectorizer.transform([text]) proba = model.predict_proba(vec)[0] label = model.predict(vec)[0] return label, max(proba) # 假设 classes_ = ['normal', 'webshell'] # proba[1] 就是“属于 WebShell”的概率model.predict_proba返回两个类别的概率数组，max取最大概率作为置信度。如果某个文件被判为webshell但概率只有0.51，这个结果只能当“待审”，不适合直接删文件。反过来，判为normal但概率是0.99，也要想一下是不是黑样本特征被白样本污染了。实际使用里，我把概率小于0.7的结果全部列为人工复核，宁可多看十份文件，不愿漏一个真马。
4.3 从“能跑”到“能用”：误报率、漏报率与人工复核机制
安全检测和广告点击率预测不一样，漏报的代价远高于误报。一个WebShell漏过去，攻击者可以持续控制服务器，而误报最多是让运维多看一眼。所以在调整alpha和ngram_range时，不能把所有希望都堆在一个F1分数上，我会单独打印漏报样本，看它们到底长什么样，是被加密了，还是用了没见过的函数名。
| 指标 | 含义 | 安全场景下的目标 |
|---|---|---|
| 误报率 | 正常文件被判成WebShell的比例 | 尽量低，但可以接受少量 |
| 漏报率 | WebShell被判成正常的比例 | 必须朝0看，这是底线 |
| F1 | 精确率和召回率的调和平均 | 越高越好，作为调参依据 |
评估时直接输出分类报告最省事：
# 在留出测试集上输出分类报告 from sklearn.metrics import classification_report y_pred = model.predict(X_test) print(classification_report(y_test, y_pred, target_names=["normal", "webshell"]))classification_report会同时给出precision、recall、f1-score，重点看webshell那行的recall。如果recall低于0.9，说明大量恶意文件被放行了，这时优先调低alpha、加大ngram_range，而不是去压误报。这一步做完，工具才算真正能放进应急流程。
还有一个容易忽略的点：检测结果要留日志。check.py就算打印了危险文件路径，如果当时没有重定向到文件，事后根本没法追溯。我一般会额外包一层输出重定向：
python check.py | tee check_result_$(date +%Y%m%d).log这样每次扫描结果都留底，被标记的文件也能回看。这不是项目自带功能，但几乎是实战必备。安全事件发生后要做溯源，没有日志的检测等于没做过。
5. 避坑指南：样本、编码、路径与模型失效的五大问题
5.1 黑样本太少，模型只会喊“正常”
现象：训练完成后，检测时把所有文件都预测为normal，包括一眼就能看出来的那句话木马。 原因：训练集里normal数量远大于WebShell，朴素贝叶斯的先验概率被拉偏，P(正常)接近0.99，后验概率自然倾向正常。即使某个文件里出现了危险token，也翻不过先验概率这道墙。 解决：把黑白样本比例拉回1:1到3:1。如果黑样本确实少，可以复制并轻微修改文件名补充数量。NB本身没有class_weight参数，靠数据层面平衡是最直接的做法。另外可以在预测时把阈值从0.5抬到0.3，让更多低概率文件进入待审，而不是直接被归为正常。
5.2 文件编码乱码：UTF-8、GBK与BOM干扰
现象：Windows上训练或检测时，读入的中文注释变成乱码，模型对含中文的正常文件误报率升高，或者直接抛UnicodeDecodeError中断。 原因：脚本用默认编码读取文件，中文Windows默认GBK，Linux默认UTF-8，而WebShell和正常代码文件两种编码都存在。部分文件还带BOM头，会把“\ufeff”混进第一个token里。 解决：读取文件时做编码降级，按UTF-8、GBK、latin1依次尝试：
def read_text(path): for enc in ("utf-8", "gbk", "latin1"): try: with open(path, "r", encoding=enc, errors="ignore") as f: return f.read() except UnicodeDecodeError: continue return ""errors="ignore"会把无法解码的字节丢掉，虽然不完美，但比报错中止强。这个函数在训练和检测两段都要替换进去，否则训练读GBK、检测读UTF-8，特征分布不一致，结果完全不可信。编码兼容是做跨平台运行时第一个要补的窟窿。
5.3 目录层级和大小写不对，训练直接中断
现象：执行train_php.py，报错FileNotFoundError: Data/WebShell/php/*.php 不存在，或者训练结束一个文件都没读到。 原因：解压后目录大小写变了，比如把WebShell写成了webshell；或者将检测目录check误当成样本目录；还有人是直接在Windows资源管理器里新建文件夹，系统隐藏了扩展名，建出来的目录名带着多余后缀。 解决：严格按项目要求的目录层级重建，php、asp、jsp全部小写，normal和WebShell首字母大写。建完后逐个确认路径存在：
ls -d Data/normal/php Data/WebShell/php Data/check这个命令能一次确认三个关键目录，任何一条报错都说明路径有问题。做安全工具最忌讳想当然，路径差一个字符，结果就是模型完全不可用。
5.4 模型文件与脚本分离，换路径后加载失败
现象：在项目根目录跑训练生成模型没报错，第二天换一个目录执行check.py，提示模型文件找不到，或者FileNotFoundError报出的是相对路径。 原因：模型保存和加载时用了相对路径，脚本不在同一个终端工作目录下运行，相对路径就失效了。训练时你正好站在项目根目录，所以一切正常，换个位置就露馅。 解决：在脚本里用Path(file).resolve().parent拼出项目绝对路径：
from pathlib import Path BASE_DIR = Path(__file__).resolve().parent model_path = BASE_DIR / "model_php.pkl"这样不管从哪个目录启动python，都能找到模型文件。这个坑很隐蔽，因为它不影响首次运行，只在你换环境、写定时任务、从别的目录调用脚本时突然发作。日志里还会打印出非常迷惑的报错，让人误以为是模型损坏。
5.5 新变种绕过，模型对未知混淆无感
现象：网上新出的WebShell变种放进Data/check，检测结果居然是normal，而且概率还很高。 原因：TF-IDF学的是训练语料里的token分布，新变种换了函数名、做了字符串拼接、或者走了加密通道，之前学到的危险特征一个都没出现。NB模型本质上是在“见过的东西”里找规律，没见过就等于正常。 解决：不要指望一个静态模型包打天下。把新变种补充进黑样本目录，重新训练对应语言的模型。同时在检测流程里加上结构特征兜底：文件里出现超长字符串、密集的变量拼接、base64片段，即使模型判正常，也要标记出来人工看。NB检测工具的价值是筛掉已知的80%，剩下20%需要人眼兜底。
6. 进阶：置信度阈值、增量训练与检测效果验证
6.1 给检测加置信度阈值
默认predict返回硬标签，只有一个“是或否”，实战里不够用。我会在check.py的输出逻辑里把predict_proba拿来做三级判断：概率大于等于0.7直接报警，0.4到0.7之间标记待人工审，低于0.4才放行。
proba = clf.predict_proba(vec)[0][1] if proba >= 0.7: verdict = "webshell" elif proba >= 0.4: verdict = "manual_check" else: verdict = "normal"这个阈值改起来成本极低，却能让工具从“一刀切”变成“分级告警”，适合真正部署到应急流程里用。
6.2 把误报样本补回训练集做增量训练
检测中漏掉的恶意样本和误报的正常文件，不要看一眼就删掉，按类型放回Data目录对应位置，再重跑对应语言的训练脚本。
cp /tmp/fp_normal.php Data/normal/php/ cp /tmp/fn_webshell.php Data/WebShell/php/ python train_php.pyNB训练成本低，全量重训比在线增量更新更可控。如果非要用partial_fit做增量，要注意TfidfVectorizer的词表也得跟着更新，否则新特征进不来，所以务实做法还是全量重训。
6.3 效果验证：用漏报率和误报率判断能不能用
每次改动样本或参数后，用留出测试集算一遍漏报率和误报率，记录模型文件、训练脚本、样本目录三者对应的版本。我只信任能复现的检测结果，模型文件脱离样本集就是黑匣子。
| 检查项 | 合格线 |
|---|---|
| WebShell召回率 | 不低于0.9 |
| 正常文件误报率 | 不高于0.1 |
| 单文件检测耗时 | 秒级以内 |
我第一次拆这类工具时，只顾把准确率调到0.95，结果没看漏报的那几个文件，差一点让一个真实样本混过去。从那以后，我每次跑完必做四件事：查样本比例、查编码、查路径、查阈值，再谈模型效果。希望帮到你。
本文还有配套的精品资源，点击获取
