tools

type Asset struct {
	URL string
	// URLTemplate renders the download URL for a version other than the pinned one, with
	// {version} substituted (no leading "v"). Empty means Draugr cannot fetch another version of
	// this platform's build, and will say so rather than guessing at a URL shape.
	URLTemplate     string
	SHA256          string
	BinaryInArchive string // name of the binary within the .tar.gz; "" = the download is the binary
	// DataInArchive is a directory prefix inside the archive to extract alongside the binary,
	// e.g. "cfg/" for kube-bench's benchmark definitions.
	//
	// Some tools are not one file. kube-bench without its cfg/ tree exits complaining about a
	// missing "target_mapping" section, which names an internal structure rather than the 276 files
	// nobody copied, so installing the binary alone is a half-install that looks whole.
	DataInArchive string
}

type Attestation struct {
	// Tool is the executable's name, e.g. "trivy".
	Tool string
	// Path is where it was found. Empty when it was not.
	Path string
	// Version is what the tool reports, when Draugr can read it.
	Version string
	// Level is how strongly Draugr can vouch for this binary.
	Level Level
	// Reason says why the level is what it is, when it is not the strongest.
	Reason string
}

type CosignSpec struct {
	// ChecksumsURL is the upstream's signed checksums file, listing each asset's SHA-256.
	ChecksumsURL string
	// ChecksumsURLTemplate and BundleURLTemplate render those URLs for another version.
	ChecksumsURLTemplate string
	BundleURLTemplate    string
	// BundleURL is the Sigstore bundle (.sigstore.json) signing ChecksumsURL.
	BundleURL string
	// IdentityRegexp is the required signing certificate identity (--certificate-identity-regexp).
	IdentityRegexp string
	// OIDCIssuer is the required OIDC issuer (--certificate-oidc-issuer).
	OIDCIssuer string
}

type Drift struct {
	// Tool is the tool's name as Draugr and its own command line spell it.
	Tool string
	// Pinned is the version this build installs.
	Pinned string
	// Latest is what the upstream publishes now, empty where the question could not be answered.
	Latest string
	// Err is why Latest is empty. A network that refused is a different answer from "current",
	// and reporting the second for the first is how a checker comes to report everything current
	// while reaching nothing.
	Err error
}

type GoSpec struct {
	// Command is the package path of the command to build.
	Command string
}

type InstallSpec struct {
	Binary  string
	Version string
	// ChecksumsURLTemplate is an *unsigned* checksums file for an arbitrary version, for an
	// upstream that publishes one but signs nothing. Weaker than Cosign and much better than
	// nothing: it catches a corrupted or truncated download.
	ChecksumsURLTemplate string
	Assets               map[string]Asset
	// Cosign, when set, verifies the release's provenance in addition to the SHA-256 pin. Nil for
	// upstreams that publish no signature (e.g. gitleaks). Those stay SHA-256-only.
	Cosign *CosignSpec
	// DataDir is where Asset.DataInArchive is written, relative to Draugr's own directory.
	// Namespaced by tool so a second tool with data files does not collide with the first.
	DataDir string
}

type Installed struct {
	Name    string
	Version string
	Path    string
	// SignatureVerified is true when an upstream cosign signature was verified (in addition
	// to the always-checked SHA-256 pin).
	SignatureVerified bool
	// ProvenanceNote summarizes the signature outcome for reporting (e.g. why it was skipped);
	// empty when the tool has no cosign provenance configured.
	ProvenanceNote string
	// AlreadyPresent is true when the pinned build was already installed and left untouched.
	AlreadyPresent bool
}

type Kind string

type Level string

type LookPathFunc func(string) (string, error)

type NodeSpec struct {
	// Package is the name on npm.
	Package string
	// Pins names the generated pair under nodepins/, without the suffixes.
	Pins string
	// Command is the executable the package provides under node_modules/.bin.
	Command string
}

type PythonSpec struct {
	// Package is the distribution name on PyPI.
	Package string
	// Pins names the generated requirements file under pythonpins/, without the extension.
	Pins string
	// MinPythonMinor is the oldest Python 3 minor this package supports.
	MinPythonMinor int
}

type RunFunc func(ctx context.Context, argv []string, env ...string) ([]byte, error)

type Status struct {
	Tool    Tool
	Found   bool
	Path    string
	Version string
	// Err is set when the tool was found but the version probe failed (non-fatal).
	Err error
	// DataFound reports whether the tool's supporting data is present. Meaningless unless the
	// tool declares DataArgs; DataChecked says whether it was asked.
	DataChecked bool
	DataFound   bool
	// DataDetail describes what was found, e.g. a template-set version.
	DataDetail string
}

type Tool struct {
	// Binary is the executable name looked up on PATH, e.g. "trivy".
	Binary string
	// VersionArgs prints the tool's version, e.g. ["--version"]. Empty skips the probe.
	VersionArgs []string
	// InstallHint tells the user how or where to install the tool when it's missing.
	InstallHint string
	// Category groups the tool: "scanner" (backs a control) or "utility" (supporting tool
	// like git or cosign). Shown in `tools list`.
	Category string
	// Optional marks a tool whose absence should not fail `doctor`. A nice-to-have that enhances
	// behavior (e.g. cosign for signature verification) rather than a requirement.
	Optional bool
	// VersionFrom reads the version out of the probe's output, for a tool that names more than
	// one. Nil takes the first semver-looking token, which is right for almost everything.
	VersionFrom func([]byte) string
	// ProbeEnv is layered over the environment for the probes below, each "K=V".
	//
	// For a tool that treats "what version are you" as an opportunity to call home. Semgrep does:
	// `semgrep --version` contacts semgrep.dev to see whether a newer release exists, and Draugr
	// asks on every scan, so the question would reach the network on a machine that has said it
	// has none. Disabling that returns the same answer.
	ProbeEnv []string
	// DataArgs probes for data the tool needs beyond its own binary, Nuclei's template set, for
	// instance. Empty means the binary is all there is.
	//
	// Being on PATH is not the same as being able to run. A tool whose data is missing fails at
	// scan time with a message about a symptom, and `doctor` exists to answer "is this going to
	// fail" before the scan rather than after it.
	DataArgs []string
	// DataFiles are paths that must exist for the tool to work, tried in order. Used where the
	// tool cannot be asked cheaply: kube-bench only reveals a missing `cfg/` by attempting a
	// benchmark, and doctor must not run a scan to find out whether a scan would work.
	DataFiles []string
	// DataOK reads DataArgs' output and reports whether the data is there, plus a short
	// description for the report. Required when DataArgs is set.
	DataOK func(out []byte) (ok bool, detail string)
	// DataHint tells the user how to obtain the data when it is missing.
	DataHint string
}

type Upstream struct {
	// Kind is how the newest version is read. Each is a different answer to the same question and
	// the difference is not cosmetic: see KindGitHubTag.
	Kind Kind
	// Ref names the thing to ask about: "owner/repo" on GitHub, a package name on PyPI or npm.
	Ref string
}