Skip to content

Commit 4d7016a

Browse files
softdev050softdev050
committed
exp,internal/govulncheck: add govulncheck API
An API is defined for internal/govulncheck. The API in exp/govulncheck is updated to use internal/govulncheck.Config and internal/govulncheck.Source. For golang/go#56042 Change-Id: Ibab2fae0685166e7712b355e2c7c2ab0b4d50c6c Reviewed-on: https://go-review.googlesource.com/c/vuln/+/440219 Reviewed-by: Jonathan Amsterdam <[email protected]> Reviewed-by: Julie Qiu <[email protected]> TryBot-Result: Gopher Robot <[email protected]> Reviewed-by: Zvonimir Pavlinovic <[email protected]> Reviewed-by: Hyang-Ah Hana Kim <[email protected]> Run-TryBot: Julie Qiu <[email protected]>
1 parent a48c6a2 commit 4d7016a

File tree

4 files changed

+209
-17
lines changed

4 files changed

+209
-17
lines changed

‎exp/govulncheck/govulncheck.go

Lines changed: 27 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,21 +2,35 @@
22
// Use of this source code is governed by a BSD-style
33
// license that can be found in the LICENSE file.
44

5-
// Package govulncheck has experimental govulncheck API.
5+
// Package govulncheck provides an experimental govulncheck API.
66
package govulncheck
77

8-
import (
9-
"context"
8+
import "golang.org/x/vuln/internal/govulncheck"
109

11-
"golang.org/x/vuln/internal/govulncheck"
12-
)
10+
// Source reports vulnerabilities that affect the analyzed packages.
11+
var Source = govulncheck.Source
12+
13+
type (
14+
// Config is the configuration for Main.
15+
Config = govulncheck.Config
16+
17+
// Result is the result of executing Source.
18+
Result = govulncheck.Result
19+
20+
// Vuln represents a single OSV entry.
21+
Vuln = govulncheck.Vuln
1322

14-
// Config is the configuration for Main.
15-
type Config = govulncheck.LegacyConfig
23+
// Module represents a specific vulnerability relevant to a
24+
// single module or package.
25+
Module = govulncheck.Module
1626

17-
// Main is the main function for the govulncheck command line tool.
18-
func Main(cfg Config) error {
19-
ctx := context.Background()
20-
_, err := govulncheck.LegacyRun(ctx, cfg)
21-
return err
22-
}
27+
// Package is a Go package with known vulnerable symbols.
28+
Package = govulncheck.Package
29+
30+
// CallStacks contains a representative call stack for each
31+
// vulnerable symbol that is called.
32+
CallStack = govulncheck.CallStack
33+
34+
// StackFrame represents a call stack entry.
35+
StackFrame = govulncheck.StackFrame
36+
)

‎internal/govulncheck/cache.go

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@
22
// Use of this source code is governed by a BSD-style
33
// license that can be found in the LICENSE file.
44

5-
// Package govulncheck supports the govulncheck command.
65
package govulncheck
76

