SourceFare压缩包扫描方案：离线代码审计的自动化实践

做代码扫描这么多年，我越来越觉得“如何把代码喂给扫描器”这件事，才是整个流程里最容易被低估的环节。大多数教程讲的是仓库集成、CI流水线、MR门禁，但现实中有一大批项目是拿不到仓库权限的：外包交付、离线网闸环境、历史遗留系统、客户只给一个源码压缩包，甚至本地代码连git仓库都还没建。SourceFare这个项目就是为这类场景做的——用户把代码打成zip或tar.gz上传，平台自动解压、识别语言、生成扫描配置，调用底层的SonarQube完成分析，最后在Web界面里拿到一份完整报告。

SourceFare的定位很清晰：不重复造扫描规则引擎的轮子，专注解决“拿到一份代码包，怎么快速得到扫描结论”这个链路问题。它面向的主要是DevSecOps工程师、安全审计人员、外包验收人员，也包括那些只是想在本地临时给项目做个代码体检的开发者。这篇文章我会把SourceFare从设计思路到核心代码、再到实际排障的完整内容都拆开讲，方便你照着搭一套属于自己团队的“压缩包代码扫描”能力。

1. 为什么不直接连仓库，而是绕一圈上传压缩包

1.1 三种主流扫描接入方式的对比

先说结论：代码扫描工具的接入方式不能只有“连仓库”这一种。SourceFare刚立项的时候，我们团队内部争论过一轮，有人觉得现在大家都在做CI/CD集成，做一个上传压缩包扫描的工具是不是有点倒退。后来列了一张表，发现根本不是谁替代谁的问题，而是每个接入方式都有自己不可替代的适用角落。

从表里能很直观看到，压缩包上传扫描的核心价值是“无仓储依赖、一次上传集中扫描”。它没有一个版本库地址的概念，不关心代码是从Git、SVN还是外网拷贝来的，只要代码打包能送进来，就能扫。这个特性放在如今的供应链安全背景下非常关键——很多时候源代码的流转根本不会经过版本库，压缩包就是唯一的交付形态。

1.2 三个让我下决心做压缩包扫描的真实场景

第一个场景是外包代码验收。供应商交付源码时，通常会提供一个打包好的源码压缩包，附带一份交付清单，但不提供仓库权限，甚至明确要求我们不得直接访问他们的版本库。这时候如果还坚持走SCM集成，流程直接卡死。SourceFare按压缩包接收，反而能用一套统一的扫描规则去约束所有供应商，谁家的代码问题多，一目了然。

第二个场景是隔离网络环境。一些安全要求比较高的项目里，生产网络和开发网络是物理隔离的，代码通过文件摆渡的方式送进扫描区。扫描区里的机器可能连DNS都无法解析版本库域名，更不用说拉取代码了。这时候唯一的办法就是把代码打成压缩包，通过刻盘或隔离文件交换设备送进来，在隔离网络内部部署一套SourceFare完成扫描。

第三个场景是本地未提交代码的快速体检。开发机上有大量未提交改动，或者接手了一个历史项目，根目录里连.git文件夹都没有。传统做法是让开发自己装SonarScanner在命令行跑，但对不熟悉工具链的新人来说，配置sonar-project.properties本身就够劝退的。包成压缩包上传到Web平台，点击上传就能看到结果，反馈成本低得多。

当然也要说清楚局限：压缩包方案做不了增量分析，也不能对分支、MR做差异门禁。它扫的是当前快照。所以如果你的目标是嵌入研发流程做持续质量管控，还是得走SCM集成或CI接入。SourceFare做的是那些“正式流程覆盖不到”的补充环节。

2. SourceFare核心设计：一份压缩包如何变成一份扫描报告

2.1 整个流程拆成四个模块

SourceFare从功能上可以拆成四层：文件接收层、解压与识别层、扫描调度层、结果展示层，每一层只干一件事。

文件接收层负责接收上传的zip/tar.gz文件，处理的不只是“把文件落盘”，还包括压缩包格式校验、文件大小限制、文件数量检查，甚至会在写入磁盘前先扫描一下文件名有没有异常。解压与识别层负责把压缩包解压到临时工作目录，然后通过项目根目录的特征文件判断技术栈。比如根目录有pom.xml认为是Java Maven工程，有package.json认为是Node工程，有go.mod是Go工程，有requirements.txt或pyproject.toml就是Python工程。这一步的结果会直接影响下一步生成的扫描配置。

