当前位置：首页 > news >正文

如何为OpenSSF Scorecard添加自定义安全检查：完整指南

news 2026/7/9 23:21:41

如何为OpenSSF Scorecard添加自定义安全检查：完整指南

【免费下载链接】scorecardOpenSSF Scorecard - Security health metrics for Open Source项目地址: https://gitcode.com/gh_mirrors/sc/scorecard

OpenSSF Scorecard是一个强大的开源安全健康度评估工具，它通过自动化的安全检查来评估开源项目的安全实践。本文将为你提供详细的指南，教你如何为Scorecard添加自定义安全检查，扩展其安全评估能力。🚀

什么是OpenSSF Scorecard？

OpenSSF Scorecard是一个开源项目安全健康度评估工具，它通过一系列自动化检查来评估开源项目的安全实践。Scorecard的核心是"探针"（probe）系统，每个探针都是一个独立的启发式检查，用于评估项目的特定安全行为。

Scorecard探针系统架构

Scorecard的探针系统设计得非常模块化，每个探针都包含三个核心文件：

def.yml- 探针的定义文档
impl.go- 探针的实际实现
impl_test.go- 探针的测试代码

探针目录结构

每个探针都位于probes/目录下的独立子目录中，例如：

probes/hasBinaryArtifacts/- 检查项目中是否包含二进制文件
probes/branchesAreProtected/- 检查分支保护设置
probes/hasOSVVulnerabilities/- 检查OSV漏洞

创建自定义安全检查的步骤

第一步：确定安全检查需求

在开始编码之前，首先需要明确你的安全检查需求。思考以下问题：

你要检查什么安全实践？
这个检查的结果应该是布尔值吗？
需要哪些数据源来执行这个检查？

第二步：创建探针目录

在你的本地Scorecard仓库中，创建一个新的探针目录：

cd /path/to/scorecard mkdir -p probes/myCustomCheck

第三步：编写探针定义文件（def.yml）

创建probes/myCustomCheck/def.yml文件，定义探针的基本信息：

id: myCustomCheck lifecycle: experimental short: Checks if the project has implemented custom security practice. motivation: > This check ensures that projects follow our custom security practice to enhance overall security posture. implementation: > The implementation analyzes project configuration files and source code to determine if the custom security practice is properly implemented. outcome: - If the practice is implemented correctly, returns OutcomeTrue. - If the practice is not implemented, returns OutcomeFalse. - If insufficient data is available, returns OutcomeNotAvailable. remediation: onOutcome: False effort: Medium text: - Implement the custom security practice by following the documentation. - Update project configuration files accordingly. ecosystem: languages: - all clients: - github - gitlab

第四步：实现探针逻辑（impl.go）

创建probes/myCustomCheck/impl.go文件，实现探针的核心逻辑：

package myCustomCheck import ( "embed" "fmt" "github.com/ossf/scorecard/v5/checker" "github.com/ossf/scorecard/v5/finding" "github.com/ossf/scorecard/v5/internal/checknames" "github.com/ossf/scorecard/v5/internal/probes" "github.com/ossf/scorecard/v5/probes/internal/utils/uerror" ) func init() { probes.MustRegister(Probe, Run, []checknames.CheckName{checknames.CustomCheck}) } //go:embed *.yml var fs embed.FS const Probe = "myCustomCheck" func Run(raw *checker.RawResults) ([]finding.Finding, string, error) { if raw == nil { return nil, "", fmt.Errorf("%w: raw", uerror.ErrNil) } // 实现你的自定义检查逻辑 // 使用raw中的数据进行分析 // 示例：检查是否满足条件 if customConditionMet { f, err := finding.NewWith(fs, Probe, "Project implements the custom security practice.", nil, finding.OutcomeTrue) if err != nil { return nil, Probe, err } return []finding.Finding{*f}, Probe, nil } else { f, err := finding.NewWith(fs, Probe, "Project does not implement the custom security practice.", nil, finding.OutcomeFalse) if err != nil { return nil, Probe, err } return []finding.Finding{*f}, Probe, nil } }

第五步：编写测试代码（impl_test.go）

创建probes/myCustomCheck/impl_test.go文件，为你的探针编写测试：

package myCustomCheck import ( "testing" "github.com/ossf/scorecard/v5/checker" "github.com/ossf/scorecard/v5/finding" ) func TestRun(t *testing.T) { t.Parallel() tests := []struct { name string raw *checker.RawResults want []finding.Finding wantErr bool }{ { name: "Test when condition is met", raw: &checker.RawResults{}, want: []finding.Finding{ { Probe: Probe, Outcome: finding.OutcomeTrue, }, }, wantErr: false, }, // 添加更多测试用例 } for _, tt := range tests { tt := tt t.Run(tt.name, func(t *testing.T) { t.Parallel() got, _, err := Run(tt.raw) // 断言和验证 }) } }

第六步：注册探针

在probes/entries.go文件中注册你的新探针：

import ( // ... 其他导入 "github.com/ossf/scorecard/v5/probes/myCustomCheck" ) // 在init函数或适当的位置注册 func init() { // 确保探针被正确注册 }

探针生命周期管理

Scorecard探针支持三种生命周期状态：

Experimental- 探针语义可能变化，无稳定性保证
Stable- 探针行为和语义不会改变
Deprecated- 探针不再支持，不应期望维护

最佳实践和注意事项

1. 代码复用

当多个探针使用相同的代码时，可以将共享代码放在probes/internal/目录下。

2. 动态内容显示

探针定义支持动态内容显示。在def.yml中使用${{ metadata.variableName }}语法，在impl.go中设置相应的元数据。

3. 错误处理

确保你的探针能够正确处理各种边界情况和错误条件。

4. 测试覆盖率

为你的探针编写全面的测试，包括正例、反例和边界情况。

5. 文档更新

更新相关文档，确保其他开发者了解你的新探针。

实际示例：分支保护检查

让我们看一个实际的探针示例 -branchesAreProtected探针：

def.yml文件定义了探针的目的和行为：

id: branchesAreProtected lifecycle: stable short: Checks if the project's default branch is protected. motivation: > Branch protection prevents force pushes and deletion of branches, which can help prevent accidental or malicious changes.

impl.go实现了检查逻辑：

func Run(raw *checker.RawResults) ([]finding.Finding, string, error) { // 检查分支保护设置 if raw.BranchProtectionResults.DefaultBranch != nil && raw.BranchProtectionResults.DefaultBranch.Protected { return finding.OutcomeTrue } return finding.OutcomeFalse }