cmd

package
v0.0.0-...-80ccc60 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 14, 2026 License: Apache-2.0 Imports: 141 Imported by: 0

Documentation

Overview

Package cmd implements Deputy's CLI commands using the Cobra framework.

This package contains all subcommand implementations (scan, fix, diff, sbom, list, policy, proxy, triage) and their supporting helpers. Commands are registered via RegisterCommands which attaches them to a root Cobra command.

Command Structure

Each command follows a consistent pattern:

  • Add{Command}Command function to register with a parent command
  • Command-specific flags and configuration
  • Execution logic that delegates to internal packages

Dependencies

Commands receive shared services through the Dependencies struct, enabling dependency injection for testing and composition. The primary dependency is services.Clients which provides access to ConnectRPC service clients.

Output Formats

Most commands support multiple output formats (table, json, sarif, github) configured via the --format flag. Format-specific rendering is handled by the report/render package.

Index

Constants

View Source 
const (
	// FormatText is the human-readable text output format.
	FormatText = "text"
	// FormatJSON is the JSON output format.
	FormatJSON = "json"
	// FormatTSV is the tab-separated values output format.
	FormatTSV = "tsv"
	// FormatSARIF is the SARIF output format for security tools.
	FormatSARIF = "sarif"
	// FormatCycloneDX is the CycloneDX SBOM format.
	FormatCycloneDX = "cyclonedx"
	// FormatCycloneDXJSON is the CycloneDX JSON SBOM format.
	FormatCycloneDXJSON = "cyclonedx-json"
	// FormatSPDX is the SPDX SBOM format.
	FormatSPDX = "spdx"
	// FormatSPDXJSON is the SPDX JSON SBOM format.
	FormatSPDXJSON = "spdx-json"
)

Output format constants used across CLI commands.

Variables

This section is empty.

Functions

func AddCacheCommand 

func AddCacheCommand(root *cobra.Command)

AddCacheCommand adds the cache subcommand to the root command.

func AddConfigCommand 

func AddConfigCommand(root *cobra.Command)

AddConfigCommand adds the config command and its subcommands to the root command.

func AddDiffCommand 

func AddDiffCommand(root *cobra.Command, c *services.Clients)

AddDiffCommand registers the diff subcommand which compares dependency inventories between two Git references (or working tree) and optionally performs vulnerability scanning on changed modules.

func AddEcosystemsCommand 

func AddEcosystemsCommand(root *cobra.Command, c *services.Clients)

AddEcosystemsCommand adds the ecosystems command to the root.

func AddExecCommand 

func AddExecCommand(root *cobra.Command, deps *Dependencies)

AddExecCommand adds the exec command to the root command.

func AddExplainCommand 

func AddExplainCommand(root *cobra.Command)

AddExplainCommand adds the explain command to the root command.

func AddFixCommand 

func AddFixCommand(root *cobra.Command, c *services.Clients)

AddFixCommand registers the fix subcommand with the root command. It configures flags for report input, plan input, and AI agent options.

func AddGraphCommand 

func AddGraphCommand(root *cobra.Command, c *services.Clients)

AddGraphCommand registers the graph subcommand. Uses the service layer for graph operations, supporting both local and remote modes.

func AddInitCommand 

func AddInitCommand(root *cobra.Command)

AddInitCommand adds the init command to the root command.

func AddListCommand 

func AddListCommand(root *cobra.Command, c *services.Clients)

AddListCommand registers the list (ls) subcommand.

func AddMCPCommand 

func AddMCPCommand(root *cobra.Command)

AddMCPCommand adds the mcp command and its subcommands to the root command.

func AddPinCommand 

func AddPinCommand(root *cobra.Command)

AddPinCommand registers the pin subcommand and its children with the root command.

func AddPolicyCommand 

func AddPolicyCommand(root *cobra.Command)

AddPolicyCommand registers the `deputy policy` command tree.

func AddProxyCommand 

func AddProxyCommand(root *cobra.Command)

AddProxyCommand adds the "proxy" command and its subcommands to the root command. The proxy command allows running Deputy as an artifact proxy server.

func AddSBOMCommand 

func AddSBOMCommand(root *cobra.Command, c *services.Clients)

AddSBOMCommand registers the sbom subcommand

func AddScanCommand 

func AddScanCommand(root *cobra.Command, c *services.Clients)

AddScanCommand registers the scan subcommand with the root command. It configures the command flags and usage examples.

func AddSecretsBaselineCommand 

func AddSecretsBaselineCommand(secretsCmd *cobra.Command)

AddSecretsBaselineCommand adds the baseline subcommand to the secrets command.

func AddSecretsCommand 

func AddSecretsCommand(root *cobra.Command, c *services.Clients)

AddSecretsCommand registers the secrets subcommand with the root command.

func AddSecretsHookCommand 

func AddSecretsHookCommand(secretsCmd *cobra.Command)

AddSecretsHookCommand adds the 'secrets hook' subcommand.

func AddServerCommand 

func AddServerCommand(root *cobra.Command)

AddServerCommand adds the server command to the root command.

func AddTriageCommand 

func AddTriageCommand(root *cobra.Command, c *services.Clients)

AddTriageCommand registers the triage subcommand.

func AddVersionCommand 

func AddVersionCommand(root *cobra.Command)

AddVersionCommand adds the version command to the root.

func RegisterCommands 

func RegisterCommands(root *cobra.Command, deps *Dependencies)

RegisterCommands attaches all first-class subcommands to the provided root Cobra command. It centralizes subcommand registration for use by both the CLI entry point and tests. deps is a pointer so callers can re-resolve the connection after flag parsing (see Dependencies.ResolveConnection) and have the registered commands observe the update.

Types

type AgentResult 

type AgentResult struct {
	// Status is the overall outcome (success, partial, failed, interrupted).
	Status render.AgentStatus
	// ExitCode is the suggested process exit code (0=success, 1=failure, 130=interrupted).
	ExitCode int
	// Err is any error that occurred during execution.
	Err error
}

AgentResult captures the outcome of an agent execution.

func (AgentResult) Error 

func (r AgentResult) Error() string

Error implements the error interface, returning the underlying error message.

func (AgentResult) HasError 

func (r AgentResult) HasError() bool

HasError returns true if the result contains an error.

func (AgentResult) Success 

func (r AgentResult) Success() bool

Success returns true if the agent completed successfully (exit code 0).

type ContentWarning 

type ContentWarning struct {
	Type        string // "bidi", "control", "binary", "homoglyph"
	Description string
	Severity    string // "high", "medium", "low"
}

ContentWarning represents a security concern found in file content.

type Dependencies 

type Dependencies struct {
	// Clients provides access to Deputy services.
	// If nil, RegisterCommands creates them via ResolveConnection.
	Clients *services.Clients

	// ServerAddress is the remote server address (for remote mode).
	// Falls back to the DEPUTY_SERVER environment variable when empty.
	ServerAddress string

	// AuthToken is the bearer token for authenticating with remote servers.
	// Falls back to the DEPUTY_AUTH_TOKEN environment variable when empty.
	AuthToken string
}

Dependencies bundles shared services for CLI commands.

Connection settings resolve with explicit-value precedence: a value set on the struct (typically from a root persistent flag) beats the corresponding environment variable, and the environment variable beats the in-process default.

func (*Dependencies) ApplyConnection 

func (d *Dependencies) ApplyConnection() error

ApplyConnection builds service clients from the connection settings as they stand, without consulting the environment: an empty ServerAddress selects in-process mode and an empty AuthToken sends no bearer token. It exists so the root command can re-apply the settings after cobra has parsed the persistent flags (commands are registered before parsing) and honor flags that were explicitly set to empty values over environment variables. When d.Clients is already set, the pointed-to struct is updated in place so every command closure that captured the pointer at registration time observes the new configuration.

func (*Dependencies) ResolveConnection 

func (d *Dependencies) ResolveConnection() error

ResolveConnection fills empty connection settings from the environment (explicit value beats environment variable beats in-process default) and builds the matching service clients via ApplyConnection.

type DependencyDiff 

type DependencyDiff struct {
	Ecosystems map[string]bool         // ecosystems with changes
	Changes    []*diffv1.PackageChange // semantic dependency changes
	Error      error                   // error during diff (non-fatal)
}

DependencyDiff represents the semantic difference in dependencies.

type DiffPolicyReport 

type DiffPolicyReport struct {
	Repo            string                  `json:"repo"`
	BaseRef         string                  `json:"baseRef"`
	TargetRef       string                  `json:"targetRef"`
	Changes         []*diffv1.PackageChange `json:"changes"`
	Vulnerabilities []report.Vulnerability  `json:"vulnerabilities"`
}

DiffPolicyReport captures the full context of a diff operation for policy evaluation.

type DockerfileAnalysisOutput 

type DockerfileAnalysisOutput struct {
	HasMultiStage       bool     `json:"has_multi_stage"`
	FinalStageIsRoot    bool     `json:"final_stage_is_root"`
	FinalStageIsScratch bool     `json:"final_stage_is_scratch"`
	SensitiveEnvVars    []string `json:"sensitive_env_vars,omitempty"`
	HasAddURL           bool     `json:"has_add_url"`
}

DockerfileAnalysisOutput contains static analysis results.

type DockerfileScanResult 

