Skip to content

Commit 1dec0a6

Browse files
gaganhr94gaganhr94
committed
docs: adds documentation for scorecard certifier
Signed-off-by: Gagan H R <[email protected]>
1 parent 9daeef9 commit 1dec0a6

File tree

1 file changed

+200
-0
lines changed

1 file changed

+200
-0
lines changed

‎guac/certifier-scorecard.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
---
2+
layout: page
3+
permalink: /guac/scorecard-certifier/
4+
title: "Scorecard certifier"
5+
parent: "How GUAC components work together"
6+
description:
7+
"Guide to using the Scorecard Certifier in GUAC for security assessment of
8+
open source repositories"
9+
---
10+
11+
# Scorecard Certifier
12+
13+
## Overview
14+
15+
The Scorecard Certifier component of [GUAC](https://guac.sh) (Graph for
16+
Understanding Artifact Composition) integrates with the
17+
[OpenSSF Scorecard](https://github.com/ossf/scorecard) project to provide
18+
comprehensive security risk assessments for open-source repositories. It
19+
evaluates repositories against industry security best practices and provides
20+
actionable security insights.
21+
22+
## Key Features
23+
24+
- **Security Risk Assessment**: Evaluates repositories using 19 comprehensive
25+
security checks
26+
27+
- **Automated Scoring**: Provides numerical scores (0-10) for each security
28+
check
29+
30+
- **Comprehensive Analysis**: Covers code review practices, dependency
31+
management, vulnerability handling, and more
32+
33+
- **Integration with GUAC**: Seamlessly connects scorecard data to GUAC's
34+
software supply chain graph
35+
36+
## Data Collection Process
37+
38+
1. **Repository Identification**:
39+
- Source repositories of packages are identified by GUAC
40+
- Supports GitHub repositories with commit SHA or tag references
41+
- Validates repository metadata and accessibility
42+
43+
2. **Scorecard Evaluation**:
44+
- Runs security checks against target repositories
45+
- Query mode: Fetches pre-computed results from OpenSSF Scorecard API
46+
- Compute mode: Executes scorecard checks using the scorecard library and
47+
computes the result
48+
49+
3. **Data Ingestion**:
50+
- Converts scorecard results to structured JSON format
51+
- Publishes results through GUAC's event stream for ingestion
52+
53+
## Operation Modes
54+
55+
The scorecard certifier supports two modes: **Query mode** (default) fetches
56+
pre-computed results from the OpenSSF Scorecard API. It's fast, requires no authentication,
57+
but only covers repositories already analyzed by OpenSSF. **Compute mode** runs
58+
scorecard checks using the scorecard library, and computes the score. It provides complete
59+
coverage of any GitHub repository, but requires a GitHub token and uses more resources.
60+
61+
## Available Options
62+
63+
### Usage
64+
65+
Basic command syntax:
66+
67+
```bash
68+
guaccollect scorecard [options]
69+
```
70+
71+
### Core Flags
72+
73+
| Flag | Description | Default |
74+
| ---------------------------- | -------------------------------------------------------------- | ------------------- |
75+
| `--certifier-batch-size int` | Sets the batch size for pagination query for the certifier | 60000 |
76+
| `--certifier-latency string` | Sets artificial latency on the certifier (e.g., m, h, s, etc.) | Not enabled (empty) |
77+
| `-h, --help` | Help for scorecard | |
78+
| `--interval string` | Polling interval (e.g., m, h, s, etc.) | 5m |
79+
| `--service-poll` | Enable polling mode | false |
80+
81+
### Scorecard-Specific Flags
82+
83+
| Flag | Description | Default |
84+
| --------------------------- | --------------------------------------------------------------- | ------- |
85+
| `--scorecard-mode` | Scorecard modes: 'query' (default) or 'compute' | `query` |
86+
| `--scorecard-http-timeout` | HTTP timeout for API requests when using 'query' mode | `30s` |
87+
88+
### Global Flags
89+
90+
| Flag | Description | Default |
91+
| ---------------------- | -------------------------------------------------------------------------------- | --------------------------------------- |
92+
| `--gql-addr string` | Endpoint used to connect to GraphQL server | `http://localhost:8080/query` |
93+
| `--pubsub-addr string` | Address to connect to NATS pubsub service | `nats://localhost:4222` |
94+
| `--blob-addr string` | Address for blob storage | `file:///tmp/blobstore?no_tmp_dir=true` |
95+
| `--header-file string` | A text file containing HTTP headers to send to the GQL server, in RFC 822 format | Not set |
96+
| `--publish-to-queue` | Enable publishing to the message queue | true |
97+
98+
## Usage Examples
99+
100+
### Query Mode (Default)
101+
102+
```bash
103+
# Use query mode with default settings
104+
guaccollect scorecard
105+
```
106+
107+
```bash
108+
# Use query mode with custom HTTP timeout
109+
guaccollect scorecard \
110+
--scorecard-mode=query \
111+
--scorecard-http-timeout=60s
112+
```
113+
114+
### Compute Mode
115+
116+
```bash
117+
# Set GitHub token (required for compute mode)
118+
export GITHUB_AUTH_TOKEN=your_github_token
119+
```
120+
121+
```bash
122+
# Use compute mode (scorecard library)
123+
guaccollect scorecard \
124+
--scorecard-mode=compute
125+
```
126+
127+
### Polling Mode
128+
129+
```bash
130+
# Enable polling with custom interval
131+
guaccollect scorecard \
132+
--service-poll \
133+
--interval=10m \
134+
--scorecard-mode=query
135+
```
136+
137+
## Prerequisites
138+
139+
### GitHub Token Setup (Compute Mode Only)
140+
141+
1. Create a GitHub Personal Access Token
142+
143+
2. Set environment variable:
144+
```bash
145+
export GITHUB_AUTH_TOKEN=ghp_your_token_here
146+
```
147+
148+
## Limitations
149+
150+
### Query Mode Limitations
151+
152+
- Limited to repositories already analyzed by OpenSSF Scorecard
153+
- No control over check configuration
154+
155+
### Compute Mode Limitations
156+
157+
- Requires GitHub authentication token
158+
- Slower execution for large repositories
159+
- May hit GitHub API rate limits with high volume
160+
161+
### General Limitations
162+
163+
- Currently supports GitHub repositories only
164+
- Requires valid commit SHA or tag reference
165+
- Results depend on repository accessibility and structure
166+
167+
## Error Handling
168+
169+
Common error scenarios and solutions:
170+
171+
### Authentication Errors (Compute Mode)
172+
173+
```
174+
Error: GITHUB_AUTH_TOKEN is not set
175+
```
176+
177+
**Solution**: Set the `GITHUB_AUTH_TOKEN` environment variable with a valid
178+
GitHub token.
179+
180+
### Repository Not Found (Query Mode)
181+
182+
```
183+
Error: repository not found in scorecard database
184+
```
185+
186+
**Solution**: Repository may not be analyzed by OpenSSF Scorecard yet. Consider
187+
using compute mode or wait for API coverage.
188+
189+
### Rate Limiting
190+
191+
```
192+
Error: API returned status 429: Rate limit exceeded
193+
```
194+
195+
**Solution**: Try reducing batch size using `--certifier-batch-size`.
196+
197+
## Additional Resources
198+
199+
- [OpenSSF Scorecard Project](https://github.com/ossf/scorecard)
200+
- [Scorecard Checks Documentation](https://github.com/ossf/scorecard/blob/main/docs/checks.md)

0 commit comments

Comments
 (0)