https://github.com/andinus/lynx

Lynx is a simple unveil & pledge wrapper
https://github.com/andinus/lynx

openbsd openbsd-pledge pledge unveil

Last synced: 12 months ago
JSON representation

Lynx is a simple unveil & pledge wrapper

• Host: GitHub
• URL: https://github.com/andinus/lynx
• Owner: andinus
• License: isc
• Created: 2020-04-06T07:08:37.000Z (almost 6 years ago)
• Default Branch: main
• Last Pushed: 2021-01-17T13:59:18.000Z (about 5 years ago)
• Last Synced: 2025-01-29T15:50:43.068Z (about 1 year ago)
• Topics: openbsd, openbsd-pledge, pledge, unveil
• Language: Go
• Homepage: https://andinus.nand.sh/lynx
• Size: 17.6 KB
• Stars: 1
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.org
  • License: LICENSE

Awesome Lists containing this project

README

          
#+SETUPFILE: ~/.emacs.d/org-templates/projects.org

#+EXPORT_FILE_NAME: index

#+OPTIONS: toc:2

#+TITLE: Lynx

Lynx is a simple /unveil/ & /pledge/ wrapper. It returns /nil/ on unsupported systems,

currently only /OpenBSD/ is supported.

| Project Home    | [[https://andinus.nand.sh/lynx][Lynx]]           |

| Source Code     | [[https://git.tilde.institute/andinus/lynx][Andinus / Lynx]] |

| GitHub (Mirror) | [[https://github.com/andinus/lynx][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.

#+BEGIN_SRC go

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)

	}

}

#+END_SRC

** 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".

#+BEGIN_SRC go

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)

	}

}

#+END_SRC

** UnveilBlock

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

You should use unix.UnveilBlock.

#+BEGIN_SRC go

package main

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

func main() {

	// Block further unveil calls.

	err = lynx.UnveilBlock()

	if err != nil {

		log.Fatal(err)

	}

}

#+END_SRC

** 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.

#+BEGIN_SRC go

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)

	}

}

#+END_SRC

** 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.

#+BEGIN_SRC go

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)

	}

}

#+END_SRC