✨ Feature DependencyDiff CLI (Version 0 Part 1)

cmd/depdiff/dependencies.go

@@ -0,0 +1,78 @@
+// Copyright 2022 Security Scorecard Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package depdiff
+
+// ChangeType is the change type (added, updated, removed) of a dependency.
+type ChangeType string
+
+const (
+	Added   ChangeType = "added"
+	Updated ChangeType = "updated"
+	Removed ChangeType = "removed"
+)
+
+// IsValid determines if a ChangeType is valid.
+func (ct *ChangeType) IsValid() bool {
+	switch *ct {
+	case Added, Updated, Removed:
+		return true
+	default:
+		return false
+	}
+}
+
+// Dependency is a dependency.
+type Dependency struct {
+	// // IsDirect suggests if the dependency is a direct dependency of a code commit.
+	// TODO: IsDirect remains a future feature since the current GitHub Dependency Review API
+	// mixes up direct and indirect dependencies in manifest files of different ecosystems.
+	IsDirect bool
+
+	// ChangeType indicates whether the dependency is added or removed.
+	ChangeType ChangeType `json:"change_type"`
+
+	// ManifestFileName is the name of the manifest file of the dependency, such as go.mod for Go.
+	ManifestFileName string `json:"manifest"`
+
+	// Ecosystem is the name of the package management system, such as NPM, GO, PYPI.
+	Ecosystem string `json:"ecosystem" bigquery:"System"`
+
+	// Name is the name of the dependency.
+	Name string `json:"name" bigquery:"Name"`
+
+	// Version is the package version of the dependency.
+	Version string `json:"version" bigquery:"Version"`
+
+	// Package URL is a short link for a package.
+	PackageURL string `json:"package_url"`
+
+	// License is the license of the dependency.
+	License string `json:"license"`
+
+	// SrcRepoURL is the source repository URL of the dependency.
+	SrcRepoURL string `json:"source_repository_url"`
+
+	// ScResults is the Scorecard scanning result of the dependency package repository.
+	ScResults ScorecardResult `json:"scorecard_results"`
+
+	// Vulnerabilities is a list of Vulnerability.
+	Vulnerabilities []Vulnerability `json:"vulnerabilities"`
+
+	// Dependencies is the list of dependencies of the current dependency,
+	// e.g. indirect (transitive) dependencies.
+	// TODO: this is not a version-zero feature, and will be used to analyze transitive
+	// dependencies in future versions.
+	Dependencies []Dependency `json:"dependencies"`
+}

cmd/depdiff/errors.go

@@ -0,0 +1,27 @@
+// Copyright 2022 Security Scorecard Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package depdiff
+
+import (
+	"errors"
+)
+
+var (
+	// ErrInvalidDepDiffFormat indicates the specified dependency diff output format is not valid.
+	ErrInvalidDepDiffFormat = errors.New("invalid depdiff format")
+
+	// ErrInvalidDepDiffFormat indicates the specified dependency diff output format is not valid.
+	ErrMarshalDepDiffToJSON = errors.New("error marshal results to JSON")
+)

cmd/depdiff/scorecard_results.go

@@ -0,0 +1,21 @@
+// Copyright 2022 Security Scorecard Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package depdiff
+
+// ScorecardResult is the Scorecard scanning result of a repository.
+type ScorecardResult struct {
+	// AggregateScore is the Scorecard aggregate score (0-10) of the dependency.
+	AggregateScore float32 `json:"score"`
+}

cmd/depdiff/vulnerabilities.go

@@ -0,0 +1,92 @@
+// Copyright 2022 Security Scorecard Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package depdiff
+
+import (
+	"time"
+)
+
+// SeverityLevel is the level of severity of a vulnerability.
+type SeverityLevel string
+
+const (
+	Critical SeverityLevel = "CRITICAL"
+	High     SeverityLevel = "HIGH"
+	Medium   SeverityLevel = "MEDIUM"
+	Moderate SeverityLevel = "MODERATE"
+	Low      SeverityLevel = "LOW"
+	None     SeverityLevel = "NONE"
+	Unknown  SeverityLevel = "UNKNOWN"
+)
+
+// IsValid determines if a SeverityLevel is valid.
+func (sl *SeverityLevel) IsValid() bool {
+	switch *sl {
+	case Critical, High, Medium, Moderate, Low, None, Unknown:
+		return true
+	default:
+		return false
+	}
+}
+
+// Source is an authoritative source of a vulnerability.
+type Source string
+
+const (
+	GHSA Source = "GHSA"
+	NSWG Source = "NSWG"
+	OSV  Source = "OSV"
+)
+
+// IsValid determines if a Source is valid.
+func (src *Source) IsValid() bool {
+	switch *src {
+	case GHSA, NSWG, OSV:
+		return true
+	default:
+		return false
+	}
+}
+
+// Vulnerability is a security vulnerability of a dependency.
+type Vulnerability struct {
+	// Source is the source of a vulnerability.
+	Source string `bigquery:"Source"`
+
+	// ID is the identifier of a vulnerability.
+	ID string `json:"advisory_ghsa_id" bigquery:"SourceID"`
+
+	// SourceURL is the source URL of a vulnerability.
+	SourceURL string `json:"advisory_url" bigquery:"SourceURL"`
+
+	// Title is the text summary of a vulnerability.
+	Title string `json:"advisory_summary" bigquery:"Title"`
+
+	// Description is a long text paragraph of a vulnerability.
+	Description string `json:"description" bigquery:"Description"`
+
+	// Score is the score of a vulnerability given by an authoritative src.
+	// TODO: this is not a version-zero property and will be included in future versions.
+	// Score bigquery.NullFloat64 `bigquery:"Score"`
+
+	// GitHubSeverity is the severity level of a vulnerability determined by GitHub.
+	GitHubSeverity SeverityLevel `json:"github_severity" bigquery:"GitHubSeverity"`
+
+	// ReferenceURLs include all URLs that are related to a vulnerability.
+	ReferenceURLs []string `json:"reference_urls" bigquery:"ReferenceURLs"`
+
+	// DisclosedTime is the time when a vulenrability is publicly disclosed.
+	DisclosedTime time.Time `json:"disclosed_time" bigquery:"Disclosed"`
+}