blocks

package
v1.4.0 Latest Latest
Warning

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

 Go to latest Published: Oct 13, 2025 License: MIT Imports: 36 Imported by: 1

Documentation

Index

Constants

View Source 
const (
	ExecutorPython            = "python3"
	ExecutorBash              = "bash"
	ExecutorSh                = "sh"
	ExecutorPowershell        = "powershell"
	ExecutorPowershellOnLinux = "pwsh"
	ExecutorRuby              = "ruby"
	ExecutorBinary            = "binary"
	ExecutorCmd               = "cmd.exe"
)

These are all the different executors that could run our inline command

View Source 
const DefaultExecutionTimeout = 100 * time.Minute

DefaultExecutionTimeout is the default timeout for step execution.

Variables

This section is empty.

Functions

func FetchAbs 

func FetchAbs(path string, workdir string) (fullpath string, err error)

FetchAbs returns the absolute path of a file given its path and the working directory. It handles cases where the path starts with "~/", is an absolute path, or is a relative path from the working directory. It logs any errors and returns them.

**Parameters:**

path: A string representing the path to the file.

workdir: A string representing the working directory.

**Returns:**

fullpath: A string representing the absolute path to the file.

error: An error if the path cannot be resolved to an absolute path.

func FetchEnv 

func FetchEnv(environ map[string]string) []string

FetchEnv converts an environment variable map into a slice of strings that can be used as an argument when running a command.

**Parameters:**

environ: A map of environment variable names to values.

**Returns:**

[]string: A slice of strings representing the environment variables and their values.

func FindFilePath 

func FindFilePath(path string, workdir string, system fs.StatFS) (string, error)

FindFilePath checks if a file exists given its path, the working directory, and an optional fs.StatFS. It handles cases where the path starts with "../", "~/", or is a relative path. It also checks a list of paths in InventoryPath for the file. It logs any errors and returns them.

**Parameters:**

path: A string representing the path to the file.

workdir: A string representing the working directory.

system: An optional fs.StatFS that can be used to check if the file exists.

**Returns:**

string: A string representing the path to the file, or an empty string if the file does not exist.

error: An error if the file cannot be found or if other errors occur.

func InferExecutor 

func InferExecutor(filePath string) string

InferExecutor infers the executor based on the file extension and returns it as a string.

func LoadTTP 

func LoadTTP(ttpFilePath string, fsys afero.Fs, execCfg *TTPExecutionConfig, stepVars map[string]string, argsKvStrs []string) (*TTP, *TTPExecutionContext, error)

LoadTTP reads a TTP file and creates a TTP instance based on its contents. If the file is empty or contains invalid data, it returns an error.

**Parameters:**

ttpFilePath: the absolute or relative path to the TTP YAML file. fsys: an afero.Fs that contains the specified TTP file path

**Returns:**

*TTP: Pointer to the created TTP instance, or nil if the file is empty or invalid. TTPExecutionContext: the initialized TTPExecutionContext suitable for passing to TTP.Execute(...) err: An error if the file contains invalid data or cannot be read.

func SetupSignalHandler added in v1.1.0 

func SetupSignalHandler() chan bool

SetupSignalHandler sets up SIGINT and SIGTERM handlers for graceful shutdown

func ShouldUseImplicitDefaultCleanup added in v1.0.9 

func ShouldUseImplicitDefaultCleanup(action Action) bool

ShouldUseImplicitDefaultCleanup is a hack to make subTTPs always run their default cleanup process even when `cleanup: default` is not explicitly specified - this is purely for backward compatibility

Types

type ActResult 

type ActResult struct {
	Stdout  string
	Stderr  string
	Outputs map[string]string
}

ActResult contains common fields produced from both the execution of steps and their associated cleanup actions

type Action added in v1.0.9 

type Action interface {
	IsNil() bool
	Validate(execCtx TTPExecutionContext) error
	Template(execCtx TTPExecutionContext) error
	Execute(execCtx TTPExecutionContext) (*ActResult, error)
	GetDescription() string
	GetDefaultCleanupAction() Action
	CanBeUsedInCompositeAction() bool
}

Action is an interface that is implemented by all action types used in steps/cleanups (such as create_file, inline, etc)

type BasicStep 

type BasicStep struct {
	ExecutorName string                  `yaml:"executor,omitempty"`
	Inline       string                  `yaml:"inline,flow"`
	Environment  map[string]string       `yaml:"env,omitempty"`
	Outputs      map[string]outputs.Spec `yaml:"outputs,omitempty"`
	// contains filtered or unexported fields
}

BasicStep is a type that represents a basic execution step.

func NewBasicStep 

func NewBasicStep() *BasicStep

NewBasicStep creates a new BasicStep instance with an initialized Act struct.

func (*BasicStep) CanBeUsedInCompositeAction added in v1.1.0 

func (ad *BasicStep) CanBeUsedInCompositeAction() bool

CanBeUsedInCompositeAction provides a default implementation of the CanBeUsedInCompositeAction method from the Action interface. This saves us from having to declare this function for every steps If a specific action needs to be used in a composite action, it can override this step

func (*BasicStep) Execute 

func (b *BasicStep) Execute(execCtx TTPExecutionContext) (*ActResult, error)

Execute runs the step and returns an error if one occurs.

func (*BasicStep) GetDefaultCleanupAction added in v1.0.9 

func (ad *BasicStep) GetDefaultCleanupAction() Action

GetDefaultCleanupAction provides a default implementation of the GetDefaultCleanupAction method from the Action interface. This saves us from having to declare this function for every steps If a specific action needs a default cleanup action (such as a create_file action), it can override this step

func (*BasicStep) GetDescription added in v1.1.0 

func (ad *BasicStep) GetDescription() string

GetDescription returns the description field from the action

func (*BasicStep) IsNil 

func (b *BasicStep) IsNil() bool

IsNil checks if a step is considered empty or uninitialized.

func (*BasicStep) Template added in v1.2.4 

func (b *BasicStep) Template(execCtx TTPExecutionContext) error

Template takes each applicable field in the step and replaces any template strings with their resolved values.

func (*BasicStep) Validate 

func (b *BasicStep) Validate(execCtx TTPExecutionContext) error