扫描调度层根据识别结果生成sonar-project.properties，然后调用本机的sonar-scanner完成分析。扫描完成后，通过SonarQube的REST API拉取任务状态和指标数据。结果展示层把bugs、vulnerabilities、code smells、coverage、duplicated lines等数据汇总展示到SourceFare自己的Web界面，同时支持导出成报告，方便在验收流程里留档。

这里有个设计选择值得展开讲：为什么SourceFare不自己实现静态分析，而是把SonarQube放在底层？答案很简单，SonarQube有着十多年积累的规则引擎和语言分析插件，任何团队想完全自研一套同等规模的静态分析规则，投入都是巨大的，而且效果大概率不如人家。SourceFare的价值增量在于“流程自动化”，即拿到一个压缩包后，从解压到配置到执行到取结果，中间所有需要人工干预的环节全部自动化。

2.2 上传与解压：绕不开的Zip Slip安全坑

压缩包上传最容易翻车的不是扫描，而是解压。如果直接把zipfile.extractall跑起来，攻击者可以构造一个包含“../”路径的文件名，让解压路径跳出预设的工作目录，覆盖服务器任意文件，这就是经典的Zip Slip漏洞。这个问题我在源码包扫描这个场景里尤其在意，因为扫描平台面临的往往不是可信内部人员，而是外部供应商上传的包，恶意构造一个压缩包试探平台底线的事情是真实存在的。

我实现安全解压的核心逻辑很简单，核心就两条：一是规范化路径，二是校验目标路径是否还在预定的工作目录内。Python里可以这样写：

python复制import zipfile
from pathlib import Path

def safe_extract(zip_path: Path, extract_dir: Path) -> None:
    with zipfile.ZipFile(zip_path, "r") as zf:
        for member in zf.namelist():
            # 将压缩包里的文件名解析为绝对路径，检查是否跳出目标目录
            member_path = Path(member)
            safe_target = (extract_dir / member_path).resolve()
            if not safe_target.is_relative_to(extract_dir.resolve()):
                raise ValueError(f"非法路径，疑似 zip-slip 攻击: {member}")
        zf.extractall(extract_dir)

除了路径安全，上传侧还要做几个硬性限制：压缩包大小建议限制在500MB以内，解压后的文件总数建议不超过5万个，压缩包总压缩比不能高得离谱。压缩比异常高的包，解压时可能瞬间撑爆磁盘，这属于解压炸弹攻击。SourceFare在接收层会对这些做校验，一旦超出阈值直接拒绝并返回错误信息，而不是让后续环节崩溃。

2.3 语言识别与项目根目录定位

代码压缩包和仓库的最大区别是：仓库有清晰的结构约定，压缩包没有。同一个Java项目，有人压缩时把项目根目录直接打进zip，有人会把外层再包一层目录。如果不做项目根目录识别，扫描器很可能对着一个错误的目录分析半天，最终结果是“No files analyzed”。

SourceFare的识别策略是“特征文件优先”，按优先级从上到下匹配。

识别出语言后，SourceFare会在解压目录里查找特征文件的具体位置，把其所在目录作为“项目根目录”。比如解压后目录结构是source/payment-adapter/，而pom.xml在source/payment-adapter/pom.xml，那项目根目录就是source/payment-adapter，后面生成的sonar-project.properties会放在这里。

对于多模块项目，比如一个父pom带着多个子module的Java工程，SourceFare会判断根pom里的modules标签，如果存在，就把父pom目录作为分析和扫描的基准目录。SonarQube的Java分析器支持多模块自动聚合，但前提是sonar.projectBaseDir指向正确。压缩包扫描场景下，这个baseDir通常就是解压出来的临时工作目录本身，配置好之后基本不用人工介入。

2.4 扫描执行与结果回传的细节

扫描调度的执行过程不是简单的“命令跑完就结束”。因为一次压缩包扫描可能耗时几分钟到几十分钟，SourceFare把扫描任务放进异步队列里执行，而不是让HTTP请求同步等待。队列方案用的是Celery加Redis，轻量场景直接用Redis就够。

