embedexe

README

embedexe

Run a program stored in a byte array such as an executable or a directory of executables embedded in a Go binary.

LIMITATIONS

• the executable must either be statically linked or the linked libraries available on the filesystem

• only works on Linux (but not on ChromeOS/crostini where the W^X policies disable executing memfds)

• an embedded executable cannot run another executable embedded in the same binary

• an embedded executable cannot use a library embedded in the same binary

EXAMPLES

• embedexe: Using a file descriptor path

• embedexe/fdexec: Using a file descriptor

• embedexe/exec: Using a byte array

• fsexe: embed a directory of executables in a Go binary and run from memory

Run an embedded executable

// Echotest forks and runs an embedded echo(1).
//
//	cp /bin/echo .
//	go build
//	./echotest hello world
package main

import (
	_ "embed"
	"log"
	"os"

	"codeberg.org/msantos/embedexe/exec"
)

//go:embed echo
var echo []byte

func main() {
	cmd := exec.Command(echo, os.Args[1:]...)

	cmd.Stdout = os.Stdout
	cmd.Stderr = os.Stderr

	if err := cmd.Run(); err != nil {
		log.Fatalln("run:", cmd, err)
	}
}

Documentation

Overview

Package embedexe executes a program stored in a byte array such as an executable or a directory of executables embedded in a Go binary.

Index

• type FD
  • func FromInt(fd int) *FD
  • func Open(exe []byte, arg0 string) (*FD, error)
  • func (fd *FD) Close() error
  • func (fd *FD) CloseExec() bool
  • func (fd *FD) Exec(argv, env []string) error
  • func (fd *FD) FD() uintptr
  • func (fd *FD) Path() string
  • func (fd *FD) SetCloseExec(b bool) error

Examples

• FD.Path
• FD.Path (Sh)
• Open

Types

type FD

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

func FromInt

func FromInt(fd int) *FD

FromInt converts a raw file descriptor into an FD.

func Open

func Open(exe []byte, arg0 string) (*FD, error)

Open returns a file descriptor to an executable stored in memory.

Example

package main

import (
	"fmt"
	"os"

	"codeberg.org/msantos/embedexe"
)

func main() {
	b := []byte("#!/bin/sh\necho $@")

	fd, err := embedexe.Open(b, "example")
	if err != nil {
		fmt.Println(err)
		return
	}
	defer fd.Close()

	if err := fd.Exec([]string{"example", "test"}, os.Environ()); err != nil {
		fmt.Println(err)
		return
	}
}

func (*FD) Close

func (fd *FD) Close() error

Close closes the executable file descriptor.

func (*FD) CloseExec

func (fd *FD) CloseExec() bool

CloseExec checks if the O_CLOEXEC flag is set on the file descriptor.

func (*FD) Exec

func (fd *FD) Exec(argv, env []string) error

Exec runs the executable referenced by the file descriptor, replacing the current running process image.

func (*FD) FD

func (fd *FD) FD() uintptr

FD returns the file descriptor.

func (*FD) Path

func (fd *FD) Path() string

Path returns the path to the executable file descriptor. Running the executable using the file descriptor path directly is an alternative to running by file descriptor in Exec.

Example

package main

import (
	"fmt"
	"os"
	"os/exec"

	"codeberg.org/msantos/embedexe"
)

func main() {
	b, err := os.ReadFile("/bin/echo")
	if err != nil {
		fmt.Println(err)
		return
	}

	fd, err := embedexe.Open(b, "echo")
	if err != nil {
		fmt.Println(err)
		return
	}

	cmd := exec.Command(fd.Path(), "-n", "test", "abc")
	cmd.Stdout = os.Stdout
	cmd.Stderr = os.Stderr

	if err := cmd.Run(); err != nil {
		fmt.Println(err)
		return
	}

}

Output:

test abc

Example (Sh)

An example of running a script contained in a memfd without execute permissions.

package main

import (
	"fmt"
	"os"
	"os/exec"

	"codeberg.org/msantos/embedexe"
)

func main() {
	b := []byte("#!/bin/sh\necho $@")

	fd, err := embedexe.Open(b, "sh")
	if err != nil {
		fmt.Println(err)
		return
	}

	cmd := exec.Command("/bin/sh", fd.Path(), "-n", "test", "abc")
	cmd.Stdout = os.Stdout
	cmd.Stderr = os.Stderr

	if err := cmd.Run(); err != nil {
		fmt.Println(err)
		return
	}

}

Output:

test abc

func (*FD) SetCloseExec

func (fd *FD) SetCloseExec(b bool) error

SetCloseExec enables or disables the O_CLOEXEC flag on the file descriptor.