Validate validates the step, checking for the necessary attributes and dependencies.

type ChangeDirectoryStep added in v1.2.2 

type ChangeDirectoryStep struct {
	Cd             string `yaml:"cd"`
	PreviousDir    string
	PreviousCDStep *ChangeDirectoryStep
	FileSystem     afero.Fs `yaml:"-,omitempty"`
	// contains filtered or unexported fields
}

ChangeDirectoryStep is a step that changes the current working directory

func NewChangeDirectoryStep added in v1.2.2 

func NewChangeDirectoryStep() *ChangeDirectoryStep

NewChangeDirectoryStep creates a new ChangeDirectoryStep instance with an initialized Act struct.

func (*ChangeDirectoryStep) CanBeUsedInCompositeAction added in v1.2.2 

func (ad *ChangeDirectoryStep) CanBeUsedInCompositeAction() bool

CanBeUsedInCompositeAction provides a default implementation of the CanBeUsedInCompositeAction method from the Action interface. This saves us from having to declare this function for every steps If a specific action needs to be used in a composite action, it can override this step

func (*ChangeDirectoryStep) Execute added in v1.2.2 

func (step *ChangeDirectoryStep) Execute(ctx TTPExecutionContext) (*ActResult, error)

Execute runs the ChangeDirectoryStep, changing the current working directory and returns an error if any occur.

**Returns:**

ActResult: the result of the action error: error if execution fails, nil otherwise

func (*ChangeDirectoryStep) GetDefaultCleanupAction added in v1.2.2 

func (step *ChangeDirectoryStep) GetDefaultCleanupAction() Action

GetDefaultCleanupAction sets the directory back to the previous directory

func (*ChangeDirectoryStep) GetDescription added in v1.2.2 

func (ad *ChangeDirectoryStep) GetDescription() string

GetDescription returns the description field from the action

func (*ChangeDirectoryStep) IsNil added in v1.2.2 

func (step *ChangeDirectoryStep) IsNil() bool

IsNil checks if a ChangeDirectoryStep is considered empty or unitializied

func (*ChangeDirectoryStep) Template added in v1.2.4 

func (step *ChangeDirectoryStep) Template(execCtx TTPExecutionContext) error

Template takes each applicable field in the step and replaces any template strings with their resolved values.

**Returns:**

error: error if template resolution fails, nil otherwise

func (*ChangeDirectoryStep) Validate added in v1.2.2 

func (step *ChangeDirectoryStep) Validate(_ TTPExecutionContext) error

Validate validates the ChangeDirectoryStep, checking for the necessary attributes and dependencies.

**Returns:**

error: error if validation fails, nil otherwise

type CommonStepFields added in v1.0.9 

type CommonStepFields struct {
	Name   string         `yaml:"name,omitempty"`
	Checks []checks.Check `yaml:"checks,omitempty"`

	// CleanupSpec is exported so that UnmarshalYAML
	// can see it - however, it should be considered
	// to be a private detail of this file
	// and not referenced elsewhere in the codebase
	CleanupSpec yaml.Node `yaml:"cleanup,omitempty"`
}

CommonStepFields contains the fields common to every type of step (such as Name). It centralizes validation to simplify the code

type CompositeAction added in v1.1.0 

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

CompositeAction is an action that executes multiple actions

func (*CompositeAction) CanBeUsedInCompositeAction added in v1.1.0 

func (ca *CompositeAction) CanBeUsedInCompositeAction() bool

CanBeUsedInCompositeAction enables this action to be used in a composite action

func (*CompositeAction) Execute added in v1.1.0 

func (ca *CompositeAction) Execute(execCtx TTPExecutionContext) (*ActResult, error)

Execute runs the step and returns an error if one occurs.

func (*CompositeAction) GetDefaultCleanupAction added in v1.1.0 

func (ad *CompositeAction) GetDefaultCleanupAction() Action

GetDefaultCleanupAction provides a default implementation of the GetDefaultCleanupAction method from the Action interface. This saves us from having to declare this function for every steps If a specific action needs a default cleanup action (such as a create_file action), it can override this step

func (*CompositeAction) GetDescription added in v1.1.0 

func (ad *CompositeAction) GetDescription() string

GetDescription returns the description field from the action

func (*CompositeAction) IsNil added in v1.1.0 

func (ad *CompositeAction) IsNil() bool

IsNil provides a default implementation of the IsNil method from the Action interface.

func (*CompositeAction) Template added in v1.2.4 

func (ca *CompositeAction) Template(execCtx TTPExecutionContext) error

Template each action in the composite action

func (*CompositeAction) Validate added in v1.1.0 

func (ca *CompositeAction) Validate(execCtx TTPExecutionContext) error

Validate validates the CompositeAction, checking for the necessary attributes and dependencies

type CopyPathStep added in v1.0.10 

type CopyPathStep struct {
	Source      string   `yaml:"copy_path,omitempty"`
	Destination string   `yaml:"to,omitempty"`
	Recursive   bool     `yaml:"recursive,omitempty"`
	Overwrite   bool     `yaml:"overwrite,omitempty"`
	Mode        int      `yaml:"mode,omitempty"`
	FileSystem  afero.Fs `yaml:"-,omitempty"`
	// contains filtered or unexported fields
}

CopyPathStep creates a new file and populates it with the specified contents from an existing path. Its intended use is simulating malicious file copies via a C2, where there is no corresponding shell history telemetry.

func NewCopyPathStep added in v1.0.10 

func NewCopyPathStep() *CopyPathStep

NewCopyPathStep creates a new CopyPathStep instance and returns a pointer to it.

func (*CopyPathStep) CanBeUsedInCompositeAction added in v1.1.0 

func (s *CopyPathStep) CanBeUsedInCompositeAction() bool

CanBeUsedInCompositeAction enables this action to be used in a composite action

func (*CopyPathStep) Execute added in v1.0.10 

func (s *CopyPathStep) Execute(_ TTPExecutionContext) (*ActResult, error)

Execute runs the step and returns an error if one occurs.

func (*CopyPathStep) GetDefaultCleanupAction added in v1.0.10 

