README.org

Lynx

Lynx is a simple unveil & pledge wrapper. It returns nil on unsupported systems, currently only OpenBSD is supported.

Project Home	Lynx
Source Code	Andinus / Lynx
GitHub (Mirror)	Lynx - GitHub

Why use lynx?

• UnveilPaths & UnveilCommands: unix package provides simple Unveil syscalls so this is useful because you don’t have to write these functions yourself manually in every project.
• lynx manages build flags for you, which means that lynx will return nil on unsupported systems whereas you have handle that yourself in unix package.

Note: Unveil, UnveilPaths & UnveilCommands ignore some errors, look at examples before using them.

Examples

UnveilPaths / UnveilPathsStrict

UnveilPaths takes a map of path, permission & unveils them one by one, it will return an error if unveil fails at any step. “no such file or directory” error is ignored, if you want to get that error too then use UnveilPathsStrict.

package main

import "git.tilde.institute/andinus/lynx"

func main() {
	paths := make(map[string]string)

	paths["/home"] = "r"
	paths["/dev/null"] = "rw"
	paths["/etc/examples"] = "rwc"
	paths["/root"] = "rwcx"

	err = lynx.UnveilPaths(paths)
	if err != nil {
		log.Fatal(err)
	}

	// This will return an error if the path doesn't exist.
	err = lynx.UnveilPathsStrict(paths)
	if err != nil {
		log.Fatal(err)
	}
}

UnveilCommands

UnveilCommands takes a slice of commands & unveils them one by one, it will return an error if unveil fails at any step. “no such file or directory” error is ignored because binaries are not placed in every PATH.

Default permission is “rx”.

package main

import "git.tilde.institute/andinus/lynx"

func main() {
	commands := []string{"cd", "ls", "rm"}

	err = lynx.UnveilCommands(commands)
	if err != nil {
		log.Fatal(err)
	}
}

UnveilBlock

UnveilBlock is just a wrapper around unix.UnveilBlock, it does nothing extra. You should use unix.UnveilBlock.

package main

import "git.tilde.institute/andinus/lynx"

func main() {
	// Block further unveil calls.
	err = lynx.UnveilBlock()
	if err != nil {
		log.Fatal(err)
	}
}

Unveil / UnveilStrict

Unveil takes a path, permission & unveils it, it will return an error if unveil fails at any step. “no such file or directory” error is ignored, if you want to get that error too then use UnveilStrict.

package main

import "git.tilde.institute/andinus/lynx"

func main() {
	path := "/dev/null"
	flags := "rw"

	err = lynx.Unveil(path, flags)
	if err != nil {
		log.Fatal(err)
	}

	// This will return an error if the path doesn't exist.
	err = lynx.UnveilStrict(path, flags)
	if err != nil {
		log.Fatal(err)
	}
}

Pledge / PledgePromises / PledgeExecpromises

These are simple wrappers to unix package functions. They add nothing extra, you could simply change lynx.Pledge to unix.Pledge & it would just work.

package main

import "git.tilde.institute/andinus/lynx"

func main() {
	promises := "stdio unveil"
	execpromises := "stdio"

	err = lynx.Pledge(promises, execpromises)
	if err != nil {
		log.Fatal(err)
	}

	// Drop promises.
	promises = "stdio"
	err = lynx.PledgePromises(promises)
	if err != nil {
		log.Fatal(err)
	}

	// Drop execpromises.
	execpromises = ""
	err = lynx.PledgeExecpromises(execpromises)
	if err != nil {
		log.Fatal(err)
	}
}