mcp

type CheckToolsInput struct {
	Path string `json:"path,omitempty" jsonschema:"path to a Saga descriptor; without it, every tool Draugr knows about is checked"`
}

type CheckToolsOutput struct {
	Ready   bool         `json:"ready" jsonschema:"true when nothing required is missing"`
	Tools   []ToolStatus `json:"tools"`
	Missing []string     `json:"missing,omitempty" jsonschema:"required tools that are absent"`
	// Remedy is the single command that installs everything missing.
	Remedy string `json:"remedy,omitempty"`
	Note   string `json:"note"`
}

type Control struct {
	Name            string   `json:"name" jsonschema:"the control's name, as used under config.controllers in a Saga"`
	Scope           string   `json:"scope" jsonschema:"whether the control runs per component or once for the project"`
	Purpose         string   `json:"purpose" jsonschema:"what the control checks for"`
	DefaultScanners []string `json:"defaultScanners" jsonschema:"scanners that run when the control is enabled"`
	OptInScanners   []string `` /* 134-byte string literal not displayed */
	// ScannerOptions is what each of this control's scanners accepts in its Saga block, keyed by
	// scanner name. An entry present but empty means that scanner accepts no options; anything
	// else written under its block is rejected before the scan runs.
	ScannerOptions map[string][]plugin.Option `` /* 151-byte string literal not displayed */
}

type ControlsOutput struct {
	Controls []Control `json:"controls"`
	// Hint is where the agent should put what it learned. Returning capability without saying
	// how to use it just moves the guesswork somewhere else.
	Hint string `json:"hint"`
}

type Counts struct {
	Critical int `json:"critical"`
	High     int `json:"high"`
	Medium   int `json:"medium"`
	Low      int `json:"low"`
}

type DiffInput struct {
	BasePath string `json:"basePath" jsonschema:"path to the results.sarif from the base revision"`
	HeadPath string `json:"headPath" jsonschema:"path to the results.sarif from the revision being proposed"`
	// FailOnNew mirrors the flag CI uses, so an assistant can ask the question the pipeline
	// will ask rather than a different one.
	FailOnNew string `` /* 261-byte string literal not displayed */
	Limit     int    `json:"limit,omitempty" jsonschema:"maximum new findings to return; defaults to 20"`
}

type DiffOutput struct {
	NewCount   int `json:"newCount" jsonschema:"findings present in head and absent from base"`
	FixedCount int `json:"fixedCount" jsonschema:"findings present in base and absent from head"`
	// New is what the change introduced, most urgent first, carrying the same remediation and
	// package detail a summary does.
	New []Finding `json:"new,omitempty"`
	// Fixed is named rather than only counted, because it is the half of a change worth saying
	// out loud and an assistant summarizing a diff has nothing else to praise.
	Fixed []Finding `json:"fixed,omitempty"`
	// WouldFail answers the question CI will ask, when failOnNew is given.
	WouldFail   bool   `json:"wouldFail,omitempty" jsonschema:"true when a new finding meets failOnNew; only meaningful when failOnNew was given"`
	GateApplied string `json:"gateApplied,omitempty" jsonschema:"the threshold wouldFail was computed against"`
	Note        string `json:"note,omitempty"`
}

type EmptyInput struct{}

type ExplainInput struct {
	RuleID string `json:"ruleId" jsonschema:"the rule to explain, in full or by the part that is unambiguous: 4.3.1 finds kube-bench/cis/4.3.1"`
	Path   string `json:"path" jsonschema:"path to a results.sarif produced by draugr scan"`
}

type ExplainOutput struct {
	RuleID      string   `json:"ruleId"`
	Description string   `json:"description,omitempty" jsonschema:"what the check is, in full rather than the truncated line a report shows"`
	Remediation string   `json:"remediation,omitempty" jsonschema:"how to fix it, as the scanner published it"`
	HelpURI     string   `json:"helpUri,omitempty"`
	FoundIn     []string `json:"foundIn,omitempty" jsonschema:"where this rule fired, capped"`
	Note        string   `json:"note,omitempty"`
}

