schemas

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Jul 14, 2025 License: GPL-3.0 Imports: 7 Imported by: 0

Documentation

Overview

Package schemas provides types that will be used in the API and marshalled or unmarshalled from user data

Index

Constants

View Source
const (
	// EnvVarPrefix is the prefix used for environment variables
	EnvVarPrefix = "OCULAR_"
	// CustomEnvVarPrefix is the prefix used for environment variables
	// specified by the user that are already prefixed with EnvVarPrefix.
	CustomEnvVarPrefix = "CUSTOM_"

	// ParamEnvVarPrefix is the prefix used for environment variables
	// that contain parameters for uploader or crawler invocations.
	ParamEnvVarPrefix = EnvVarPrefix + "PARAM_"
)
View Source
const (
	EnvVarTargetDownloader = EnvVarPrefix + "TARGET_DOWNLOADER"
	EnvVarTargetIdentifier = EnvVarPrefix + "TARGET_IDENTIFIER"
	EnvVarTargetVersion    = EnvVarPrefix + "TARGET_VERSION"
	EnvVarTargetDir        = EnvVarPrefix + "TARGET_DIR"
	EnvVarResultsDir       = EnvVarPrefix + "RESULTS_DIR"
	EnvVarProfileName      = EnvVarPrefix + "PROFILE_NAME"
	EnvVarPipelineID       = EnvVarPrefix + "PIPELINE_ID"

	EnvVarUploaderHost  = EnvVarPrefix + "UPLOADER_HOST"
	EnvVarExtractorPort = EnvVarPrefix + "EXTRACTOR_PORT"
	EnvVarUploaderName  = EnvVarPrefix + "UPLOADER_NAME"
)
View Source
const (
	EnvVarOcularTokenPath = EnvVarPrefix + "SERVICE_ACCOUNT_TOKEN_PATH" // #nosec G101

	EnvVarCrawlerName = EnvVarPrefix + "CRAWLER_NAME"
	EnvVarContextName = EnvVarPrefix + "CONTEXT_NAME"
	EnvVarAPIBaseURL  = EnvVarPrefix + "API_BASE_URL"
)
View Source
const (
	// RunStatusPendingString is the string representation of RunStatusPending.
	RunStatusPendingString = "Pending"
	// RunStatusRunningString is the string representation of RunStatusRunning.
	RunStatusRunningString = "Running"
	// RunStatusSuccessString is the string representation of RunStatusSuccess.
	RunStatusSuccessString = "Success"
	// RunStatusFailureString is the string representation of RunStatusFailure.
	RunStatusFailureString = "Failure"
	// RunStatusCancelledString is the string representation of RunStatusCancelled.
	RunStatusCancelledString = "Cancelled"
	// RunStatusErrorString is the string representation of RunStatusError.
	RunStatusErrorString = "Error"
	// RunStatusNotRanString is the string representation of RunStatusNotRan.
	RunStatusNotRanString = "NotRan"
	// RunStatusUnknownString is the string representation of RunStatusUnknown.
	RunStatusUnknownString = "Unknown"
)
View Source
const (
	// ClusterContextHeader is the header used to pass the cluster context name in requests.
	ClusterContextHeader = "X-ClusterContext-Name"
)

Variables

This section is empty.

Functions

func EnvToParameterName

func EnvToParameterName(name string) string

EnvToParameterName converts an environment variable name to the parameter name

func FormatParamName

func FormatParamName(name string) string

FormatParamName formats a parameter name to be used as an environment variable. It replaces all non-alphanumeric characters with underscores

func IsValidSecretMount

func IsValidSecretMount(mountType SecretMountType) bool

IsValidSecretMount checks if the given mount type is valid.

func ParameterNameToEnv

func ParameterNameToEnv(name string) string

ParameterNameToEnv converts a parameter name to the environment variable name it would be passed as in the container

Types

type APIResponse

type APIResponse[T any] struct {
	Success  bool     `json:"success"            yaml:"success"`
	Error    ErrorMsg `json:"error,omitempty"    yaml:"error,omitempty"`
	Response T        `json:"response,omitempty" yaml:"response,omitempty"`
}

type APIVersionResponse

type APIVersionResponse struct {
	Version   string `json:"version"             yaml:"version"`
	BuildTime string `json:"buildTime,omitempty" yaml:"buildTime,omitempty"`
	Commit    string `json:"commit,omitempty"    yaml:"commit,omitempty"`
}

type Crawler

Crawler represents a crawler container configuration. It will serve as the base container configuration for crawler containers that are executed during a search. For more information on the configuration of the crawler container, see the schemas.UserContainerWithParameters type.

type Downloader

type Downloader = UserContainer

Downloader represents the init container that will download the static asset.

type EnvVar

type EnvVar struct {
	Name  string `json:"name,omitempty"  yaml:"name,omitempty"`
	Value string `json:"value,omitempty" yaml:"value,omitempty"`
}

EnvVar represents an environment variable.

type ErrorMsg

