README
¶
Package tools
Purpose
Provides automatic installation and version management for external CLI tools required by quark (trivy, dockle).
Functionality
- Auto-installation - Automatically installs missing tools using
go install - Commit hash pinning - Tools pinned to specific git commits for immutability and reproducibility
- Session caching - Tracks installed tools per session to avoid redundant checks
- PATH verification - Ensures tools are accessible after installation
Public API
type Tool struct {
Name string // Binary name
ImportPath string // Go import path
Version string // Commit hash
}
type Installer struct { ... }
func NewInstaller(log zerolog.Logger) *Installer
// Installation operations
func (i *Installer) Ensure(tool Tool) (string, error)
func (i *Installer) GetToolPath(tool Tool) string
// Predefined tools
var Trivy Tool // v0.59.1 pinned to commit 9aabfd2
var Dockle Tool // v0.4.15 pinned to commit 5436857
Design
- Immutable versioning: Uses git commit SHAs instead of tags (tags can be moved/deleted)
- Reproducible builds: Same commit always produces same binary
- Go module integration: Uses
go installfor automatic compilation and installation - Thread-safe: Mutex-protected installation tracking
- GOPATH/GOBIN aware: Respects user's Go environment configuration
Installation Strategy
Tools are installed via go install <import-path>@<commit-hash>:
- Check if tool already verified in current session (fast path)
- Check if tool exists in PATH
- If not found, run
go installwith pinned commit hash - Verify installation succeeded and tool is now in PATH
- Cache result for session
Version Pinning
Commit hashes provide cryptographic immutability:
- Git commit SHA-256 hashes are permanent and cannot be changed
- Go modules automatically convert to pseudo-versions (e.g.,
v0.0.0-20250205xxxxxx-9aabfd2) - No risk of tag deletion or movement breaking builds
Updating Tools
To update a tool version:
- Find the release on GitHub
- Get the commit hash for that release tag
- Update the
Versionfield in the Tool definition - Test with
go install <import-path>@<new-commit-hash>
Dependencies
- External: Uses
go installcommand (requires Go toolchain) - Internal: None (standalone module)
Security Notes
- Tools are compiled from source (not downloading pre-built binaries)
- Source code is controlled by commit hash pinning
- No supply chain attacks via moved/deleted tags
Documentation
¶
Overview ¶
Package tools provides auto-installation for external tools.
Installation Strategy ¶
Tools are installed using `go install <import-path>@<commit-hash>` which provides: - Immutable pinning: commit hashes never change (unlike tags which can be moved) - Reproducible builds: same commit always produces same binary - Security: we control exact source code being compiled
Version Pinning ¶
Commit hashes are used instead of version tags because: - Git tags can be deleted or moved to different commits - Commit SHA-256 hashes are cryptographically immutable - Go modules convert commit hashes to pseudo-versions automatically
Example: go install github.com/aquasecurity/trivy/cmd/trivy@9aabfd2 Go converts to: v0.0.0-20250205xxxxxx-9aabfd2 (pseudo-version)
Updating Tool Versions ¶
To update a tool: 1. Find the release on GitHub (e.g., github.com/aquasecurity/trivy/releases) 2. Get the commit hash for that release tag 3. Update the Version field in the Tool struct 4. Test with `go install <import-path>@<new-commit-hash>`
Never use short commit hashes in production - always use at least 7 characters for collision resistance (Go will accept and expand them).
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // Trivy vulnerability scanner - pinned to v0.59.1 (commit 9aabfd2). Trivy = Tool{ Name: "trivy", ImportPath: "github.com/aquasecurity/trivy/cmd/trivy", Version: "9aabfd2", } // Dockle container image linter - pinned to v0.4.15 (commit 5436857). Dockle = Tool{ Name: "dockle", ImportPath: "github.com/goodwithtech/dockle/cmd/dockle", Version: "5436857", } )
Functions ¶
This section is empty.
Types ¶
type Installer ¶
type Installer struct {
// contains filtered or unexported fields
}
Installer manages tool installation.
func NewInstaller ¶
NewInstaller creates a new tool installer.
func (*Installer) Ensure ¶
Ensure ensures the tool is installed and available. Returns the path to the tool binary.
func (*Installer) GetToolPath ¶
GetToolPath returns the expected path for a tool in GOPATH/bin or GOBIN.
Source Files