type Finding struct {
	Priority string  `json:"priority,omitempty" jsonschema:"P1 (act now) through P4 (lowest)"`
	Severity string  `json:"severity" jsonschema:"critical, high, medium or low"`
	Score    float64 `json:"score,omitempty" jsonschema:"CVSS-style numeric severity, when the scanner gave one"`
	RuleID   string  `json:"ruleId"`
	Scanner  string  `json:"scanner,omitempty"`
	Location string  `json:"location,omitempty" jsonschema:"file:line, image reference, or endpoint"`
	Message  string  `json:"message"`
	HelpURI  string  `json:"helpUri,omitempty" jsonschema:"where the rule is documented, for background beyond the remediation below"`

	// Remediation is the fix in the scanner's own words, not a summary of it.
	Remediation string `` /* 137-byte string literal not displayed */
	// Action classifies what kind of fix it is, so an assistant can tell work it can do from
	// work that belongs to whoever publishes the image or operates the cluster.
	Action string `` /* 217-byte string literal not displayed */
	// Package names what to upgrade and to what.
	Package      string `json:"package,omitempty" jsonschema:"the package this finding is in"`
	Version      string `json:"version,omitempty" jsonschema:"the version installed"`
	FixedVersion string `` /* 153-byte string literal not displayed */
	Ecosystem    string `` /* 139-byte string literal not displayed */
	PURL         string `json:"purl,omitempty" jsonschema:"package URL, portable across ecosystems"`
	// Component ties a finding to the part of the system it was found in, which is what its
	// priority was computed from.
	Component string `json:"component,omitempty" jsonschema:"the component in the descriptor this finding belongs to"`
	// Image and OSEndOfLife answer "why can I not just upgrade this".
	Image       string `json:"image,omitempty" jsonschema:"the image this finding is in, when it came from one"`
	OSEndOfLife bool   `` /* 134-byte string literal not displayed */
}

type FixListInput struct {
	Path  string `json:"path" jsonschema:"path to a results.sarif produced by draugr scan"`
	Limit int    `json:"limit,omitempty" jsonschema:"maximum actions to return; defaults to 20"`
}

type FixListOutput struct {
	Actions []report.Action `json:"actions" jsonschema:"things to do, most urgent first; each says how many findings it clears"`
	Clears  int             `json:"clears" jsonschema:"findings these actions resolve between them"`
	Note    string          `json:"note,omitempty"`
}

type ListSurveyorsOutput struct {
	Surveyors []SurveyorInfo `json:"surveyors"`
	Hint      string         `json:"hint"`
}

type Options struct {
	// Scan says whether a client may start scans. The zero value is ScanOff.
	Scan ScanMode
	// Registry supplies the controllers and scanners. Required.
	Registry *engine.Registry
	// Root is the directory searched for Saga descriptors to expose as resources. Empty means
	// the working directory.
	Root string
	// Surveyors supplies the discovery plugins. Empty disables survey and list_surveyors, so a
	// caller embedding this server chooses whether it may reach a cluster or a forge at all.
	Surveyors *surveyor.Registry
}

type ScanInput struct {
	Path        string `json:"path" jsonschema:"path to the Saga descriptor to scan"`
	MinPriority string `json:"minPriority,omitempty" jsonschema:"only return findings at this priority or above: p1, p2, p3 or p4"`
	Limit       int    `json:"limit,omitempty" jsonschema:"maximum findings to return; defaults to 20"`
}

type ScanMode string

type ScanOutput struct {
	Verdict string `json:"verdict" jsonschema:"pass or fail, by the same policy the CI gate applies"`
	// Controls that actually ran, so the caller can see the scope rather than infer it.
	Controls []string `json:"controls" jsonschema:"the controls this scan ran; nothing outside them was examined"`
	// Uncovered names surfaces the descriptor declares that no enabled control looked at.
	Uncovered []string `json:"uncovered,omitempty" jsonschema:"surfaces this descriptor declares that no enabled control examined"`
	// Unexamined is the same sentence for everything no control covers at all.
	Unexamined string `json:"unexamined" jsonschema:"what a Draugr scan does not examine, whatever the verdict"`
	// Delivered names where the descriptor's publishers put the report, so a caller can point
	// the user at a file, or read it back later instead of scanning again.
	Delivered []string `json:"delivered,omitempty" jsonschema:"where this run's reports were delivered, from the descriptor's config.publishers"`
	SummarizeOutput
}

type SchemaOutput struct {
	Schema  map[string]any `json:"schema" jsonschema:"the JSON Schema for a Saga descriptor"`
	Version string         `json:"draugrVersion" jsonschema:"the Draugr build this schema came from"`
	Hint    string         `json:"hint"`
}

type SummarizeInput struct {
	Path string `json:"path" jsonschema:"path to a results.sarif or report.json produced by draugr scan"`
	// MinPriority narrows the list the way --min-priority does on the CLI.
	MinPriority string `json:"minPriority,omitempty" jsonschema:"only return findings at this priority or above: p1, p2, p3 or p4"`
	// Limit caps how many findings come back. Context is the scarce resource here.
	Limit int `json:"limit,omitempty" jsonschema:"maximum findings to return; defaults to 20"`
}

type SummarizeOutput struct {
	Total int `json:"total" jsonschema:"findings the report judged, before any priority filter; excludes suppressed"`
	// Suppressed is reported rather than hidden: an assistant that cannot see a decision was
	// made cannot tell an accepted risk from one nobody has looked at.
	Suppressed int       `` /* 139-byte string literal not displayed */
	Returned   int       `json:"returned"`
	Counts     Counts    `json:"counts"`
	Findings   []Finding `json:"findings"`
	Note       string    `json:"note,omitempty"`
}

type SurveyInput struct {
	// Surveys is a list because an application is rarely one surface. The repositories in an
	// organization and the images running in a namespace are the same application described twice,
	// and merging them into one descriptor is the point. Running them separately gives two
	// descriptors that each look complete.
	Surveys []SurveyRequest `json:"surveys" jsonschema:"the surveyors to run; results merge into one descriptor"`
	Name    string          `json:"name,omitempty" jsonschema:"project name for the descriptor"`
	Version string          `json:"version,omitempty" jsonschema:"release version for the descriptor; defaults to 0.0.0"`
}

type SurveyOutput struct {
	// Saga is the descriptor as YAML, for the caller to show, edit and write itself.
	Saga string `json:"saga" jsonschema:"the descriptor this survey produced, as YAML"`
	// Components names what was found, so a caller can say what it discovered without parsing.
	Components []string `json:"components,omitempty"`
	// Controls are the ones the discovered surface turned on.
	Controls []string `json:"controls,omitempty"`
	Note     string   `json:"note,omitempty"`
	// Warning carries what the survey could not reach. A survey that half worked and reads as
	// complete is the failure worth naming: the descriptor looks finished and is not.
	Warning string `json:"warning,omitempty"`
}

type SurveyRequest struct {
	Surveyor string `json:"surveyor" jsonschema:"which surveyor to run; list_surveyors names them"`
	Ref      string `` /* 136-byte string literal not displayed */
}

type SurveyorInfo struct {
	Name     string   `json:"name"`
	Provides []string `json:"provides" jsonschema:"what it discovers: repositories, images, hosts"`
}

type ToolStatus struct {
	Name      string `json:"name"`
	Installed bool   `json:"installed"`
	Version   string `json:"version,omitempty"`
	Path      string `json:"path,omitempty"`
	Category  string `json:"category,omitempty" jsonschema:"scanner (backs a control) or utility (supporting, e.g. git)"`
	Optional  bool   `json:"optional,omitempty" jsonschema:"absence of an optional tool is not a problem"`
	// Install is the command a person would run. Draugr will not run it for you.
	Install string `json:"install,omitempty"`
}

type ValidateInput struct {
	Path    string `json:"path,omitempty" jsonschema:"path to a Saga descriptor on disk"`
	Content string `json:"content,omitempty" jsonschema:"the descriptor's YAML content, for validating an edit before writing it"`
}

type ValidateOutput struct {
	Valid bool `json:"valid"`
	// Error is why it isn't, in the same words the CLI would use.
	Error string `json:"error,omitempty"`
	// Components and Controls describe what the descriptor actually asks for, which is how an
	// agent checks that a descriptor says what it intended rather than merely parsing.
	Components []string `json:"components,omitempty"`
	Controls   []string `json:"controls,omitempty"`
}