Documentation
¶
Index ¶
- Constants
- func NewServer(mcpCtx Context) *server.MCPServer
- type CompactDiffResponse
- type CompactDiffSummary
- type CompactExplainMatch
- type CompactExplainResponse
- type CompactFinding
- type CompactScanResponse
- type CompactSummary
- type Context
- type Diagnostic
- type DiffRequest
- type DiffRunResult
- type ExplainRequest
- type ExplainRunResult
- type OptionsAdapter
- type PackageIdentity
- type ProjectSummary
- type RemediationGroup
- type ScanRequest
- type ScanRunResult
- type SecurityDelta
- type TruncationInfo
Constants ¶
const ( ClassificationFixAvailable = "fix_available" ClassificationNoFixUpstream = "no_fix_upstream" ClassificationWontFix = "wont_fix" ClassificationPolicyOnly = "policy_only" ClassificationUnknown = "unknown" )
Classification values for CompactFinding.Classification.
const ( ActionDirectBump = "direct-bump" ActionTransitiveOverride = "transitive-override" ActionLockfileRefresh = "lockfile-refresh" ActionNoFixUpstream = "no-fix-upstream" ActionPolicyReview = "policy-review" )
Remediation actions for RemediationGroup.Action.
const CompactSchemaVersion = "mcp/1"
CompactSchemaVersion tags the agent-facing MCP response shapes. It is versioned independently of the CLI JSON schema: MCP responses are compact projections sized for tool-result limits, not the full document contract.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type CompactDiffResponse ¶ added in v0.17.0
type CompactDiffResponse struct {
SchemaVersion string `json:"schema_version"`
Command string `json:"command"`
Comparison output.DiffComparison `json:"comparison"`
Summary CompactDiffSummary `json:"summary"`
SecurityDelta SecurityDelta `json:"security_delta"`
Remediations []RemediationGroup `json:"remediations,omitempty"`
Diagnostics []Diagnostic `json:"diagnostics,omitempty"`
Truncation *TruncationInfo `json:"truncation,omitempty"`
Hint string `json:"hint,omitempty"`
}
CompactDiffResponse is the bomly_diff tool result: the branch-aware security delta ("what does this ref fix vs base, what remains after merge") with integrated remediation context for what is still open.
func BuildCompactDiff ¶ added in v0.17.0
func BuildCompactDiff(run DiffRunResult) CompactDiffResponse
BuildCompactDiff projects a diff run into the agent-facing compact response. Introduced and persisted findings — the ones still open after merge — get remediation groups built against the head state; resolved findings are listed against the base registry (they no longer exist on head).
type CompactDiffSummary ¶ added in v0.17.0
type CompactDiffSummary struct {
ManifestsAdded int `json:"manifests_added,omitempty"`
ManifestsChanged int `json:"manifests_changed,omitempty"`
ManifestsRemoved int `json:"manifests_removed,omitempty"`
PackagesAdded int `json:"packages_added,omitempty"`
PackagesChanged int `json:"packages_changed,omitempty"`
PackagesRemoved int `json:"packages_removed,omitempty"`
Introduced int `json:"introduced,omitempty"`
Resolved int `json:"resolved,omitempty"`
Persisted int `json:"persisted,omitempty"`
EnrichRan bool `json:"enrich_ran"`
AuditRan bool `json:"audit_ran"`
}
CompactDiffSummary counts manifest/package/finding deltas.
type CompactExplainMatch ¶ added in v0.17.0
type CompactExplainMatch struct {
Package output.PackageRef `json:"package"`
Direct *bool `json:"direct,omitempty"`
Paths [][]string `json:"paths,omitempty"`
Remediations []RemediationGroup `json:"remediations,omitempty"`
Findings []CompactFinding `json:"findings,omitempty"`
ManifestPath string `json:"manifest_path,omitempty"`
PackageManager string `json:"package_manager,omitempty"`
}
CompactExplainMatch is one resolved target for the queried package: where it sits in the graph, its full advisory detail, and the remediation context for its findings.
type CompactExplainResponse ¶ added in v0.17.0
type CompactExplainResponse struct {
SchemaVersion string `json:"schema_version"`
Command string `json:"command"`
Query string `json:"query"`
Matches []CompactExplainMatch `json:"matches"`
Diagnostics []Diagnostic `json:"diagnostics,omitempty"`
Truncation *TruncationInfo `json:"truncation,omitempty"`
Hint string `json:"hint,omitempty"`
}
CompactExplainResponse is the bomly_explain tool result: dependency paths plus full advisory detail and integrated fix context for one package. Bounded by construction — one package's advisories are a few KB.
func BuildCompactExplain ¶ added in v0.17.0
func BuildCompactExplain(query string, run ExplainRunResult) CompactExplainResponse
BuildCompactExplain projects an explain run into the agent-facing shape. The full ExplainResponse target payloads stay the source of paths and package identity; the raw findings/graph/registry attach remediation.
type CompactFinding ¶ added in v0.17.0
type CompactFinding struct {
VulnID string `json:"vuln_id"`
Kind string `json:"kind"`
Aliases []string `json:"aliases,omitempty"`
Severity string `json:"severity,omitempty"`
Disposition string `json:"disposition,omitempty"`
Classification string `json:"classification"`
Package PackageIdentity `json:"package"`
Direct *bool `json:"direct,omitempty"`
ShortestPath []string `json:"shortest_path,omitempty"`
FixedIn string `json:"fixed_in,omitempty"`
KEV bool `json:"kev,omitempty"`
EPSS float64 `json:"epss,omitempty"`
Reachability string `json:"reachability,omitempty"`
Title string `json:"title,omitempty"`
}
CompactFinding is one actionable-or-informational finding, sized for agent consumption: advisory identifiers and fix data, no descriptions, reference URLs, or CVSS vectors. Full advisory detail for one package is available via the bomly_explain tool.
type CompactScanResponse ¶ added in v0.17.0
type CompactScanResponse struct {
SchemaVersion string `json:"schema_version"`
Command string `json:"command"`
Project ProjectSummary `json:"project"`
Summary CompactSummary `json:"summary"`
Remediations []RemediationGroup `json:"remediations,omitempty"`
Informational []CompactFinding `json:"informational,omitempty"`
Packages []string `json:"packages,omitempty"`
Diagnostics []Diagnostic `json:"diagnostics,omitempty"`
Truncation *TruncationInfo `json:"truncation,omitempty"`
Hint string `json:"hint,omitempty"`
}
CompactScanResponse is the bomly_scan tool result: remediation-grouped actionable findings plus counts of everything omitted. For the complete JSON document use the CLI (`bomly scan --format json`); for full advisory detail on one package use bomly_explain.
func BuildCompactScan ¶ added in v0.17.0
func BuildCompactScan(run ScanRunResult) CompactScanResponse
BuildCompactScan projects a full scan run into the agent-facing compact response: ranked remediation groups, informational findings, coverage counts, and pipeline diagnostics. Without audit it returns a summary plus a capped package inventory.
type CompactSummary ¶ added in v0.17.0
type CompactSummary struct {
Manifests int `json:"manifests"`
TotalPackages int `json:"total_packages"`
VulnerablePackages int `json:"vulnerable_packages,omitempty"`
CleanPackages int `json:"clean_packages,omitempty"`
FindingsBySeverity map[string]int `json:"findings_by_severity,omitempty"`
Actionable int `json:"actionable,omitempty"`
Informational int `json:"informational,omitempty"`
EnrichRan bool `json:"enrich_ran"`
AuditRan bool `json:"audit_ran"`
}
CompactSummary tells the agent what the scan covered and what the compact response omitted (clean packages are counted, not listed).
type Context ¶
type Context struct {
Adapter OptionsAdapter
Version string
}
Context carries the adapter and version into tool handlers.
type Diagnostic ¶ added in v0.17.0
type Diagnostic struct {
Stage string `json:"stage"`
Source string `json:"source,omitempty"`
Message string `json:"message"`
}
Diagnostic surfaces one pipeline warning (detector fallback, matcher failure, analyzer degradation) so agents can see why results may be partial without re-running with -v.
type DiffRequest ¶
type DiffRequest struct {
Base string `json:"base"`
Head string `json:"head"`
Path string `json:"path"`
Image string `json:"image"`
SBOM bool `json:"sbom"`
Enrich bool `json:"enrich"`
Audit bool `json:"audit"`
Analyze bool `json:"analyze"`
FailOn string `json:"fail_on"`
AllowVulnerabilityIDs string `json:"allow_vulnerability_ids"`
AllowLicenses string `json:"allow_licenses"`
DenyLicenses string `json:"deny_licenses"`
LicenseExemptPackages string `json:"license_exempt_packages"`
DenyPackages string `json:"deny_packages"`
DenyGroups string `json:"deny_groups"`
ProtectedPackages string `json:"protected_packages"`
TyposquatThreshold string `json:"typosquat_threshold"`
TyposquatMode string `json:"typosquat_mode"`
WarnOnly bool `json:"warn_only"`
}
DiffRequest holds per-call overrides for the bomly_diff tool.
type DiffRunResult ¶ added in v0.17.0
type DiffRunResult struct {
Response output.DiffResponse
Introduced []sdk.Finding
Resolved []sdk.Finding
Persisted []sdk.Finding
HeadGraph *sdk.Graph
HeadRegistry *sdk.PackageRegistry
BaseRegistry *sdk.PackageRegistry
HeadManifests []output.ScanManifest
Diagnostics []Diagnostic
EnrichRan bool
AuditRan bool
}
DiffRunResult carries a diff run's output plus the audit delta buckets ([]sdk.Finding per bucket, computed version-independently by advisory id) and the head-side domain data used to build remediation context for what remains after merge.
type ExplainRequest ¶
type ExplainRequest struct {
Package string `json:"package"`
Path string `json:"path"`
Enrich bool `json:"enrich"`
Audit bool `json:"audit"`
Analyze bool `json:"analyze"`
}
ExplainRequest holds per-call overrides for the bomly_explain tool.
type ExplainRunResult ¶ added in v0.17.0
type ExplainRunResult struct {
Response output.ExplainResponse
Findings []sdk.Finding
Graph *sdk.Graph
Registry *sdk.PackageRegistry
Manifests []output.ScanManifest
Diagnostics []Diagnostic
EnrichRan bool
AuditRan bool
}
ExplainRunResult carries an explain run's output plus the raw domain data the compact builders need to attach remediation context to the queried package.
type OptionsAdapter ¶
type OptionsAdapter interface {
RunScan(ctx context.Context, req ScanRequest) (ScanRunResult, error)
RunExplain(ctx context.Context, req ExplainRequest) (ExplainRunResult, error)
RunDiff(ctx context.Context, req DiffRequest) (DiffRunResult, error)
ListPlugins(ctx context.Context) (managedplugin.ListResponse, error)
}
OptionsAdapter is implemented by the CLI adapter in internal/cli/mcp_cmd.go. It lives in package cli so it can access unexported pipeline helpers.
type PackageIdentity ¶ added in v0.17.0
type PackageIdentity struct {
Name string `json:"name"`
Org string `json:"org,omitempty"`
Version string `json:"version,omitempty"`
Purl string `json:"purl,omitempty"`
Ecosystem string `json:"ecosystem,omitempty"`
}
PackageIdentity carries the full identity of a package: the ecosystem-native display name (e.g. "@tailwindcss/postcss"), the org/scope component, and the PURL. Presentation code must never collapse scoped names to the bare name.
func (PackageIdentity) Label ¶ added in v0.17.0
func (p PackageIdentity) Label() string
Label returns a human-readable name@version label.
type ProjectSummary ¶ added in v0.17.0
type ProjectSummary struct {
Name string `json:"name,omitempty"`
Path string `json:"path,omitempty"`
}
ProjectSummary is a lean project descriptor for compact responses.
type RemediationGroup ¶ added in v0.17.0
type RemediationGroup struct {
Action string `json:"action"`
TargetPackage PackageIdentity `json:"target_package"`
ManifestPath string `json:"manifest_path,omitempty"`
PackageManager string `json:"package_manager,omitempty"`
RecommendedVersion string `json:"recommended_version,omitempty"`
OverrideAdvice string `json:"override_advice,omitempty"`
Recommendation string `json:"recommendation,omitempty"`
Fixes []CompactFinding `json:"fixes"`
}
RemediationGroup is the integrated fix context: one concrete change (bump this direct dependency in this manifest to this version) and every finding that change closes. Groups are ranked most-urgent first.
type ScanRequest ¶
type ScanRequest struct {
Path string `json:"path"`
Image string `json:"image"`
URL string `json:"url"`
Ref string `json:"ref"`
Enrich bool `json:"enrich"`
Audit bool `json:"audit"`
Analyze bool `json:"analyze"`
FailOn string `json:"fail_on"`
Ecosystems string `json:"ecosystems"`
Scope string `json:"scope"`
}
ScanRequest holds per-call overrides for the bomly_scan tool.
type ScanRunResult ¶ added in v0.17.0
type ScanRunResult struct {
Response output.ScanResponse
Findings []sdk.Finding
Graph *sdk.Graph
Registry *sdk.PackageRegistry
Diagnostics []Diagnostic
EnrichRan bool
AuditRan bool
}
ScanRunResult carries a scan run's full output back to the MCP layer: the structured response plus the raw domain data (findings, graph, registry) the compact builders group and rank, and the pipeline diagnostics mapped by the adapter (internal/mcp never imports internal/engine).
type SecurityDelta ¶ added in v0.17.0
type SecurityDelta struct {
Introduced []CompactFinding `json:"introduced,omitempty"`
Resolved []CompactFinding `json:"resolved,omitempty"`
Persisted []CompactFinding `json:"persisted,omitempty"`
}
SecurityDelta buckets advisory findings by what merging head changes.
type TruncationInfo ¶ added in v0.17.0
type TruncationInfo struct {
Truncated bool `json:"truncated"`
OmittedFindings int `json:"omitted_findings,omitempty"`
OmittedGroups int `json:"omitted_groups,omitempty"`
OmittedPackages int `json:"omitted_packages,omitempty"`
OmittedPaths int `json:"omitted_paths,omitempty"`
Note string `json:"note,omitempty"`
}
TruncationInfo reports exactly what the caps cut so the agent knows the response is partial and how to drill down.
Source Files