白盒代码扫描系统 —— 部署手册（小白版）

这份文档教你从零在一台 Linux 服务器上搭起一套能用的白盒代码扫描系统也叫 SAST静态代码安全扫描。面向对象完全没搭过、看不懂架构也没关系的新手。照着一步步复制命令执行即可。本手册特意做了简化去掉了 Jenkins、发布门禁、自动监工那一整套只保留最核心的能力——「你给一份 Java 代码它扫出漏洞你在网页上看和评审」。先把这套跑通理解了再谈复杂化。0. 先花 1 分钟搞懂它长什么样简化后整套系统就是同一台服务器上的 4 个东西你的浏览器 │ 访问 http://服务器IP ▼ ┌───────────┐ /api/ 转发 ┌──────────────┐ │ nginx │ ──────────────▶│ 后端 Flask │ ← 结果管理台看漏洞、评审 │ (80端口) │ │ gunicorn:5000│ └───────────┘ └──────┬───────┘ 网页(前端) │ 读写 ▼ ┌──────────────┐ │ MySQL │ ← 存项目/扫描/漏洞 └──────────────┘ 另外一个命令行脚本 scan_and_upload.py ──────────────────────────────────────────── 你运行它 → 它调用 CodeQL 扫描一个 Java 项目 → 把漏洞塞进上面的 MySQLCodeQL 真正干活的扫描引擎GitHub 出品免费。后端 MySQL nginx 网页 一个「结果管理台」只负责展示和评审漏洞本身不扫描。scan_and_upload.py 我们写的小脚本替代生产里那一大套自动化让你手动扫一个项目。理解这张图后面每一步就知道自己在装哪块了。1. 准备一台服务器系统Ubuntu 22.04 LTS本文命令以它为准CentOS 也行把apt换成yum即可。配置4 核 8G 内存、40G 硬盘起步CodeQL 编译 Java 项目挺吃内存。网络能访问外网下载软件用。账号用root或者一个能sudo的普通用户。下文所有命令都在这台服务器的终端里执行。看到sudo开头就是需要管理员权限。2. 装基础软件一条条复制执行sudoaptupdatesudoaptinstall-ypython3 python3-pip python3-venvgitunzipwgetnginx mysql-serversudoaptinstall-yopenjdk-8-jdk maven# 扫 Java 项目要用 JDK8 Maven装完检查版本能打印出来就说明装好了python3--versionjava-versionmvn-version3. 装 MySQL 并建数据库3.1 启动 MySQLsudosystemctlenable--nowmysql3.2 建库、建账号进入 MySQLsudomysql在mysql提示符里逐行粘贴下面的 SQL把你的密码换成你自己想的密码记牢它CREATEDATABASEsec_sastCHARACTERSETutf8mb4;CREATEUSERsast127.0.0.1IDENTIFIEDBY你的密码;GRANTALLPRIVILEGESONsec_sast.*TOsast127.0.0.1;FLUSHPRIVILEGES;EXIT;说明sec_sast是数据库名后端写死用这个名字别改sast是访问它的账号。4. 部署后端结果管理台的大脑4.1 把代码放到服务器把本项目里的ubuntu_sast文件夹整个上传到服务器例如放到/home/ubuntu/ubuntu_sast。可以用scp、宝塔、FileZilla 等任意方式怎么方便怎么来。之后进入该目录cd/home/ubuntu/ubuntu_sast4.2 改数据库连接编辑app/config.pynanoapp/config.py把第一行的数据库地址改成你自己的就是第 3 步建的账号密码SQLALCHEMY_DATABASE_URImysqlpymysql://sast:你的密码127.0.0.1:3306/sec_sast?connect_timeout10改完按CtrlO回车保存CtrlX退出。4.3 装 Python 依赖pip3install-rrequirements.txt pip3installgunicorn requests pymysql# 运行/扫描脚本还要用这几个4.4 初始化数据库表项目里已经放好了一个init_db.py在ubuntu_sast目录下。直接运行python3 init_db.py看到完成就说明表和默认策略都建好了。4.5 启动后端gunicorn-w4-b127.0.0.1:5000--timeout600run:app看到类似Listening at: http://127.0.0.1:5000就是成功了。先别关这个窗口新开一个终端做后面的事等全部跑通后再看 4.6 改成后台常驻。快速自测新终端里curl-shttp://127.0.0.1:5000/userLogin-HContent-Type: application/json\-d{username:admin,password:123456}返回里带token就说明后端正常。默认登录账号密码是admin / 123456写死在代码里。上线前务必改掉见第 10 节。4.6 可选让后端后台常驻正式用的时候不希望关窗口就停。用 nohup 挂后台cd/home/ubuntu/ubuntu_sastnohupgunicorn-w4-b127.0.0.1:5000--timeout600run:appgunicorn.log21想看日志tail -f /home/ubuntu/ubuntu_sast/gunicorn.log想停pkill -f gunicorn -w 4 -b 127.0.0.1:50005. 部署前端网页前端是一个编译好的网页但里面写死了服务器地址所以我们要重新编译一次让它调用「同域名下的 /api/」。5.1 装 Node.jscurl-fsSLhttps://deb.nodesource.com/setup_16.x|sudo-Ebash-sudoaptinstall-ynodejsnode-v# 能打印版本就行5.2 编译前端把本项目的ubuntu_sast_web-main文件夹上传到服务器例如/home/ubuntu/ubuntu_sast_web然后cd/home/ubuntu/ubuntu_sast_web# 把接口地址改成相对路径 /api/关键否则网页找不到后端echoENV production.env.productionechoVUE_APP_BASE_API /api/.env.productionnpminstall# 装依赖第一次会慢耐心等npmrun build:prod# 编译产物在 dist/ 目录编译完网页文件就在/home/ubuntu/ubuntu_sast_web/dist/。如果npm install报错多半是 Node 版本问题。本项目用 Node 16 最稳别用太新的版本。6. 配置 nginx把网页和后端拼到一起新建配置文件sudonano/etc/nginx/sites-available/sast粘贴以下内容dist路径按你实际的改server { listen 80; server_name _; # 网页 root /home/ubuntu/ubuntu_sast_web/dist; index index.html; location / { try_files $uri $uri/ /index.html; } # 以 /api/ 开头的请求转发给后端并去掉 /api 前缀 location /api/ { proxy_pass http://127.0.0.1:5000/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; client_max_body_size 100m; # SARIF 可能较大放宽上传体积 } }启用并重启 nginxsudoln-sf/etc/nginx/sites-available/sast /etc/nginx/sites-enabled/sastsudorm-f/etc/nginx/sites-enabled/default# 去掉默认站点避免冲突sudonginx-t# 检查配置有没有写错sudosystemctl reload nginx现在用浏览器打开http://你的服务器IP应该能看到登录页了。用admin / 123456登录。登进去后「项目/扫描列表」是空的——正常因为还没扫过任何东西。下一步就去扫。7. 安装扫描引擎 CodeQLcd/optsudowgethttps://github.com/github/codeql-action/releases/latest/download/codeql-bundle-linux64.tar.gzsudotar-xzfcodeql-bundle-linux64.tar.gz# 解压出 /opt/codeql 目录/opt/codeql/codeql--version# 能打印版本就装好了这个 bundle 已经自带了 Java 安全规则库包括我们要用的java-security-experimental.qls不用另外下规则。8. 扫描第一个项目真正跑一次项目里已经放好了扫描脚本deploy/scan_and_upload.py。它会编译代码 → CodeQL 分析 → 把规则和漏洞塞进数据库一条命令搞定。8.1 改脚本顶部的配置nano/home/ubuntu/deploy/scan_and_upload.py# 路径按你放的位置改开头这几行和你前面填的保持一致CODEQL/opt/codeql/codeql# 第 7 步的路径API_BASEhttp://127.0.0.1:5000# 后端地址一般不用改DBdict(host127.0.0.1,port3306,usersast,password你的密码,databasesec_sast,charsetutf8mb4)# 和第 3 步一致WORK_DIR/home/ubuntu/scan_work# 随便一个空目录脚本会自动建8.2 准备一份 Java 代码要扫的必须是能用 Maven 编译的 Java 项目有pom.xml。没有现成的可以先拿这个官方靶场练手故意留了很多漏洞cd/home/ubuntugitclone https://github.com/WebGoat/WebGoat.git8.3 开扫python3 /home/ubuntu/deploy/scan_and_upload.py webgoat /home/ubuntu/WebGoat参数说明webgoat 你给项目起的名字后面是代码目录。过程会比较久要真编译一遍代码 跑规则几分钟到十几分钟。看到最后打印✅ 上传完成打开网页进「扫描列表」找到webgoat-2026...就成功了。9. 在网页上看结果、做评审浏览器打开http://你的服务器IP用 admin/123456 登录。进扫描列表点刚才那次扫描就能看到扫出来的漏洞。点每条漏洞可以看污点从哪来、流到哪里source → sink → 数据流路径。对每条漏洞可以标记确认confirm 这是真漏洞忽略ignore 误报或可接受。状态含义全部忽略/没漏洞 no_error有待看的 reviewing有确认的真漏洞 error。以后再扫别的项目或者同一项目再扫一次重复第 8.3 步换项目名和目录即可。10. 上线前必做的安全加固 ⚠️这套代码是原型有几个默认的弱点正式用之前请务必处理改登录密码编辑ubuntu_sast/app/routes/login_routes.py把开头的USERNAME admin、PASSWORD 123456、SECRET_KEY ...全改掉改完重启后端。不要把 5000 端口和数据库直接暴露到公网只让 nginx 的 80或加了 HTTPS 的 443对外。后端只监听127.0.0.1:5000本手册已经这么配了数据库只允许本机访问。很多接口没有登录校验上传、读漏洞、读源码等。所以整台机器不要放公网裸奔放在内网或加一层网关/VPN 访问。数据库密码、任何密钥都别用示例值用你自己的强密码。11. 常见问题FAQQ网页打得开但登录/列表一直转圈或报错。A多半是前端接口地址没配对。确认第 5.2 步.env.production里是VUE_APP_BASE_API /api/且重新npm run build:prod过再确认 nginx 的/api/转发段没写错。浏览器按 F12 看「网络」里请求打到哪个地址是不是 404/502。Q502 Bad Gateway。A后端没起来。回到第 4.5 步确认 gunicorn 在跑curl 127.0.0.1:5000/userLogin能通。Q扫描脚本报数据库连接/外键相关错误。A检查脚本顶部DB配置和app/config.py是否一致确认第 4.4 步init_db.py跑过表和策略要先建好。Qcodeql database create失败。A基本都是代码本身编译不过。先单独在代码目录里手动跑一遍mvn clean package -Dmaven.test.skiptrue能编过了再扫。JDK 版本不对也会失败本手册用 JDK8。Q扫完了但网页里那次扫描显示 0 个漏洞。A可能这个项目确实没命中规则换 WebGoat 这种靶场一定能扫出东西用来验证链路是否通。12. 各步骤在装什么 —— 一句话回顾步骤装的东西作用2~3基础软件 MySQL地基 存数据4后端 Flask (gunicorn:5000)结果管理台大脑、提供接口5~6前端网页 nginx你在浏览器上看的界面7CodeQL真正的扫描引擎8scan_and_upload.py手动扫一个项目并把漏洞入库9——在网页上看漏洞、做评审跑通这套你就拥有了一个能实际使用的白盒扫描系统。想进一步做成「提交代码自动扫描 卡发布」就是在第 8 步的脚本外面接 Jenkins/流水线去自动触发——那是生产版的复杂度等基础版玩熟了再说。