type ErrorMsg = string
const (

	// ErrUnknown is a generic error message used when the error type is not known.
	ErrUnknown ErrorMsg = "unknown error"
	// ErrInvalidPayload is returned when the payload is invalid and cannot be parsed.
	ErrInvalidPayload    ErrorMsg = "invalid payload, unable to parse"
	ErrInvalidParameter  ErrorMsg = "invalid parameter, unable to parse"
	ErrInvalidIdentifier ErrorMsg = "invalid identifier, unable to parse"
	ErrResourceNotFound  ErrorMsg = "resource not found"

	// ErrDefaultContextNotEnabled is returned when no context is set and
	// the default context is not enabled in the system configuration.
	ErrDefaultContextNotEnabled ErrorMsg = "no context set and default context is not enabled"

	// ErrInvalidAuthenticationHeader is returned when the authentication header is invalid.
	ErrInvalidAuthenticationHeader ErrorMsg = "invalid authentication header"
	// ErrInvalidTokenHeader is returned when the bearer token header is invalid.
	ErrInvalidTokenHeader ErrorMsg = "invalid bearer token"
	// ErrUnauthenticated is returned when the user is not authenticated.
	ErrUnauthenticated ErrorMsg = "unable to authenticate"
	// ErrUnauthorized is returned when the user is not authorized to access the resource.
	ErrUnauthorized ErrorMsg = "unauthorized to access resource"
)

type ExecutionID

type ExecutionID = uuid.UUID

func ParseExecutionID

func ParseExecutionID(id string) (ExecutionID, error)

type ParameterDefinition

type ParameterDefinition struct {
	// Description is the description of the parameter.
	Description string `json:"description,omitempty" yaml:"description,omitempty" description:"Description of the parameter."`
	// Required is true if the parameter is required.
	Required bool `` /* 184-byte string literal not displayed */
	// Default is the default value for the parameter.
	// It is only valid if Required is false.
	Default string `json:"default,omitempty"     yaml:"default,omitempty"`
}

ParameterDefinition is a definition of a parameter that can be passed to a container. It defines the name of the parameter, a description of the parameter, whether the parameter is required, and a default value for the parameter (when not required).

type Pipeline

type Pipeline struct {
	// ID is the unique identifier for the pipeline execution.
	ID ExecutionID `json:"ID" yaml:"ID" profile:"id" description:"The unique identifier for the pipeline execution."`

	Profile string `json:"profile" yaml:"profile" description:"The profile to use for the pipeline execution."`

	// Target represents the target that the pipeline will run against.
	Target       Target    `json:"target"       yaml:"target"       description:"The target that the pipeline will run against."`
	ScanStatus   RunStatus `json:"scanStatus"   yaml:"scanStatus"   description:"The status of the pipeline execution."`
	UploadStatus RunStatus `json:"uploadStatus" yaml:"uploadStatus" description:"The status of the upload job execution."`
}

type PipelineRequest

type PipelineRequest struct {
	ProfileName string `json:"profileName" yaml:"profileName"`
	Target      Target `json:"target"      yaml:"target"`
}

PipelineRequest represents a request to run a pipeline

type Profile

type Profile struct {
	// Scanners is a list of [Scanner] that will all be run
	// in parallel, with their current working directory set to
	// the directory where the target has been downloaded to.
	Scanners []Scanner `json:"scanners"  yaml:"scanners"  description:"A list of scanners that will be run over the target."`
	// Artifacts is a list of paths to the artifacts that will be produced
	// by the scanners. These paths are relative to the results directory
	Artifacts []string `` /* 170-byte string literal not displayed */
	// Uploaders is a list of [UploaderRunRequest] that will be used to upload
	// the results of the scanners. An uploader will be passed each of the artifacts
	// as command line arguments, prefixed by the argument '--' . Each [UploaderRunRequest] must specify the
	// name of the uploader and any parameters that are required.
	Uploaders []UploaderRunRequest `` /* 331-byte string literal not displayed */
}

Profile represents a series of scanners to run over a static asset and where to upload the results.

type ResourceName

type ResourceName = string

type RunStatus

type RunStatus uint8

RunStatus represents the status of a job run.

const (
	// RunStatusNotRan is used when the run has not been executed yet.
	RunStatusNotRan RunStatus = iota
	// RunStatusPending is used when the run is pending.
	RunStatusPending
	// RunStatusRunning is used when the run is running.
	RunStatusRunning
	// RunStatusSuccess is used when the run is successful.
	RunStatusSuccess
	// RunStatusFailure is used when the run has failed.
	RunStatusFailure
	// RunStatusCancelled is used when the run has been cancelled.
	RunStatusCancelled
	// RunStatusError is used when the run has encountered an error.
	// NOTE: this is different from failure, as it indicates that the run
	// was not able to complete due to an error, rather than a failure during the
	// execution of the run.
	RunStatusError
	// RunStatusUnknown is used when the status of the run is not known.
	RunStatusUnknown
)

func (RunStatus) MarshalJSON

func (r RunStatus) MarshalJSON() ([]byte, error)

func (RunStatus) MarshalYAML

func (r RunStatus) MarshalYAML() (interface{}, error)

func (RunStatus) PrepareJSONSchema

func (r RunStatus) PrepareJSONSchema(schema *jsonschema.Schema) error