func (s *CopyPathStep) GetDefaultCleanupAction() Action

GetDefaultCleanupAction will instruct the calling code to remove the path created by this action

func (*CopyPathStep) GetDescription added in v1.1.0 

func (ad *CopyPathStep) GetDescription() string

GetDescription returns the description field from the action

func (*CopyPathStep) IsNil added in v1.0.10 

func (s *CopyPathStep) IsNil() bool

IsNil checks if the step is nil or empty and returns a boolean value.

func (*CopyPathStep) Template added in v1.2.4 

func (s *CopyPathStep) Template(execCtx TTPExecutionContext) error

Template takes each applicable field in the step and replaces any template strings with their resolved values.

**Returns:**

error: error if template resolution fails, nil otherwise

func (*CopyPathStep) Validate added in v1.0.10 

func (s *CopyPathStep) Validate(_ TTPExecutionContext) error

Validate validates the step, checking for the necessary attributes and dependencies

type CreateFileStep added in v1.0.8 

type CreateFileStep struct {
	Path       string   `yaml:"create_file,omitempty"`
	Contents   string   `yaml:"contents,omitempty"`
	Overwrite  bool     `yaml:"overwrite,omitempty"`
	Mode       int      `yaml:"mode,omitempty"`
	FileSystem afero.Fs `yaml:"-,omitempty"`
	// contains filtered or unexported fields
}

CreateFileStep creates a new file and populates it with the specified contents. Its intended use is simulating malicious file creation through an editor program or via a C2, where there is no corresponding shell history telemetry

func NewCreateFileStep added in v1.0.8 

func NewCreateFileStep() *CreateFileStep

NewCreateFileStep creates a new CreateFileStep instance and returns a pointer to it.

func (*CreateFileStep) CanBeUsedInCompositeAction added in v1.1.0 

func (ad *CreateFileStep) CanBeUsedInCompositeAction() bool

CanBeUsedInCompositeAction provides a default implementation of the CanBeUsedInCompositeAction method from the Action interface. This saves us from having to declare this function for every steps If a specific action needs to be used in a composite action, it can override this step

func (*CreateFileStep) Execute added in v1.0.8 

func (s *CreateFileStep) Execute(_ TTPExecutionContext) (*ActResult, error)

Execute runs the step and returns an error if one occurs.

func (*CreateFileStep) GetDefaultCleanupAction added in v1.0.9 

func (s *CreateFileStep) GetDefaultCleanupAction() Action

GetDefaultCleanupAction will instruct the calling code to remove the path created by this action

func (*CreateFileStep) GetDescription added in v1.1.0 

func (ad *CreateFileStep) GetDescription() string

GetDescription returns the description field from the action

func (*CreateFileStep) IsNil added in v1.0.8 

func (s *CreateFileStep) IsNil() bool

IsNil checks if the step is nil or empty and returns a boolean value.

func (*CreateFileStep) Template added in v1.2.4 

func (s *CreateFileStep) Template(execCtx TTPExecutionContext) error

Template takes each applicable field in the step and replaces any template strings with their resolved values.

**Returns:**

error: error if template resolution fails, nil otherwise

func (*CreateFileStep) Validate added in v1.0.8 

func (s *CreateFileStep) Validate(_ TTPExecutionContext) error

Validate validates the step, checking for the necessary attributes and dependencies.

type Edit 

type Edit struct {
	Old    string `yaml:"old,omitempty"`
	New    string `yaml:"new,omitempty"`
	Append string `yaml:"append,omitempty"`
	Delete string `yaml:"delete,omitempty"`
	Regexp bool   `yaml:"regexp,omitempty"`
	// contains filtered or unexported fields
}

Edit represents a single old+new find-and-replace pair

type EditStep 

type EditStep struct {
	FileToEdit string   `yaml:"edit_file,omitempty"`
	Edits      []*Edit  `yaml:"edits,omitempty"`
	FileSystem afero.Fs `yaml:"-,omitempty"`
	BackupFile string   `yaml:"backup_file,omitempty"`
	// contains filtered or unexported fields
}

EditStep represents one or more edits to a specific file

func NewEditStep 

func NewEditStep() *EditStep

NewEditStep creates a new EditStep instance with an initialized Act struct.

func (*EditStep) CanBeUsedInCompositeAction added in v1.1.0 

func (s *EditStep) CanBeUsedInCompositeAction() bool

CanBeUsedInCompositeAction enables this action to be used in a composite action

func (*EditStep) Execute 

func (s *EditStep) Execute(execCtx TTPExecutionContext) (*ActResult, error)

Execute runs the step and returns an error if one occurs.

func (*EditStep) GetDefaultCleanupAction added in v1.0.9 

func (s *EditStep) GetDefaultCleanupAction() Action

GetDefaultCleanupAction will instruct the calling code to copy the file to the backup file to the original path on cleanup.

func (*EditStep) GetDescription added in v1.1.0 

func (ad *EditStep) GetDescription() string

GetDescription returns the description field from the action

func (*EditStep) IsNil 

func (s *EditStep) IsNil() bool

IsNil checks if the step is nil or empty and returns a boolean value.

func (*EditStep) Template added in v1.2.4 

func (s *EditStep) Template(execCtx TTPExecutionContext) error

Template takes each applicable field in the step and replaces any template strings with their resolved values.

**Returns:**

error: error if template resolution fails, nil otherwise

func (*EditStep) Validate 

func (s *EditStep) Validate(execCtx TTPExecutionContext) error

Validate validates the step, checking for the necessary attributes and dependencies

type ExecutionResult 

type ExecutionResult struct {
	ActResult
	Cleanup *ActResult
}

ExecutionResult stores the results/outputs generated by executing a Step

type Executor added in v1.2.0 

type Executor interface {
	Execute(ctx context.Context, execCtx TTPExecutionContext) (*ActResult, error)
}

Executor is an interface that defines the Execute method.

func NewExecutor added in v1.2.0 

func NewExecutor(executorName string, inline string, filePath string, args []string, environment map[string]string) Executor

NewExecutor creates a new ScriptExecutor or FileExecutor based on the executorName

type ExpectSpec added in v1.1.0 