任务进入队列后，worker按顺序执行以下步骤：

1. 创建以任务ID命名的临时工作目录。
2. 执行安全解压。
3. 识别语言并定位项目根目录。
4. 生成sonar-project.properties。
5. 调用sonar-scanner命令执行扫描。
6. 轮询SonarQube的API，确认分析任务结束。
7. 拉取指标，把数据写入数据库并更新任务状态。

拉取结果的代码不算复杂，但有一个细节特别容易踩坑：SonarQube使用token调用API时，不是把token放到Authorization头里，而是使用HTTP Basic Auth，用户名随便填，密码填token。我第一次集成时把token当成Bearer Token传，结果一直返回401，后来翻官方文档才明白。

python复制import requests

SONARQUBE_URL = "http://localhost:9000"
TOKEN = "sqa_xxxxxxxx"

def fetch_measures(component_key: str) -> dict:
    metrics = "bugs,vulnerabilities,code_smells,coverage,duplicated_lines_density,security_hotspots"
    url = f"{SONARQUBE_URL}/api/measures/component"
    params = {
        "component": component_key,
        "metricKeys": metrics
    }
    resp = requests.get(url, params=params, auth=(TOKEN, ""), timeout=30)
    resp.raise_for_status()
    data = resp.json()
    result = {}
    for item in data.get("component", {}).get("measures", []):
        result[item["metric"]] = item["value"]
    return result

这套结果拉取的逻辑稳定跑了大半年。有一点要提醒：如果扫描直接在前台subprocess.run里同步执行，一旦压缩包很大，整个后端接口会长时间占用，这是最常被忽略的并发设计隐患。SourceFare从一开始就把任务状态字段设计出来，任务创建后立即返回task_id，前端轮询任务状态，用户不会在浏览器里干等。

3. 实操演练：从上传压缩包到产出扫描报告

3.1 准备一套可复现的扫描环境

要跑通SourceFare，底层至少需要SonarQube服务端、SonarScanner命令行工具和一个能跑SourceFare后端的环境。这里用一个最小的Docker Compose把SonarQube服务和PostgreSQL数据库一起起起来。

yaml复制version: "3.9"
services:
  sonarqube:
    image: sonarqube:lts-community
    container_name: sonarqube
    depends_on:
      - db
    environment:
      SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonar
      SONAR_JDBC_USERNAME: sonar
      SONAR_JDBC_PASSWORD: sonar
    ports:
      - "9000:9000"
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_extensions:/opt/sonarqube/extensions

  db:
    image: postgres:13
    environment:
      POSTGRES_USER: sonar
      POSTGRES_PASSWORD: sonar
      POSTGRES_DB: sonar
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  sonarqube_data:
  sonarqube_extensions:
  postgres_data:

启动之后访问http://localhost:9000，默认账号admin/admin，第一次登录会强制改密码。改完之后在“My Account -> Security”里创建令牌，SourceFare后端就靠这个令牌向SonarQube提交扫描和拉取结果。

SonarScanner要安装在SourceFare后端所在的主机。Linux下下载解压后把bin目录加进PATH即可，装好后先执行sonar-scanner -v确认版本正常。这里有个容易忽略的坑：如果SourceFare后端跑在容器里，要注意容器能否通过主机名访问到SonarQube的9000端口。很多人本地命令行扫得好好的，一放进容器就跑不通，多半是网络模式没配好，容器内的localhost指向的是容器自己。

3.2 后端核心代码：把上传到扫描串起来

下面是SourceFare后端用FastAPI写的上传接口简化版。它把从接收文件到返回结果的整个主流程串了一遍，核心逻辑可以直接抄到自己的项目里：

python复制import shutil
import subprocess
import tempfile
from pathlib import Path

from fastapi import FastAPI, File, UploadFile

app = FastAPI()
UPLOAD_DIR = Path("/data/sourcefare/uploads")
WORK_DIR = Path("/data/sourcefare/workspace")

