command

README

Command source

This source provides the ability to run commands on systems as part of the operation of a secondary source. The items returned by this source are marked as hidden meaning they won't be saved in the database or shown in a GUI, they only exist top help inform the creation of other, higher level items.

Get

Running a Get request against this source will simplex execute the command in the query and return the item, for example the following request:

{
    "context": "some-server.company.com",
    "linkdepth": 0,
    "method": 0,
    "query": "hostname",
    "type": "command"
}

Would return an item with the following attributes:

{
    "exitCode": 0,
    "name": "hostname",
    "stderr": '',
    "stdout": "some-server"
}

Search

The Search method is used to run commands with more complex requirements. The query for the Search method should be an instance of the CommandParams struct as JSON e.g.

{
    // Command specifies the command to run, including all arguments
    "command": "cat /etc/hosts",

    // ExpectedExit is the expected exit code (usually 0)
    "expected_exit": 0,

    // Timeout before cancelling the command. This can be provided in any
    // format that can be parsed using `time.ParseDuration` such as "300ms",
    // or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m",
    // "h".
    "timeout": "10s",

    // Dir specifies the working directory of the command.
    "dir": "/tmp",

    // Env specifies environment variables that should be set when running the
    // command
    "env": {
        "ENV_VAR": "foo",
    },

    // STDIN specifies the binary data that should be piped to the command as
    // STDIN. This can be used for example to simulate user intaction for
    // programs that read from STDIN. This will be encoded using base64 to a
    // string in JSON
    "stdin": "eWVzCnllcwpubwo=",
}

Documentation

Index

• Constants
• type CommandParams
  • func (cp CommandParams) MarshalJSON() ([]byte, error)
  • func (cp *CommandParams) PowerShellWrap() (string, []string, error)
  • func (cp *CommandParams) Run(ctx context.Context) (*sdp.Item, error)
  • func (cp *CommandParams) ShellWrap() (string, []string, error)
  • func (cp *CommandParams) UnmarshalJSON(data []byte) error
• type CommandSource
  • func (s *CommandSource) Contexts() []string
  • func (s *CommandSource) Find(ctx context.Context, itemContext string) ([]*sdp.Item, error)
  • func (s *CommandSource) Get(ctx context.Context, itemContext string, query string) (*sdp.Item, error)
  • func (s *CommandSource) Hidden() bool
  • func (s *CommandSource) Name() string
  • func (s *CommandSource) Search(ctx context.Context, itemContext string, query string) ([]*sdp.Item, error)
  • func (s *CommandSource) Type() string
  • func (s *CommandSource) Weight() int
• type UserInfo

Constants

const DefaultTimeout = 10 * time.Second

Types

type CommandParams

type CommandParams struct {
	// Command specifies the command to run, including all arguments
	Command string `json:"command"`

	// ExpectedExit is the expected exit code (usually 0)
	ExpectedExit int `json:"expected_exit"`

	// Dir specifies the working directory of the command.
	Dir string `json:"dir"`

	// Env specifies environment variables that should be set when running the
	// command
	Env map[string]string `json:"env"`

	// STDIN specifies the binary data that should be piped to the command as
	// STDIN. This can be used for example to simulate user intaction for
	// programs that read from STDIN. This will be encoded using base64 to a
	// string in JSON
	STDIN []byte `json:"stdin"`
}

func (CommandParams) MarshalJSON

func (cp CommandParams) MarshalJSON() ([]byte, error)

MarshalJSON Converts the object to JSON

func (*CommandParams) PowerShellWrap

func (cp *CommandParams) PowerShellWrap() (string, []string, error)

PowerShellWrap Wraps a given command and args in the required arguments so that the command runs inside powershell

func (*CommandParams) Run

func (cp *CommandParams) Run(ctx context.Context) (*sdp.Item, error)

Run Runs the command and returns an item and error

func (*CommandParams) ShellWrap

func (cp *CommandParams) ShellWrap() (string, []string, error)

ShellWrap Wraps a given command and args in the required arguments so that the command runs inside a shell, the default being bash, but falling back to sh if bash is not available

func (*CommandParams) UnmarshalJSON

func (cp *CommandParams) UnmarshalJSON(data []byte) error

UnmarshalJSON Converts the object from JSON

type CommandSource

type CommandSource struct{}

CommandSource struct on which all methods are registered

func (*CommandSource) Contexts

func (s *CommandSource) Contexts() []string

List of contexts that this source is capable of find items for

func (*CommandSource) Find

func (s *CommandSource) Find(ctx context.Context, itemContext string) ([]*sdp.Item, error)

Find Gets information about all item that the source can possibly find. If nothing is found then just return an empty list (Required)

func (*CommandSource) Get

func (s *CommandSource) Get(ctx context.Context, itemContext string, query string) (*sdp.Item, error)

Get Runs a single command as specified in the query. This should include the full command to run, including arguments, as a string. This command will be run with default values for all other parametres. For more complex commands, use Search()

func (*CommandSource) Hidden

func (s *CommandSource) Hidden() bool

Hidden command items should be hidden as they are only used when needed, and should be covered by some higher layer of abstraction like a secondary source

func (*CommandSource) Name

func (s *CommandSource) Name() string

Name Returns the name of the backend package. This is used for debugging and logging (Required)

func (*CommandSource) Search

func (s *CommandSource) Search(ctx context.Context, itemContext string, query string) ([]*sdp.Item, error)

Search runs a command with a given set of parameteres. These paremeteres should be supplied as a single JSON string, in the format of a `CommandParams` struct e.g.

{
    "command": "cat /etc/hosts",
    "expected_exit": 0,
    "timeout": "5s",
    "dir": "/etc",
    "env": {
        "FOO": "BAR"
    }
}

func (*CommandSource) Type

func (s *CommandSource) Type() string

Type is the type of items that this returns (Required)

func (*CommandSource) Weight

func (s *CommandSource) Weight() int

Weighting of duplicate sources

type UserInfo

type UserInfo struct {
	// Username The user to run the command as
	Username string `json:"username"`
	// Password (optional) The password required for that user. On linux this is the
	// password that will be provided to sudo, in wondows this is the
	// password of the user themselves
	Password string `json:"password,omitempty"`
}