scan

package
v3.0.0 Latest Latest
Warning

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

 Go to latest Published: Sep 29, 2024 License: MIT Imports: 25 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrMissingProfiles is the error returned when the `scan` cannot be started because there are no profiles.
	ErrMissingProfiles = errors.New("missing profiles")
	// ErrMissingEntryPoints is the error returned when the `scan` cannot be started because there are no entry point finders.
	ErrMissingEntryPoints = errors.New("missing entry point finders")
	// ErrMissingRequestBuilder is the error returned when the `scan` cannot be started because there is no request builder configured.
	ErrMissingRequestBuilder = errors.New("missing requester builder")
	// ErrMissingFileSystemAbstraction is the error returned when the `scan` cannot be started because there is no file system abstraction configured.
	ErrMissingFileSystemAbstraction = errors.New("missing file system abstraction")
	// ErrMissingContext is the error returned when the `scan` cannot be started because there is no [context.Context].
	ErrMissingContext = errors.New("missing context")
)

Functions

This section is empty.

Types

type BlindHostPoller 

type BlindHostPoller interface {
	Search(substr string) *blindhost.Interaction
	BruteSearch(substr string) *blindhost.Interaction
}

BlindHostPoller defines the behavior expected from an agent that can continuously poll a `blindhost` looking for blindhost.Interaction instances.

type CfgOption 

type CfgOption func(*Config)

CfgOption is a function that modifies a Config instance. See WithRPS and WithConcurrency as examples.

func CfgOptionsFromJSON 

func CfgOptionsFromJSON(r io.Reader) ([]CfgOption, error)

CfgOptionsFromJSON parses a JSON document from a io.Reader, and turn its contents into a slice of CfgOption.

The expected payload is slightly different from Config struct.

For instance, it uses pointers to make it easier to determine whether a value was set or not.

Also, note that the parameter names is slightly different as well. The latter uses long, camel-cased names.

func WithBlindHost 

func WithBlindHost(blindHost string) CfgOption

WithBlindHost sets the blind host.

func WithBlindHostKey 

func WithBlindHostKey(blindHostKey string) CfgOption

WithBlindHostKey sets the blind host key.

func WithConcurrency 

func WithConcurrency(concurrency int) CfgOption

WithConcurrency sets the concurrency level.

func WithCustomTokens 

func WithCustomTokens(customTokens map[string]string) CfgOption

WithCustomTokens sets the custom tokens.

func WithPayloadStrategy 

func WithPayloadStrategy(ps string) CfgOption

WithPayloadStrategy sets the payload strategy.

func WithRPS 

func WithRPS(rps int) CfgOption

WithRPS sets the rate of requests per second.

type CloseFunc 

type CloseFunc func()

CloseFunc is a function that can be used to close something that's open. For instance, a channel, a socket or a file descriptor.

Internal details will vary depending on the function that returns it.

type Config 

type Config struct {
	RPS             int `default:"100"`
	Concurrency     int `default:"100"`
	Version         string
	SaveOnStop      bool
	InMemory        bool
	BlindHost       string
	BlindHostKey    string
	EmailAddress    bool
	CustomTokens    map[string]string
	PayloadStrategy PayloadStrategy

	Silent           bool
	StreamErrors     bool
	StreamMatches    bool
	ShowResponses    bool
	ShowErrors       bool
	ShowAll          bool
	ShowAllRequests  bool
	ShowAllResponses bool

	OutPath   string
	OutFormat string
}

Config defines the configuration used by the scanner to perform a scan. It includes options to control the scanner's behavior, such as the rate of requests per second, the concurrency level, and the output format.

func (Config) BlindHostConfigured 

func (c Config) BlindHostConfigured() bool

BlindHostConfigured returns whether the blind host and its key are configured.

func (Config) Clone 

func (c Config) Clone() Config

Clone returns a deep copy of the Config instance.

type CustomTokens 

type CustomTokens = map[string]string

CustomTokens is a type that represents a collection of pairs (key, value) that can be used to replace certain tokens (i.e. placeholders) in a request.Request.

