简介：以「产品说明—安装说明—使用说明—故障修复」四段式结构组织的 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 SCA（Static 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 对环境的挑剔程度超出大多数人的预期。它不是装完就能跑的轻量工具，而是一个要吃掉大量内存做数据流分析的重量级引擎。手册里如果有系统要求表，建议至少包含以下四行：

还要补一条：安装路径不要带空格和中文。很多人不把这条当回事，直到 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.outputFile=cp.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 会对那些无法解析的类型生成不完整的调用图，导致数据流断掉——比如一个用户输入的字符串进了某个方法后返回一个 object，SCA 看不到方法内部实现，就可能报不全。这类参数细节建议在手册里以“语言快速参考”表格呈现，而不是散落在长篇步骤里。

3.4 输出格式与报告生成：-f、-format 与 FPR 文件的去向

很多人以为扫描结束拿到 PDF 报告就完事了，这是对 SCA 最大的误解。PDF 只是一种渲染输出，真相是：事实源永远是 FPR 文件，其他格式都是从 FPR 转录出来的。手册里必须写清楚：FPR（Fortify Project Result）才是唯一的原始扫描结果，PDF/HTML/SARIF 都是从它生成的派生物。扫描时务必把-f result.fpr -format fpr作为必选固定参数，审计工作台只认 FPR。如果团队要对接 DevSecOps 流水线，SARIF 格式的价值大于 PDF，因为它能被 IDE 插件和安全平台直接消费。输出格式对照表我一般这样写：

还不能漏掉增量扫描的用法。重新扫描整个大项目很费时间，常用做法是用-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 id="CustomSourceRule" type="TaintSource"> <Description>自定义网关请求头作为污染源</Description> <MetaData> <Attributes> <Attribute name="category">Custom Source</Attribute> </Attributes> </MetaData> <TaintSource> <Match type="method" name="getHeader" package="com.example.gateway"/> <Return type="java.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 中文环境下源码常是 GBK，Linux 下是 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.encoding=UTF-8"，保证扫描进程自身输出日志时不会损坏多字节字符。这个坑特别隐蔽，因为它不影响扫描是否成功，只影响结果展示——如果你不看代码片段，甚至根本不会发现。

5.3 依赖解析卡死：Maven 项目翻译阶段一直卡在下载依赖

现象：sourceanalyzer扫描 Maven 项目时，进度停在某处长时间不动，或者直接报找不到某个 jar 的类定义。

原因：SCA 在做类型解析时需要读取第三方库的 class 文件，而你没有把依赖 classpath 传进去，它试图自己从 Maven 仓库拉取，拉不到就卡死。

解决：翻译前把依赖 classpath 导出到本地文件，然后明确传给 SCA。具体做法见第 3 章的完整命令：

mvn -DskipTests dependency:build-classpath -Dmdep.outputFile=cp.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 手册，会比从零开始省下不止一个通宵。

本文还有配套的精品资源，点击获取