type ExpectSpec struct {
	Inline    string     `yaml:"inline"`
	Responses []Response `yaml:"responses"`
}

ExpectSpec represents the expect block in the expect step.

**Attributes:**

Inline: Inline script to execute. Responses: List of expected prompts and responses.

type ExpectStep added in v1.1.0 

type ExpectStep struct {
	Chdir       string                  `yaml:"chdir,omitempty"`
	Timeout     int                     `yaml:"timeout,omitempty"`
	Executor    string                  `yaml:"executor,omitempty"`
	Expect      *ExpectSpec             `yaml:"expect,omitempty"`
	Environment map[string]string       `yaml:"env,omitempty"`
	Outputs     map[string]outputs.Spec `yaml:"outputs,omitempty"`
	// contains filtered or unexported fields
}

ExpectStep represents an expect command.

**Attributes:**

Chdir: Directory to change to before executing the command. Responses: List of expected prompts and responses. Timeout: Timeout duration for the expect command. Executor: Shell to use for executing the command. Environment: Environment variables for the command. Inline: Inline script to execute. CleanupStep: Command to run for cleanup after execution. Outputs: Outputs generated by the command.

func NewExpectStep added in v1.1.0 

func NewExpectStep() *ExpectStep

NewExpectStep creates a new ExpectStep instance.

**Returns:**

*ExpectStep: A pointer to the newly created ExpectStep.

func (*ExpectStep) CanBeUsedInCompositeAction added in v1.1.0 

func (s *ExpectStep) CanBeUsedInCompositeAction() bool

CanBeUsedInCompositeAction enables this action to be used in a composite action.

**Returns:**

bool: True if the action can be used in a composite action.

func (*ExpectStep) Execute added in v1.1.0 

func (s *ExpectStep) Execute(execCtx TTPExecutionContext) (*ActResult, error)

Execute runs the step and returns an error if one occurs.

**Parameters:**

execCtx: The execution context containing environment variables and working directory.

**Returns:**

*ActResult: A pointer to the action result. error: An error if execution fails.

func (*ExpectStep) GetDefaultCleanupAction added in v1.1.0 

func (ad *ExpectStep) GetDefaultCleanupAction() Action

GetDefaultCleanupAction provides a default implementation of the GetDefaultCleanupAction method from the Action interface. This saves us from having to declare this function for every steps If a specific action needs a default cleanup action (such as a create_file action), it can override this step

func (*ExpectStep) GetDescription added in v1.1.0 

func (ad *ExpectStep) GetDescription() string

GetDescription returns the description field from the action

func (*ExpectStep) IsNil added in v1.1.0 

func (s *ExpectStep) IsNil() bool

IsNil checks if the step is nil or empty and returns a boolean value.

**Returns:**

bool: True if the step is nil or empty, false otherwise.

func (*ExpectStep) Template added in v1.2.4 

func (s *ExpectStep) Template(execCtx TTPExecutionContext) error

Template takes each applicable field in the step and replaces any template strings with their resolved values.

**Returns:**

error: error if template resolution fails, nil otherwise

func (*ExpectStep) Validate added in v1.1.0 

func (s *ExpectStep) Validate(_ TTPExecutionContext) error

Validate validates the step, checking for the necessary attributes and dependencies.

**Parameters:**

execCtx: The execution context containing environment variables and working directory.

**Returns:**

error: An error if validation fails.

type FetchURIStep added in v1.0.8 

type FetchURIStep struct {
	FetchURI   string   `yaml:"fetch_uri,omitempty"`
	Retries    string   `yaml:"retries,omitempty"`
	Location   string   `yaml:"location,omitempty"`
	Proxy      string   `yaml:"proxy,omitempty"`
	Overwrite  bool     `yaml:"overwrite,omitempty"`
	FileSystem afero.Fs `yaml:"-,omitempty"`
	// contains filtered or unexported fields
}

FetchURIStep represents a step in a process that consists of a main action, a cleanup action, and additional metadata.

func NewFetchURIStep added in v1.0.8 

func NewFetchURIStep() *FetchURIStep

NewFetchURIStep creates a new FetchURIStep instance and returns a pointer to it.

func (*FetchURIStep) CanBeUsedInCompositeAction added in v1.1.0 

func (ad *FetchURIStep) CanBeUsedInCompositeAction() bool

CanBeUsedInCompositeAction provides a default implementation of the CanBeUsedInCompositeAction method from the Action interface. This saves us from having to declare this function for every steps If a specific action needs to be used in a composite action, it can override this step

func (*FetchURIStep) Execute added in v1.0.8 

func (f *FetchURIStep) Execute(execCtx TTPExecutionContext) (*ActResult, error)

Execute runs the step and returns an error if one occurs.

func (*FetchURIStep) GetDefaultCleanupAction added in v1.0.9 

func (f *FetchURIStep) GetDefaultCleanupAction() Action

GetDefaultCleanupAction will instruct the calling code to remove the file fetched by this action.

func (*FetchURIStep) GetDescription added in v1.1.0 

func (ad *FetchURIStep) GetDescription() string

GetDescription returns the description field from the action

func (*FetchURIStep) IsNil added in v1.0.8 

func (f *FetchURIStep) IsNil() bool

IsNil checks if the step is nil or empty and returns a boolean value.

func (*FetchURIStep) Template added in v1.2.4 

func (f *FetchURIStep) Template(execCtx TTPExecutionContext) error

Template takes each applicable field in the step and replaces any template strings with their resolved values.

**Returns:**

error: error if template resolution fails, nil otherwise

func (*FetchURIStep) Validate added in v1.0.8 

func (f *FetchURIStep) Validate(execCtx TTPExecutionContext) error

Validate validates the FetchURIStep. It checks that the Act field is valid, Location is set with a valid file path, and Uri is set.

If Location is set, it ensures that the path exists and retrieves its absolute path.

type FileExecutor added in v1.2.0 

type FileExecutor struct {
	Name        string
	FilePath    string
	Args        []string
	Environment map[string]string
}

FileExecutor executes TTP steps by calling a script file or binary with arguments

func (*FileExecutor) Execute added in v1.2.0 

func (e *FileExecutor) Execute(ctx context.Context, execCtx TTPExecutionContext) (*ActResult, error)

