Skip to content

Commit 7bec021

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

File tree

1 file changed

+233
-0
lines changed

1 file changed

+233
-0
lines changed

‎guac/certifier-scorecard.md‎

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

0 commit comments

Comments
 (0)