github.com/iDigitalFlame/xmt@v0.5.4/c2/task/engines.go (about)

     1  //go:build scripts && go1.18
     2  // +build scripts,go1.18
     3  
     4  // Copyright (C) 2020 - 2023 iDigitalFlame
     5  //
     6  // This program is free software: you can redistribute it and/or modify
     7  // it under the terms of the GNU General Public License as published by
     8  // the Free Software Foundation, either version 3 of the License, or
     9  // any later version.
    10  //
    11  // This program is distributed in the hope that it will be useful,
    12  // but WITHOUT ANY WARRANTY; without even the implied warranty of
    13  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    14  // GNU General Public License for more details.
    15  //
    16  // You should have received a copy of the GNU General Public License
    17  // along with this program.  If not, see <https://www.gnu.org/licenses/>.
    18  //
    19  
    20  package task
    21  
    22  import (
    23  	"context"
    24  
    25  	"github.com/iDigitalFlame/xmt/data"
    26  	"github.com/iDigitalFlame/xmt/util/xerr"
    27  )
    28  
    29  // Engine is an interface that allows for extending XMT with non-compiled code
    30  // for easy deploy-ability and flexibility.
    31  //
    32  // Each Script interface contains a single function that will take a Context,
    33  // an environment block and the script code string.
    34  //
    35  // The result of this function will be the output of the script and any errors
    36  // that may occur.
    37  //
    38  // By default, the 'ID', 'OS', 'PID' 'PPID', 'OSVER' and 'HOSTNAME' variables
    39  // are built-in to assist with code runtime.
    40  type Engine interface {
    41  	Invoke(context.Context, map[string]any, string) (string, error)
    42  }
    43  
    44  // RegisterEngine is a function that can be used to register a Scripting engine
    45  // into the XMT client tasking runtime.
    46  //
    47  // Script engines can increase the footprint of the compiled binary, so engines
    48  // must be registered manually.
    49  //
    50  // See the 'cmd/script' package for scripting engines.
    51  //
    52  // C2 Details:
    53  //
    54  //	ID: <Supplied>
    55  //
    56  //	Input:
    57  //	    string (script)
    58  //	Output:
    59  //	    string (output)
    60  func RegisterEngine(i uint8, s Engine) error {
    61  	if i < 21 {
    62  		return xerr.Sub("mapping ID is invalid", 0x63)
    63  	}
    64  	if Mappings[i] != nil {
    65  		return xerr.Sub("mapping ID is already exists", 0x64)
    66  	}
    67  	Mappings[i] = func(x context.Context, r data.Reader, w data.Writer) error {
    68  		c, err := r.StringVal()
    69  		if err != nil {
    70  			return err
    71  		}
    72  		o, err := s.Invoke(x, createEnvironment(), c)
    73  		if err != nil {
    74  			return err
    75  		}
    76  		w.WriteString(o)
    77  		return nil
    78  	}
    79  	return nil
    80  }