Execute runs the binary with arguments

type FileStep 

type FileStep struct {
	FilePath    string                  `yaml:"file,omitempty"`
	Executor    string                  `yaml:"executor,omitempty"`
	Environment map[string]string       `yaml:"env,omitempty"`
	Outputs     map[string]outputs.Spec `yaml:"outputs,omitempty"`
	Args        []string                `yaml:"args,omitempty,flow"`
	// contains filtered or unexported fields
}

FileStep represents a step in a process that consists of a main action, a cleanup action, and additional metadata.

func NewFileStep 

func NewFileStep() *FileStep

NewFileStep creates a new FileStep instance and returns a pointer to it.

func (*FileStep) CanBeUsedInCompositeAction added in v1.1.0 

func (ad *FileStep) CanBeUsedInCompositeAction() bool

CanBeUsedInCompositeAction provides a default implementation of the CanBeUsedInCompositeAction method from the Action interface. This saves us from having to declare this function for every steps If a specific action needs to be used in a composite action, it can override this step

func (*FileStep) Cleanup 

func (f *FileStep) Cleanup(execCtx TTPExecutionContext) (*ActResult, error)

Cleanup is a method to establish a link with the Cleanup interface. Assumes that the type is the cleanup step and is invoked by f.CleanupStep.Cleanup.

func (*FileStep) Execute 

func (f *FileStep) Execute(execCtx TTPExecutionContext) (*ActResult, error)

Execute runs the step and returns an error if one occurs.

func (*FileStep) GetDefaultCleanupAction added in v1.0.9 

func (ad *FileStep) GetDefaultCleanupAction() Action

GetDefaultCleanupAction provides a default implementation of the GetDefaultCleanupAction method from the Action interface. This saves us from having to declare this function for every steps If a specific action needs a default cleanup action (such as a create_file action), it can override this step

func (*FileStep) GetDescription added in v1.1.0 

func (ad *FileStep) GetDescription() string

GetDescription returns the description field from the action

func (*FileStep) IsNil 

func (f *FileStep) IsNil() bool

IsNil checks if the step is nil or empty and returns a boolean value.

func (*FileStep) Template added in v1.2.4 

func (f *FileStep) Template(execCtx TTPExecutionContext) error

Template takes each applicable field in the step and replaces any template strings with their resolved values.

**Returns:**

error: error if template resolution fails, nil otherwise

func (*FileStep) Validate 

func (f *FileStep) Validate(execCtx TTPExecutionContext) error

Validate validates the FileStep. It checks that the Act field is valid, and that either FilePath is set with a valid file path, or InlineLogic is set with valid code.

If FilePath is set, it ensures that the file exists and retrieves its absolute path.

If Executor is not set, it infers the executor based on the file extension. It then checks that the executor is in the system path, and if CleanupStep is not nil, it validates the cleanup step as well. It logs any errors and returns them.

type HTTPHeader added in v1.2.3 

type HTTPHeader struct {
	Field string `yaml:"field,omitempty"`
	Value string `yaml:"value,omitempty"`
}

HTTPHeader represents a key-value pair for HTTP header.

type HTTPParameter added in v1.2.3 

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

HTTPParameter represents a single HTTP parameter.

type HTTPRequestStep added in v1.2.3 

type HTTPRequestStep struct {
	HTTPRequest string           `yaml:"http_request,omitempty"`
	Type        string           `yaml:"type,omitempty"`
	Headers     []*HTTPHeader    `yaml:"headers,omitempty"`
	Parameters  []*HTTPParameter `yaml:"parameters,omitempty"`
	Body        string           `yaml:"body,omitempty"`
	Regex       string           `yaml:"regex,omitempty"`
	Proxy       string           `yaml:"proxy,omitempty"`
	Response    string           `yaml:"response,omitempty"`
	// contains filtered or unexported fields
}

HTTPRequestStep represents a step in a process that consists of a main action, a cleanup action, and additional metadata.

func NewHTTPRequestStep added in v1.2.3 

func NewHTTPRequestStep() *HTTPRequestStep

NewHTTPRequestStep creates a new HTTPRequestStep instance and returns a pointer to it.

func (*HTTPRequestStep) CanBeUsedInCompositeAction added in v1.2.3 

func (ad *HTTPRequestStep) CanBeUsedInCompositeAction() bool

CanBeUsedInCompositeAction provides a default implementation of the CanBeUsedInCompositeAction method from the Action interface. This saves us from having to declare this function for every steps If a specific action needs to be used in a composite action, it can override this step

func (*HTTPRequestStep) Execute added in v1.2.3 

func (r *HTTPRequestStep) Execute(execCtx TTPExecutionContext) (*ActResult, error)

Execute runs the step and returns an error if one occurs.

func (*HTTPRequestStep) GetDefaultCleanupAction added in v1.2.3 

func (ad *HTTPRequestStep) GetDefaultCleanupAction() Action

GetDefaultCleanupAction provides a default implementation of the GetDefaultCleanupAction method from the Action interface. This saves us from having to declare this function for every steps If a specific action needs a default cleanup action (such as a create_file action), it can override this step

func (*HTTPRequestStep) GetDescription added in v1.2.3 

func (ad *HTTPRequestStep) GetDescription() string

GetDescription returns the description field from the action

func (*HTTPRequestStep) IsNil added in v1.2.3 

func (r *HTTPRequestStep) IsNil() bool

IsNil checks if the step is nil or empty and returns a boolean value.

func (*HTTPRequestStep) SendRequest added in v1.2.3 

func (r *HTTPRequestStep) SendRequest(execCtx TTPExecutionContext) error

HTTPRequest executes the HTTPRequestStep.

func (*HTTPRequestStep) Template added in v1.2.4 

func (r *HTTPRequestStep) Template(execCtx TTPExecutionContext) error

Template takes each applicable field in the step and replaces any template strings with their resolved values.

**Returns:**

error: error if template resolution fails, nil otherwise

func (*HTTPRequestStep) Validate added in v1.2.3 

func (r *HTTPRequestStep) Validate(execCtx TTPExecutionContext) error

Validate validates the HTTPRequestStep.