@app.post("/api/scan")
async def upload_and_scan(file: UploadFile = File(...)):
    task_id = generate_task_id()
    zip_path = UPLOAD_DIR / f"{task_id}_{file.filename}"

    # 保存压缩包
    with zip_path.open("wb") as buffer:
        shutil.copyfileobj(file.file, buffer)

    # 安全解压
    extract_dir = WORK_DIR / task_id
    extract_dir.mkdir(parents=True)
    safe_extract(zip_path, extract_dir)

    # 识别语言、生成扫描配置
    lang = detect_language(extract_dir)
    props = extract_dir / "sonar-project.properties"
    props.write_text(build_sonar_properties(task_id, lang), encoding="utf-8")

    # 调用 sonar-scanner
    subprocess.run(["sonar-scanner", f"-Dproject.settings={props}"],
                   cwd=extract_dir, check=True, timeout=1800)

    # 拉取指标
    measures = fetch_measures(f"sourcefare_{task_id}")

    return {"task_id": task_id, "measures": measures}

build_sonar_properties函数里，生成的内容大致如下：

properties复制sonar.projectKey=sourcefare_20250118_153200_abcd
sonar.projectName=thirdparty-payment-adapter
sonar.projectVersion=1.0.0
sonar.sources=.
sonar.sourceEncoding=UTF-8
sonar.java.binaries=
sonar.exclusions=**/node_modules/**,**/dist/**,**/build/**,**/target/**,**/.git/**,**/coverage/**

有几个细节单独说。

sonar.sources在SourceFare里不是无脑填“.”，而是会根据上一步识别出的项目根目录动态算出相对路径。如果项目根目录就是解压目录本身，填“.”没问题；如果源码在二级甚至三级目录下，就必须填对应路径，否则扫描结果大概率是空的。sonar.exclusions里的排除规则则是SourceFare在生成配置时自动附加的，目的是把构建产物和依赖目录从分析范围里剔除，这能显著提升扫描速度。

还有一个Java项目特有的细节：空着的sonar.java.binaries并不是什么参数都传了。对纯源码扫描场景，SourceFare会把sonar.java.source设置为当前JDK的版本；但如果你明确知道压缩包里带了编译产物，或者在构建流程里能拿到class文件，那最好把sonar.java.binaries指向target/classes或build/classes。否则Java项目里很多依赖字节码上下文的规则，比如空指针、资源未关闭之类的检查项，会因为缺少上下文而漏报。

3.3 用curl做一次完整的扫描

假设我们拿到了一个名为payment-adapter的项目，目录在~/projects/payment-adapter。先打包，注意打包时把不必要的内容排除掉：

bash复制cd ~/projects/payment-adapter
zip -r payment-adapter.zip . -x "node_modules/*" -x ".git/*" -x "dist/*"
curl -X POST -F "file=@payment-adapter.zip" http://localhost:8000/api/scan

如果SourceFare后端正常启动，这条curl会返回一个JSON，里面包含task_id和measure数据：

json复制{
  "task_id": "task_20250118_153200",
  "measures": {
    "bugs": "12",
    "vulnerabilities": "3",
    "code_smells": "215",
    "coverage": "",
    "duplicated_lines_density": "6.8",
    "security_hotspots": "28"
  }
}

这时的扫描结果是同步等待出来的。真实项目里SourceFare返回的应该是task_id，而measures字段要通过后续请求获取，避免大包扫描把HTTP连接占用太久。我第一次实现时图省事，直接同步执行，结果一个200MB的包把整个接口挂住了将近一小时，前端一直转圈，这是个非常典型的反面教材。

3.4 报告里到底看什么

扫描完成后，打开SonarQube界面，点进同名项目，看到的就是这次压缩包快照的完整分析结果。重点看四类指标：

Bugs和Vulnerabilities是代码的缺陷和安全漏洞，按严重程度分为Blocker、Critical、Major、Minor。外包验收时我们通常把Major以上的问题数量作为第一道门槛。Code Smells是维护性导向的问题，不一定影响当前功能，但会显著提高后续改造成本。Coverage覆盖率在压缩包扫描场景下通常拿不到，因为需要执行测试才能生成覆盖率数据，纯源码包没有这个上下文。Duplicated Lines重复代码行，这个依赖语言插件的跨文件分析，扫描后能很快看出有没有大段的复制粘贴代码。

这里要明确一点：SourceFare并不改变SonarQube的扫描规则，也不对指标做二次加工。它做的是让同一个SonarQube实例能更方便地接收“非仓库形态”的代码，报告里的每一项指标都还是SonarQube规则引擎算出来的，权威性和手工扫描完全一致。

4. 常见问题与排查实录

4.1 问题速查表

压缩包扫描落地过程中，踩过的坑基本都有共性。我把诊断经验整理成了一张速查表：

4.2 实录一：扫描飞快但“No files analyzed”

有一次，上传一个Java压缩包后，SourceFare几乎瞬间返回了结果，但SonarQube项目里显示分析文件数为0。打开扫描日志，发现sonar-scanner正常连接服务端，没有任何报错，就是没有分析到源码。

排查的思路是这样展开的：第一，确认解压目录里是不是真的有源码；第二，看生成的sonar-project.properties里sonar.sources指向哪里；第三，看压缩包解压后是不是多了一层文件夹。最终定位到最后一个原因——压缩包在项目根目录外包了一层目录，目录层级变成了source/payment-adapter/server/src/java/xxx，而sonar-project.properties放在了解压根目录，sonar.sources又是“.”，SonarQube在这个层级上没有识别出Java源码。

解决办法不复杂，把sonar.sources显式指向实际的源码根目录，而不是无脑用“.”。这件事也印证了语言识别模块里“定位项目根目录”这一步的必要性——压缩包没有统一目录规范，自动识别根目录必须前置，否则后续配置全是错的。

还有一个常见的相关问题：新版SonarQube推荐让分析器自动识别语言，不建议在配置里硬写sonar.language。只有多语言工程或自动识别明确失败时才需要手动指定。我们排查过几次“代码没分析到”的问题，最后发现是配置文件里写死了sonar.language=java，而压缩包里实际上是Kotlin代码，语言插件直接不匹配。

4.3 实录二：解压后的文件权限导致扫描器读不到

另一个印象深刻的坑和权限有关。SourceFare早期部署在单独的一台Linux服务器上，上传进程使用root启动，解压出来的文件owner是root，权限是700。而sonar-scanner进程是另一个运维账号启动的，扫描时连解压目录都进不去，分析自然全部失败。

这个问题在容器化部署里更隐蔽。如果SourceFare容器以root运行，而SonarScanner容器或宿主机进程以uid=1000运行，就会出现“上传能成功、解压能成功、扫描永远失败”的诡异现象。

解决方法是解压完成后，统一对工作目录执行chmod -R a+rX，确保扫描进程有读取权限。更规范的做法是SourceFare容器固定以非root用户运行，比如uid=1000，并在入口脚本里把工作目录的owner设置成该用户。这样既避免权限问题，也减少容器以root运行带来的安全风险。

5. 压缩包扫描的效率优化与验收落地

5.1 压缩前的“减法”原则

影响压缩包扫描耗时最直接的因素，不是代码量，而是压缩包里塞了多少不该塞的东西。我自己有过一次非常直观的数据对比：一个常见的Spring Boot项目，未清理时压缩包约180MB，包含node_modules、target、日志文件，扫描耗时30分钟；清理后压缩包只有8MB，扫描耗时3分钟。10倍的差距，压缩包里的垃圾占了很大比例。

所以SourceFare在帮助文档和上传页面上都会强调“压缩前先做减法”：

• 删除.git目录，它体积大且SonarQube默认排除，没必要打包。
• 删除node_modules、target、build、vendor、dist等构建产物和第三方依赖目录。
• 检查是否有日志文件、图片、视频等非源码资源，这些对静态分析没有任何意义。

如果你不想让团队成员手动处理，SourceFare在解压后也会做一次“硬排除”，即无论压缩包里有没有这些目录，生成的sonar-project.properties都会自动加上对应的exclusions。这样做能保证扫描效率，也能避免第三方代码被误纳入分析范围，导致问题数量统计失真的情况。

5.2 增加质量门禁状态，让扫描结果直接支撑验收

压缩包扫描做多了之后，我发现光把指标展示出来还不够。外包验收场景里，安全团队最关心的是“这个包能不能过审”。与其让每个人打开SonarQube界面手工判断，不如在SourceFare里直接集成质量门禁状态。

调用SonarQube的质量门禁API，代码很短：

python复制def fetch_quality_gate_status(project_key: str) -> str:
    url = f"{SONARQUBE_URL}/api/qualitygates/project_status"
    resp = requests.get(url