简介以「产品说明—安装说明—使用说明—故障修复」四段式结构组织的 Fortify SCA 安装使用手册范本面向应用安全测试、代码审计人员以及希望将 Fortify SCA 纳入日常研发流程的团队完整覆盖工具特性、产品更新、安装文件准备、支持的系统平台、语言与编译器、Eclipse 插件配置等前置内容可当作企业安全规范文档、项目交付物或内部培训材料直接借鉴改编。压缩包共 1 个文件类型为 docx大小约 2MB便于按需修改、补充团队内部细节并做版本维护。范本在安装环节分 Windows、Linux、Unix 给出操作流程并单独说明 Eclipse 插件安装方式使用部分介绍扫描指南与扫描结果分析帮助读者理解分析视图、常见输出信息及结果判断方法故障修复则围绕日志调试和转换失败两类典型问题给出排查思路减少实际构建集成中的踩坑几率。资源已有 52 人学习适合需要快速落地 Fortify SCA 标准化操作手册的安全工程师或研发团队也适合用作内部安全培训的参考资料。1. 拿到一个叫“Fortify-SCA-安装使用手册范本.docx”的文件别急着当它只是安装文档如果你是安全负责人或研发工程师第一次接触 Fortify SCA大概率是团队要过等保或客户安全审计被要求“上静态代码扫描”。这时候别人丢给你一份《Fortify-SCA-安装使用手册范本.docx》你打开一看里面无非是环境要求、安装命令、扫描截图。但真正让这份文档有价值的不是安装本身而是它能不能让团队里任何一个人照着走完“装好 → 扫出结果 → 看懂结果 → 修复验证”的全流程并且让每次扫描的结果可复现、可对比。Fortify SCAStatic Code Analyzer是业界最常见的静态应用安全测试工具之一主打对 Java、JavaScript、C#、Python 等语言的源码级漏洞检测。它跟那些只做正则匹配的轻量工具不一样核心是“数据流分析”——从污染源追到危险函数所以能报出完整的攻击链。这篇笔记会把一份可落地的手册范本拆开讲安装时哪些组件必须认识、扫描命令怎么调参、结果怎么解读、哪些坑会让你一晚上白干。适合三类人刚接手 SCA 的运维、要给团队写扫描规范的开发负责人、以及被审计逼着补流程的安全工程师。2. Fortify SCA 到底装了什么先看懂组件再写安装手册很多人安装 SCA 就是一路下一步装完能跑个命令就觉得自己会了。实际上一套 SCA 包含四个角色完全不同的部分安装手册先要做的不是贴安装向导截图而是把组件关系画清楚。否则后续团队问“为什么我能扫描但看不到结果”“为什么审计工作台打不开别人的 FPR 文件”你根本没法回答。2.1 sourceanalyzer、Scan Wizard 与 Audit Workbench三个可执行文件对应三种使用场景Fortify SCA 安装目录的 bin 下至少有sourceanalyzer、scan、auditworkbench三个入口加上一个fortifyclient用于配合 CI。它们的关系是sourceanalyzer负责把源码翻译成中间模型scan负责跑规则引擎做漏洞匹配两者通常连在一起执行Audit Workbench审计工作台则是一个图形界面用来打开扫描生成的 FPR 文件做人工审计fortifyclient用于把扫描任务提交给 Fortify SSC软件安全中心做集中管理。手册里我会建议单独写一节“组件地图”用一张表列出每个可执行文件的名字、作用、什么时候用。别小看这步团队里最容易出现的翻车现场是有人直接在 Windows 上双击auditworkbench.exe然后问“为什么打不开 FPR”——多半是他拿到的 FPR 是 Linux 上用不同版本 SCA 生成的或者安装时根本没装审计台组件。2.2 安装手册里的系统要求表JDK、内存、磁盘一个都不能含糊SCA 对环境的挑剔程度超出大多数人的预期。它不是装完就能跑的轻量工具而是一个要吃掉大量内存做数据流分析的重量级引擎。手册里如果有系统要求表建议至少包含以下四行检查项建议要求原因JDK 版本JDK 8 或 JDK 11具体看当前 SCA 版本支持矩阵sourceanalyzer 启动依赖 JAVA_HOME版本不对会直接报 UnsupportedClassVersionError内存扫描机不低于 16GB推荐 32GBJava 大项目翻译阶段容易撑爆堆内存至少留 8GB 给 SCA 进程磁盘不少于被扫描项目体积的 10 倍翻译过程会产生中间文件默认在用户目录下的.fortify缓存操作系统Linux 与 Windows 均可同一份 FPR 最好在同一系统版本上生成和审计跨系统打开容易出兼容问题还要补一条安装路径不要带空格和中文。很多人不把这条当回事直到 CI 里拼接命令时发现路径被截断才回来改。FPR 文件路径同理建议全英文。2.3 安装完成后的自检命令三分钟确认装没装对安装手册里最容易被忽略的是“怎么验证安装成功”。很多人只写了安装向导的下一步截图用户照着装完却不知道是否可用。我会在手册里加一组自检命令让用户装完先跑一遍确认环境没问题再进入扫描环节。# 1. 确认 sourceanalyzer 可执行且能正确识别 Java 环境 sourceanalyzer -version # 2. 用一个极小目录做翻译扫描冒烟测试确认规则引擎正常 mkdir -p /tmp/fortify-smoke echo class A { String s null; } /tmp/fortify-smoke/A.java sourceanalyzer -b smoke-test -source 1.8 -encoding UTF-8 /tmp/fortify-smoke/A.java -f /tmp/smoke.fpr -format fpr -scan # 3. 确认 FPR 文件生成成功 ls -lh /tmp/smoke.fpr这三条命令每条都有明确目的第一条检查基础环境变量JAVA_HOME没配好或版本不对这一步就会报错第二条用一段故意写空的 Java 类做翻译 扫描的最小闭环能跑通说明规则包加载正常第三条确认产物落盘。如果第二步报“no rules were loaded”或“rulepack update required”说明安装时的规则包没有正确解压常见原因是安装时选了自定义组件导致 Rules 目录缺失。这组命令建议直接写进手册的“首次验证”章节让每个新环境都必须过一遍。3. 把扫描流程写进手册translate scan 两阶段最小命令Fortify SCA 的扫描不是“指定一个目录然后等结果”这么简单。它的执行逻辑分两个阶段translate翻译和 scan扫描。翻译阶段把源码解析成中间表示比如把 Java 字节码转成统一的 IR扫描阶段再把规则包里的漏洞模式套到 IR 上做数据流分析。两个阶段可以一条命令完成也可以分开执行但手册里必须讲清楚它们的区别否则用户面对超时、内存溢出根本不知道是哪一步挂的。3.1 为什么必须分两步翻译与扫描是两套独立的黑匣子翻译阶段的本质是把源代码变成一种与语言无关的中间模型。它会做语法解析、类型解析、调用关系构建听起来简单实际上对构建环境的依赖非常大。一个 Java Maven 项目如果依赖不完整翻译阶段就会漏掉大量第三方类的方法签名导致扫描结果漏报。而扫描阶段是在翻译产物上做规则匹配的它不接触源码只看中间模型。这就解释了三个常见现象第一为什么先mvn clean compile再扫描比直接扫.java文件准得多因为编译后的 class 文件带了完整类型信息第二为什么扫描同一个项目每次结果会不一样因为你可能没有-clean清掉上一次的翻译缓存第三为什么报错说“source file not found”因为翻译阶段没有把源码路径传给 sourceanalyzer。把这些写进手册让用户理解“两个阶段各自独立失败”比只丢一条命令有用得多。3.2 Java/Maven 项目的最小扫描命令与参数拆解一个 Java Maven 项目的完整扫描命令我通常会给出下面这组。注意它不是最短命令而是“最短的可复现命令”——加上-clean、-encoding和-log能让你在出错时不至于黑匣子式瞎猜。# 在 pom.xml 所在目录执行先把项目编译好并导出依赖 classpath mvn -DskipTests clean compile dependency:build-classpath -Dmdep.outputFilecp.txt # 指定 Fortify 的 build id并清掉之前的缓存 sourceanalyzer -b demo-build -clean # 翻译 扫描一条命令完成指定源码版本、编码、classpath输出 fpr sourceanalyzer -b demo-build -source 1.8 -encoding UTF-8 \ -cp target/classes:$(cat cp.txt) \ -f demo.fpr -format fpr \ -scan参数说明如下-b demo-build是 build id它是这次扫描的唯一标识后续增量扫描和结果对比都靠它建议用“项目名日期”命名比如order-service-20250601-clean会清掉该 build id 之前的所有中间数据避免旧翻译结果污染本次扫描这是踩坑率最高的参数——不加它你会扫描到一堆已经被删掉的旧代码-source 1.8指定源码语言版本决定了解析器按什么语法规则解析Java 项目如果源码用了高版本语法但这里写低了会报语法错误-encoding UTF-8解决中文注释乱码问题原因后面避坑章节详说-cp传入编译后的 class 目录和依赖 jar 的路径这是减少漏报的关键-f指定输出文件路径-scan触发规则匹配阶段。3.3 其他语言的扫描写法JavaScript、Python、C# 的参数差异手册里如果团队混合开发你得给每种语言一行最小命令。JavaScript 项目不需要-cp直接指定源码目录即可但 Vite/Webpack 打包后的代码扫描意义不大建议扫 src 目录Python 项目需要指定 Python 版本否则默认按旧语法解析会把f-string当语法错误C# 项目有专门的 msbuild 集成可以用-msbuild参数配合.sln文件进行。# JavaScript/TypeScript: 直接扫源码目录node 相关框架需要额外参数 sourceanalyzer -b web-ui -clean -encoding UTF-8 ./src -f web-ui.fpr -format fpr -scan # Python: 指定版本避免 f-string 等语法被误判 sourceanalyzer -b python-api -clean -source 3.8 -encoding UTF-8 ./app -f python-api.fpr -format fpr -scan # C#: 需要先还原 NuGet 依赖再用 msbuild 集成方式扫描整个解决方案 sourceanalyzer -b dotnet-api -clean -libdir ./packages ./Api.sln -f dotnet-api.fpr -format fpr -scan-libdir是 C# 项目用来告诉 SCA 依赖程序集在哪的参数效果和 Java 的-cp类似。没有它SCA 会对那些无法解析的类型生成不完整的调用图导致数据流断掉——比如一个用户输入的字符串进了某个方法后返回一个 objectSCA 看不到方法内部实现就可能报不全。这类参数细节建议在手册里以“语言快速参考”表格呈现而不是散落在长篇步骤里。3.4 输出格式与报告生成-f、-format 与 FPR 文件的去向很多人以为扫描结束拿到 PDF 报告就完事了这是对 SCA 最大的误解。PDF 只是一种渲染输出真相是事实源永远是 FPR 文件其他格式都是从 FPR 转录出来的。手册里必须写清楚FPRFortify Project Result才是唯一的原始扫描结果PDF/HTML/SARIF 都是从它生成的派生物。扫描时务必把-f result.fpr -format fpr作为必选固定参数审计工作台只认 FPR。如果团队要对接 DevSecOps 流水线SARIF 格式的价值大于 PDF因为它能被 IDE 插件和安全平台直接消费。输出格式对照表我一般这样写格式用途备注FPR审计、二次分析、增量对比唯一包含全部中间分析数据的格式PDF给管理层或审计方看的交付物不可二次分析仅用于展示HTML快速在浏览器里查看适合开发人员自测后自查SARIF对接 CI/CD 或 IDE 插件能被主流平台解析结构化字段完整XML老式平台集成部分老旧平台仍依赖此格式还不能漏掉增量扫描的用法。重新扫描整个大项目很费时间常用做法是用-o old.fpr指向上次的 FPR 做增量分析只报告新增或变更代码引入的漏洞。这个参数叫“old FPR”不是“output”注意别和-f搞混我见过不止一个人把-o和-f写反导致结果文件被覆盖。4. 结果解读与规则配置是手册里最容易写空的一章安装手册如果写到“扫描完成生成报告”就结束那这份手册的实际价值要打个对折。因为对团队来说最难的不是把扫描跑起来而是跑完之后怎么办。漏洞列表里上千条 issue哪些是真问题哪些是误报怎么分派给开发修复后怎么验证这些如果不写成规范SCA 上了线也是摆设。4.1 从 FPR 到报告审计工作台里必须定下三个动作审计工作台打开 FPR 后界面会按 Tag 分类显示漏洞。但如果没有约定每个人的处理方式都不一样有人把误报直接删掉有人给 issue 标状态不删。我的习惯是在手册里规定三个动作过滤、分派、标记。过滤靠的是左侧的 Filter 面板按高/中/低或漏洞类型筛出当前版本必须解决的 Critical 项分派是把每个 issue 分配到具体开发通过设置 issue 的状态字段实现常见状态流是“新建 → 已分配 → 已修复 → 已验证”标记则是处理误报用“Not an Issue”标记并附上评论说明原因。这三个动作全部通过审计工作台完成而且是可追溯的——每一次状态变更都有记录。这相当于给团队定了一个轻量级的漏洞管理流程不依赖外部平台也能运转。如果有 Fortify SSC还可以把 FPR 上传上去做统一统计但那是后话手册里先落地 Workbench 就够。4.2 规则包更新为什么新漏洞检测依赖这件小事规则包Rulepack是 SCA 判断你代码有没有漏洞的“知识库”它决定扫描器认识哪些漏洞模式。一年不更新规则包新增的漏洞模式就不会被扫描出来。但更新规则包有一个扎心的副作用规则数据更新了同样一份代码的扫描结果会变多报或少报都可能出现。这意味着手册里必须有一条“更新规则包后要重建基线”的约定。实际操作很简单SCA 安装目录下有一个 rules 目录里面是.bundle规则包文件。离线环境拿不到新规则时常见做法是找一台能连外网的机器把更新包下载后拷进来或者在 SCA 安装包里找到 Update Center 工具。但无论哪种方式更新后别急着直接拿新规则比对历史结果——先对主项目重新扫一遍生成新基线。这个动作能避免“明明没改代码漏洞数却涨了”的尴尬局面。规则的版本管理建议这样把 rules 目录打成压缩包按日期命名存档这样出问题可以随时回滚相当于给规则上了后悔药。4.3 自定义规则哪些场景千万别瞎写SCA 支持自定义规则允许你写 XML 规则文件放进 customrules 目录让扫描器识别自有框架里的危险函数。但这条线公开的教训特别多。最常见的坑是对“配置类误报”强行上自定义规则去压制结果规则写太宽把真漏洞也滤掉了。我见过最典型的一个失败案例是有人为了消除“Hardcoded Password”的误报写了一条把所有赋值给config对象的字符串都视为安全的规则——结果真密码也被放过了。自定义规则的正确打开方式是识别自有代码库里的污染源和汇聚点比如你公司的网关框架里有一个getHeader()方法SCA 不知道它其实是用户输入这时写一条规则把它声明为Source类型才是有效的。规则文件的骨架很简单RuleDefinition Rule idCustomSourceRule typeTaintSource Description自定义网关请求头作为污染源/Description MetaData Attributes Attribute namecategoryCustom Source/Attribute /Attributes /MetaData TaintSource Match typemethod namegetHeader packagecom.example.gateway/ Return typejava.lang.String/ /TaintSource /Rule /RuleDefinition这段 XML 的逻辑是当代码里出现com.example.gateway包下某类的getHeader()方法返回字符串时SCA 会把这个返回值视为不可信输入从它往下追踪数据流。注意RuleDefinition根节点不能少且规则文件要用 UTF-8 编码保存并放在 customrules 目录下重启生效。诊断规则写得比代码还复杂的场景我的建议非常直接如果规则超过了十行还带一堆条件很可能是错误的思路不如接受这条误报并在审计工作台里手动标记为压制一条误报引入漏报风险不值当。5. 安装与扫描的避坑清单现象、原因、解决这章是我最想写的部分。Fortify SCA 的报错信息经常语焉不详出门全靠猜。以下五条是团队使用中踩过的高频坑按“现象 → 原因 → 解决”写照做可以省掉大量试错时间。5.1 先看这个扫描跑到一半进程退出没有任何错误输出现象扫描命令执行到一半终端直接回到 shell 提示符没有报错也没有生成 FPR。原因SCA 扫描阶段内存溢出JVM 被杀掉。这是大项目最常见的失败方式因为翻译阶段或扫描阶段默认堆内存不够。解决给 SCA 的启动脚本加上内存参数常见做法是在sourceanalyzer前设置_JAVA_OPTIONS环境变量。具体命令如下按需把堆大小调到适合项目规模的值export _JAVA_OPTIONS-Xmx8G -Xss2M sourceanalyzer -b big-project -clean ./src -f result.fpr -format fpr -scan注意-Xmx8G决定 JVM 最大堆如果机器只有 16G 内存建议给扫描进程 8G 上限给系统留出余量否则系统本身会先卡死。调整后如果依然退出看一下系统日志的 OOM kill 记录如果是 Linux用dmesg | tail检查。另外还有一个容易被忽略的点sourceanalyzer的翻译和扫描是同一进程执行的如果确定卡在翻译阶段可以考虑先单独跑翻译、再单独跑扫描分两步能定位到底哪一步在吃内存。5.2 扫描报告里的日志中文全变乱码现象审计工作台里看到的代码片段和注释是乱码或者日志输出中中文显示为???。原因SCA 翻译源码时没有指定正确的文件编码。Windows 中文环境下源码常是 GBKLinux 下是 UTF-8如果统一按默认编码解析解析器会把字节流拆错。解决翻译阶段显式指定编码和源码实际编码保持一致。对绝大多数现代项目来说就是下面这样sourceanalyzer -b demo-build -encoding UTF-8 -source 1.8 ./src -f demo.fpr -format fpr -scan如果源码用了 GBK 编码把-encoding改成GBK。还有一层保障同步设置JAVA_TOOL_OPTIONS-Dfile.encodingUTF-8保证扫描进程自身输出日志时不会损坏多字节字符。这个坑特别隐蔽因为它不影响扫描是否成功只影响结果展示——如果你不看代码片段甚至根本不会发现。5.3 依赖解析卡死Maven 项目翻译阶段一直卡在下载依赖现象sourceanalyzer扫描 Maven 项目时进度停在某处长时间不动或者直接报找不到某个 jar 的类定义。原因SCA 在做类型解析时需要读取第三方库的 class 文件而你没有把依赖 classpath 传进去它试图自己从 Maven 仓库拉取拉不到就卡死。解决翻译前把依赖 classpath 导出到本地文件然后明确传给 SCA。具体做法见第 3 章的完整命令mvn -DskipTests dependency:build-classpath -Dmdep.outputFilecp.txt sourceanalyzer -b demo-build -cp target/classes:$(cat cp.txt) ./src -f demo.fpr -format fpr -scan有人会问直接扫src/main/java不指定 classpath 不行吗行但扫描结果的质量会明显下降——类型信息不全数据流分析无法跨方法追踪漏洞会漏报或报成“不可达”。另外如果项目里有多个模块需要把每个模块的 target/classes 和所有依赖 jar 都拼到-cp里所以建议用脚本拼接而不是手写路径。5.4 扫描结果里全是旧代码的漏洞明明已经删掉的文件还在报现象删除了一个 Java 文件并重新扫描漏洞列表里依然能看到该文件的 issue甚至数量和上次一模一样。原因没有用-clean清理 build id 的翻译缓存。SCA 会把本 build id 的历史翻译结果缓存起来如果新扫描没有清理它会和历史数据混在一起分析。解决在每次全量扫描前加-clean参数。注意-clean加在翻译阶段也就是要放在 build id 之后、源码路径之前sourceanalyzer -b demo-build -clean ./src -f demo.fpr -format fpr -scan如果项目结构里有target/或dist/这类构建产物目录强烈建议在传给 SCA 的源码路径中排除它们。常见的做法是用-exclude参数指定需要排除的目录每次扫描时执行sourceanalyzer -b demo-build -clean -exclude target -exclude dist ./src -f demo.fpr -format fpr -scan不排除 target 目录的后果编译产物中的 class 会被再次当作扫描对象出现大量重复 issue 和误报。如果你发现扫描时间异常长先怀疑是不是把构建产物也扫进去了。5.5 审计工作台打不开 FPR报“版本不支持”或直接崩溃现象开发同事从 CI 系统下载 FPR 文件后在本地审计工作台打开时报错或者打开后漏洞列表为空。原因FPR 文件由高版本 SCA 生成本地审计台版本太低或反向本地版本高于生成版本。FPR 结构在不同版本间有差异SCA 对低版本生成的 FPR 兼容较高但对新版本生成的旧文件兼容较差。解决让本地审计工作台与扫描机上的 SCA 保持同版本这是最省心的做法。如果确实需要跨版本打开用扫描机上的 auditworkbench 打开后另存为一个新版本 FPR 再拷走。另外FPR 文件路径中不要包含中文或空格某些版本对这类路径的处理有 bug会导致打开后白屏。这两个问题都是环境层面的手册里把“审计台与扫描器同一版本”放在“使用约定”一节中能省掉大量无谓的工单。6. 让手册范本真正落地章节骨架与验证动作一份《Fortify-SCA-安装使用手册范本.docx》值不值得沿用就看它有没有让读者形成一个“照做不会错”的心智。我在维护多套扫描环境后把手册固定成六节环境要求、安装步骤、首次验证、日常扫描、规则更新、应急排查。其中“首次验证”就是第二章里的sourceanalyzer -version和冒烟扫描“日常扫描”就是第三章的 translate scan 两条命令。“应急排查”这节我会把第五章的避坑清单压缩成一张二维表现象列、检查动作列、解决命令列。不写长段落只写“内存被杀 → 查 dmesg → 加大-Xmx”这样现场处理的人能对上号秒操作。规则更新那节要写死一条规矩更新后必须重新跑全量扫描生成新基线 FPR并存档旧 FPR 和规则包版本号否则未来对比漏洞增量时根本说不清变化是代码引入的还是规则引入的。最后给你一个自检标准找团队里一个没装过 Fortify SCA 的同事把手册丢给他只许看手册操作如果他能独立完成安装、扫描、打开 FPR 看到结果且没有向你提问说明这份手册合格。我最早写这类手册时就吃了只写安装不写验证的亏团队十几个人装完环境各自踩坑五天都没跑通一个完整扫描。后来每加一章必配一条验证命令问题当场暴露手册才能真正从“阅后即焚”变成团队的资产。希望这份拆解能帮到你照着这个骨架去补全自己的 SCA 手册会比从零开始省下不止一个通宵。本文还有配套的精品资源点击获取