type KillProcessStep added in v1.2.5 

type KillProcessStep struct {
	ProcessID                 string `yaml:"kill_process_id,omitempty"`
	ProcessName               string `yaml:"kill_process_name,omitempty"`
	ErrorOnFindProcessFailure bool   `yaml:"error_on_find_process_failure,omitempty"`
	ErrorOnKillFailure        bool   `yaml:"error_on_kill_failure,omitempty"`
	// contains filtered or unexported fields
}

KillProcessStep kills a process using ID/name Its intended use is simulating malicious programs stopping critical applications/processes

func NewKillProcessStep added in v1.2.5 

func NewKillProcessStep() *KillProcessStep

NewKillProcessStep creates a new KillProcessStep instance and returns a pointer to it.

func (*KillProcessStep) CanBeUsedInCompositeAction added in v1.2.5 

func (ad *KillProcessStep) CanBeUsedInCompositeAction() bool

CanBeUsedInCompositeAction provides a default implementation of the CanBeUsedInCompositeAction method from the Action interface. This saves us from having to declare this function for every steps If a specific action needs to be used in a composite action, it can override this step

func (*KillProcessStep) Execute added in v1.2.5 

func (s *KillProcessStep) Execute(_ TTPExecutionContext) (*ActResult, error)

Execute runs the step and returns an error if one occurs while extracting PIDs or killing processes.

func (*KillProcessStep) GetDefaultCleanupAction added in v1.2.5 

func (ad *KillProcessStep) GetDefaultCleanupAction() Action

GetDefaultCleanupAction provides a default implementation of the GetDefaultCleanupAction method from the Action interface. This saves us from having to declare this function for every steps If a specific action needs a default cleanup action (such as a create_file action), it can override this step

func (*KillProcessStep) GetDescription added in v1.2.5 

func (ad *KillProcessStep) GetDescription() string

GetDescription returns the description field from the action

func (*KillProcessStep) IsNil added in v1.2.5 

func (s *KillProcessStep) IsNil() bool

IsNil checks if the step is nil or empty and returns a boolean value.

func (*KillProcessStep) Template added in v1.2.5 

func (s *KillProcessStep) Template(execCtx TTPExecutionContext) error

Template takes each applicable field in the step and replaces any template strings with their resolved values.

**Returns:**

error: error if template resolution fails, nil otherwise

func (*KillProcessStep) Validate added in v1.2.5 

func (s *KillProcessStep) Validate(_ TTPExecutionContext) error

Validate validates the step, checking for the necessary attributes and dependencies.

type MitreAttack added in v1.0.8 

type MitreAttack struct {
	Tactics       []string `yaml:"tactics,omitempty"`
	Techniques    []string `yaml:"techniques,omitempty"`
	SubTechniques []string `yaml:"subtechniques,omitempty"`
}

MitreAttack represents mappings to the MITRE ATT&CK framework.

**Attributes:**

Tactics: A string slice containing the MITRE ATT&CK tactic(s) associated with the TTP. Techniques: A string slice containing the MITRE ATT&CK technique(s) associated with the TTP. SubTechniques: A string slice containing the MITRE ATT&CK sub-technique(s) associated with the TTP.

type PreambleFields added in v1.1.0 

type PreambleFields struct {
	APIVersion         string              `yaml:"api_version,omitempty"`
	UUID               string              `yaml:"uuid,omitempty"`
	Name               string              `yaml:"name,omitempty"`
	Description        string              `yaml:"description"`
	MitreAttackMapping *MitreAttack        `yaml:"mitre,omitempty"`
	Requirements       *RequirementsConfig `yaml:"requirements,omitempty"`
	ArgSpecs           []args.Spec         `yaml:"args,omitempty,flow"`
}

PreambleFields are TTP fields that can be parsed prior to rendering the TTP steps with `text/template`

**Attributes:**

Name: The name of the TTP. Description: A description of the TTP. MitreAttackMapping: A MitreAttack object containing mappings to the MITRE ATT&CK framework. Requirements: The Requirements to run the TTP ArgSpecs: An slice of argument specifications for the TTP.

func (*PreambleFields) Validate added in v1.1.0 

func (pf *PreambleFields) Validate(strict bool) error

Validate validates the preamble fields. It is used by both `ttpforge run` and `ttpforge test`

type PrintStrAction added in v1.0.9 

type PrintStrAction struct {
	Message string `yaml:"print_str,omitempty"`
	// contains filtered or unexported fields
}

PrintStrAction is used to print a string to the console

func NewPrintStrAction added in v1.1.0 

func NewPrintStrAction() *PrintStrAction

NewPrintStrAction creates a new PrintStrAction.

func (*PrintStrAction) CanBeUsedInCompositeAction added in v1.1.0 

func (ad *PrintStrAction) CanBeUsedInCompositeAction() bool

CanBeUsedInCompositeAction provides a default implementation of the CanBeUsedInCompositeAction method from the Action interface. This saves us from having to declare this function for every steps If a specific action needs to be used in a composite action, it can override this step

func (*PrintStrAction) Execute added in v1.0.9 

func (s *PrintStrAction) Execute(execCtx TTPExecutionContext) (*ActResult, error)

Execute runs the step and returns an error if one occurs.

func (*PrintStrAction) GetDefaultCleanupAction added in v1.0.9 

func (ad *PrintStrAction) GetDefaultCleanupAction() Action

GetDefaultCleanupAction provides a default implementation of the GetDefaultCleanupAction method from the Action interface. This saves us from having to declare this function for every steps If a specific action needs a default cleanup action (such as a create_file action), it can override this step

func (*PrintStrAction) GetDescription added in v1.1.0 

func (ad *PrintStrAction) GetDescription() string

GetDescription returns the description field from the action

func (*PrintStrAction) IsNil added in v1.0.9 

func (s *PrintStrAction) IsNil() bool

IsNil checks if the step is nil or empty and returns a boolean value.

func (*PrintStrAction) Template added in v1.2.4 

func (s *PrintStrAction) Template(execCtx TTPExecutionContext) error

Template takes each applicable field in the step and replaces any template strings with their resolved values.

**Returns:**

error: error if template resolution fails, nil otherwise