func (RunStatus) String

func (r RunStatus) String() string

RunStatusString returns a string representation of the run status.

func (*RunStatus) UnmarshalJSON

func (r *RunStatus) UnmarshalJSON(data []byte) error

func (*RunStatus) UnmarshalYAML

func (r *RunStatus) UnmarshalYAML(value *yaml.Node) error

type Scanner

type Scanner = UserContainer

Scanner represents a scanner that will be run over the target. The scanner will be run in a container with the current working directory set to the directory where the target has been downloaded to.

type Schedule

type Schedule = string

type ScheduleRequest

type ScheduleRequest struct {
	CrawlerName string            `json:"crawlerName" yaml:"crawlerName"`
	Schedule    string            `json:"schedule"    yaml:"schedule"`
	Parameters  map[string]string `json:"parameters"  yaml:"parameters"`
}

ScheduleRequest represents a request to schedule a search

type ScheduledSearch

type ScheduledSearch struct {
	ID          ExecutionID       `yaml:"id,omitempty"       json:"id,omitempty"         description:"The unique identifier for the scheduled search."`
	Schedule    Schedule          `` /* 141-byte string literal not displayed */
	CrawlerName string            `` /* 147-byte string literal not displayed */
	Parameters  map[string]string `yaml:"params,omitempty"   json:"parameters,omitempty" description:"The parameters to pass to the pipeline execution."`
}
type Search struct {
	CrawlerName string `json:"crawlerName"          yaml:"crawlerName"`
	// RunID is the ID of the run.
	ID ExecutionID `json:"runID"                yaml:"runID"`
	// Parameters is a map of parameter name to value.
	Parameters map[string]string `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	// Status is the status of the run.
	Status RunStatus `json:"status"               yaml:"status"`
}

type SearchRequest

type SearchRequest struct {
	CrawlerName string            `json:"crawlerName" yaml:"crawlerName"`
	Parameters  map[string]string `json:"parameters"  yaml:"parameters"`
}

SearchRequest represents a request to run a search

type Secret

type Secret []byte

Secret is a type that represents a secret value. The byte slices contains the raw text of the secret.

func (Secret) String

func (s Secret) String() string

type SecretMountType

type SecretMountType = string

SecretMountType represents the type of secret mount. it can be either an environment variable (SecretMountTypeEnvVar) or a file (SecretMountTypeFile).

const (
	// SecretMountTypeEnvVar is used to mount a secret as an environment variable.
	SecretMountTypeEnvVar SecretMountType = "envVar"
	// SecretMountTypeFile is used to mount a secret as a file.
	SecretMountTypeFile SecretMountType = "file"
)

type SecretRef

type SecretRef struct {
	Name        string          `json:"name"                  yaml:"name"                  description:"Name of the secret to reference."`
	MountType   SecretMountType `` /* 265-byte string literal not displayed */
	MountTarget string          `` /* 246-byte string literal not displayed */
	Required    bool            `` /* 175-byte string literal not displayed */
}

SecretRef represents a reference to a secret. It should define the secret name and how to mount it. If a secret is marked required, the application will fail to start or define containers that reference it if the secret is not found.

type Target

type Target struct {
	Downloader string `json:"downloader" yaml:"downloader"`
	Identifier string `json:"identifier" yaml:"identifier"`
	Version    string `json:"version"    yaml:"version"`
}

Target represents a target for a pipeline It contains the downloader, identifier and version of the target

type Uploader

type Uploader = UserContainerWithParameters

type UploaderRunRequest

type UploaderRunRequest struct {
	Name       string            `json:"name"                 yaml:"name"`
	Parameters map[string]string `json:"parameters,omitempty" yaml:"parameters,omitempty"`
}

UploaderRunRequest represents an uploader that will be used to upload

type UserContainer

type UserContainer struct {
	Image           string   `json:"image"                     yaml:"image"                     mapstructure:"image"`
	ImagePullPolicy string   `json:"imagePullPolicy,omitempty" yaml:"imagePullPolicy,omitempty" mapstructure:"imagePullPolicy"`
	Command         []string `json:"command,omitempty"         yaml:"command,omitempty,flow"    mapstructure:"command"`
	Args            []string `json:"args,omitempty"            yaml:"args,omitempty,flow"       mapstructure:"args"`

	Secrets []SecretRef `json:"secrets,omitempty" yaml:"secrets,omitempty"`
	Env     []EnvVar    `json:"env,omitempty"     yaml:"env,omitempty"`
}

UserContainer represents a user defined container that will be run by the application. It is a subset and simplified version of k8s.io/api/core/v1.Container.

type UserContainerWithParameters

type UserContainerWithParameters struct {
	UserContainer `                               yaml:",inline"`
	Parameters    map[string]ParameterDefinition `` /* 191-byte string literal not displayed */
}

UserContainerWithParameters is a wrapper around the UserContainer type that additionally defines a set of parameters that can be passed to the container. There parameters will be passed to the container as environment variables. During the API call that invokes the container, the user should pass the values for the parameters as a map of strings. Parameters that are required should be validated for existence. See ParameterDefinition for more information on defining parameters.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL