OpenSCA接入GitHub Action详细教学文档

一、OpenSCA与GitHub Action集成概述

OpenSCA是一款软件供应链安全分析工具，通过将其接入GitHub Action，可以在代码提交或合并请求时自动执行依赖组件安全扫描，从软件供应链入口控制风险面。

二、准备工作

1. 获取OpenSCA云漏洞库服务token

• 访问OpenSCA官网获取token
• 在GitHub仓库中设置secret：
  • 进入仓库Settings → Secrets and variables → Actions
  • 点击"New repository secret"
  • 名称设为OPENSCA_TOKEN，值为获取的token

2. 配置GitHub Actions权限

为避免Permission denied错误：

1. 进入仓库Settings → Actions → General
2. 在"Workflow permissions"部分
3. 选择"Read and write permissions"
4. 保存设置

三、基础集成配置

1. 基本workflow示例

name: OpenSCA Scan

on:
  push:
    branches: [ "master", "main" ]
  pull_request:
    branches: [ "master", "main" ]

jobs:
  opensca-scan:
    runs-on: ubuntu-latest
    name: OpenSCA Scan
    steps:
      - name: Checkout your code
        uses: actions/checkout@v4
      
      - name: Run OpenSCA Scan
        uses: XmirrorSecurity/opensca-scan-action@v1
        with:
          token: ${{ secrets.OPENSCA_TOKEN }}

2. 参数说明

四、高级使用场景

1. 同步检测结果至OpenSCA SaaS指定项目

1. 在OpenSCA SaaS平台获取ProjectID
2. 在GitHub仓库secrets中添加OPENSCA_PROJECT_ID
3. 修改workflow：

- name: Run OpenSCA Scan
  uses: XmirrorSecurity/opensca-scan-action@v1
  with:
    token: ${{ secrets.OPENSCA_TOKEN }}
    proj: ${{ secrets.OPENSCA_PROJECT_ID }}

2. 保留日志用于问题排查

- name: Run OpenSCA Scan
  uses: XmirrorSecurity/opensca-scan-action@v1
  with:
    token: ${{ secrets.OPENSCA_TOKEN }}
    need-artifact: "true"

3. 上传特定格式的检测报告

- name: Run OpenSCA Scan
  uses: XmirrorSecurity/opensca-scan-action@v1
  with:
    token: ${{ secrets.OPENSCA_TOKEN }}
    out: "outputs/result.json,outputs/result.html"
    need-artifact: "true"

注意：仅outputs目录下的结果文件会被上传

五、查看扫描结果

1. GitHub Security页面：

   • 进入仓库的Security → Code scanning
   • 查看OpenSCA扫描结果

2. OpenSCA SaaS平台：

   • 在Action日志中查找跳转链接
   • 访问链接查看更详细的分析结果

3. Artifacts（如果配置了need-artifact）：

   • 在workflow run的summary页面底部
   • 可下载日志和结果文件

六、常见问题解决

1. Permission denied错误

• 确保已按照"准备工作"部分配置了Actions的读写权限

2. 找不到artifact

• 确认workflow中配置了need-artifact: "true"
• 检查是否在workflow run的summary页面底部查找

3. 其他问题

• 向OpenSCA项目组提交ISSUE获取支持

七、最佳实践建议

1. 对于关键分支（如master/main）配置push和pull_request触发
2. 对于敏感项目，建议同步结果至OpenSCA SaaS平台
3. 定期检查扫描结果并处理高风险依赖
4. 考虑将扫描结果作为合并请求的必须通过条件

通过以上配置，您的项目将在每次代码变更时自动进行依赖组件安全扫描，有效控制软件供应链风险。