func (*PrintStrAction) Validate added in v1.0.9 

func (s *PrintStrAction) Validate(_ TTPExecutionContext) error

Validate validates the step, checking for the necessary attributes and dependencies

type RemovePathAction added in v1.0.9 

type RemovePathAction struct {
	Path       string   `yaml:"remove_path,omitempty"`
	Recursive  bool     `yaml:"recursive,omitempty"`
	FileSystem afero.Fs `yaml:"-,omitempty"`
	// contains filtered or unexported fields
}

RemovePathAction is invoked by adding remove_path to a given YAML step. It will delete the file at the specified path You must pass `recursive: true` to delete directories

func NewRemovePathAction added in v1.1.0 

func NewRemovePathAction() *RemovePathAction

NewRemovePathAction creates a new RemovePathAction.

func (*RemovePathAction) CanBeUsedInCompositeAction added in v1.1.0 

func (s *RemovePathAction) CanBeUsedInCompositeAction() bool

CanBeUsedInCompositeAction enables this action to be used in a composite action

func (*RemovePathAction) Execute added in v1.0.9 

func (s *RemovePathAction) Execute(_ TTPExecutionContext) (*ActResult, error)

Execute runs the step and returns an error if one occurs.

func (*RemovePathAction) GetDefaultCleanupAction added in v1.0.9 

func (ad *RemovePathAction) GetDefaultCleanupAction() Action

GetDefaultCleanupAction provides a default implementation of the GetDefaultCleanupAction method from the Action interface. This saves us from having to declare this function for every steps If a specific action needs a default cleanup action (such as a create_file action), it can override this step

func (*RemovePathAction) GetDescription added in v1.1.0 

func (ad *RemovePathAction) GetDescription() string

GetDescription returns the description field from the action

func (*RemovePathAction) IsNil added in v1.0.9 

func (s *RemovePathAction) IsNil() bool

IsNil checks if the step is nil or empty and returns a boolean value.

func (*RemovePathAction) Template added in v1.2.4 

func (s *RemovePathAction) Template(execCtx TTPExecutionContext) error

Template takes each applicable field in the step and replaces any template strings with their resolved values.

**Returns:**

error: error if template resolution fails, nil otherwise

func (*RemovePathAction) Validate added in v1.0.9 

func (s *RemovePathAction) Validate(_ TTPExecutionContext) error

Validate validates the step, checking for the necessary attributes and dependencies

type RenderParameters added in v1.1.0 

type RenderParameters struct {
	Args     map[string]interface{}
	Platform platforms.Spec
}

RenderParameters is a container for all of the runtime parameters used in the TTP template rendering process

type RequirementsConfig added in v1.0.10 

type RequirementsConfig struct {
	ExpectSuperuser bool             `yaml:"superuser,omitempty"`
	Platforms       []platforms.Spec `yaml:"platforms,omitempty"`
}

RequirementsConfig specifies the prerequisites that must be satisfied before executing a particular TTP.

**Attributes:**

ExpectSuperuser: Whether the TTP assumes superuser privileges

func (*RequirementsConfig) Validate added in v1.0.10 

func (rc *RequirementsConfig) Validate() error

Validate checks that the requirements section is well-formed - it does not actually check that the requirements are met.

func (*RequirementsConfig) Verify added in v1.0.10 

func (rc *RequirementsConfig) Verify(ctx checks.VerificationContext) error

Verify checks that the requirements specified in the requirements section are actually satisfied by the environment in which the TTP is currently running.

type Response added in v1.1.0 

type Response struct {
	Prompt   string `yaml:"prompt"`
	Response string `yaml:"response"`
}

Response represents a prompt-response pair.

**Attributes:**

Prompt: The expected prompt to match. Response: The response to send when the prompt is matched.

type ScriptExecutor added in v1.2.0 

type ScriptExecutor struct {
	Name        string
	Inline      string
	Environment map[string]string
}

ScriptExecutor executes TTP steps by passing script via stdin

func (*ScriptExecutor) Execute added in v1.2.0 

func (e *ScriptExecutor) Execute(ctx context.Context, execCtx TTPExecutionContext) (*ActResult, error)

Execute runs the command

type Step 

type Step struct {
	CommonStepFields
	// contains filtered or unexported fields
}

Step contains a TTPForge executable action and its associated cleanup action (if specified)

func (*Step) Cleanup added in v1.0.9 

func (s *Step) Cleanup(execCtx TTPExecutionContext) (*ActResult, error)

Cleanup runs the cleanup action associated with this step

func (*Step) Execute 

func (s *Step) Execute(execCtx TTPExecutionContext) (*ActResult, error)

Execute runs the action associated with this step and sends result/error to channels of the context

func (*Step) ParseAction added in v1.0.9 

func (s *Step) ParseAction(node *yaml.Node) (Action, error)

ParseAction decodes an action (from step or cleanup) in YAML format into the appropriate struct

func (*Step) ShouldCleanupOnFailure added in v1.0.9 

func (s *Step) ShouldCleanupOnFailure() bool

ShouldCleanupOnFailure specifies that this step should be cleaned up even if its Execute(...) failed. We usually don't want to do this - for example, you shouldn't try to remove_path a create_file that failed) However, certain step types (especially SubTTPs) need to run cleanup even if they fail

func (*Step) Template added in v1.2.4 

func (s *Step) Template(execCtx TTPExecutionContext) error

Template replaces variables in the step action

func (*Step) UnmarshalYAML added in v1.0.9 

func (s *Step) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML implements custom deserialization process to ensure that the step action and its cleanup action are decoded to the correct struct type

func (*Step) Validate 

func (s *Step) Validate(execCtx TTPExecutionContext) error

Validate checks that both the step action and cleanup action are valid

func (*Step) VerifyChecks added in v1.1.0 

func (s *Step) VerifyChecks() error

VerifyChecks runs all checks and returns an error if any of them fail

type StepResultsRecord 

type StepResultsRecord struct {
	ByName  map[string]*ExecutionResult
	ByIndex []*ExecutionResult
}

StepResultsRecord provides convenient accessors that be used to query the results of executing individual TTP steps

func NewStepResultsRecord 

