licensefinder/license_finder

Pivotal License Finder 镜像文档

镜像概述

Pivotal License Finder 是一款专注于开源许可证合规性管理的工具镜像，基于Ruby开发，旨在自动识别项目依赖项的许可证信息，帮助开发团队和企业确保使用的开源组件符合内部合规策略及外部***要求。该镜像集成了许可证扫描引擎、依赖解析器和报告生成模块，支持主流开发语言和构建工具，可无缝集成到开发和CI/CD流程中。

核心功能与特性

• 多语言与包管理器支持：兼容Java(Maven/Gradle)、JavaScript(npm/yarn)、Python(pip)、Ruby(Bundler)、Go(mod)等主流技术栈
• 全面的许可证识别：内置许可证数据库，可识别超过200种开源许可证（如MIT、Apache-2.0、GPL等）及其变体
• 合规报告生成：支持HTML、JSON、CSV等多种输出格式，报告包含依赖明细、许可证类型、合规状态等关键信息
• 冲突检测与风险提示：自动识别许可证冲突（如GPL依赖与商业项目冲突），并提供风险等级评估
• 灵活的配置策略：支持自定义允许/禁止许可证列表、忽略特定依赖或许可证规则
• CI/CD集成能力：提供命令行接口，可通过脚本集成到Jenkins、GitHub Actions等CI/CD工具中实现自动化检查

使用场景

• 开发阶段合规检查：开发团队在日常开发中定期扫描项目依赖，确保引入的开源组件符合团队合规要求
• 发布前合规审计：企业在软件产品发布前，对所有依赖项进行全面许可证审计，降低***风险
• 第三方组件评估：评估外部引入的SDK或库时，快速获取其许可证信息，判断是否符合引入标准
• CI/CD自动化检查：在代码提交或构建阶段自动执行许可证扫描，阻止不合规依赖进入代码库

使用方法与配置说明

基本扫描命令

通过挂载项目目录到容器，执行基础扫描并生成默认报告：

bash
docker run -v /本地项目路径:/project docker.xuanyuan.run/pivotal/license-finder analyze /project

注：/本地项目路径需替换为实际项目根目录路径，容器会自动识别项目类型并扫描依赖

生成指定格式报告

使用--format参数指定报告格式，--output指定输出路径：

bash
# 生成HTML报告（默认格式）
docker run -v /本地项目路径:/project docker.xuanyuan.run/pivotal/license-finder analyze /project --format html --output /project/license-report.html

# 生成JSON报告（便于机器解析）
docker run -v /本地项目路径:/project docker.xuanyuan.run/pivotal/license-finder analyze /project --format json --output /project/license-report.json

自定义合规策略

通过项目根目录下的license_finder.yml配置文件定义合规规则，示例配置：

yaml
# license_finder.yml
allowed_licenses:
  - MIT
  - Apache-2.0
  - BSD-3-Clause
ignored_dependencies:
  - name: "低风险内部依赖包"  # 忽略特定依赖
    version: "1.0.0"
ignored_licenses:
  - "LicenseRef-Proprietary"  # 忽略私有许可证

挂载配置文件并应用策略：

bash
docker run -v /本地项目路径:/project -v /本地配置路径/license_finder.yml:/project/license_finder.yml docker.xuanyuan.run/pivotal/license-finder analyze /project --config /project/license_finder.yml

关键参数说明

环境变量配置

通过环境变量调整容器运行参数：

Docker Compose 集成示例

创建docker-compose.yml实现配置持久化和简化操作：

yaml
version: '3.8'
services:
  license-scan:
    image: docker.xuanyuan.run/pivotal/license-finder
    volumes:
      - ./my-project:/project  # 挂载项目目录
      - ./config:/config       # 挂载配置文件目录
      - cache-volume:/root/.license_finder/cache  # 持久化缓存
    environment:
      - LOG_LEVEL=debug
      - HTTPS_PROXY=http://proxy.example.com:8080
    command: >
      analyze /project 
      --config /config/license_finder.yml 
      --format json 
      --output /project/reports/license.json 
      --fail-on non-allowed

volumes:
  cache-volume:  # 缓存卷用于加速重复扫描

高级配置：忽略特定依赖

通过命令行参数临时忽略单个依赖（需指定名称和版本）：

bash
docker run -v /本地项目路径:/project docker.xuanyuan.run/pivotal/license-finder analyze /project --ignore "dependency-name:1.2.3"

注意事项

1. 依赖文件要求：项目根目录需存在包管理文件（如package.json、pom.xml等），否则无法识别依赖
2. 网络要求：首次扫描需访问外部包仓库（如npmjs、Maven Central）以下载依赖元数据，建议配置代理或确保网络通畅
3. 缓存优化：通过持久化缓存目录（如示例中的cache-volume）可减少重复扫描的网络请求和时间消耗
4. 配置文件优先级：命令行参数优先级高于配置文件，相同配置项会覆盖配置文件设置