The scorecard serve subcommand exposes Scorecard scans over HTTP. A client
sends a repository or package name with optional scan settings and receives
the scan result as JSON. This spec covers the listening address, endpoints,
request parameters, response format, error responses, middleware behavior,
and shutdown.
The system SHALL start an HTTP server on 127.0.0.1 at the port given by
the PORT environment variable, defaulting to 8080, when the user runs
scorecard serve. A --listen value with a port SHALL set the host and
port; a value without one SHALL set only the host. The server SHALL log
Server listening on <host>:<port>, SHALL time out reading request
headers after 10 seconds, and SHALL log at info level. If the server
cannot listen, the command MUST exit with a non-zero status.
- GIVEN
PORTis not set - WHEN a user runs
scorecard serve - THEN the server listens on
127.0.0.1:8080
- GIVEN
PORT=9000 - WHEN a user runs
scorecard serve - THEN the server listens on
127.0.0.1:9000
- GIVEN
PORT=9000 - WHEN a user runs
scorecard serve --listen 0.0.0.0 - THEN the server listens on
0.0.0.0:9000
- GIVEN
PORT=9000 - WHEN a user runs
scorecard serve --listen 0.0.0.0:9001 - THEN the server listens on
0.0.0.0:9001
- GIVEN the port is already in use
- WHEN a user runs
scorecard serve - THEN the command exits with a non-zero status and an error naming the address
- AND no requests are served
The system SHALL respond to requests for /health with status 200 and an
empty body without running a scan.
- WHEN a client sends
GET /health - THEN the server responds with status 200 and no scan is performed
The system SHALL run a scan for GET and POST requests to any path other
than /health. Requests with any other method SHALL receive status 404.
- WHEN a client sends
GET /?repo=github.com/ossf/scorecard - THEN the server scans
github.com/ossf/scorecard
- WHEN a client sends
PUT / - THEN the server responds with status 404
- WHEN a client sends
OPTIONS / - THEN the server responds with status 404 and no scan is performed
For GET requests the system SHALL read the query parameters repo,
npm, pypi, rubygems, nuget, commit, file_mode, checks
(comma-separated), probes (comma-separated), show_details, and
show_annotations. show_details and show_annotations SHALL be enabled
only by the exact value true. GET requests SHALL NOT accept a commit
depth.
- WHEN a client sends
GET /?repo=owner/repo&checks=License,SAST&show_details=true - THEN the server reads
LicenseandSASTas the requested checks and enables details
- WHEN a client sends
show_details=1 - THEN details are not included
For POST requests the system SHALL decode a JSON body with the optional
fields repo, npm, pypi, rubygems, nuget, commit, file_mode,
checks (array), probes (array), commit_depth (integer),
show_details (boolean), and show_annotations (boolean). A body that is
not valid JSON MUST receive status 400 with the text invalid request body.
- WHEN a client posts
{"repo": "owner/repo", "checks": ["License"], "commit_depth": 10} - THEN the server runs the License check with a commit depth of 10
- WHEN a client posts
{not json - THEN the server responds with status 400 and
invalid request body
The system SHALL default an empty commit to HEAD and an empty
file_mode to archive. An empty or absent check list SHALL select every
check that applies to the commit and repository type. When the commit is
not HEAD, the default set SHALL contain only checks supporting
commit-based analysis, and an explicitly requested check without
commit-based support SHALL fail the request with status 500 and a body
beginning GetEnabled: that contains Unsupported RequestType. Checks
whose documentation excludes the target repository's host type SHALL be
skipped. When the internal GitHub integration check override is active,
its check list SHALL replace the checks given in the request; the
override is defined in cli.
- WHEN a client posts
{"repo": "owner/repo"} - THEN the server runs every check supported for a GitHub repository at
HEAD
- GIVEN a requested check does not support GitLab repositories
- WHEN a client requests that check for a GitLab repository
- THEN the check is omitted from the result
- WHEN a client posts
{"repo": "owner/repo", "commit": "<sha>"} - THEN the server runs only the checks that support commit-based analysis
- GIVEN a check that does not support commit-based analysis
- WHEN a client requests that check with a
commitother thanHEAD - THEN the server responds with status 500 and a body beginning
GetEnabled:that containsUnsupported RequestType
- GIVEN the internal GitHub integration check override is active
- WHEN a client posts
{"repo": "owner/repo", "checks": ["License"]} - THEN the server selects checks from the override list instead of
License
The system MUST require exactly one of repo, npm, pypi, rubygems, or
nuget and MUST reject an unsupported file_mode. A request failing
validation MUST receive status 400 with a body beginning
invalid options: followed by the validation errors.
- WHEN a client sends
GET /with no input parameter - THEN the server responds with status 400 and a body containing "exactly one of"
- WHEN a client posts
{"repo": "owner/repo", "npm": "left-pad"} - THEN the server responds with status 400
- WHEN a client sends
file_mode=svn - THEN the server responds with status 400 and "unsupported file mode"
The system SHALL accept a probes value in GET and POST requests but
MUST NOT use it: every scan runs checks, never individual probes.
- WHEN a client posts
{"repo": "owner/repo", "probes": ["hasLicenseFile"]} - THEN the server runs checks as if
probeswere absent - AND the response contains check results, not probe findings
- WHEN a client sends
GET /?repo=owner/repo - THEN the server runs checks and responds with status 200
On success the system SHALL respond with status 200, the header
Content-Type: application/json, and the scan result in the same JSON
structure as the CLI --format=json output, with checks sorted by name.
Details and annotations SHALL be included only when requested.
- WHEN a valid scan completes
- THEN the response is status 200 with
Content-Type: application/json - AND the body lists checks in alphabetical order
The system SHALL respond with status 500 and a plain-text message when a request passes validation but cannot be served. The message SHALL begin with a prefix naming the failed step:
fetchGitRepositoryFromPackageManagers:when package resolution failsmaking remote repo:when the repository cannot be parsedcannot read yaml file:when the check documentation cannot be readGetEnabled:when check selection failsscorecard.Run:when the scan failsfailed to format results:when the result cannot be serialized
- WHEN a client posts
{"repo": "owner/repo", "checks": ["Nope"]} - THEN the server responds with status 500 and a body beginning
GetEnabled:that containsinvalid check: Nope
- WHEN a client posts
{"repo": "::bad::"} - THEN the server responds with status 500 and a body beginning
making remote repo:
The system MUST NOT add Access-Control-Allow-* headers to any response.
A request is cross-site when its Sec-Fetch-Site header is present and is
neither same-origin nor none. Without that header, a request is
cross-site when its Origin host and port differ from the Host header.
A cross-site request on any path and method MUST receive status 403 and
cross-origin request rejected, and no scan runs.
- WHEN a browser on another site sends
OPTIONS / - THEN the response has no
Access-Control-Allow-Originheader
- WHEN a client sends
GET /?repo=owner/repowithSec-Fetch-Site: cross-site - THEN the server responds with status 403 and no scan is performed
- WHEN a client sends
POST /withHost: 127.0.0.1:8080andOrigin: http://example.com - THEN the server responds with status 403 and no scan is performed
- WHEN a client sends
GET /?repo=owner/repowithSec-Fetch-Site: none - THEN the server runs the scan
- WHEN a client sends
GET /?repo=owner/repowith neitherSec-Fetch-SitenorOrigin - THEN the server runs the scan
The system SHALL recover from a panic while handling a request, log it, and
respond with status 500 and internal server error. The system SHALL log
each completed request with its method, path, and duration.
- WHEN handling a request panics
- THEN the server responds with status 500 and
internal server error - AND continues serving later requests
- WHEN a request completes
- THEN the server logs
request completed method=<method> path=<path> duration=<duration>
The system SHALL begin shutting down when it receives SIGINT or SIGTERM,
log Shutting down server..., and allow in-flight requests up to 5 seconds
to finish. If shutdown does not complete in time, the command MUST exit
with a non-zero status and a server shutdown: error.
- GIVEN the server is idle
- WHEN it receives
SIGTERM - THEN it logs
Shutting down server...and exits with status 0
- GIVEN a scan is still running
- WHEN the server receives
SIGINTand the scan does not finish within 5 seconds - THEN the command exits with a non-zero status and a
server shutdown:error
The serve command's long help text SHALL state that the server has no
authentication or rate limiting and runs every scan with the server's own
credentials. It SHALL state that the server listens on 127.0.0.1 unless
--listen names another address. It SHALL recommend using --listen
only on a trusted network, with a token limited to the repositories the
server is meant to scan.
- WHEN a user runs
scorecard serve --help - THEN the output states that the server has no authentication or rate limiting
- AND the output states that scans run with the server's credentials
- AND the output states that the server listens on
127.0.0.1by default - AND the output recommends a trusted network and a limited token
A host is loopback when it is localhost or a loopback IP address; an
empty host is not. When the listening host is not loopback, the system
SHALL log at startup that the server has no authentication and is
reachable from other hosts.
- WHEN a user runs
scorecard serve --listen 0.0.0.0 - THEN the server logs that it has no authentication and is reachable from other hosts
- WHEN a user runs
scorecard serve - THEN the server does not log that message
When the listening host is loopback, a request whose Host header names
a host that is not loopback MUST receive status 403 and host not allowed, and no scan runs. The port in Host SHALL be ignored, and names
SHALL be compared without regard to case.
- GIVEN the server listens on
127.0.0.1:8080 - WHEN a client sends
GET /?repo=owner/repowithHost: other.example:8080 - THEN the server responds with status 403 and no scan is performed
- GIVEN the server listens on
127.0.0.1:8080 - WHEN a client sends
GET /healthwithHost: localhost:8080,Host: 127.0.0.1:8080, orHost: [::1]:8080 - THEN the server responds with status 200
- GIVEN the server listens on
0.0.0.0:8080 - WHEN a client sends
GET /healthwithHost: scorecard.internal - THEN the server responds with status 200
The system MUST respond with status 413 and request body too large,
without running a scan, to a POST request whose body exceeds 1 MiB.
- WHEN a client posts a 2 MiB body
- THEN the server responds with status 413 and no scan is performed