func NewStepResultsRecord() *StepResultsRecord

NewStepResultsRecord generates an appropriately initialized StepResultsRecord

type SubTTPStep 

type SubTTPStep struct {
	TtpRef string            `yaml:"ttp"`
	Args   map[string]string `yaml:"args"`
	// contains filtered or unexported fields
}

SubTTPStep represents a step within a parent TTP that references a separate TTP file.

func NewSubTTPStep 

func NewSubTTPStep() *SubTTPStep

NewSubTTPStep creates a new SubTTPStep and returns a pointer to it.

func (*SubTTPStep) CanBeUsedInCompositeAction added in v1.1.0 

func (ad *SubTTPStep) CanBeUsedInCompositeAction() bool

CanBeUsedInCompositeAction provides a default implementation of the CanBeUsedInCompositeAction method from the Action interface. This saves us from having to declare this function for every steps If a specific action needs to be used in a composite action, it can override this step

func (*SubTTPStep) Execute 

func (s *SubTTPStep) Execute(_ TTPExecutionContext) (*ActResult, error)

Execute runs each step of the TTP file associated with the SubTTPStep and manages the outputs and cleanup steps.

func (*SubTTPStep) GetDefaultCleanupAction added in v1.0.9 

func (s *SubTTPStep) GetDefaultCleanupAction() Action

GetDefaultCleanupAction will instruct the calling code to cleanup all successful steps of this subTTP

func (*SubTTPStep) GetDescription added in v1.1.0 

func (ad *SubTTPStep) GetDescription() string

GetDescription returns the description field from the action

func (*SubTTPStep) IsNil 

func (s *SubTTPStep) IsNil() bool

IsNil checks if the step is nil or empty and returns a boolean value.

func (*SubTTPStep) Template added in v1.2.4 

func (s *SubTTPStep) Template(execCtx TTPExecutionContext) error

Template takes each applicable field in the step and replaces any template strings with their resolved values.

**Returns:**

error: error if template resolution fails, nil otherwise

func (*SubTTPStep) Validate 

func (s *SubTTPStep) Validate(execCtx TTPExecutionContext) error

Validate checks the validity of the SubTTPStep by ensuring the following conditions are met: The associated Act is valid. The TTP file associated with the SubTTPStep can be successfully unmarshalled. The TTP file path is not empty. The steps within the TTP file do not contain any nested SubTTPSteps. If any of these conditions are not met, an error is returned.

type TTP 

type TTP struct {
	PreambleFields `yaml:",inline"`
	Environment    map[string]string `yaml:"env,flow,omitempty"`
	Steps          []Step            `yaml:"steps,omitempty,flow"`
	// Omit WorkDir, but expose for testing.
	WorkDir string `yaml:"-"`
}

TTP represents the top-level structure for a TTP (Tactics, Techniques, and Procedures) object.

**Attributes:**

Environment: A map of environment variables to be set for the TTP. Steps: An slice of steps to be executed for the TTP. WorkDir: The working directory for the TTP.

func RenderTemplatedTTP 

func RenderTemplatedTTP(ttpStr string, rp RenderParameters) (*TTP, error)

RenderTemplatedTTP is a function that utilizes Golang's `text/template` for template substitution. It replaces template expressions like `{{ .Args.myarg }}` with corresponding values. This function must be invoked prior to YAML unmarshaling, as the template syntax `{{ ... }}` may result in invalid YAML under specific conditions.

**Parameters:**

ttpStr: A string containing the TTP template to be rendered. execCfg: A pointer to a TTPExecutionConfig that represents the execution configuration for the TTP.

**Returns:**

*TTP: A pointer to the TTP object created from the template. error: An error if the rendering or unmarshaling process fails.

func (*TTP) Execute added in v1.0.9 

func (t *TTP) Execute(execCtx TTPExecutionContext) error

Execute executes all of the steps in the given TTP, then runs cleanup if appropriate

func (*TTP) MarshalYAML 

func (t *TTP) MarshalYAML() (interface{}, error)

MarshalYAML is a custom marshalling implementation for the TTP structure. It encodes a TTP object into a formatted YAML string, handling the indentation and structure of the output YAML.

func (*TTP) RunCleanup added in v1.1.0 

func (t *TTP) RunCleanup(execCtx TTPExecutionContext) error

RunCleanup executes all required cleanup for steps in the given TTP.

func (*TTP) RunSteps 

func (t *TTP) RunSteps(execCtx TTPExecutionContext) error

RunSteps executes all of the steps in the given TTP.

func (*TTP) Validate added in v1.0.9 

func (t *TTP) Validate(execCtx TTPExecutionContext) error

Validate ensures that all components of the TTP are valid It checks key fields, then iterates through each step and validates them in turn

type TTPExecutionConfig 

type TTPExecutionConfig struct {
	DryRun              bool
	NoCleanup           bool
	CleanupDelaySeconds uint
	Repo                repos.Repo
	Stdout              io.Writer
	Stderr              io.Writer
}

TTPExecutionConfig - pass this into RunSteps to control TTP execution

type TTPExecutionContext 

type TTPExecutionContext struct {
	Cfg         TTPExecutionConfig
	Vars        *TTPExecutionVars
	StepResults *StepResultsRecord
	// contains filtered or unexported fields
}

TTPExecutionContext - holds config and context for the currently executing TTP

func NewTTPExecutionContext added in v1.1.0 

func NewTTPExecutionContext() TTPExecutionContext

NewTTPExecutionContext creates a new TTPExecutionContext with empty config and created channels

func (TTPExecutionContext) ExpandVariables 

func (c TTPExecutionContext) ExpandVariables(inStrs []string) ([]string, error)

ExpandVariables takes a string containing the following types of variables and expands all of them to their appropriate values:

* Step outputs: ($forge.steps.bar.outputs.baz)

**Parameters:**

inStrs: the list of strings that have variables expanded

**Returns:**

[]string: the corresponding strings with variables expanded error: an error if there is a problem

type TTPExecutionVars added in v1.2.2 

type TTPExecutionVars struct {
	WorkDir  string
	StepVars map[string]string
}

TTPExecutionVars - mutable store to carry variables between steps

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.