aisap

README

aisap

AppImage SAndboxing Project (pronounced /eɪsæp/): a tool to help sandbox AppImages through bwrap.

EARLY DEVELOPMENT! Many parts of this are subject to change and should be expected to until it reaches a more stable form.

What is it?

aisap intends to be a simple way to implement Android/Flatpak style sandboxing with AppImages. It has a profile system, but it intends to keep it as basic as possible, making it easier to understand what a program actually requires to run without dealing with the hassle of individually cherry-picking files.

It currently has a basic re-implementaion of the go-appimage API, so modifying existing Go programs to include sandboxing should be fairly painless

Using aisap:

1. aisap cli
2. aisap Go implementation
3. aisap Zig implementation (DOCS WIP) (IMPLEMENTATION NOT YET USABLE)

(there's also some very early C bindings, which will be implemented in Zig. I will begin working on the docs as soon as I feel the C API is sufficiently usable.)

The ultimate goal is to have as many AppImages in aisap's internal library as possible, while smaller, less known apps may request their own permssions per the developer. Running programs sandboxed should mostly be seamless and feel native with the system

For additional information on the permission system, see here

As it is currently, the main aisap implementation requires a squashfuse binary to function. I have attempted to create Go squashfuse bindings with essentially zero success, so it will likely remain that way for the forseeable future. Luckily, I have started working on a Zig implementation of aisap, and due to Zig's extremely easy C interop, I already have some pretty decent Zig squashfuse bindings to use. Don't expect the Zig implementation to be done super soon, but it should be completely self-contained once it is and I will probably replace the main CLI tool with it.

Documentation

Index

• Variables
• type AppImage
  • func NewAppImage(src string) (*AppImage, error)
  • func (ai *AppImage) Architectures() []string
  • func (ai *AppImage) DataDir() string
  • func (ai *AppImage) Destroy() error
  • func (ai *AppImage) ExtractFile(path string, dest string, resolveSymlinks bool) error
  • func (ai *AppImage) ExtractFileReader(path string) (io.ReadCloser, error)
  • func (ai *AppImage) Icon() (io.ReadCloser, string, error)
  • func (ai *AppImage) IsMounted() bool
  • func (ai *AppImage) Md5() string
  • func (ai *AppImage) Mount(dest ...string) error
  • func (ai *AppImage) MountDir() string
  • func (ai AppImage) Permissions() (*permissions.AppImagePerms, error)
  • func (ai *AppImage) RootDir() string
  • func (ai *AppImage) Sandbox(perms *permissions.AppImagePerms, args []string) error
  • func (ai *AppImage) SetDataDir(d string)
  • func (ai *AppImage) SetRootDir(d string)
  • func (ai *AppImage) SetTempDir(d string)
  • func (ai *AppImage) SetTrusted(trusted bool) error
  • func (ai *AppImage) TempDir() string
  • func (ai *AppImage) Thumbnail() (io.Reader, error)
  • func (ai *AppImage) Trusted() bool
  • func (ai *AppImage) Type() int
  • func (ai *AppImage) Unmount() error
  • func (ai AppImage) WrapArgs(perms *permissions.AppImagePerms, args []string) ([]string, error)

Variables

var (
	NilAppImage = errors.New("AppImage is nil")
	NoPath      = errors.New("AppImage contains no path")
	NotMounted  = errors.New("AppImage is not mounted")

	InvalidDesktopFile   = errors.New("desktop file wasn't parsed")
	NoDesktopFile        = errors.New("no (or >1) desktop entry was found inside bundle")
	NoIcon               = errors.New("bundle doesn't specify an icon")
	InvalidIconExtension = errors.New("no valid icon extensions (svg, png) found inside bundle")

	NoMountPoint = errors.New("mount point doesn't exist")
)

var (
	Version = "UNDEFINED"
)

Current version of aisap Defined in `zig/build.zig.zon` When using aisap as a library, `--ldflags="-X github.com/mgord9518/aisap.Version=[VERSION HERE]"` should be updated to the value contained in build.zig.zon

Types

type AppImage

type AppImage struct {
	Desktop *ini.File // INI of internal desktop entry
	Path    string    // Location of AppImage

	Name       string // AppImage name from the desktop entry
	Version    string
	UpdateInfo string
	Offset     int // Offset of SquashFS image

	// These will both be removed when the Zig-implemented C bindings
	// become usable
	CurrentArg   int      // Should only ever be used for the C bindings
	WrapArgsList []string // Should only ever be used for the C bindings
	// contains filtered or unexported fields
}

func NewAppImage

func NewAppImage(src string) (*AppImage, error)

Create a new AppImage object from a path

func (*AppImage) Architectures

func (ai *AppImage) Architectures() []string

func (*AppImage) DataDir

func (ai *AppImage) DataDir() string

func (*AppImage) Destroy

func (ai *AppImage) Destroy() error

Unmounts an AppImage

func (*AppImage) ExtractFile

func (ai *AppImage) ExtractFile(path string, dest string, resolveSymlinks bool) error

Extract a file from the AppImage's interal filesystem image

func (*AppImage) ExtractFileReader

func (ai *AppImage) ExtractFileReader(path string) (io.ReadCloser, error)

Like `ExtractFile()` but gives access to the reader instead of extracting

func (*AppImage) Icon

func (ai *AppImage) Icon() (io.ReadCloser, string, error)

Returns the icon reader of the AppImage, valid formats are SVG and PNG

func (*AppImage) IsMounted

func (ai *AppImage) IsMounted() bool

func (*AppImage) Md5

func (ai *AppImage) Md5() string

func (*AppImage) Mount

func (ai *AppImage) Mount(dest ...string) error

Takes an optional argument to mount at a specific location (failing if it doesn't exist or more than one arg given. If none given, automatically create a temporary directory and mount to it

func (*AppImage) MountDir

func (ai *AppImage) MountDir() string

func (AppImage) Permissions

func (ai AppImage) Permissions() (*permissions.AppImagePerms, error)

Retrieve permissions from the AppImage in the following order:

1: User-configured settings in ~/.local/share/aisap/profiles/[ai.Name]
2: aisap internal permissions library
3: Permissions defined in the AppImage's desktop file

func (*AppImage) RootDir

func (ai *AppImage) RootDir() string

func (*AppImage) Sandbox

func (ai *AppImage) Sandbox(perms *permissions.AppImagePerms, args []string) error

Executes AppImage through bwrap and creates a portable home if one doesn't already exist Returns error if AppImagePerms.Level < 1

func (*AppImage) SetDataDir

func (ai *AppImage) SetDataDir(d string)

Set the directory for the sandboxed AppImage's `HOME`

func (*AppImage) SetRootDir

func (ai *AppImage) SetRootDir(d string)

Set the directory the sandbox pulls system files from

func (*AppImage) SetTempDir

func (ai *AppImage) SetTempDir(d string)

Set the directory for the sandboxed AppImage's `TMPDIR`

func (*AppImage) SetTrusted

func (ai *AppImage) SetTrusted(trusted bool) error

func (*AppImage) TempDir

func (ai *AppImage) TempDir() string

func (*AppImage) Thumbnail

func (ai *AppImage) Thumbnail() (io.Reader, error)

Return a reader for the `.DirIcon` file of the AppImage

func (*AppImage) Trusted

func (ai *AppImage) Trusted() bool

Returns `true` if the AppImage in question is both executable and has its profile copied to the aisap config dir. This is to ensure the permissions can't change under the user's feet through an update to the AppImage

func (*AppImage) Type

func (ai *AppImage) Type() int

Return type of AppImage

func (*AppImage) Unmount

func (ai *AppImage) Unmount() error

Deprecated: *AppImage.Destroy() should be used instead

func (AppImage) WrapArgs

func (ai AppImage) WrapArgs(perms *permissions.AppImagePerms, args []string) ([]string, error)

Returns the bwrap arguments to sandbox the AppImage