xray

Documentation

Index

• Constants
• Variables
• func OnCommand(xc *app.ExecutionContext, gparams *commands.GenericParams, targetRef string, ...)
• func RegisterCommand()

Constants

const (
	Name  = "xray"
	Usage = "Shows what's inside of your container image and reverse engineers its Dockerfile"
	Alias = "x"
)

const (
	FlagChanges                = "changes"
	FlagChangesOutput          = "changes-output"
	FlagLayer                  = "layer"
	FlagAddImageManifest       = "add-image-manifest"
	FlagAddImageConfig         = "add-image-config"
	FlagLayerChangesMax        = "layer-changes-max"
	FlagAllChangesMax          = "all-changes-max"
	FlagAddChangesMax          = "add-changes-max"
	FlagModifyChangesMax       = "modify-changes-max"
	FlagDeleteChangesMax       = "delete-changes-max"
	FlagChangePath             = "change-path"
	FlagChangeData             = "change-data"
	FlagChangeDataHash         = "change-data-hash"
	FlagReuseSavedImage        = "reuse-saved-image"
	FlagTopChangesMax          = "top-changes-max"
	FlagHashData               = "hash-data"
	FlagDetectUTF8             = "detect-utf8"
	FlagDetectDuplicates       = "detect-duplicates"
	FlagShowDuplicates         = "show-duplicates"
	FlagShowSpecialPerms       = "show-special-perms"
	FlagChangeMatchLayersOnly  = "change-match-layers-only"
	FlagExportAllDataArtifacts = "export-all-data-artifacts"
	FlagDetectAllCertFiles     = "detect-all-certs"
	FlagDetectAllCertPKFiles   = "detect-all-cert-pks"
)

Xray command flag names

const (
	FlagChangesUsage                = "Show layer change details for the selected change type (values: none, all, delete, modify, add)"
	FlagChangesOutputUsage          = "Where to show the changes (values: all, report, console)"
	FlagLayerUsage                  = "Show details for the selected layer (using layer index or ID)"
	FlagAddImageManifestUsage       = "Add raw image manifest to the command execution report file"
	FlagAddImageConfigUsage         = "Add raw image config object to the command execution report file"
	FlagLayerChangesMaxUsage        = "Maximum number of changes to show for each layer"
	FlagAllChangesMaxUsage          = "Maximum number of changes to show for all layers"
	FlagAddChangesMaxUsage          = "Maximum number of 'add' changes to show for all layers"
	FlagModifyChangesMaxUsage       = "Maximum number of 'modify' changes to show for all layers"
	FlagDeleteChangesMaxUsage       = "Maximum number of 'delete' changes to show for all layers"
	FlagChangePathUsage             = "Include changes for the files that match the path pattern (Glob/Match in Go and **)"
	FlagChangeDataUsage             = "Include changes for the files that match the data pattern (regex)"
	FlagReuseSavedImageUsage        = "Reuse saved container image"
	FlagTopChangesMaxUsage          = "Maximum number of top changes to track"
	FlagChangeDataHashUsage         = "Include changes for the files that match the provided data hashes (sha1)"
	FlagHashDataUsage               = "Generate file data hashes"
	FlagDetectUTF8Usage             = "Detect utf8 files and optionally extract the discovered utf8 file content"
	FlagDetectDuplicatesUsage       = "Detect duplicate files based on their hashes"
	FlagShowDuplicatesUsage         = "Show discovered duplicate file paths"
	FlagShowSpecialPermsUsage       = "Show files with special permissions (setuid,setgid,sticky)"
	FlagChangeMatchLayersOnlyUsage  = "Show only layers with change matches"
	FlagExportAllDataArtifactsUsage = "" /* 142-byte string literal not displayed */
	FlagDetectAllCertFilesUsage     = "Detect all certifcate files"
	FlagDetectAllCertPKFilesUsage   = "Detect all certifcate private key files"
)

Xray command flag usage info

Variables

