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 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 Level string

type LookPathFunc func(string) (string, error)

type RunFunc func(ctx context.Context, argv []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
	// 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
}