hakurei: move container helpers toplevel

Signed-off-by: Ophestra <cat@gensokyo.uk>

6 files changed, 921 insertions, 0 deletions

diff --git a/vfs/mangle.go b/vfs/mangle.go
new file mode 100644
index 00000000..83aba589
--- /dev/null
+++ b/vfs/mangle.go
@@ -0,0 +1,30 @@
+package vfs
+
+import "strings"
+
+func Unmangle(s string) string {
+	if !strings.ContainsRune(s, '\\') {
+		return s
+	}
+
+	v := make([]byte, len(s))
+	var (
+		j int
+		c byte
+	)
+	for i := 0; i < len(s); i++ {
+		c = s[i]
+		if c == '\\' && len(s) > i+3 &&
+			(s[i+1] == '0' || s[i+1] == '1') &&
+			(s[i+2] >= '0' && s[i+2] <= '7') &&
+			(s[i+3] >= '0' && s[i+3] <= '7') {
+			c = ((s[i+1] - '0') << 6) |
+				((s[i+2] - '0') << 3) |
+				(s[i+3] - '0')
+			i += 3
+		}
+		v[j] = c
+		j++
+	}
+	return string(v[:j])
+}
diff --git a/vfs/mangle_test.go b/vfs/mangle_test.go
new file mode 100644
index 00000000..54af8fbf
--- /dev/null
+++ b/vfs/mangle_test.go
@@ -0,0 +1,27 @@
+package vfs_test
+
+import (
+	"testing"
+
+	"git.gensokyo.uk/security/hakurei/vfs"
+)
+
+func TestUnmangle(t *testing.T) {
+	testCases := []struct {
+		want   string
+		sample string
+	}{
+		{`\, `, `\134\054\040`},
+		{`(10) source -- maybe empty string`, `(10)\040source\040--\040maybe empty string`},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.want, func(t *testing.T) {
+			got := vfs.Unmangle(tc.sample)
+			if got != tc.want {
+				t.Errorf("Unmangle: %q, want %q",
+					got, tc.want)
+			}
+		})
+	}
+}
diff --git a/vfs/mountinfo.go b/vfs/mountinfo.go
new file mode 100644
index 00000000..bcb3063f
--- /dev/null
+++ b/vfs/mountinfo.go
@@ -0,0 +1,260 @@
+// Package vfs provides bindings and iterators over proc_pid_mountinfo(5).
+package vfs
+
+import (
+	"bufio"
+	"errors"
+	"fmt"
+	"io"
+	"iter"
+	"slices"
+	"strconv"
+	"strings"
+	"syscall"
+)
+
+const (
+	MS_NOSYMFOLLOW = 0x100
+)
+
+var (
+	ErrMountInfoFields = errors.New("unexpected field count")
+	ErrMountInfoEmpty  = errors.New("unexpected empty field")
+	ErrMountInfoDevno  = errors.New("bad maj:min field")
+	ErrMountInfoSep    = errors.New("bad optional fields separator")
+)
+
+type (
+	// A MountInfoDecoder reads and decodes proc_pid_mountinfo(5) entries from an input stream.
+	MountInfoDecoder struct {
+		s *bufio.Scanner
+		m *MountInfo
+
+		current  *MountInfo
+		parseErr error
+		complete bool
+	}
+
+	// MountInfo represents the contents of a proc_pid_mountinfo(5) document.
+	MountInfo struct {
+		Next *MountInfo
+		MountInfoEntry
+	}
+
+	// MountInfoEntry represents a proc_pid_mountinfo(5) entry.
+	MountInfoEntry struct {
+		// mount ID: a unique ID for the mount (may be reused after umount(2)).
+		ID int `json:"id"`
+		// parent ID: the ID of the parent mount (or of self for the root of this mount namespace's mount tree).
+		Parent int `json:"parent"`
+		// major:minor: the value of st_dev for files on this filesystem (see stat(2)).
+		Devno DevT `json:"devno"`
+		// root: the pathname of the directory in the filesystem which forms the root of this mount.
+		Root string `json:"root"`
+		// mount point: the pathname of the mount point relative to the process's root directory.
+		Target string `json:"target"`
+		// mount options: per-mount options (see mount(2)).
+		VfsOptstr string `json:"vfs_optstr"`
+		// optional fields: zero or more fields of the form "tag[:value]"; see below.
+		// separator: the end of the optional fields is marked by a single hyphen.
+		OptFields []string `json:"opt_fields"`
+		// filesystem type: the filesystem type in the form "type[.subtype]".
+		FsType string `json:"fstype"`
+		// mount source: filesystem-specific information or "none".
+		Source string `json:"source"`
+		// super options: per-superblock options (see mount(2)).
+		FsOptstr string `json:"fs_optstr"`
+	}
+
+	DevT [2]int
+)
+
+// Flags interprets VfsOptstr and returns the resulting flags and unmatched options.
+func (e *MountInfoEntry) Flags() (flags uintptr, unmatched []string) {
+	for _, s := range strings.Split(e.VfsOptstr, ",") {
+		switch s {
+		case "rw":
+		case "ro":
+			flags |= syscall.MS_RDONLY
+		case "nosuid":
+			flags |= syscall.MS_NOSUID
+		case "nodev":
+			flags |= syscall.MS_NODEV
+		case "noexec":
+			flags |= syscall.MS_NOEXEC
+		case "nosymfollow":
+			flags |= MS_NOSYMFOLLOW
+		case "noatime":
+			flags |= syscall.MS_NOATIME
+		case "nodiratime":
+			flags |= syscall.MS_NODIRATIME
+		case "relatime":
+			flags |= syscall.MS_RELATIME
+		default:
+			unmatched = append(unmatched, s)
+		}
+	}
+	return
+}
+
+// NewMountInfoDecoder returns a new decoder that reads from r.
+//
+// The decoder introduces its own buffering and may read data from r beyond the mountinfo entries requested.
+func NewMountInfoDecoder(r io.Reader) *MountInfoDecoder {
+	return &MountInfoDecoder{s: bufio.NewScanner(r)}
+}
+
+func (d *MountInfoDecoder) Decode(v **MountInfo) (err error) {
+	for d.scan() {
+	}
+	err = d.Err()
+	if err == nil {
+		*v = d.m
+	}
+	return
+}
+
+// Entries returns an iterator over mountinfo entries.
+func (d *MountInfoDecoder) Entries() iter.Seq[*MountInfoEntry] {
+	return func(yield func(*MountInfoEntry) bool) {
+		for cur := d.m; cur != nil; cur = cur.Next {
+			if !yield(&cur.MountInfoEntry) {
+				return
+			}
+		}
+		for d.scan() {
+			if !yield(&d.current.MountInfoEntry) {
+				return
+			}
+		}
+	}
+}
+
+func (d *MountInfoDecoder) Err() error {
+	if err := d.s.Err(); err != nil {
+		return err
+	}
+	return d.parseErr
+}
+
+func (d *MountInfoDecoder) scan() bool {
+	if d.complete {
+		return false
+	}
+	if !d.s.Scan() {
+		d.complete = true
+		return false
+	}
+
+	m := new(MountInfo)
+	if err := parseMountInfoLine(d.s.Text(), &m.MountInfoEntry); err != nil {
+		d.parseErr = err
+		d.complete = true
+		return false
+	}
+
+	if d.current == nil {
+		d.m = m
+		d.current = d.m
+	} else {
+		d.current.Next = m
+		d.current = d.current.Next
+	}
+	return true
+}
+
+func parseMountInfoLine(s string, ent *MountInfoEntry) error {
+	// prevent proceeding with misaligned fields due to optional fields
+	f := strings.Split(s, " ")
+	if len(f) < 10 {
+		return ErrMountInfoFields
+	}
+
+	// 36 35 98:0 /mnt1 /mnt2 rw,noatime master:1 - ext3 /dev/root rw,errors=continue
+	// (1)(2)(3)   (4)   (5)      (6)      (7)   (8) (9)   (10)         (11)
+
+	// (1) id
+	if id, err := strconv.Atoi(f[0]); err != nil { // 0
+		return err
+	} else {
+		ent.ID = id
+	}
+
+	// (2) parent
+	if parent, err := strconv.Atoi(f[1]); err != nil { // 1
+		return err
+	} else {
+		ent.Parent = parent
+	}
+
+	// (3) maj:min
+	if n, err := fmt.Sscanf(f[2], "%d:%d", &ent.Devno[0], &ent.Devno[1]); err != nil {
+		return err
+	} else if n != 2 {
+		// unreachable
+		return ErrMountInfoDevno
+	}
+
+	// (4) mountroot
+	ent.Root = Unmangle(f[3])
+	if ent.Root == "" {
+		return ErrMountInfoEmpty
+	}
+
+	// (5) target
+	ent.Target = Unmangle(f[4])
+	if ent.Target == "" {
+		return ErrMountInfoEmpty
+	}
+
+	// (6) vfs options (fs-independent)
+	ent.VfsOptstr = Unmangle(f[5])
+	if ent.VfsOptstr == "" {
+		return ErrMountInfoEmpty
+	}
+
+	// (7) optional fields, terminated by " - "
+	i := len(f) - 4
+	ent.OptFields = f[6:i]
+
+	// (8) optional fields end marker
+	if f[i] != "-" {
+		return ErrMountInfoSep
+	}
+	i++
+
+	// (9) FS type
+	ent.FsType = Unmangle(f[i])
+	if ent.FsType == "" {
+		return ErrMountInfoEmpty
+	}
+	i++
+
+	// (10) source -- maybe empty string
+	ent.Source = Unmangle(f[i])
+	i++
+
+	// (11) fs options (fs specific)
+	ent.FsOptstr = Unmangle(f[i])
+
+	return nil
+}
+
+func (e *MountInfoEntry) EqualWithIgnore(want *MountInfoEntry, ignore string) bool {
+	return (e.ID == want.ID || want.ID == -1) &&
+		(e.Parent == want.Parent || want.Parent == -1) &&
+		(e.Devno == want.Devno || (want.Devno[0] == -1 && want.Devno[1] == -1)) &&
+		(e.Root == want.Root || want.Root == ignore) &&
+		(e.Target == want.Target || want.Target == ignore) &&
+		(e.VfsOptstr == want.VfsOptstr || want.VfsOptstr == ignore) &&
+		(slices.Equal(e.OptFields, want.OptFields) || (len(want.OptFields) == 1 && want.OptFields[0] == ignore)) &&
+		(e.FsType == want.FsType || want.FsType == ignore) &&
+		(e.Source == want.Source || want.Source == ignore) &&
+		(e.FsOptstr == want.FsOptstr || want.FsOptstr == ignore)
+}
+
+func (e *MountInfoEntry) String() string {
+	return fmt.Sprintf("%d %d %d:%d %s %s %s %s %s %s %s",
+		e.ID, e.Parent, e.Devno[0], e.Devno[1], e.Root, e.Target, e.VfsOptstr,
+		strings.Join(append(e.OptFields, "-"), " "), e.FsType, e.Source, e.FsOptstr)
+}
diff --git a/vfs/mountinfo_test.go b/vfs/mountinfo_test.go
new file mode 100644
index 00000000..255f1c9c
--- /dev/null
+++ b/vfs/mountinfo_test.go
@@ -0,0 +1,404 @@
+package vfs_test
+
+import (
+	"encoding/json"
+	"errors"
+	"iter"
+	"path"
+	"reflect"
+	"slices"
+	"strconv"
+	"strings"
+	"syscall"
+	"testing"
+
+	"git.gensokyo.uk/security/hakurei/vfs"
+)
+
+func TestMountInfo(t *testing.T) {
+	testCases := []mountInfoTest{
+		{"count", sampleMountinfoBase + `
+21 20 0:53/ /mnt/test rw,relatime - tmpfs  rw
+21 16 0:17 / /sys/fs/cgroup rw,nosuid,nodev,noexec,relatime - tmpfs tmpfs rw,mode=755`,
+			vfs.ErrMountInfoFields, "", nil, nil, nil},
+
+		{"sep", sampleMountinfoBase + `
+21 20 0:53 / /mnt/test rw,relatime shared:212 _ tmpfs  rw
+21 16 0:17 / /sys/fs/cgroup rw,nosuid,nodev,noexec,relatime - tmpfs tmpfs rw,mode=755`,
+			vfs.ErrMountInfoSep, "", nil, nil, nil},
+
+		{"id", sampleMountinfoBase + `
+id 20 0:53 / /mnt/test rw,relatime shared:212 - tmpfs  rw
+21 16 0:17 / /sys/fs/cgroup rw,nosuid,nodev,noexec,relatime - tmpfs tmpfs rw,mode=755`,
+			strconv.ErrSyntax, "", nil, nil, nil},
+
+		{"parent", sampleMountinfoBase + `
+21 parent 0:53 / /mnt/test rw,relatime shared:212 - tmpfs  rw
+21 16 0:17 / /sys/fs/cgroup rw,nosuid,nodev,noexec,relatime - tmpfs tmpfs rw,mode=755`,
+			strconv.ErrSyntax, "", nil, nil, nil},
+
+		{"devno", sampleMountinfoBase + `
+21 20 053 / /mnt/test rw,relatime shared:212 - tmpfs  rw
+21 16 0:17 / /sys/fs/cgroup rw,nosuid,nodev,noexec,relatime - tmpfs tmpfs rw,mode=755`,
+			nil, "unexpected EOF", nil, nil, nil},
+
+		{"maj", sampleMountinfoBase + `
+21 20 maj:53 / /mnt/test rw,relatime shared:212 - tmpfs  rw
+21 16 0:17 / /sys/fs/cgroup rw,nosuid,nodev,noexec,relatime - tmpfs tmpfs rw,mode=755`,
+			nil, "expected integer", nil, nil, nil},
+
+		{"min", sampleMountinfoBase + `
+21 20 0:min / /mnt/test rw,relatime shared:212 - tmpfs  rw
+21 16 0:17 / /sys/fs/cgroup rw,nosuid,nodev,noexec,relatime - tmpfs tmpfs rw,mode=755`,
+			nil, "expected integer", nil, nil, nil},
+
+		{"mountroot", sampleMountinfoBase + `
+21 20 0:53  /mnt/test rw,relatime - tmpfs  rw
+21 16 0:17 / /sys/fs/cgroup rw,nosuid,nodev,noexec,relatime - tmpfs tmpfs rw,mode=755`,
+			vfs.ErrMountInfoEmpty, "", nil, nil, nil},
+
+		{"target", sampleMountinfoBase + `
+21 20 0:53 /  rw,relatime - tmpfs  rw
+21 16 0:17 / /sys/fs/cgroup rw,nosuid,nodev,noexec,relatime - tmpfs tmpfs rw,mode=755`,
+			vfs.ErrMountInfoEmpty, "", nil, nil, nil},
+
+		{"vfs options", sampleMountinfoBase + `
+21 20 0:53 / /mnt/test  - tmpfs  rw
+21 16 0:17 / /sys/fs/cgroup rw,nosuid,nodev,noexec,relatime - tmpfs tmpfs rw,mode=755`,
+			vfs.ErrMountInfoEmpty, "", nil, nil, nil},
+
+		{"FS type", sampleMountinfoBase + `
+21 20 0:53 / /mnt/test rw,relatime -   rw
+21 16 0:17 / /sys/fs/cgroup rw,nosuid,nodev,noexec,relatime - tmpfs tmpfs rw,mode=755`,
+			vfs.ErrMountInfoEmpty, "", nil, nil, nil},
+
+		{"base", sampleMountinfoBase, nil, "", []*wantMountInfo{
+			m(15, 20, 0, 3, "/", "/proc", "rw,relatime", o(), "proc", "/proc", "rw", syscall.MS_RELATIME, nil),
+			m(16, 20, 0, 15, "/", "/sys", "rw,relatime", o(), "sysfs", "/sys", "rw", syscall.MS_RELATIME, nil),
+			m(17, 20, 0, 5, "/", "/dev", "rw,relatime", o(), "devtmpfs", "udev", "rw,size=1983516k,nr_inodes=495879,mode=755", syscall.MS_RELATIME, nil),
+			m(18, 17, 0, 10, "/", "/dev/pts", "rw,relatime", o(), "devpts", "devpts", "rw,gid=5,mode=620,ptmxmode=000", syscall.MS_RELATIME, nil),
+			m(19, 17, 0, 16, "/", "/dev/shm", "rw,relatime", o(), "tmpfs", "tmpfs", "rw", syscall.MS_RELATIME, nil),
+			m(20, 1, 8, 4, "/", "/", "ro,noatime,nodiratime,meow", o(), "ext3", "/dev/sda4", "rw,errors=continue,user_xattr,acl,barrier=0,data=ordered", syscall.MS_RDONLY|syscall.MS_NOATIME|syscall.MS_NODIRATIME, []string{"meow"}),
+		},
+			mn(20, 1, 8, 4, "/", "/", "ro,noatime,nodiratime,meow", o(), "ext3", "/dev/sda4", "rw,errors=continue,user_xattr,acl,barrier=0,data=ordered", false,
+				mn(15, 20, 0, 3, "/", "/proc", "rw,relatime", o(), "proc", "/proc", "rw", false, nil,
+					mn(16, 20, 0, 15, "/", "/sys", "rw,relatime", o(), "sysfs", "/sys", "rw", false, nil,
+						mn(17, 20, 0, 5, "/", "/dev", "rw,relatime", o(), "devtmpfs", "udev", "rw,size=1983516k,nr_inodes=495879,mode=755", false,
+							mn(18, 17, 0, 10, "/", "/dev/pts", "rw,relatime", o(), "devpts", "devpts", "rw,gid=5,mode=620,ptmxmode=000", false, nil,
+								mn(19, 17, 0, 16, "/", "/dev/shm", "rw,relatime", o(), "tmpfs", "tmpfs", "rw", false, nil, nil)),
+							nil))), nil), func(n *vfs.MountInfoNode) []*vfs.MountInfoNode {
+				return []*vfs.MountInfoNode{
+					n,
+					n.FirstChild,
+					n.FirstChild.NextSibling,
+					n.FirstChild.NextSibling.NextSibling,
+					n.FirstChild.NextSibling.NextSibling.FirstChild,
+					n.FirstChild.NextSibling.NextSibling.FirstChild.NextSibling,
+				}
+			}},
+
+		{"sample", sampleMountinfo, nil, "", []*wantMountInfo{
+			m(15, 20, 0, 3, "/", "/proc", "rw,relatime", o(), "proc", "/proc", "rw", syscall.MS_RELATIME, nil),
+			m(16, 20, 0, 15, "/", "/sys", "rw,relatime", o(), "sysfs", "/sys", "rw", syscall.MS_RELATIME, nil),
+			m(17, 20, 0, 5, "/", "/dev", "rw,relatime", o(), "devtmpfs", "udev", "rw,size=1983516k,nr_inodes=495879,mode=755", syscall.MS_RELATIME, nil),
+			m(18, 17, 0, 10, "/", "/dev/pts", "rw,relatime", o(), "devpts", "devpts", "rw,gid=5,mode=620,ptmxmode=000", syscall.MS_RELATIME, nil),
+			m(19, 17, 0, 16, "/", "/dev/shm", "rw,relatime", o(), "tmpfs", "tmpfs", "rw", syscall.MS_RELATIME, nil),
+			m(20, 1, 8, 4, "/", "/", "rw,noatime", o(), "ext3", "/dev/sda4", "rw,errors=continue,user_xattr,acl,barrier=0,data=ordered", syscall.MS_NOATIME, nil),
+			m(21, 16, 0, 17, "/", "/sys/fs/cgroup", "rw,nosuid,nodev,noexec,relatime", o(), "tmpfs", "tmpfs", "rw,mode=755", syscall.MS_NOSUID|syscall.MS_NODEV|syscall.MS_NOEXEC|syscall.MS_RELATIME, nil),
+			m(22, 21, 0, 18, "/", "/sys/fs/cgroup/systemd", "rw,nosuid,nodev,noexec,relatime", o(), "cgroup", "cgroup", "rw,release_agent=/lib/systemd/systemd-cgroups-agent,name=systemd", syscall.MS_NOSUID|syscall.MS_NODEV|syscall.MS_NOEXEC|syscall.MS_RELATIME, nil),
+			m(23, 21, 0, 19, "/", "/sys/fs/cgroup/cpuset", "rw,nosuid,nodev,noexec,relatime", o(), "cgroup", "cgroup", "rw,cpuset", syscall.MS_NOSUID|syscall.MS_NODEV|syscall.MS_NOEXEC|syscall.MS_RELATIME, nil),
+			m(24, 21, 0, 20, "/", "/sys/fs/cgroup/ns", "rw,nosuid,nodev,noexec,relatime", o(), "cgroup", "cgroup", "rw,ns", syscall.MS_NOSUID|syscall.MS_NODEV|syscall.MS_NOEXEC|syscall.MS_RELATIME, nil),
+			m(25, 21, 0, 21, "/", "/sys/fs/cgroup/cpu", "rw,nosuid,nodev,noexec,relatime", o(), "cgroup", "cgroup", "rw,cpu", syscall.MS_NOSUID|syscall.MS_NODEV|syscall.MS_NOEXEC|syscall.MS_RELATIME, nil),
+			m(26, 21, 0, 22, "/", "/sys/fs/cgroup/cpuacct", "rw,nosuid,nodev,noexec,relatime", o(), "cgroup", "cgroup", "rw,cpuacct", syscall.MS_NOSUID|syscall.MS_NODEV|syscall.MS_NOEXEC|syscall.MS_RELATIME, nil),
+			m(27, 21, 0, 23, "/", "/sys/fs/cgroup/memory", "rw,nosuid,nodev,noexec,relatime", o(), "cgroup", "cgroup", "rw,memory", syscall.MS_NOSUID|syscall.MS_NODEV|syscall.MS_NOEXEC|syscall.MS_RELATIME, nil),
+			m(28, 21, 0, 24, "/", "/sys/fs/cgroup/devices", "rw,nosuid,nodev,noexec,relatime", o(), "cgroup", "cgroup", "rw,devices", syscall.MS_NOSUID|syscall.MS_NODEV|syscall.MS_NOEXEC|syscall.MS_RELATIME, nil),
+			m(29, 21, 0, 25, "/", "/sys/fs/cgroup/freezer", "rw,nosuid,nodev,noexec,relatime", o(), "cgroup", "cgroup", "rw,freezer", syscall.MS_NOSUID|syscall.MS_NODEV|syscall.MS_NOEXEC|syscall.MS_RELATIME, nil),
+			m(30, 21, 0, 26, "/", "/sys/fs/cgroup/net_cls", "rw,nosuid,nodev,noexec,relatime", o(), "cgroup", "cgroup", "rw,net_cls", syscall.MS_NOSUID|syscall.MS_NODEV|syscall.MS_NOEXEC|syscall.MS_RELATIME, nil),
+			m(31, 21, 0, 27, "/", "/sys/fs/cgroup/blkio", "rw,nosuid,nodev,noexec,relatime", o(), "cgroup", "cgroup", "rw,blkio", syscall.MS_NOSUID|syscall.MS_NODEV|syscall.MS_NOEXEC|syscall.MS_RELATIME, nil),
+			m(32, 16, 0, 28, "/", "/sys/kernel/security", "rw,relatime", o(), "autofs", "systemd-1", "rw,fd=22,pgrp=1,timeout=300,minproto=5,maxproto=5,direct", syscall.MS_RELATIME, nil),
+			m(33, 17, 0, 29, "/", "/dev/hugepages", "rw,relatime", o(), "autofs", "systemd-1", "rw,fd=23,pgrp=1,timeout=300,minproto=5,maxproto=5,direct", syscall.MS_RELATIME, nil),
+			m(34, 16, 0, 30, "/", "/sys/kernel/debug", "rw,relatime", o(), "autofs", "systemd-1", "rw,fd=24,pgrp=1,timeout=300,minproto=5,maxproto=5,direct", syscall.MS_RELATIME, nil),
+			m(35, 15, 0, 31, "/", "/proc/sys/fs/binfmt_misc", "rw,relatime", o(), "autofs", "systemd-1", "rw,fd=25,pgrp=1,timeout=300,minproto=5,maxproto=5,direct", syscall.MS_RELATIME, nil),
+			m(36, 17, 0, 32, "/", "/dev/mqueue", "rw,relatime", o(), "autofs", "systemd-1", "rw,fd=26,pgrp=1,timeout=300,minproto=5,maxproto=5,direct", syscall.MS_RELATIME, nil),
+			m(37, 15, 0, 14, "/", "/proc/bus/usb", "rw,relatime", o(), "usbfs", "/proc/bus/usb", "rw", syscall.MS_RELATIME, nil),
+			m(38, 33, 0, 33, "/", "/dev/hugepages", "rw,relatime", o(), "hugetlbfs", "hugetlbfs", "rw", syscall.MS_RELATIME, nil),
+			m(39, 36, 0, 12, "/", "/dev/mqueue", "rw,relatime", o(), "mqueue", "mqueue", "rw", syscall.MS_RELATIME, nil),
+			m(40, 20, 8, 6, "/", "/boot", "rw,noatime", o(), "ext3", "/dev/sda6", "rw,errors=continue,barrier=0,data=ordered", syscall.MS_NOATIME, nil),
+			m(41, 20, 253, 0, "/", "/home/kzak", "rw,noatime", o(), "ext4", "/dev/mapper/kzak-home", "rw,barrier=1,data=ordered", syscall.MS_NOATIME, nil),
+			m(42, 35, 0, 34, "/", "/proc/sys/fs/binfmt_misc", "rw,relatime", o(), "binfmt_misc", "none", "rw", syscall.MS_RELATIME, nil),
+			m(43, 16, 0, 35, "/", "/sys/fs/fuse/connections", "rw,relatime", o(), "fusectl", "fusectl", "rw", syscall.MS_RELATIME, nil),
+			m(44, 41, 0, 36, "/", "/home/kzak/.gvfs", "rw,nosuid,nodev,relatime", o(), "fuse.gvfs-fuse-daemon", "gvfs-fuse-daemon", "rw,user_id=500,group_id=500", syscall.MS_NOSUID|syscall.MS_NODEV|syscall.MS_RELATIME, nil),
+			m(45, 20, 0, 37, "/", "/var/lib/nfs/rpc_pipefs", "rw,relatime", o(), "rpc_pipefs", "sunrpc", "rw", syscall.MS_RELATIME, nil),
+			m(47, 20, 0, 38, "/", "/mnt/sounds", "rw,relatime", o(), "cifs", "//foo.home/bar/", "rw,unc=\\\\foo.home\\bar,username=kzak,domain=SRGROUP,uid=0,noforceuid,gid=0,noforcegid,addr=192.168.111.1,posixpaths,serverino,acl,rsize=16384,wsize=57344", syscall.MS_RELATIME, nil),
+			m(49, 20, 0, 56, "/", "/mnt/test/foobar", "rw,relatime,nosymfollow", o("shared:323"), "tmpfs", "tmpfs", "rw", syscall.MS_RELATIME|vfs.MS_NOSYMFOLLOW, nil),
+		}, nil, nil},
+
+		{"sample nosrc", sampleMountinfoNoSrc, nil, "", []*wantMountInfo{
+			m(15, 20, 0, 3, "/", "/proc", "rw,relatime", o(), "proc", "/proc", "rw", syscall.MS_RELATIME, nil),
+			m(16, 20, 0, 15, "/", "/sys", "rw,relatime", o(), "sysfs", "/sys", "rw", syscall.MS_RELATIME, nil),
+			m(17, 20, 0, 5, "/", "/dev", "rw,relatime", o(), "devtmpfs", "udev", "rw,size=1983516k,nr_inodes=495879,mode=755", syscall.MS_RELATIME, nil),
+			m(18, 17, 0, 10, "/", "/dev/pts", "rw,relatime", o(), "devpts", "devpts", "rw,gid=5,mode=620,ptmxmode=000", syscall.MS_RELATIME, nil),
+			m(19, 17, 0, 16, "/", "/dev/shm", "rw,relatime", o(), "tmpfs", "tmpfs", "rw", syscall.MS_RELATIME, nil),
+			m(20, 1, 8, 4, "/", "/", "rw,noatime", o(), "ext3", "/dev/sda4", "rw,errors=continue,user_xattr,acl,barrier=0,data=ordered", syscall.MS_NOATIME, nil),
+			m(21, 20, 0, 53, "/", "/mnt/test", "rw,relatime", o("shared:212"), "tmpfs", "", "rw", syscall.MS_RELATIME, nil),
+		}, nil, nil},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Run("decode", func(t *testing.T) {
+				var got *vfs.MountInfo
+				d := vfs.NewMountInfoDecoder(strings.NewReader(tc.sample))
+				err := d.Decode(&got)
+				tc.check(t, d, "Decode",
+					func(yield func(*vfs.MountInfoEntry) bool) {
+						for cur := got; cur != nil; cur = cur.Next {
+							if !yield(&cur.MountInfoEntry) {
+								return
+							}
+						}
+					}, func() error { return err })
+				t.Run("reuse", func(t *testing.T) {
+					tc.check(t, d, "Entries",
+						d.Entries(), d.Err)
+				})
+			})
+
+			t.Run("iter", func(t *testing.T) {
+				d := vfs.NewMountInfoDecoder(strings.NewReader(tc.sample))
+				tc.check(t, d, "Entries",
+					d.Entries(), d.Err)
+
+				t.Run("reuse", func(t *testing.T) {
+					tc.check(t, d, "Entries",
+						d.Entries(), d.Err)
+				})
+			})
+
+			t.Run("yield", func(t *testing.T) {
+				d := vfs.NewMountInfoDecoder(strings.NewReader(tc.sample))
+				v := false
+				d.Entries()(func(entry *vfs.MountInfoEntry) bool { v = !v; return v })
+				d.Entries()(func(entry *vfs.MountInfoEntry) bool { return false })
+
+				tc.check(t, d, "Entries",
+					d.Entries(), d.Err)
+
+				t.Run("reuse", func(t *testing.T) {
+					tc.check(t, d, "Entries",
+						d.Entries(), d.Err)
+				})
+			})
+		})
+	}
+}
+
+type mountInfoTest struct {
+	name      string
+	sample    string
+	wantErr   error
+	wantError string
+	want      []*wantMountInfo
+
+	wantNode     *vfs.MountInfoNode
+	wantCollectF func(n *vfs.MountInfoNode) []*vfs.MountInfoNode
+}
+
+func (tc *mountInfoTest) check(t *testing.T, d *vfs.MountInfoDecoder, funcName string,
+	got iter.Seq[*vfs.MountInfoEntry], gotErr func() error) {
+	i := 0
+	for cur := range got {
+		if i == len(tc.want) {
+			if funcName != "Decode" && (tc.wantErr != nil || tc.wantError != "") {
+				continue
+			}
+
+			t.Errorf("%s: got more than %d entries", funcName, len(tc.want))
+			break
+		}
+
+		if !reflect.DeepEqual(cur, &tc.want[i].MountInfoEntry) {
+			t.Errorf("%s: entry %d\ngot:  %#v\nwant: %#v",
+				funcName, i, cur, tc.want[i])
+		}
+
+		flags, unmatched := cur.Flags()
+		if flags != tc.want[i].flags {
+			t.Errorf("Flags(%q): %#x, want %#x",
+				cur.VfsOptstr, flags, tc.want[i].flags)
+		}
+		if !slices.Equal(unmatched, tc.want[i].unmatched) {
+			t.Errorf("Flags(%q): unmatched = %#q, want %#q",
+				cur.VfsOptstr, unmatched, tc.want[i].unmatched)
+		}
+
+		i++
+	}
+
+	if i != len(tc.want) {
+		t.Errorf("%s: got %d entries, want %d", funcName, i, len(tc.want))
+	}
+
+	if tc.wantErr == nil && tc.wantError == "" && tc.wantCollectF != nil {
+		t.Run("unfold", func(t *testing.T) {
+			n, err := d.Unfold("/")
+			if err != nil {
+				t.Errorf("Unfold: error = %v", err)
+			} else {
+				t.Run("stop", func(t *testing.T) {
+					v := false
+					n.Collective()(func(node *vfs.MountInfoNode) bool { v = !v; return v })
+				})
+
+				if !reflect.DeepEqual(n, tc.wantNode) {
+					t.Errorf("Unfold: %s, want %s",
+						mustMarshal(n), mustMarshal(tc.wantNode))
+				}
+
+				t.Run("collective", func(t *testing.T) {
+					wantCollect := tc.wantCollectF(n)
+					if gotCollect := slices.Collect(n.Collective()); !reflect.DeepEqual(gotCollect, wantCollect) {
+						t.Errorf("Collective: \ngot  %#v\nwant %#v",
+							gotCollect, wantCollect)
+					}
+				})
+			}
+		})
+	} else if tc.wantNode != nil || tc.wantCollectF != nil {
+		panic("invalid test case")
+	} else if _, err := d.Unfold("/"); !errors.Is(err, tc.wantErr) {
+		if tc.wantError == "" {
+			t.Errorf("Unfold: error = %v, wantErr %v",
+				err, tc.wantErr)
+		} else if err != nil && err.Error() != tc.wantError {
+			t.Errorf("Unfold: error = %q, wantError %q",
+				err, tc.wantError)
+		}
+	}
+
+	if err := gotErr(); !errors.Is(err, tc.wantErr) {
+		if tc.wantError == "" {
+			t.Errorf("%s: error = %v, wantErr %v",
+				funcName, err, tc.wantErr)
+		} else if err != nil && err.Error() != tc.wantError {
+			t.Errorf("%s: error = %q, wantError %q",
+				funcName, err, tc.wantError)
+		}
+	}
+}
+
+func mustMarshal(v any) string {
+	p, err := json.Marshal(v)
+	if err != nil {
+		panic(err.Error())
+	}
+	return string(p)
+}
+
+type wantMountInfo struct {
+	vfs.MountInfoEntry
+	flags     uintptr
+	unmatched []string
+}
+
+func m(
+	id, parent, maj, min int, root, target, vfsOptstr string, optFields []string, fsType, source, fsOptstr string,
+	flags uintptr, unmatched []string,
+) *wantMountInfo {
+	return &wantMountInfo{
+		vfs.MountInfoEntry{
+			ID:        id,
+			Parent:    parent,
+			Devno:     vfs.DevT{maj, min},
+			Root:      root,
+			Target:    target,
+			VfsOptstr: vfsOptstr,
+			OptFields: optFields,
+			FsType:    fsType,
+			Source:    source,
+			FsOptstr:  fsOptstr,
+		}, flags, unmatched,
+	}
+}
+
+func mn(
+	id, parent, maj, min int, root, target, vfsOptstr string, optFields []string, fsType, source, fsOptstr string,
+	covered bool, firstChild, nextSibling *vfs.MountInfoNode,
+) *vfs.MountInfoNode {
+	return &vfs.MountInfoNode{
+		MountInfoEntry: &vfs.MountInfoEntry{
+			ID:        id,
+			Parent:    parent,
+			Devno:     vfs.DevT{maj, min},
+			Root:      root,
+			Target:    target,
+			VfsOptstr: vfsOptstr,
+			OptFields: optFields,
+			FsType:    fsType,
+			Source:    source,
+			FsOptstr:  fsOptstr,
+		},
+		FirstChild:  firstChild,
+		NextSibling: nextSibling,
+		Clean:       path.Clean(target),
+		Covered:     covered,
+	}
+}
+
+func o(field ...string) []string {
+	if field == nil {
+		return []string{}
+	}
+	return field
+}
+
+const (
+	sampleMountinfoBase = `15 20 0:3 / /proc rw,relatime - proc /proc rw
+16 20 0:15 / /sys rw,relatime - sysfs /sys rw
+17 20 0:5 / /dev rw,relatime - devtmpfs udev rw,size=1983516k,nr_inodes=495879,mode=755
+18 17 0:10 / /dev/pts rw,relatime - devpts devpts rw,gid=5,mode=620,ptmxmode=000
+19 17 0:16 / /dev/shm rw,relatime - tmpfs tmpfs rw
+20 1 8:4 / / ro,noatime,nodiratime,meow - ext3 /dev/sda4 rw,errors=continue,user_xattr,acl,barrier=0,data=ordered`
+
+	sampleMountinfo = `15 20 0:3 / /proc rw,relatime - proc /proc rw
+16 20 0:15 / /sys rw,relatime - sysfs /sys rw
+17 20 0:5 / /dev rw,relatime - devtmpfs udev rw,size=1983516k,nr_inodes=495879,mode=755
+18 17 0:10 / /dev/pts rw,relatime - devpts devpts rw,gid=5,mode=620,ptmxmode=000
+19 17 0:16 / /dev/shm rw,relatime - tmpfs tmpfs rw
+20 1 8:4 / / rw,noatime - ext3 /dev/sda4 rw,errors=continue,user_xattr,acl,barrier=0,data=ordered
+21 16 0:17 / /sys/fs/cgroup rw,nosuid,nodev,noexec,relatime - tmpfs tmpfs rw,mode=755
+22 21 0:18 / /sys/fs/cgroup/systemd rw,nosuid,nodev,noexec,relatime - cgroup cgroup rw,release_agent=/lib/systemd/systemd-cgroups-agent,name=systemd
+23 21 0:19 / /sys/fs/cgroup/cpuset rw,nosuid,nodev,noexec,relatime - cgroup cgroup rw,cpuset
+24 21 0:20 / /sys/fs/cgroup/ns rw,nosuid,nodev,noexec,relatime - cgroup cgroup rw,ns
+25 21 0:21 / /sys/fs/cgroup/cpu rw,nosuid,nodev,noexec,relatime - cgroup cgroup rw,cpu
+26 21 0:22 / /sys/fs/cgroup/cpuacct rw,nosuid,nodev,noexec,relatime - cgroup cgroup rw,cpuacct
+27 21 0:23 / /sys/fs/cgroup/memory rw,nosuid,nodev,noexec,relatime - cgroup cgroup rw,memory
+28 21 0:24 / /sys/fs/cgroup/devices rw,nosuid,nodev,noexec,relatime - cgroup cgroup rw,devices
+29 21 0:25 / /sys/fs/cgroup/freezer rw,nosuid,nodev,noexec,relatime - cgroup cgroup rw,freezer
+30 21 0:26 / /sys/fs/cgroup/net_cls rw,nosuid,nodev,noexec,relatime - cgroup cgroup rw,net_cls
+31 21 0:27 / /sys/fs/cgroup/blkio rw,nosuid,nodev,noexec,relatime - cgroup cgroup rw,blkio
+32 16 0:28 / /sys/kernel/security rw,relatime - autofs systemd-1 rw,fd=22,pgrp=1,timeout=300,minproto=5,maxproto=5,direct
+33 17 0:29 / /dev/hugepages rw,relatime - autofs systemd-1 rw,fd=23,pgrp=1,timeout=300,minproto=5,maxproto=5,direct
+34 16 0:30 / /sys/kernel/debug rw,relatime - autofs systemd-1 rw,fd=24,pgrp=1,timeout=300,minproto=5,maxproto=5,direct
+35 15 0:31 / /proc/sys/fs/binfmt_misc rw,relatime - autofs systemd-1 rw,fd=25,pgrp=1,timeout=300,minproto=5,maxproto=5,direct
+36 17 0:32 / /dev/mqueue rw,relatime - autofs systemd-1 rw,fd=26,pgrp=1,timeout=300,minproto=5,maxproto=5,direct
+37 15 0:14 / /proc/bus/usb rw,relatime - usbfs /proc/bus/usb rw
+38 33 0:33 / /dev/hugepages rw,relatime - hugetlbfs hugetlbfs rw
+39 36 0:12 / /dev/mqueue rw,relatime - mqueue mqueue rw
+40 20 8:6 / /boot rw,noatime - ext3 /dev/sda6 rw,errors=continue,barrier=0,data=ordered
+41 20 253:0 / /home/kzak rw,noatime - ext4 /dev/mapper/kzak-home rw,barrier=1,data=ordered
+42 35 0:34 / /proc/sys/fs/binfmt_misc rw,relatime - binfmt_misc none rw
+43 16 0:35 / /sys/fs/fuse/connections rw,relatime - fusectl fusectl rw
+44 41 0:36 / /home/kzak/.gvfs rw,nosuid,nodev,relatime - fuse.gvfs-fuse-daemon gvfs-fuse-daemon rw,user_id=500,group_id=500
+45 20 0:37 / /var/lib/nfs/rpc_pipefs rw,relatime - rpc_pipefs sunrpc rw
+47 20 0:38 / /mnt/sounds rw,relatime - cifs //foo.home/bar/ rw,unc=\\foo.home\bar,username=kzak,domain=SRGROUP,uid=0,noforceuid,gid=0,noforcegid,addr=192.168.111.1,posixpaths,serverino,acl,rsize=16384,wsize=57344
+49 20 0:56 / /mnt/test/foobar rw,relatime,nosymfollow shared:323 - tmpfs tmpfs rw`
+
+	sampleMountinfoNoSrc = `15 20 0:3 / /proc rw,relatime - proc /proc rw
+16 20 0:15 / /sys rw,relatime - sysfs /sys rw
+17 20 0:5 / /dev rw,relatime - devtmpfs udev rw,size=1983516k,nr_inodes=495879,mode=755
+18 17 0:10 / /dev/pts rw,relatime - devpts devpts rw,gid=5,mode=620,ptmxmode=000
+19 17 0:16 / /dev/shm rw,relatime - tmpfs tmpfs rw
+20 1 8:4 / / rw,noatime - ext3 /dev/sda4 rw,errors=continue,user_xattr,acl,barrier=0,data=ordered
+21 20 0:53 / /mnt/test rw,relatime shared:212 - tmpfs  rw`
+)
diff --git a/vfs/unfold.go b/vfs/unfold.go
new file mode 100644
index 00000000..ca0e37b7
--- /dev/null
+++ b/vfs/unfold.go
@@ -0,0 +1,107 @@
+package vfs
+
+import (
+	"iter"
+	"path"
+	"strings"
+	"syscall"
+)
+
+// MountInfoNode positions a [MountInfoEntry] in its mount hierarchy.
+type MountInfoNode struct {
+	*MountInfoEntry
+	FirstChild  *MountInfoNode `json:"first_child"`
+	NextSibling *MountInfoNode `json:"next_sibling"`
+
+	Clean   string `json:"clean"`
+	Covered bool   `json:"covered"`
+}
+
+// Collective returns an iterator over visible mountinfo nodes.
+func (n *MountInfoNode) Collective() iter.Seq[*MountInfoNode] {
+	return func(yield func(*MountInfoNode) bool) { n.visit(yield) }
+}
+
+func (n *MountInfoNode) visit(yield func(*MountInfoNode) bool) bool {
+	if !n.Covered && !yield(n) {
+		return false
+	}
+	for cur := n.FirstChild; cur != nil; cur = cur.NextSibling {
+		if !cur.visit(yield) {
+			return false
+		}
+	}
+	return true
+}
+
+// Unfold unfolds the mount hierarchy and resolves covered paths.
+func (d *MountInfoDecoder) Unfold(target string) (*MountInfoNode, error) {
+	targetClean := path.Clean(target)
+
+	var mountinfoSize int
+	for range d.Entries() {
+		mountinfoSize++
+	}
+	if err := d.Err(); err != nil {
+		return nil, err
+	}
+
+	mountinfo := make([]*MountInfoNode, mountinfoSize)
+	// mount ID to index lookup
+	idIndex := make(map[int]int, mountinfoSize)
+	// final entry to match target
+	targetIndex := -1
+	{
+		i := 0
+		for ent := range d.Entries() {
+			mountinfo[i] = &MountInfoNode{Clean: path.Clean(ent.Target), MountInfoEntry: ent}
+			idIndex[ent.ID] = i
+			if mountinfo[i].Clean == targetClean {
+				targetIndex = i
+			}
+
+			i++
+		}
+	}
+
+	if targetIndex == -1 {
+		return nil, syscall.ESTALE
+	}
+
+	for _, cur := range mountinfo {
+		var parent *MountInfoNode
+		if p, ok := idIndex[cur.Parent]; !ok {
+			continue
+		} else {
+			parent = mountinfo[p]
+		}
+
+		if !strings.HasPrefix(cur.Clean, targetClean) {
+			continue
+		}
+		if parent.Clean == cur.Clean {
+			parent.Covered = true
+		}
+
+		covered := false
+		nsp := &parent.FirstChild
+		for s := parent.FirstChild; s != nil; s = s.NextSibling {
+			if strings.HasPrefix(cur.Clean, s.Clean) {
+				covered = true
+				break
+			}
+
+			if strings.HasPrefix(s.Clean, cur.Clean) {
+				*nsp = s.NextSibling
+			} else {
+				nsp = &s.NextSibling
+			}
+		}
+		if covered {
+			continue
+		}
+		*nsp = cur
+	}
+
+	return mountinfo[targetIndex], nil
+}
diff --git a/vfs/unfold_test.go b/vfs/unfold_test.go
new file mode 100644
index 00000000..59e52041
--- /dev/null
+++ b/vfs/unfold_test.go
@@ -0,0 +1,93 @@
+package vfs_test
+
+import (
+	"errors"
+	"reflect"
+	"slices"
+	"strings"
+	"syscall"
+	"testing"
+
+	"git.gensokyo.uk/security/hakurei/vfs"
+)
+
+func TestUnfold(t *testing.T) {
+	testCases := []struct {
+		name    string
+		sample  string
+		target  string
+		wantErr error
+
+		want         *vfs.MountInfoNode
+		wantCollectF func(n *vfs.MountInfoNode) []*vfs.MountInfoNode
+		wantCollectN []string
+	}{
+		{
+			"no match",
+			sampleMountinfoBase,
+			"/mnt",
+			syscall.ESTALE, nil, nil, nil,
+		},
+		{
+			"cover",
+			`33 1 0:33 / / rw,relatime shared:1 - tmpfs impure rw,size=16777216k,mode=755
+37 33 0:32 / /proc rw,nosuid,nodev,noexec,relatime shared:41 - proc proc rw
+551 33 0:121 / /mnt rw,relatime shared:666 - tmpfs tmpfs rw
+595 551 0:123 / /mnt rw,relatime shared:990 - tmpfs tmpfs rw
+611 595 0:142 / /mnt/etc rw,relatime shared:1112 - tmpfs tmpfs rw
+625 644 0:142 /passwd /mnt/etc/passwd rw,relatime shared:1112 - tmpfs tmpfs rw
+641 625 0:33 /etc/passwd /mnt/etc/passwd rw,relatime shared:1 - tmpfs impure rw,size=16777216k,mode=755
+644 611 0:33 /etc/passwd /mnt/etc/passwd rw,relatime shared:1 - tmpfs impure rw,size=16777216k,mode=755
+`, "/mnt", nil,
+			mn(595, 551, 0, 123, "/", "/mnt", "rw,relatime", o("shared:990"), "tmpfs", "tmpfs", "rw", false,
+				mn(611, 595, 0, 142, "/", "/mnt/etc", "rw,relatime", o("shared:1112"), "tmpfs", "tmpfs", "rw", false,
+					mn(644, 611, 0, 33, "/etc/passwd", "/mnt/etc/passwd", "rw,relatime", o("shared:1"), "tmpfs", "impure", "rw,size=16777216k,mode=755", true,
+						mn(625, 644, 0, 142, "/passwd", "/mnt/etc/passwd", "rw,relatime", o("shared:1112"), "tmpfs", "tmpfs", "rw", true,
+							mn(641, 625, 0, 33, "/etc/passwd", "/mnt/etc/passwd", "rw,relatime", o("shared:1"), "tmpfs", "impure", "rw,size=16777216k,mode=755", false,
+								nil, nil), nil), nil), nil), nil), func(n *vfs.MountInfoNode) []*vfs.MountInfoNode {
+				return []*vfs.MountInfoNode{n, n.FirstChild, n.FirstChild.FirstChild.FirstChild.FirstChild}
+			}, []string{"/mnt", "/mnt/etc", "/mnt/etc/passwd"},
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			d := vfs.NewMountInfoDecoder(strings.NewReader(tc.sample))
+			got, err := d.Unfold(tc.target)
+
+			if !errors.Is(err, tc.wantErr) {
+				t.Errorf("Unfold: error = %v, wantErr %v",
+					err, tc.wantErr)
+			}
+
+			if !reflect.DeepEqual(got, tc.want) {
+				t.Errorf("Unfold:\ngot  %s\nwant %s",
+					mustMarshal(got), mustMarshal(tc.want))
+			}
+
+			if err == nil && tc.wantCollectF != nil {
+				t.Run("collective", func(t *testing.T) {
+					wantCollect := tc.wantCollectF(got)
+					gotCollect := slices.Collect(got.Collective())
+					if !reflect.DeepEqual(gotCollect, wantCollect) {
+						t.Errorf("Collective: \ngot  %#v\nwant %#v",
+							gotCollect, wantCollect)
+					}
+					t.Run("target", func(t *testing.T) {
+						gotCollectN := slices.Collect[string](func(yield func(v string) bool) {
+							for _, cur := range gotCollect {
+								if !yield(cur.Clean) {
+									return
+								}
+							}
+						})
+						if !reflect.DeepEqual(gotCollectN, tc.wantCollectN) {
+							t.Errorf("Collective: got %q, want %q",
+								gotCollectN, tc.wantCollectN)
+						}
+					})
+				})
+			}
+		})
+	}
+}