type Customizable 

type Customizable interface {
	Customize(ep entrypoint.Entrypoint)
}

Customizable defines the behavior of any object that can be customized with an `entrypoint`.

type Error 

type Error struct {
	URL       string
	Requests  []*request.Request
	Responses []*response.Response
	Err       string
}

Error represents an error that occurred during a scan, containing the URL, the requests and responses that were made, and the error message.

There can be multiple Error per scan.

type FileSystem 

type FileSystem interface {
	FileSystemStats
	FileSystemErrors
	FileSystemMatches
	FileSystemSummaries
	FileSystemTemplates
	Cleanup(ctx context.Context) error
}

FileSystem defines the behavior expected from a scan file system, used to store and retrieve Match, Error, and TaskSummary instances.

type FileSystemErrors 

type FileSystemErrors interface {
	StoreError(ctx context.Context, err Error) error
	LoadErrors(ctx context.Context) ([]Error, error)
	ErrorsIterator(ctx context.Context) (chan Error, CloseFunc, error)
}

FileSystemErrors defines the behavior expected from a scan file system to store and retrieve Error instances.

type FileSystemMatches 

type FileSystemMatches interface {
	StoreMatch(ctx context.Context, match Match) error
	LoadMatches(ctx context.Context) ([]Match, error)
	MatchesIterator(ctx context.Context) (chan Match, CloseFunc, error)
}

FileSystemMatches defines the behavior expected from a scan file system to store and retrieve Match instances.

type FileSystemStats 

type FileSystemStats interface {
	StoreStats(ctx context.Context, stats *Stats) error
	LoadStats(ctx context.Context) (*Stats, error)
}

FileSystemStats defines the behavior expected from a scan file system to store and retrieve Stats instances.

type FileSystemSummaries 

type FileSystemSummaries interface {
	StoreTaskSummary(ctx context.Context, ts TaskSummary) error
	LoadTasksSummaries(ctx context.Context) ([]TaskSummary, error)
	TasksSummariesIterator(ctx context.Context) (chan TaskSummary, CloseFunc, error)
}

FileSystemSummaries defines the behavior expected from a scan file system to store and retrieve TaskSummary instances.

type FileSystemTemplates 

type FileSystemTemplates interface {
	StoreTemplate(ctx context.Context, tpl Template) error
	LoadTemplates(ctx context.Context) ([]Template, error)

	// TemplatesIterator returns a channel of Template (or an error),
	// so the channel can be used as an iterator.
	// The returned channel is closed when the iterator is done (no more elements)
	// or when the context is canceled.
	// Thus, the context cancellation can also be used to stop the iteration.
	TemplatesIterator(ctx context.Context) (chan Template, error)
}

FileSystemTemplates defines the behavior expected from a scan file system to store and retrieve Template instances.

type LineOfWork 

type LineOfWork struct {
	Template    Template
	Entrypoints []entrypoint.Entrypoint
	Tasks       []*Task

	sync.RWMutex
	Matches map[string]struct{}
}

