mcp

type Accepted struct {
	RuleID           string `json:"ruleId"`
	Severity         string `json:"severity"`
	Location         string `json:"location,omitempty"`
	Component        string `json:"component,omitempty"`
	Package          string `json:"package,omitempty"`
	Version          string `json:"version,omitempty"`
	Justification    string `json:"justification" jsonschema:"the reason recorded with the decision"`
	AcceptedBy       string `json:"acceptedBy,omitempty" jsonschema:"who accepted it; empty means the decision is unattributed"`
	Expires          string `json:"expires,omitempty" jsonschema:"YYYY-MM-DD the acceptance lapses; empty means it does not"`
	Origin           string `` /* 167-byte string literal not displayed */
	Author           string `json:"author,omitempty" jsonschema:"who made an imported VEX statement"`
	Asserted         string `json:"asserted,omitempty" jsonschema:"when an imported VEX statement was made"`
	Source           string `json:"source,omitempty" jsonschema:"the descriptor, fragment or VEX document the decision was written in"`
	VEXStatus        string `json:"vexStatus,omitempty" jsonschema:"not_affected, affected or fixed; empty reads as affected"`
	VEXJustification string `json:"vexJustification,omitempty" jsonschema:"why the product is not affected, from VEX's fixed vocabulary"`
}

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.controls 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 Escalation struct {
	From   string `json:"from" jsonschema:"the severity the scanner reported"`
	To     string `json:"to" jsonschema:"the severity the finding was ranked at"`
	Signal string `json:"signal" jsonschema:"kev (observed exploitation) or epss (predicted probability of exploitation)"`
	Detail string `json:"detail"`
	AsOf   string `json:"asOf,omitempty" jsonschema:"the day the dataset was obtained, YYYY-MM-DD"`
}

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 Feed struct {
	Signal    string  `json:"signal" jsonschema:"kev or epss"`
	AsOf      string  `json:"asOf,omitempty" jsonschema:"the day the copy was obtained, YYYY-MM-DD; empty for a file supplied by hand"`
	Stale     bool    `json:"stale,omitempty" jsonschema:"the copy was older than the scan's maxAge when it was read"`
	Entries   int     `json:"entries,omitempty"`
	Threshold float64 `json:"threshold,omitempty" jsonschema:"the EPSS probability at or above which a finding was raised"`
}

type FeedStatus struct {
	Name        string `json:"name" jsonschema:"the feed, as named to draugr feeds update"`
	Description string `json:"description"`
	Cached      bool   `json:"cached"`
	FetchedAt   string `json:"fetchedAt,omitempty" jsonschema:"when Draugr fetched the cached copy, RFC 3339 in UTC"`
	Age         string `json:"age,omitempty" jsonschema:"how long ago the cached copy was fetched, rounded for reading"`
	AgeSeconds  int64  `json:"ageSeconds,omitempty"`
	Stale       bool   `json:"stale" jsonschema:"true when the cached copy is older than maxAge"`
	Source      string `json:"source" jsonschema:"the URL the feed is fetched from"`
	Bytes       int64  `json:"bytes,omitempty" jsonschema:"size of the cached copy on disk, decompressed"`
	Size        string `json:"size,omitempty" jsonschema:"size of the cached copy, rounded for reading"`
	SHA256      string `json:"sha256,omitempty" jsonschema:"digest of the cached copy, recorded when it was fetched"`
	// IfStale is stated for every feed, cached or not, because the consequence differs by feed:
	// an exploitability feed past its age is still read, and the Go database is not.
	IfStale string `json:"ifStale" jsonschema:"what a scan does with this feed once its copy is stale"`
}

type FeedsStatusOutput struct {
	Dir     string       `json:"dir" jsonschema:"the feed cache directory"`
	MaxAge  string       `` /* 133-byte string literal not displayed */
	Feeds   []FeedStatus `json:"feeds"`
	Missing []string     `json:"missing,omitempty" jsonschema:"feeds with no cached copy"`
	Stale   []string     `json:"stale,omitempty" jsonschema:"feeds whose cached copy is older than maxAge"`
	// Next is the command a person would run. Draugr will not run it for you.
	Next string `` /* 131-byte string literal not displayed */
	Note string `json:"note"`
}

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 */

	// The evidence behind the rank, as fields rather than a sentence, so an assistant asked "why is
	// this P1" or "can we even reach it" answers from what Draugr decided rather than guessing.
	Reachability *Reachability `` /* 132-byte string literal not displayed */
	Escalation   *Escalation   `json:"escalation,omitempty" jsonschema:"the exploitability signal that raised this finding's severity, when one did"`
	AlsoFoundBy  []string      `json:"alsoFoundBy,omitempty" jsonschema:"other scanners that reported the same flaw; counted once, under this finding"`
}

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; `draugr mcp` passes
	// ScanEffects.
	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 ProposeInput struct {
	Path string `` /* 169-byte string literal not displayed */
	// PerDirectory is `draugr init --per-directory`.
	PerDirectory bool `` /* 152-byte string literal not displayed */
}

type ProposeOutput struct {
	// Saga is the descriptor as YAML, byte for byte what `draugr init` would write.
	Saga string `` /* 155-byte string literal not displayed */
	// Path is where the descriptor belongs: its repositories are written relative to it.
	Path string `json:"path" jsonschema:"the file to save the descriptor as; its repository URLs are relative to this directory"`
	// Components and Controls describe what the proposal asks for without parsing it.
	Components []string `json:"components,omitempty"`
	Controls   []string `json:"controls,omitempty"`
	// Existing names the descriptors already in the directory. `draugr init` refuses to overwrite
	// one, and a proposal handed back beside an existing file reads as a replacement for it unless
	// something says the file is there.
	Existing []string `` /* 145-byte string literal not displayed */
	Note     string   `json:"note,omitempty"`
	Warning  string   `json:"warning,omitempty"`
}

type Reachability struct {
	State    string   `json:"state" jsonschema:"reachable, unreachable, or unknown (the analyzer ran and could not tell)"`
	Analyzer string   `json:"analyzer" jsonschema:"the tool that decided"`
	Method   string   `json:"method,omitempty" jsonschema:"how it decided, for example symbol-level call graph"`
	RankedAs string   `json:"rankedAs,omitempty" jsonschema:"the severity the finding was ranked at after reachability was applied, when it moved"`
	Symbols  []string `json:"symbols,omitempty" jsonschema:"the vulnerable functions the analyzer looked for"`
	Path     []string `json:"path,omitempty" jsonschema:"one call path from this project's code to a vulnerable function, outermost first"`
}

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"`
	// Unread names the dependency files in scope that no scanner took packages from, and the
	// Terraform files calling a module no scanner loaded.
	Unread []UnreadFile `` /* 174-byte string literal not displayed */
	// 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 the results.sarif draugr scan wrote; report.json beside it holds the verdict and no findings"`
	// 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        `json:"suppressed,omitempty" jsonschema:"findings a recorded decision took out of the ranking; not part of total"`
	Returned   int        `json:"returned"`
	Counts     Counts     `json:"counts"`
	Findings   []Finding  `json:"findings"`
	Accepted   []Accepted `` /* 172-byte string literal not displayed */
	// Feeds is empty when no exploitability data was loaded, which is the answer to "was this
	// checked against KEV" and not an omission.
	Feeds []Feed `` /* 135-byte string literal not displayed */
	Next  string `json:"next" jsonschema:"what to do with this result"`
	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; omitted when empty"`
}

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 UnreadFile struct {
	Component  string   `json:"component"`
	Repository string   `json:"repository,omitempty"`
	Path       string   `json:"path"`
	Reason     string   `json:"reason" jsonschema:"no lockfile, no pinned versions, no packages read, or modules not loaded"`
	Controls   []string `json:"controls" jsonschema:"the controls whose scanners did not read it"`
}

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"`
}