✨ cmd: Refactor to make importable

[justaugustus]

What kind of change does this PR introduce?

(Is it a bug fix, feature, docs update, something else?)
Feature

• PR title follows the guidelines defined in our pull request documentation

• cmd: Refactor to make importable

• options: Add support for parsing via environment variables

• options: Support setting feature flags via option

• cmd: Replace version with sigs.k8s.io/release-utils/version

• cmd: Move option validation into pre-run function

Signed-off-by: Stephen Augustus [email protected]

What is the current behavior?

scorecard is not importable, which means any consumers needing to leverage it need to either:

1. Grab the binary and wrap it (ref: https://github.com/ossf/scorecard-action/blob/2003da293e5ad0555c10ace5034de009632ca932/Dockerfile#L33-L34, https://github.com/ossf/scorecard-action/blob/2003da293e5ad0555c10ace5034de009632ca932/entrypoint.sh#L104-L128)
2. Implement parts of existing scorecard packages, which may not may not do option validation the same way we do, or afford them the complete functionality of scorecard (ref: https://github.com/ossf/allstar/blob/e507312ca14971734db95e10a50fac840360a21c/pkg/policies/branch/branch.go)

There are plenty of existing issues for this:

• Allstar: Update Scorecard Interface allstar#21, Convert Binary Artifacts policy to be a generic scorecard policy allstar#22, Feature: require GitHub Actions to be present allstar#28, [WIP] policies: Add check for scorecard policies allstar#114
• scorecard-action: Use Scorecard's Go APIs scorecard-action#107, Create a Golang-based entrypoint for scorecard-action (1/n) scorecard-action#122

Witness (@colek42) probably has more to consider as well.

What is the new behavior (if this is a feature change)?**

• (N/A - this refactor increases test coverage) Tests for the changes have been added (for bug fixes/features)

For consumers using cobra, you can now create a scorecard *cobra.Command using cmd.New():

package main

import (
	"log"

	"github.com/ossf/scorecard/v4/cmd"
)

func main() {
	if err := cmd.New().Execute(); err != nil {
		log.Fatalf("error during command execution: %v", err)
	}
}

We've also added support for setting a subset of scorecard options via environment variables (using https://github.com/caarlos0/env).

The intent is not to support all options, but to allow specific use cases like scorecard-action, which already uses environment variables for configuration.

Which issue(s) this PR fixes

Continues #1645 and partially addresses #1683.

Special notes for your reviewer

h/t to @n3wscott for the cobra pattern!

Does this PR introduce a user-facing change?

For user-facing changes, please add a concise, human-readable release note to
the release-note

(In particular, describe what changes users might need to make in their
application as a result of this pull request.)

- cmd: Refactor to make importable
- options: Add support for parsing via environment variables
- options: Support setting feature flags via option
- cmd: Replace `version` with sigs.k8s.io/release-utils/version
- cmd: Move option validation into pre-run function

[codecov]

Codecov Report

Merging #1696 (836cca7) into main (738b246) will increase coverage by 3.13%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main    #1696      +/-   ##
==========================================
+ Coverage   57.89%   61.02%   +3.13%     
==========================================
  Files          58       58              
  Lines        5907     5907              
==========================================
+ Hits         3420     3605     +185     
+ Misses       2248     2057     -191     
- Partials      239      245       +6     

[github-actions]

Integration tests success for
[2ae12f3]
(https://github.com/ossf/scorecard/actions/runs/1919519909)

[github-actions]

Integration tests success for
[f755153]
(https://github.com/ossf/scorecard/actions/runs/1919839030)

[justaugustus]

@colek42 -- Not sure if this is helpful for witness, but FYI!

[justaugustus]

Also noting to minimize the diff and generally keep things simple, I opted not to create a package per subcommand.
We only have one command here, but here's what a more complex example would look like:

❯ tree -L 3 cmd/cosign
cmd/cosign
├── cli
│   ├── attach
│   │   ├── sbom.go
│   │   └── sig.go
│   ├── attach.go
│   ├── attest
│   │   └── attest.go
│   ├── attest.go
│   ├── clean.go
│   ├── commands.go
│   ├── completion.go
│   ├── copy
│   │   └── copy.go
│   ├── copy.go
│   ├── dockerfile
│   │   ├── verify.go
│   │   └── verify_test.go
│   ├── dockerfile.go
│   ├── download
│   │   ├── sbom.go
│   │   └── signature.go
│   ├── download.go
│   ├── fulcio
│   │   ├── depcheck_test.go
│   │   ├── fulcio.go
│   │   ├── fulcio_test.go
│   │   ├── fulcioroots
│   │   └── fulcioverifier
│   ├── generate
│   │   ├── generate.go
│   │   ├── generate_key_pair.go
│   │   └── generate_key_pair_test.go
│   ├── generate.go
│   ├── generate_key_pair.go
│   ├── initialize
│   │   └── init.go
│   ├── initialize.go
│   ├── manifest
│   │   ├── verify.go
│   │   └── verify_test.go
│   ├── manifest.go
│   ├── options
│   │   ├── annotations.go
│   │   ├── annotations_test.go
│   │   ├── attach.go
│   │   ├── attest.go
│   │   ├── copy.go
│   │   ├── errors.go
│   │   ├── experimental.go
│   │   ├── files.go
│   │   ├── flags.go
│   │   ├── flags_test.go
│   │   ├── fulcio.go
│   │   ├── generate.go
│   │   ├── generate_key_pair.go
│   │   ├── initialize.go
│   │   ├── oidc.go
│   │   ├── options.go
│   │   ├── piv_tool.go
│   │   ├── pkcs11_tool.go
│   │   ├── policy.go
│   │   ├── predicate.go
│   │   ├── public_key.go
│   │   ├── reference.go
│   │   ├── registry.go
│   │   ├── rekor.go
│   │   ├── root.go
│   │   ├── security_key.go
│   │   ├── sign.go
│   │   ├── signblob.go
│   │   ├── triangulate.go
│   │   ├── upload.go
│   │   └── verify.go
│   ├── piv_tool.go
│   ├── piv_tool_disabled.go
│   ├── pivcli
│   │   └── commands.go
│   ├── pkcs11_tool.go
│   ├── pkcs11_tool_disabled.go
│   ├── pkcs11cli
│   │   └── commands.go
│   ├── policy_init.go
│   ├── policy_init_test.go
│   ├── public_key.go
│   ├── publickey
│   │   ├── public_key.go
│   │   └── public_key_test.go
│   ├── sign
│   │   ├── sign.go
│   │   ├── sign_blob.go
│   │   └── sign_test.go
│   ├── sign.go
│   ├── signblob.go
│   ├── triangulate
│   │   └── triangulate.go
│   ├── triangulate.go
│   ├── upload
│   │   ├── blob.go
│   │   └── wasm.go
│   ├── upload.go
│   ├── verify
│   │   ├── verify.go
│   │   ├── verify_attestation.go
│   │   └── verify_blob.go
│   ├── verify.go
│   ├── version.go
│   └── version_test.go
├── main.go
└── webhook
    ├── depcheck_test.go
    ├── kodata
    │   ├── HEAD -> ../../../../.git/HEAD
    │   ├── LICENSE -> ../../../../LICENSE
    │   └── refs -> ../../../../.git/refs
    └── main.go

[github-actions]

Integration tests success for
[836cca7]
(https://github.com/ossf/scorecard/actions/runs/1920165454)

[azeemshaikh38]

Love the changes, thanks! Please do test out the command locally since we do not have tests for these as of now. Ref: #1690 #1691

[justaugustus]

Love the changes, thanks!

Hehe, I'm already excited!

❯ scorecard-action --help
A program that shows security scorecard for an open source software.

Usage:
  ./scorecard [--repo=<repo_url>] [--local=folder] [--checks=check1,...]
	 [--show-details] or ./scorecard --{npm,pypi,rubygems}=<package_name>
	 [--checks=check1,...] [--show-details] [flags]
  ./scorecard [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  serve       Serve the scorecard program over http
  version     Prints the version

Flags:
      --checks strings     Checks to run. Possible values are: Signed-Releases,CII-Best-Practices,Fuzzing,Token-Permissions,Pinned-Dependencies,Packaging,Binary-Artifacts,Branch-Protection,Contributors,License,Dangerous-Workflow,Maintained,Security-Policy,Vulnerabilities,CI-Tests,Code-Review,Dependency-Update-Tool,SAST
      --commit string      commit to analyze (default "HEAD")
      --format string      output format allowed values are [default, json] (default "default")
  -h, --help               help for ./scorecard
      --local string       local folder to check
      --metadata strings   metadata for the project. It can be multiple separated by commas
      --npm string         npm package to check, given that the npm package has a GitHub repository
      --pypi string        pypi package to check, given that the pypi package has a GitHub repository
      --repo string        repository to check
      --rubygems string    rubygems package to check, given that the rubygems package has a GitHub repository
      --show-details       show extra details about each check
      --verbosity string   set the log level (default "info")

Use "./scorecard [command] --help" for more information about a command.

Please do test out the command locally since we do not have tests for these as of now. Ref: #1690 #1691

Will do!

[naveensrinivasan]

This is really cool! Thanks @justaugustus