Building a Go Dependency Scanner From Scratch

What is a Go Dependency Scanner?

A Go dependency scanner is a tool that examines a Go project’s module graph to identify external packages, version constraints, and known security vulnerabilities. It parses go.mod and go.sum files, resolves transitive dependencies, and cross‑references vulnerability databases (e.g., GitHub Advisory Database, OSV).

• Provides visibility into the third‑party code your binary ships.
• Enables automated policy enforcement (e.g., disallowing vulnerable versions).
• Supports continuous integration pipelines for early risk detection.

Why Build Your Own Scanner?

While third‑party solutions exist, creating a custom scanner offers several advantages:

• Tailored policies: Align scanning rules with your organization’s risk tolerance.
• Full control over data sources: Integrate internal vulnerability feeds or proprietary advisories.
• Lightweight footprint: Only include the functionality you need, reducing build time and binary size.
• Learning opportunity: Deepen understanding of Go modules, the Go toolchain, and software supply‑chain security.

How to Build a Go Dependency Scanner From Scratch

1. Set Up the Project Structure

Create a minimal Go module that will house the scanner logic.

• Run go mod init github.com/yourorg/godep-scanner
• Organize code into packages: cmd/scan for the CLI, internal/parser for module parsing, and internal/vuln for vulnerability lookup.

2. Parse Go Module Files

Leverage the standard library’s golang.org/x/mod packages.

• Use modfile.Parse to read go.mod.
• Use modfile.Require to extract direct dependencies.
• Resolve transitive dependencies with modgraph (or invoke go list -m all and capture output).

3. Build a Dependency Graph

Represent each module as a node with version information and edges for “requires”.

• Store the graph in a map[string]*Module where the key is modulePath@version.
• Detect cycles and duplicate entries during construction.

4. Integrate Vulnerability Data

Fetch vulnerability advisories from public APIs.

• GitHub Advisory Database: GET with appropriate query.
• OSV.dev: GET (supports batch queries).
• Cache responses locally to avoid rate‑limit issues.

5. Match Advisories to Modules

For each module in the graph, compare its version against the affected version ranges in the advisory.

• Use semver comparison (package golang.org/x/mod/semver).
• Collect matches into a report structure: module, vulnerable version, advisory ID, severity, and fix version.

6. Output Results

Provide multiple output formats for CI integration.

• Human‑readable table (default).
• JSON for machine parsing: {"module":"github.com/pkg/errors","vulnerable_version":"v0.8.0","fixed_in":"v0.9.1","advisory":"GHSA-xxxx"}
• Optional SARIF export for security dashboards.

7. Package as a CLI Tool

Implement the main function in cmd/scan/main.go to accept flags:

• -path: directory of the Go project (default: current working directory).
• -format: output format (table|json|sarif).
• -quiet: exit code 0 if no vulnerabilities, 1 otherwise (useful for CI).

8. Add Tests and CI

Write unit tests for each package using the standard testing framework.

• Mock vulnerability API responses with httptest servers.
• Validate graph construction against known module sets.

Configure a CI pipeline (GitHub Actions, GitLab CI, etc.) to run go test ./... and lint with golangci-lint.

9. Distribute the Binary

Use goreleaser to produce cross‑platform binaries and optionally publish a Docker image.

• Define release assets for Linux, macOS, and Windows.
• Tag releases with semantic versioning (e.g., v1.0.0).