LineOfWork is the aggregation for all the Task, for a given Template. In other words: - There is a LineOfWork for each request to be scanned:

  • For which we identify all the Entrypoints,
  • and combine with profile.Profile, to generate all starting possible combinations:
  • For every combination of entrypoint.Entrypoint (see Task.EntrypointIdx)
  • with every payload (see Task.PayloadIdx). [Rough estimate: #profiles x #payloads x #entrypoints]

=

  • Then, during the execution of the scan, more Task can be created, because one Task can be forked into more than one (for each step). So, every Task represents a path of steps, where every other step (except the current) did match.

type Match 

type Match struct {
	URL                   string
	Requests              []*request.Request
	Responses             []*response.Response
	ProfileName           string
	ProfileTags           []string
	IssueName             string
	IssueSeverity         string
	IssueConfidence       string
	IssueDetail           string
	IssueBackground       string
	RemediationDetail     string
	RemediationBackground string
	IssueParam            string
	ProfileType           string
	Payload               string
	Occurrences           [][]occurrence.Occurrence
	Grep                  string
	At                    time.Time
}

Match represents a match found during a scan, containing the URL, the requests and responses that were made, and some other details associated with the match, like the profile's name and some information about the issue.

There can be multiple Match per scan. See the `internal/match` package for further details.

type Modifier 

type Modifier interface {
	Modify(step *profile.Step, tpl Template, req request.Request) request.Request
}

Modifier defines the behavior of a request modifier, which is a component capable of modifying the given request based on certain given requirements.

type ParamsCfg 

type ParamsCfg struct {
	Params   []string
	Size     int
	Method   string
	Encoding string
}

ParamsCfg defines the configuration for request parameters and is responsible for splitting them into chunked groups.

func (ParamsCfg) Alter 

func (pCfg ParamsCfg) Alter(tpl Template) []Template

Alter takes a Template as an input, and using the given ParamsCfg it constructs a new set of Template.

type PayloadStrategy 

type PayloadStrategy string

PayloadStrategy represents the strategy used to inject payloads during the scan execution. It can be either PayloadStrategyOnlyOnce or PayloadStrategyAll. 

const (
	PayloadStrategyOnlyOnce PayloadStrategy = "only_once"
	PayloadStrategyAll      PayloadStrategy = "all"
)

func PayloadStrategyFromString 

func PayloadStrategyFromString(s string) PayloadStrategy

PayloadStrategyFromString converts a string into a PayloadStrategy.

func (PayloadStrategy) IsOnlyOnce 

func (ps PayloadStrategy) IsOnlyOnce() bool

IsOnlyOnce returns whether the payload strategy is PayloadStrategyOnlyOnce.

func (PayloadStrategy) String 

func (ps PayloadStrategy) String() string

String returns the string representation of the PayloadStrategy.

type Requester 

type Requester interface {
	Do(ctx context.Context, req *request.Request) (response.Response, error)
}

Requester defines the behavior expected from a requester, capable to perform an HTTP request.Request and return the response.Response got.

type RequesterBuilder 

type RequesterBuilder func() (Requester, error)

RequesterBuilder is a function that returns a Requester instance.

type Runner 

type Runner struct {
	// contains filtered or unexported fields
}

Runner is the main component responsible for orchestrating `scan` executions.

func NewRunner 

func NewRunner(opts *RunnerOpts) *Runner

NewRunner constructs a new Runner instance.

func (*Runner) Start 

func (r *Runner) Start() (err error)

Start starts the `scan` execution.

type RunnerOpts 

type RunnerOpts struct {
	// contains filtered or unexported fields
}

RunnerOpts is the structure that holds the configuration for the Runner to start a `scan`.

func DefaultRunnerOpts 

func DefaultRunnerOpts() *RunnerOpts

DefaultRunnerOpts constructs an empty instance of RunnerOpts.

func (*RunnerOpts) WithActiveProfiles 

func (opts *RunnerOpts) WithActiveProfiles(activeProfiles []*profile.Active) *RunnerOpts

WithActiveProfiles sets the given active profiles to the RunnerOpts instance.

func (*RunnerOpts) WithBlindHostPoller 

func (opts *RunnerOpts) WithBlindHostPoller(bhPoller BlindHostPoller) *RunnerOpts

WithBlindHostPoller sets the given blind host poller to the RunnerOpts instance.

func (*RunnerOpts) WithConfiguration 

func (opts *RunnerOpts) WithConfiguration(cfg Config) *RunnerOpts

WithConfiguration sets the given `scan` configuration to the RunnerOpts instance.

func (*RunnerOpts) WithContext 

func (opts *RunnerOpts) WithContext(ctx context.Context) *RunnerOpts

WithContext sets the given context to the RunnerOpts instance.

func (*RunnerOpts) WithEntrypointFinders 

func (opts *RunnerOpts) WithEntrypointFinders(finders []entrypoint.Finder) *RunnerOpts

WithEntrypointFinders sets the given entrypoint finders to the RunnerOpts instance.

func (*RunnerOpts) WithFileSystem 

func (opts *RunnerOpts) WithFileSystem(fileSystem FileSystem) *RunnerOpts

WithFileSystem sets the given file system abstraction to the RunnerOpts instance.

func (*RunnerOpts) WithModifiers 

func (opts *RunnerOpts) WithModifiers(modifiers []Modifier) *RunnerOpts

WithModifiers sets the given modifiers to the RunnerOpts instance.

func (*RunnerOpts) WithOnError 

func (opts *RunnerOpts) WithOnError(fn onErrorFunc) *RunnerOpts

WithOnError sets the given `onError` callback to the RunnerOpts instance.

func (*RunnerOpts) WithOnFinished 

func (opts *RunnerOpts) WithOnFinished(fn func(*Stats, error)) *RunnerOpts

WithOnFinished sets the given `onFinished` callback to the RunnerOpts instance.

func (*RunnerOpts) WithOnMatch 

func (opts *RunnerOpts) WithOnMatch(fn onMatchFunc) *RunnerOpts

WithOnMatch sets the given `onMatch` callback to the RunnerOpts instance.

func (*RunnerOpts) WithOnTask 

func (opts *RunnerOpts) WithOnTask(fn onTaskFunc) *RunnerOpts

WithOnTask sets the given `onTask` callback to the RunnerOpts instance.

func (*RunnerOpts) WithOnUpdated 

func (opts *RunnerOpts) WithOnUpdated(fn func(*Stats)) *RunnerOpts

WithOnUpdated sets the given `onUpdated` callback to the RunnerOpts instance.

func (*RunnerOpts) WithPassiveReqProfiles 

func (opts *RunnerOpts) WithPassiveReqProfiles(passiveReqProfiles []*profile.Request) *RunnerOpts

WithPassiveReqProfiles sets the given passive request profiles to the RunnerOpts instance.

func (*RunnerOpts) WithPassiveResProfiles 

func (opts *RunnerOpts) WithPassiveResProfiles(passiveResProfiles []*profile.Response) *RunnerOpts

WithPassiveResProfiles sets the given passive response profiles to the RunnerOpts instance.

func (*RunnerOpts) WithRequesterBuilder 

func (opts *RunnerOpts) WithRequesterBuilder(fn RequesterBuilder) *RunnerOpts

WithRequesterBuilder sets the given request builder to the RunnerOpts instance.

func (*RunnerOpts) WithSaveAllRequests 

func (opts *RunnerOpts) WithSaveAllRequests(saveAllRequests bool) *RunnerOpts

WithSaveAllRequests sets the given `saveAllRequests` boolean to the RunnerOpts instance.

func (*RunnerOpts) WithSaveAllResponses 

func (opts *RunnerOpts) WithSaveAllResponses(saveAllResponses bool) *RunnerOpts

WithSaveAllResponses sets the given `saveAllResponses` boolean to the RunnerOpts instance.

func (*RunnerOpts) WithSaveResponses 

func (opts *RunnerOpts) WithSaveResponses(saveResponses bool) *RunnerOpts

WithSaveResponses sets the given `saveResponses` boolean to the RunnerOpts instance.

type Stats 

type Stats struct {
	NumOfTotalRequests     int
	NumOfPerformedRequests int
	NumOfSucceedRequests   int
	NumOfFailedRequests    int
	NumOfSkippedRequests   int

	NumOfRequestsToAnalyze  int
	NumOfResponsesToAnalyze int

	TemplatesEnded map[int]struct{}

	NumOfEntrypoints int
	NumOfMatches     int

	StartedAt time.Time

	sync.Mutex
}

Stats is a structure that holds multiple stats about the scan process, such as the number of requests, the number of performed requests, etc.

func NewStats 

func NewStats() *Stats

NewStats creates a new instance of Stats.

type Task 

type Task struct {
	// IsBase is true if the task is a base task.
	// In such case, the task is not associated to a profile.
	// Thus, does not have a step nor a payload, nor an entrypoint.
	IsBase bool

	// Profile is the profile associated with the task. If defined, always as profile.ActiveProfile.
	Profile *profile.Active
	// StepIdx is the index of the step within the Profile steps the task is at.
	StepIdx int
	// PayloadIdx is the index of the payload within the Profile payloads the task is associated to.
	// It is equal to -1 when it is profile.RawRequestV2, or it is not associated to any Profile.
	PayloadIdx int

	Requests    []*request.Request
	Responses   []*response.Response
	Occurrences [][]occurrence.Occurrence
	Performed   bool
	Match       bool
	Error       error

	// LoW is an internal reference to the LineOfWork
	// it belongs to. It must be non-nil.
	LoW *LineOfWork
	// EntrypointIdx is the index of the entrypoint within the LineOfWork entrypoints the task is associated to.
	// It is equal to -1 when it is not associated to any LineOfWork entrypoint. If so, use Entrypoint instead.
	EntrypointIdx int
	// Entrypoint is an entrypoint.Entrypoint not included within the LineOfWork entrypoints.
	// Only used when it is not associated to any LineOfWork entrypoint. By the default, use EntrypointIdx.
	Entrypoint entrypoint.Entrypoint
}

Task is an atomic unit of work within a `scan`, which is what composes a Template.

type TaskSummary 

type TaskSummary struct {
	URL       string
	Requests  []*request.Request
	Responses []*response.Response
}

TaskSummary represents a summary of a scan task, which corresponds to one of the iterations where one (or multiple) requests are targeted against a URL, and some checks are performed over the responses, looking for one (or multiple) Match.

type Template 

type Template struct {
	Idx         int
	OriginalURL string
	request.Request
	Response *response.Response
}

Template is an abstraction that represents a request and response pair used for scanning. It also contains the original URL and the unique index within the entire scan.

func NewTemplate 

func NewTemplate(ctx context.Context, idx int, req request.Request, res *response.Response) Template

NewTemplate instantiates a new Template with the given request.Request, the response.Response, if any, and the given index. So, similar to manually populating the Template fields but with some validations in place.

func TemplateFromRawBytes 

func TemplateFromRawBytes(ctx context.Context, idx int, pCfg ParamsCfg, fileBytes []byte, opts ...request.Option) ([]Template, error)

TemplateFromRawBytes initializes a slice of Template with the given ParamsCfg, a slice of request.Option and interpreting the slice of bytes as a file that contains a raw HTTP request.

func TemplatesFromZipBytes 

func TemplatesFromZipBytes(ctx context.Context, pCfg ParamsCfg, fileBytes []byte, opts ...request.Option) ([]Template, error)

TemplatesFromZipBytes initializes a slice of Template with the given ParamsCfg, a slice of request.Option and interpreting the slice of bytes as the contents of a zipped (.zip) file that contains one or more files, each containing a raw HTTP request.

func (Template) Clone 

func (tpl Template) Clone(idx int) Template

Clone returns a clone (copy) of the Template, keeping the same index, URL, and deep-copying the request.Request.

type Writer 

type Writer interface {
	WriteConfig(ctx context.Context, cfg Config) error

	WriteStats(ctx context.Context, fs FileSystem) error
	WriteMatchesSummary(ctx context.Context, fs FileSystem) error

	WriteError(ctx context.Context, err Error) error
	WriteErrors(ctx context.Context, fs FileSystem) error

	WriteMatch(ctx context.Context, match Match, includeResponse bool) error
	WriteMatches(ctx context.Context, fs FileSystem, includeResponses bool) error

	WriteTasks(ctx context.Context, fs FileSystem, allRequests, allResponses bool) error
}

Writer defines the behavior expected from a scan writer, used to write Config, Stats, Match, Error, and TaskSummary instances to a specific output (e.g. stdout or file) in a specific format (e.g. JSON).

Source Files

View all Source files

Directories

Path Synopsis
platform
cli
filesystem
http/client
metrics
writer
encode
profilefakes

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.