var CLI = &cli.Command{
	Name:    Name,
	Aliases: []string{Alias},
	Usage:   Usage,
	Flags: []cli.Flag{
		commands.Cflag(commands.FlagTarget),
		commands.Cflag(commands.FlagPull),
		commands.Cflag(commands.FlagDockerConfigPath),
		commands.Cflag(commands.FlagRegistryAccount),
		commands.Cflag(commands.FlagRegistrySecret),
		commands.Cflag(commands.FlagShowPullLogs),
		cflag(FlagChanges),
		cflag(FlagChangesOutput),
		cflag(FlagLayer),
		cflag(FlagAddImageManifest),
		cflag(FlagAddImageConfig),
		cflag(FlagLayerChangesMax),
		cflag(FlagAllChangesMax),
		cflag(FlagAddChangesMax),
		cflag(FlagModifyChangesMax),
		cflag(FlagDeleteChangesMax),
		cflag(FlagChangePath),
		cflag(FlagChangeData),
		cflag(FlagReuseSavedImage),
		cflag(FlagTopChangesMax),
		cflag(FlagChangeMatchLayersOnly),
		cflag(FlagHashData),
		cflag(FlagDetectUTF8),
		cflag(FlagDetectAllCertFiles),
		cflag(FlagDetectAllCertPKFiles),
		cflag(FlagDetectDuplicates),
		cflag(FlagShowDuplicates),
		cflag(FlagShowSpecialPerms),
		cflag(FlagChangeDataHash),
		cflag(FlagExportAllDataArtifacts),
		commands.Cflag(commands.FlagRemoveFileArtifacts),
	},
	Action: func(ctx *cli.Context) error {
		xc := app.NewExecutionContext(Name)

		targetRef := ctx.String(commands.FlagTarget)

		if targetRef == "" {
			if ctx.Args().Len() < 1 {
				xc.Out.Error("param.target", "missing image ID/name")
				cli.ShowCommandHelp(ctx, Name)
				return nil
			} else {
				targetRef = ctx.Args().First()
			}
		}

		gcvalues, err := commands.GlobalFlagValues(ctx)
		if err != nil {
			xc.Out.Error("param.global", err.Error())
			xc.Out.State("exited",
				ovars{
					"exit.code": -1,
				})
			xc.Exit(-1)
		}

		doDetectAllCertFiles := ctx.Bool(FlagDetectAllCertFiles)
		doDetectAllCertPKFiles := ctx.Bool(FlagDetectAllCertPKFiles)

		xdArtifactsPath := ctx.String(FlagExportAllDataArtifacts)

		doPull := ctx.Bool(commands.FlagPull)
		dockerConfigPath := ctx.String(commands.FlagDockerConfigPath)
		registryAccount := ctx.String(commands.FlagRegistryAccount)
		registrySecret := ctx.String(commands.FlagRegistrySecret)
		doShowPullLogs := ctx.Bool(commands.FlagShowPullLogs)

		changes, err := parseChangeTypes(ctx.StringSlice(FlagChanges))
		if err != nil {
			xc.Out.Error("param.error.change.types", err.Error())
			xc.Out.State("exited",
				ovars{
					"exit.code": -1,
				})
			xc.Exit(-1)
		}

		if xdArtifactsPath != "" {

			changes["delete"] = struct{}{}
			changes["modify"] = struct{}{}
			changes["add"] = struct{}{}
		}

		rawChangesOutputs := ctx.StringSlice(FlagChangesOutput)
		if xdArtifactsPath != "" && len(rawChangesOutputs) == 0 {
			rawChangesOutputs = append(rawChangesOutputs, "report")
		}

		changesOutputs, err := parseChangeOutputTypes(rawChangesOutputs)
		if err != nil {
			xc.Out.Error("param.error.change.output", err.Error())
			xc.Out.State("exited",
				ovars{
					"exit.code": -1,
				})
			xc.Exit(-1)
		}

		if xdArtifactsPath != "" {
			changesOutputs["report"] = struct{}{}
		}

		layers, err := commands.ParseTokenSet(ctx.StringSlice(FlagLayer))
		if err != nil {
			xc.Out.Error("param.error.layer", err.Error())
			xc.Out.State("exited",
				ovars{
					"exit.code": -1,
				})
			xc.Exit(-1)
		}

		layerChangesMax := ctx.Int(FlagLayerChangesMax)
		allChangesMax := ctx.Int(FlagAllChangesMax)
		addChangesMax := ctx.Int(FlagAddChangesMax)
		modifyChangesMax := ctx.Int(FlagModifyChangesMax)
		deleteChangesMax := ctx.Int(FlagDeleteChangesMax)
		topChangesMax := ctx.Int(FlagTopChangesMax)

		changePathMatchers, err := parseChangePathMatchers(ctx.StringSlice(FlagChangePath))
		if err != nil {
			xc.Out.Error("param.error.change.path", err.Error())
			xc.Out.State("exited",
				ovars{
					"exit.code": -1,
				})
			xc.Exit(-1)
		}

		changeDataMatchers, err := parseChangeDataMatchers(ctx.StringSlice(FlagChangeData))
		if err != nil {
			xc.Out.Error("param.error.change.data", err.Error())
			xc.Out.State("exited",
				ovars{
					"exit.code": -1,
				})
			xc.Exit(-1)
		}

		doAddImageManifest := ctx.Bool(FlagAddImageManifest)
		if xdArtifactsPath != "" {
			doAddImageManifest = true
		}

		doAddImageConfig := ctx.Bool(FlagAddImageConfig)
		if xdArtifactsPath != "" {
			doAddImageConfig = true
		}

		doRmFileArtifacts := ctx.Bool(commands.FlagRemoveFileArtifacts)
		doReuseSavedImage := ctx.Bool(FlagReuseSavedImage)

		doHashData := ctx.Bool(FlagHashData)
		if xdArtifactsPath != "" {
			doHashData = true
		}

		doDetectDuplicates := ctx.Bool(FlagDetectDuplicates)
		if doDetectDuplicates {
			doHashData = true
		}

		rawDetectUTF8 := ctx.String(FlagDetectUTF8)
		if xdArtifactsPath != "" && rawDetectUTF8 == "" {
			rawDetectUTF8 = "dump:utf8.tgz::10000000"
		}

		utf8Detector, err := parseDetectUTF8(rawDetectUTF8)
		if err != nil {
			xc.Out.Error("param.error.detect.utf8", err.Error())
			xc.Out.State("exited",
				ovars{
					"exit.code": -1,
				})
			xc.Exit(-1)
		}

		if utf8Detector != nil && !doHashData {
			xc.Out.Error("param.error.detect.utf8", "--detect-utf8 requires option --hash-data")
			xc.Out.State("exited",
				ovars{
					"exit.code": -1,
				})
			xc.Exit(-1)
		}

		doShowDuplicates := ctx.Bool(FlagShowDuplicates)
		doShowSpecialPerms := ctx.Bool(FlagShowSpecialPerms)

		changeDataHashMatchers, err := parseChangeDataHashMatchers(ctx.StringSlice(FlagChangeDataHash))
		if err != nil {
			xc.Out.Error("param.error.change.data.hash", err.Error())
			xc.Out.State("exited",
				ovars{
					"exit.code": -1,
				})
			xc.Exit(-1)
		}

		changeMatchLayersOnly := ctx.Bool(FlagChangeMatchLayersOnly)

		OnCommand(
			xc,
			gcvalues,
			targetRef,
			doPull,
			dockerConfigPath,
			registryAccount,
			registrySecret,
			doShowPullLogs,
			changes,
			changesOutputs,
			layers,
			layerChangesMax,
			allChangesMax,
			addChangesMax,
			modifyChangesMax,
			deleteChangesMax,
			topChangesMax,
			changePathMatchers,
			changeDataMatchers,
			changeDataHashMatchers,
			doHashData,
			doDetectDuplicates,
			doShowDuplicates,
			doShowSpecialPerms,
			changeMatchLayersOnly,
			doAddImageManifest,
			doAddImageConfig,
			doReuseSavedImage,
			doRmFileArtifacts,
			utf8Detector,
			doDetectAllCertFiles,
			doDetectAllCertPKFiles,
			xdArtifactsPath,
		)

		return nil
	},
}

var CommandFlagSuggestions = &commands.FlagSuggestions{
	Names: []prompt.Suggest{
		{Text: commands.FullFlagName(commands.FlagTarget), Description: commands.FlagTargetUsage},
		{Text: commands.FullFlagName(commands.FlagPull), Description: commands.FlagPullUsage},
		{Text: commands.FullFlagName(commands.FlagShowPullLogs), Description: commands.FlagShowPullLogsUsage},
		{Text: commands.FullFlagName(commands.FlagRegistryAccount), Description: commands.FlagRegistryAccountUsage},
		{Text: commands.FullFlagName(commands.FlagRegistrySecret), Description: commands.FlagRegistrySecretUsage},
		{Text: commands.FullFlagName(commands.FlagDockerConfigPath), Description: commands.FlagDockerConfigPathUsage},
		{Text: commands.FullFlagName(FlagChanges), Description: FlagChangesUsage},
		{Text: commands.FullFlagName(FlagChangesOutput), Description: FlagChangesOutputUsage},
		{Text: commands.FullFlagName(FlagLayer), Description: FlagLayerUsage},
		{Text: commands.FullFlagName(FlagAddImageManifest), Description: FlagAddImageManifestUsage},
		{Text: commands.FullFlagName(FlagAddImageConfig), Description: FlagAddImageConfigUsage},
		{Text: commands.FullFlagName(FlagLayerChangesMax), Description: FlagLayerChangesMaxUsage},
		{Text: commands.FullFlagName(FlagAllChangesMax), Description: FlagAllChangesMaxUsage},
		{Text: commands.FullFlagName(FlagAddChangesMax), Description: FlagAddChangesMaxUsage},
		{Text: commands.FullFlagName(FlagModifyChangesMax), Description: FlagModifyChangesMaxUsage},
		{Text: commands.FullFlagName(FlagDeleteChangesMax), Description: FlagDeleteChangesMaxUsage},
		{Text: commands.FullFlagName(FlagChangePath), Description: FlagChangePathUsage},
		{Text: commands.FullFlagName(FlagChangeData), Description: FlagChangeDataUsage},
		{Text: commands.FullFlagName(FlagReuseSavedImage), Description: FlagReuseSavedImageUsage},
		{Text: commands.FullFlagName(FlagHashData), Description: FlagHashDataUsage},
		{Text: commands.FullFlagName(FlagDetectUTF8), Description: FlagDetectUTF8Usage},
		{Text: commands.FullFlagName(FlagDetectDuplicates), Description: FlagDetectDuplicatesUsage},
		{Text: commands.FullFlagName(FlagShowDuplicates), Description: FlagShowDuplicatesUsage},
		{Text: commands.FullFlagName(FlagShowSpecialPerms), Description: FlagShowSpecialPermsUsage},
		{Text: commands.FullFlagName(FlagChangeDataHash), Description: FlagChangeDataHashUsage},
		{Text: commands.FullFlagName(FlagTopChangesMax), Description: FlagTopChangesMaxUsage},
		{Text: commands.FullFlagName(FlagDetectAllCertFiles), Description: FlagDetectAllCertFilesUsage},
		{Text: commands.FullFlagName(FlagDetectAllCertPKFiles), Description: FlagDetectAllCertPKFilesUsage},
		{Text: commands.FullFlagName(FlagExportAllDataArtifacts), Description: FlagExportAllDataArtifactsUsage},
		{Text: commands.FullFlagName(commands.FlagRemoveFileArtifacts), Description: commands.FlagRemoveFileArtifactsUsage},
	},
	Values: map[string]commands.CompleteValue{
		commands.FullFlagName(commands.FlagPull):                commands.CompleteBool,
		commands.FullFlagName(commands.FlagShowPullLogs):        commands.CompleteBool,
		commands.FullFlagName(commands.FlagDockerConfigPath):    commands.CompleteFile,
		commands.FullFlagName(commands.FlagTarget):              commands.CompleteTarget,
		commands.FullFlagName(FlagChanges):                      completeLayerChanges,
		commands.FullFlagName(FlagChangesOutput):                completeOutputs,
		commands.FullFlagName(FlagAddImageManifest):             commands.CompleteBool,
		commands.FullFlagName(FlagAddImageConfig):               commands.CompleteBool,
		commands.FullFlagName(FlagHashData):                     commands.CompleteBool,
		commands.FullFlagName(FlagDetectDuplicates):             commands.CompleteBool,
		commands.FullFlagName(FlagShowDuplicates):               commands.CompleteTBool,
		commands.FullFlagName(FlagShowSpecialPerms):             commands.CompleteTBool,
		commands.FullFlagName(FlagReuseSavedImage):              commands.CompleteTBool,
		commands.FullFlagName(FlagDetectAllCertFiles):           commands.CompleteBool,
		commands.FullFlagName(FlagDetectAllCertPKFiles):         commands.CompleteBool,
		commands.FullFlagName(commands.FlagRemoveFileArtifacts): commands.CompleteBool,
	},
}

var CommandSuggestion = prompt.Suggest{
	Text:        Name,
	Description: Usage,
}

var Flags = map[string]cli.Flag{
	FlagChanges: &cli.StringSliceFlag{
		Name:    FlagChanges,
		Value:   cli.NewStringSlice(""),
		Usage:   FlagChangesUsage,
		EnvVars: []string{"DSLIM_CHANGES"},
	},
	FlagChangesOutput: &cli.StringSliceFlag{
		Name:    FlagChangesOutput,
		Value:   cli.NewStringSlice("all"),
		Usage:   FlagChangesOutputUsage,
		EnvVars: []string{"DSLIM_CHANGES_OUTPUT"},
	},
	FlagLayer: &cli.StringSliceFlag{
		Name:    FlagLayer,
		Value:   cli.NewStringSlice(),
		Usage:   FlagLayerUsage,
		EnvVars: []string{"DSLIM_LAYER"},
	},
	FlagAddImageManifest: &cli.BoolFlag{
		Name:    FlagAddImageManifest,
		Usage:   FlagAddImageManifestUsage,
		EnvVars: []string{"DSLIM_XRAY_IMAGE_MANIFEST"},
	},
	FlagAddImageConfig: &cli.BoolFlag{
		Name:    FlagAddImageConfig,
		Usage:   FlagAddImageConfigUsage,
		EnvVars: []string{"DSLIM_XRAY_IMAGE_CONFIG"},
	},
	FlagLayerChangesMax: &cli.IntFlag{
		Name:    FlagLayerChangesMax,
		Value:   -1,
		Usage:   FlagLayerChangesMaxUsage,
		EnvVars: []string{"DSLIM_XRAY_LAYER_CHANGES_MAX"},
	},
	FlagAllChangesMax: &cli.IntFlag{
		Name:    FlagAllChangesMax,
		Value:   -1,
		Usage:   FlagAllChangesMaxUsage,
		EnvVars: []string{"DSLIM_XRAY_ALL_CHANGES_MAX"},
	},
	FlagAddChangesMax: &cli.IntFlag{
		Name:    FlagAddChangesMax,
		Value:   -1,
		Usage:   FlagAddChangesMaxUsage,
		EnvVars: []string{"DSLIM_XRAY_ADD_CHANGES_MAX"},
	},
	FlagModifyChangesMax: &cli.IntFlag{
		Name:    FlagModifyChangesMax,
		Value:   -1,
		Usage:   FlagModifyChangesMaxUsage,
		EnvVars: []string{"DSLIM_XRAY_MODIFY_CHANGES_MAX"},
	},
	FlagDeleteChangesMax: &cli.IntFlag{
		Name:    FlagDeleteChangesMax,
		Value:   -1,
		Usage:   FlagDeleteChangesMaxUsage,
		EnvVars: []string{"DSLIM_XRAY_DELETE_CHANGES_MAX"},
	},
	FlagChangePath: &cli.StringSliceFlag{
		Name:    FlagChangePath,
		Value:   cli.NewStringSlice(),
		Usage:   FlagChangePathUsage,
		EnvVars: []string{"DSLIM_XRAY_CHANGE_PATH"},
	},
	FlagChangeData: &cli.StringSliceFlag{
		Name:    FlagChangeData,
		Value:   cli.NewStringSlice(),
		Usage:   FlagChangeDataUsage,
		EnvVars: []string{"DSLIM_XRAY_CHANGE_DATA"},
	},
	FlagReuseSavedImage: &cli.BoolFlag{
		Name:    FlagReuseSavedImage,
		Value:   true,
		Usage:   FlagReuseSavedImageUsage,
		EnvVars: []string{"DSLIM_XRAY_REUSE_SAVED"},
	},
	FlagTopChangesMax: &cli.IntFlag{
		Name:    FlagTopChangesMax,
		Value:   20,
		Usage:   FlagTopChangesMaxUsage,
		EnvVars: []string{"DSLIM_XRAY_TOP_CHANGES_MAX"},
	},
	FlagHashData: &cli.BoolFlag{
		Name:    FlagHashData,
		Usage:   FlagHashDataUsage,
		EnvVars: []string{"DSLIM_XRAY_HASH_DATA"},
	},
	FlagDetectUTF8: &cli.StringFlag{
		Name:    FlagDetectUTF8,
		Usage:   FlagDetectUTF8Usage,
		EnvVars: []string{"DSLIM_XRAY_DETECT_UTF8"},
	},
	FlagDetectDuplicates: &cli.BoolFlag{
		Name:    FlagDetectDuplicates,
		Value:   true,
		Usage:   FlagDetectDuplicatesUsage,
		EnvVars: []string{"DSLIM_XRAY_DETECT_DUP"},
	},
	FlagShowDuplicates: &cli.BoolFlag{
		Name:    FlagShowDuplicates,
		Usage:   FlagShowDuplicatesUsage,
		EnvVars: []string{"DSLIM_XRAY_SHOW_DUP"},
	},
	FlagShowSpecialPerms: &cli.BoolFlag{
		Name:    FlagShowSpecialPerms,
		Value:   true,
		Usage:   FlagShowSpecialPermsUsage,
		EnvVars: []string{"DSLIM_XRAY_SHOW_SPECIAL"},
	},
	FlagChangeDataHash: &cli.StringSliceFlag{
		Name:    FlagChangeDataHash,
		Value:   cli.NewStringSlice(),
		Usage:   FlagChangeDataHashUsage,
		EnvVars: []string{"DSLIM_XRAY_CHANGE_DATA_HASH"},
	},
	FlagChangeMatchLayersOnly: &cli.BoolFlag{
		Name:    FlagChangeMatchLayersOnly,
		Usage:   FlagChangeMatchLayersOnlyUsage,
		EnvVars: []string{"DSLIM_XRAY_CHANGE_MATCH_LAYERS_ONLY"},
	},
	FlagExportAllDataArtifacts: &cli.StringFlag{
		Name:    FlagExportAllDataArtifacts,
		Usage:   FlagExportAllDataArtifactsUsage,
		EnvVars: []string{"DSLIM_XRAY_EXPORT_ALL_DARTIFACTS"},
	},
	FlagDetectAllCertFiles: &cli.BoolFlag{
		Name:    FlagDetectAllCertFiles,
		Usage:   FlagDetectAllCertFilesUsage,
		EnvVars: []string{"DSLIM_XRAY_DETECT_ALL_CERTS"},
	},
	FlagDetectAllCertPKFiles: &cli.BoolFlag{
		Name:    FlagDetectAllCertPKFiles,
		Usage:   FlagDetectAllCertPKFilesUsage,
		EnvVars: []string{"DSLIM_XRAY_DETECT_ALL_CERT_PKS"},
	},
}