87
import (

‎internal/govulncheck/result.go

Lines changed: 146 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,153 @@
11
// Copyright 2022 The Go Authors. All rights reserved.
22
// Use of this source code is governed by a BSD-style
33
// license that can be found in the LICENSE file.
4+
5+
// Package govulncheck provides functionality to support the govulncheck command.
46
package govulncheck
57

6-
// Result is contains output information for govulncheck.
7-
//
8-
// TODO(https://go.dev/issue/56042): this API is a work in progress.
8+
import (
9+
"go/token"
10+
11+
"golang.org/x/tools/go/packages"
12+
"golang.org/x/vuln/client"
13+
"golang.org/x/vuln/osv"
14+
)
15+
16+
// LoadMode is the level of information needed for each package
17+
// for running golang.org/x/tools/go/packages.Load.
18+
var LoadMode = packages.NeedName | packages.NeedImports | packages.NeedTypes |
19+
packages.NeedSyntax | packages.NeedTypesInfo | packages.NeedDeps |
20+
packages.NeedModule
21+
22+
// Config is used for configuring the output of govulncheck.
23+
type Config struct {
24+
// Client is the client used to make requests to a vulnerability
25+
// database(s). If nil, a default client is constructed that makes requests
26+
// to vuln.go.dev.
27+
Client client.Client
28+
29+
// GoVersion specifies the Go version used when analyzing source code.
30+
//
31+
// By default, GoVersion is the go command version found from the PATH.
32+
GoVersion string
33+
34+
// Verbosity controls the stdout and stderr output when running Source.
35+
//
36+
// TODO(https://go.dev/issue/56042): make this an enum.
37+
Verbosity string
38+
}
39+
40+
// Result is the result of executing Source or Binary.
941
type Result struct {
42+
// Vulns contains all vulnerabilities that are called or imported by
43+
// the analyzed module.
44+
Vulns []*Vuln
45+
}
46+
47+
// Vuln represents a single OSV entry.
48+
type Vuln struct {
49+
// OSV contains all data from the OSV entry for this vulnerability.
50+
OSV *osv.Entry
51+
52+
// Modules contains all of the modules in the OSV entry where a
53+
// vulnerable package is imported by the target source code or binary.
54+
//
55+
// For example, a module M with two packages M/p1 and M/p2, where only p1
56+
// is vulnerable, will appear in this list if and only if p1 is imported by
57+
// the target source code or binary.
58+
Modules []*Module
59+
}
60+
61+
// IsCalled reports whether the vulnerability is called, therefore
62+
// affecting the target source code or binary.
63+
//
64+
// TODO(https://go.dev/issue/56042): implement
65+
func (v *Vuln) IsCalled() bool {
66+
return false
67+
}
68+
69+
// Module represents a specific vulnerability relevant to a single module.
70+
type Module struct {
71+
// Path is the module path of the module containing the vulnerability.
72+
//
73+
// Importable packages in the standard library will have the path "stdlib".
74+
Path string
75+
76+
// FoundVersion is the module version where the vulnerability was found.
77+
FoundVersion string
78+
79+
// FixedVersion is the module version where the vulnerability was
80+
// fixed. If there are multiple fixed versions in the OSV report, this will
81+
// be the latest fixed version.
82+
//
83+
// This is empty if a fix is not available.
84+
FixedVersion string
85+
86+
// Packages contains all the vulnerable packages in OSV entry that are
87+
// imported by the target source code or binary.
88+
//
89+
// For example, given a module M with two packages M/p1 and M/p2, where
90+
// both p1 and p2 are vulnerable, p1 and p2 will each only appear in this
91+
// list they are individually imported by the target source code or binary.
92+
Packages []*Package
93+
}
94+
95+
// Package is a Go package with known vulnerable symbols.
96+
type Package struct {
97+
// Path is the import path of the package containing the vulnerability.
98+
Path string
99+
100+
// CallStacks contains a representative call stack for each
101+
// vulnerable symbol that is called.
102+
//
103+
// For vulnerabilities found from binary analysis, only CallStack.Symbol
104+
// will be provided.
105+
//
106+
// For non-affecting vulnerabilities reported from the source mode
107+
// analysis, this will be empty.
108+
CallStacks []CallStack
109+
}
110+
111+
// CallStacks contains a representative call stack for a vulnerable
112+
// symbol.
113+
type CallStack struct {
114+
// Symbol is the name of the detected vulnerable function
115+
// or method.
116+
//
117+
// This follows the naming convention in the OSV report.
118+
Symbol string
119+
120+
// Summary is a one-line description of the callstack, used by the
121+
// default govulncheck mode.
122+
//
123+
// Example: module3.main calls github.com/shiyanhui/dht.DHT.Run
124+
Summary string
125+
126+
// Frames contains an entry for each stack in the call stack.
127+
//
128+
// Frames are sorted starting from the entry point to the
129+
// imported vulnerable symbol. The last frame in Frames should match
130+
// Symbol.
131+
Frames []*StackFrame
132+
}
133+
134+
// StackFrame represents a call stack entry.
135+
type StackFrame struct {
136+
// PackagePath is the import path.
137+
PkgPath string
138+
139+
// FuncName is the function name.
140+
FuncName string
141+
142+
// RecvName is the receiver name, if the symbol is a
143+
// method.
144+
//
145+
// The client can create the final symbol name by
146+
// prepending RecvName to FuncName.
147+
RecvName string
148+
149+
// Position describes an arbitrary source position
150+
// including the file, line, and column location.
151+
// A Position is valid if the line number is > 0.
152+
Position token.Position
10153
}

‎internal/govulncheck/run.go

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
// Copyright 2022 The Go Authors. All rights reserved.
2+
// Use of this source code is governed by a BSD-style
3+
// license that can be found in the LICENSE file.
4+
5+
package govulncheck
6+
7+
import (
8+
"context"
9+
"errors"
10+
"io"
11+
12+
"golang.org/x/vuln/vulncheck"
13+
)
14+
15+
// Source reports vulnerabilities that affect the analyzed packages.
16+
//
17+
// Vulnerabilities can be called (affecting the package, because a vulnerable
18+
// symbol is actually exercised) or just imported by the package
19+
// (likely having a non-affecting outcome).
20+
//
21+
// This function is used for source code analysis by cmd/govulncheck and
22+
// exp/govulncheck.
23+
//
24+
// TODO(https://go.dev/issue/56042): implement
25+
func Source(ctx context.Context, cfg *Config, pkgs []*vulncheck.Package) (*Result, error) {
26+
return nil, errors.New("not implemented")
27+
}
28+
29+
// Binary detects presence of vulnerable symbols in exe.
30+
//
31+
// This function is used for binary analysis by cmd/govulncheck.
32+
//
33+
// TODO(https://go.dev/issue/56042): implement
34+
func Binary(ctx context.Context, cfg *Config, exe io.ReaderAt) (*Result, error) {
35+
return nil, errors.New("not implemented")
36+
}

0 commit comments

Comments
 (0)