type DockerfileScanResult struct {
	Path           string                   `json:"path"`
	StageCount     int                      `json:"stage_count"`
	Stages         []DockerfileStageOutput  `json:"stages"`
	Analysis       DockerfileAnalysisOutput `json:"analysis"`
	PolicyFindings []report.PolicyFinding   `json:"policy_findings,omitempty"`
}

DockerfileScanResult is the structured output of a Dockerfile scan.

type DockerfileStageOutput 

type DockerfileStageOutput struct {
	Index          int      `json:"index"`
	Name           string   `json:"name,omitempty"`
	BaseImage      string   `json:"base_image"`
	Platform       string   `json:"platform,omitempty"`
	IsScratch      bool     `json:"is_scratch"`
	IsBuilder      bool     `json:"is_builder"`
	User           string   `json:"user,omitempty"`
	IsRoot         bool     `json:"is_root"`
	ExposedPorts   []string `json:"exposed_ports,omitempty"`
	HasHealthcheck bool     `json:"has_healthcheck"`
}

DockerfileStageOutput represents a stage in the scan output.

type GraphFormat 

type GraphFormat string

GraphFormat represents supported graph output formats. 

const (
	GraphFormatText    GraphFormat = "text"
	GraphFormatJSON    GraphFormat = "json"
	GraphFormatDOT     GraphFormat = "dot"
	GraphFormatMermaid GraphFormat = "mermaid"
	GraphFormatD3      GraphFormat = "d3"
)

type ListItem 

type ListItem struct {
	Ecosystem string `json:"ecosystem"`
	Name      string `json:"name"`
	Version   string `json:"version"`
	IsDirect  bool   `json:"isDirect"`
	PURL      string `json:"purl,omitempty"`
	Sources   string `json:"sources,omitempty"`
}

ListItem represents a single dependency entry for output.

type ModuleDeprecation 

type ModuleDeprecation struct {
	Module  string `json:"module"`
	Suggest string `json:"suggest"`
	URL     string `json:"url,omitempty"`
}

ModuleDeprecation captures information about a deprecated module and its suggested replacement (future enrichment hook).

type SecretsDiffResult 

type SecretsDiffResult struct {
	Repository string            `json:"repository"`
	BaseRef    string            `json:"baseRef"`
	TargetRef  string            `json:"targetRef"`
	BaseHash   string            `json:"baseHash"`
	TargetHash string            `json:"targetHash"`
	Generated  string            `json:"generated"`
	NewSecrets int               `json:"newSecrets"`
	Findings   []secrets.Finding `json:"findings"`
}

SecretsDiffResult contains results from a diff-based secret scan.

type SecretsResult 

type SecretsResult struct {
	// Target is the file or directory that was scanned.
	Target string `json:"target"`
	// Generated is the ISO 8601 timestamp when the scan was performed.
	Generated string `json:"generated"`
	// FilesScanned is the number of files analyzed.
	FilesScanned int `json:"filesScanned"`
	// SecretsFound is the total number of secrets detected.
	SecretsFound int `json:"secretsFound"`
	// HighConfidenceCount is the number of findings with >= 90% confidence.
	HighConfidenceCount int `json:"highConfidenceCount"`
	// Findings contains detected secrets.
	Findings []secrets.Finding `json:"findings"`
	// Stats provides aggregate counts by secret type.
	Stats map[secrets.SecretType]int `json:"stats"`
}

SecretsResult is the structured output of a secrets scan.

type WorkspaceReviewResult 

type WorkspaceReviewResult int

WorkspaceReviewResult indicates what the user decided to do with workspace changes. 

const (
	// ReviewAccept syncs all changes to the original workspace
	ReviewAccept WorkspaceReviewResult = iota
	// ReviewReject discards all changes
	ReviewReject
	// ReviewSelective allows user to pick which changes to keep
	ReviewSelective
	// ReviewAbort cancels the review without taking action
	ReviewAbort
)

func ReviewWorkspaceChanges 

func ReviewWorkspaceChanges(
	ctx context.Context,
	isolator workspace.Isolator,
	stdin io.Reader,
	stdout, stderr io.Writer,
) (WorkspaceReviewResult, error)

ReviewWorkspaceChanges displays changes and prompts the user for action. Returns the user's decision and any error.

func ReviewWorkspaceChangesFromEvent 

func ReviewWorkspaceChangesFromEvent(
	ctx context.Context,
	event *sandboxv1.WorkspaceChangesEvent,
	stdin io.Reader,
	stdout, stderr io.Writer,
) (WorkspaceReviewResult, error)

ReviewWorkspaceChangesFromEvent handles the review workflow using data from a WorkspaceChangesEvent. This is used when receiving changes via streaming (proto-based) rather than direct isolator access.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.