Functions

func OnCommand

func OnCommand(
	xc *app.ExecutionContext,
	gparams *commands.GenericParams,
	targetRef string,
	doPull bool,
	dockerConfigPath string,
	registryAccount string,
	registrySecret string,
	doShowPullLogs bool,
	changes map[string]struct{},
	changesOutputs map[string]struct{},
	layers map[string]struct{},
	layerChangesMax int,
	allChangesMax int,
	addChangesMax int,
	modifyChangesMax int,
	deleteChangesMax int,
	topChangesMax int,
	changePathMatchers []*dockerimage.ChangePathMatcher,
	changeDataMatcherList []*dockerimage.ChangeDataMatcher,
	changeDataHashMatcherList []*dockerimage.ChangeDataHashMatcher,
	doHashData bool,
	doDetectDuplicates bool,
	doShowDuplicates bool,
	doShowSpecialPerms bool,
	changeMatchLayersOnly bool,
	doAddImageManifest bool,
	doAddImageConfig bool,
	doReuseSavedImage bool,
	doRmFileArtifacts bool,
	utf8Detector *dockerimage.UTF8Detector,
	doDetectAllCertFiles bool,
	doDetectAllCertPKFiles bool,
	xdArtifactsPath string,
)

OnCommand implements the 'xray' docker-slim command

func RegisterCommand

func RegisterCommand()