caps

package module
v0.10.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 28, 2023 License: Apache-2.0 Imports: 10 Imported by: 0

README

caps

PkgGoDev License Build and Test Coverage Go Report Card

A pure-Go minimalist package for getting and setting the capabilities of Linux tasks (threads). No need for linking with libcap.

Example: Dropping and Regaining Effective Capabilities

To drop the calling task's effective capabilities only, without dropping the permitted capabilities:

// Make sure to lock this Go routine to its current OS-level task (thread).
runtime.LockOSThread()

origcaps := caps.OfThisTask()
dropped := origcaps.Clone()
dropped.Effective.Clear()
caps.SetForThisTask(dropped)

To regain only a specific effective capability:

dropped.Effective.Add(caps.CAP_SYS_ADMIN)
caps.SetForThisTask(dropped)

And finally to regain all originally effective capabilities:

caps.SetForThisTask(origcaps)

Go Version Support

caps supports versions of Go that are noted by the Go release policy, that is, major versions N and N-1 (where N is the current major version).

Contributing

Please see CONTRIBUTING.md.

caps is Copyright 2023 Harald Albrecht, and licensed under the Apache License, Version 2.0.

Documentation

Overview

Package caps provides a minimalist interface to getting and setting the capabilities of Linux tasks (threads). It is a pure Go implementation that does not need any linking with the C libcap. However, it isn't any drop-in replacement for the libcap.git Go module (if that even is possible).

The focus of this module is on dropping and regaining effective capabilities, as well as dropping permitted capabilities. That is, a more Go-like API to the capget(2) and capset(2) Linux syscalls.

Dropping and Regaining Effective Capabilities

To drop the calling task's effective capabilities only, without dropping the permitted capabilities: 

// Make sure to lock this Go routine to its current OS-level task (thread).
runtime.LockOSThread()

origcaps := caps.OfThisTask()
dropped := origcaps.Clone()
dropped.Effective.Clear()
caps.SetForThisTask(dropped)

To regain only a specific effective capability: 

dropped.Effective.Add(caps.CAP_SYS_ADMIN)
caps.SetForThisTask(dropped)

And finally to regain all originally effective capabilities: 

caps.SetForThisTask(origcaps)

Notes

This package assumes at least a kernel version 2.65 or later and does not support older kernels.

The Linux kernel actually returns the version of the capabilities user-space structure it uses “natively” in the capabilities header version field if this version field is set to an invalid or unsupported version (such as 0 which was never be used and won't ever). In this case, EINVAL is returned.

Index

Constants

View Source 
const (

	/* In a system with the [_POSIX_CHOWN_RESTRICTED] option defined, this
	overrides the restriction of changing file ownership and group
	ownership. */
	CAP_CHOWN = 0
	/* Override all DAC access, including ACL execute access if
	[_POSIX_ACL] is defined. Excluding DAC access covered by
	CAP_LINUX_IMMUTABLE. */
	CAP_DAC_OVERRIDE = 1
	/* Overrides all DAC restrictions regarding read and search on files
	and directories, including ACL restrictions if [_POSIX_ACL] is
	defined. Excluding DAC access covered by CAP_LINUX_IMMUTABLE. */
	CAP_DAC_READ_SEARCH = 2
	/* Overrides all restrictions about allowed operations on files, where
	file owner ID must be equal to the user ID, except where CAP_FSETID
	is applicable. It doesn’t override MAC and DAC restrictions. */
	CAP_FOWNER = 3
	/* Overrides the following restrictions that the effective user ID
	shall match the file owner ID when setting the S_ISUID and S_ISGID
	bits on that file; that the effective group ID (or one of the
	supplementary group IDs) shall match the file owner ID when setting
	the S_ISGID bit on that file; that the S_ISUID and S_ISGID bits are
	cleared on successful return from chown(2) (not implemented). */
	CAP_FSETID = 4
	/* Overrides the restriction that the real or effective user ID of a
	process sending a signal must match the real or effective user ID
	of the process receiving the signal. */
	CAP_KILL = 5
	/* Allows setgid(2) manipulation

	Allows setgroups(2)

	Allows forged gids on socket credentials passing. */
	CAP_SETGID = 6
	/* Allows set*uid(2) manipulation (including fsuid).

	Allows forged pids on socket credentials passing. */
	CAP_SETUID = 7
	/* Without VFS support for capabilities:
	Transfer any capability in your permitted set to any pid,
	remove any capability in your permitted set from any pid
	With VFS support for capabilities (neither of above, but)
	Add any capability from current’s capability bounding set
	to the current process’ inheritable set
	Allow taking bits out of capability bounding set
	Allow modification of the securebits for a process
	*/
	CAP_SETPCAP = 8
	/* Allow modification of S_IMMUTABLE and S_APPEND file attributes */
	CAP_LINUX_IMMUTABLE = 9
	/* Allows binding to TCP/UDP sockets below 1024

	Allows binding to ATM VCIs below 32 */
	CAP_NET_BIND_SERVICE = 10
	/* Allow broadcasting, listen to multicast */
	CAP_NET_BROADCAST = 11
	/* Allow interface configuration

	Allow administration of IP firewall, masquerading and accounting

	Allow setting debug option on sockets

	Allow modification of routing tables

	Allow setting arbitrary process / process group ownership on
	sockets

	Allow binding to any address for transparent proxying (also via NET_RAW)

	Allow setting TOS (type of service)

	Allow setting promiscuous mode

	Allow clearing driver statistics

	Allow multicasting

	Allow read/write of device-specific registers

	Allow activation of ATM control sockets */
	CAP_NET_ADMIN = 12
	/* Allow use of RAW sockets

	Allow use of PACKET sockets

	Allow binding to any address for transparent proxying (also via NET_ADMIN) */
	CAP_NET_RAW = 13
	/* Allow locking of shared memory segments

	Allow mlock and mlockall (which doesn’t really have anything to do
	with IPC) */
	CAP_IPC_LOCK = 14
	/* Override IPC ownership checks */
	CAP_IPC_OWNER = 15
	/* Insert and remove kernel modules - modify kernel without limit */
	CAP_SYS_MODULE = 16
	/* Allow ioperm/iopl access

	Allow sending USB messages to any device via /dev/bus/usb */
	CAP_SYS_RAWIO = 17
	/* Allow use of chroot() */
	CAP_SYS_CHROOT = 18
	/* Allow ptrace() of any process */
	CAP_SYS_PTRACE = 19
	/* Allow configuration of process accounting */
	CAP_SYS_PACCT = 20
	/* Allow configuration of the secure attention key

	Allow administration of the random device

	Allow examination and configuration of disk quotas

	Allow setting the domainname

	Allow setting the hostname

	Allow calling bdflush()

	Allow mount() and umount(), setting up new smb connection

	Allow some autofs root ioctls

	Allow nfsservctl

	Allow VM86_REQUEST_IRQ

	Allow to read/write pci config on alpha

	Allow irix_prctl on mips (setstacksize)

	Allow flushing all cache on m68k (sys_cacheflush)

	Allow removing semaphores

	Used instead of CAP_CHOWN to "chown" IPC message queues, semaphores
	and shared memory

	Allow locking/unlocking of shared memory segment

	Allow turning swap on/off

	Allow forged pids on socket credentials passing

	Allow setting readahead and flushing buffers on block devices

	Allow setting geometry in floppy driver

	Allow turning DMA on/off in xd driver

	Allow administration of md devices (mostly the above, but some
	extra ioctls)

	Allow tuning the ide driver

	Allow access to the nvram device

	Allow administration of apm_bios, serial and bttv (TV) device

	Allow manufacturer commands in isdn CAPI support driver

	Allow reading non-standardized portions of pci configuration space

	Allow DDI debug ioctl on sbpcd driver

	Allow setting up serial ports

	Allow sending raw qic-117 commands

	Allow enabling/disabling tagged queuing on SCSI controllers and sending
	arbitrary SCSI commands

	Allow setting encryption key on loopback filesystem

	Allow setting zone reclaim policy */
	CAP_SYS_ADMIN = 21
	/* Allow use of reboot() */
	CAP_SYS_BOOT = 22
	/* Allow raising priority and setting priority on other (different
	UID) processes

	Allow use of FIFO and round-robin (realtime) scheduling on own
	processes and setting the scheduling algorithm used by another
	process.

	Allow setting cpu affinity on other processes */
	CAP_SYS_NICE = 23
	/* Override resource limits. Set resource limits.

	Override quota limits.

	Override reserved space on ext2 filesystem

	Modify data journaling mode on ext3 filesystem (uses journaling
	resources)

	NOTE: ext2 honors fsuid when checking for resource overrides, so
	you can override using fsuid too

	Override size restrictions on IPC message queues

	Allow more than 64hz interrupts from the real-time clock

	Override max number of consoles on console allocation

	Override max number of keymaps */
	CAP_SYS_RESOURCE = 24
	/* Allow manipulation of system clock

	Allow irix_stime on mips

	Allow setting the real-time clock */
	CAP_SYS_TIME = 25
	/* Allow configuration of tty devices

	Allow vhangup() of tty */
	CAP_SYS_TTY_CONFIG = 26
	/* Allow the privileged aspects of mknod() */
	CAP_MKNOD = 27
	/* Allow taking of leases on files */
	CAP_LEASE = 28
	/* Allow writing the audit log via unicast netlink socket */
	CAP_AUDIT_WRITE = 29
	/* Allow configuration of audit via unicast netlink socket */
	CAP_AUDIT_CONTROL = 30
	/* Set capabilities on files. */
	CAP_SETFCAP = 31
	/* Override MAC access.
	The base kernel enforces no MAC policy.
	An LSM may enforce a MAC policy, and if it does and it chooses
	to implement capability based overrides of that policy, this is
	the capability it should use to do so. */
	CAP_MAC_OVERRIDE = 32
	/* Allow MAC configuration or state changes.
	The base kernel requires no MAC configuration.
	An LSM may enforce a MAC policy, and if it does and it chooses
	to implement capability based checks on modifications to that
	policy or the data required to maintain it, this is the
	capability it should use to do so. */
	CAP_MAC_ADMIN = 33
	/* Allow configuring the kernel’s syslog (printk behaviour) */
	CAP_SYSLOG = 34
	/* Allow triggering something that will wake the system */
	CAP_WAKE_ALARM = 35
	/* Allow preventing system suspends */
	CAP_BLOCK_SUSPEND = 36
	/* Allow reading the audit log via multicast netlink socket */
	CAP_AUDIT_READ = 37
	/* Allow system performance and observability privileged operations using
	perf_events, i915_perf and other kernel subsystems. */
	CAP_PERFMON = 38
	/*
		CAP_BPF allows the following BPF operations:
		- Creating all types of BPF maps
		- Advanced verifier features
		- Indirect variable access
		- Bounded loops
		- BPF to BPF function calls
		- Scalar precision tracking
		- Larger complexity limits
		- Dead code elimination
		- And potentially other features
		- Loading BPF Type Format (BTF) data
		- Retrieve xlated and JITed code of BPF programs
		- Use bpf_spin_lock() helper
		* CAP_PERFMON relaxes the verifier checks further:
		- BPF progs can use of pointer-to-integer conversions
		- speculation attack hardening measures are bypassed
		- bpf_probe_read to read arbitrary kernel memory is allowed
		- bpf_trace_printk to print kernel memory is allowed
		* CAP_SYS_ADMIN is required to use bpf_probe_write_user.
		* CAP_SYS_ADMIN is required to iterate system wide loaded
		programs, maps, links, BTFs and convert their IDs to file descriptors.
		* CAP_PERFMON and CAP_BPF are required to load tracing programs.
		CAP_NET_ADMIN and CAP_BPF are required to load networking programs.
	*/
	CAP_BPF = 39
	/* Allow checkpoint/restore related operations

	Allow PID selection during clone3()

	Allow writing to ns_last_pid */
	CAP_CHECKPOINT_RESTORE = 40

	MaxCapabilityNumber = 40
)
View Source 
const (
	LINUX_CAPABILITY_U32S_1 = 1
	LINUX_CAPABILITY_U32S_2 = 2
	LINUX_CAPABILITY_U32S_3 = 2
)
View Source 
const LibcapSemVer = "2.69"

SemVer of the libcap definitions.

Variables

View Source 
var CapabilityNameByNumber = map[int]string{
	0:  "CAP_CHOWN",
	1:  "CAP_DAC_OVERRIDE",
	2:  "CAP_DAC_READ_SEARCH",
	3:  "CAP_FOWNER",
	4:  "CAP_FSETID",
	5:  "CAP_KILL",
	6:  "CAP_SETGID",
	7:  "CAP_SETUID",
	8:  "CAP_SETPCAP",
	9:  "CAP_LINUX_IMMUTABLE",
	10: "CAP_NET_BIND_SERVICE",
	11: "CAP_NET_BROADCAST",
	12: "CAP_NET_ADMIN",
	13: "CAP_NET_RAW",
	14: "CAP_IPC_LOCK",
	15: "CAP_IPC_OWNER",
	16: "CAP_SYS_MODULE",
	17: "CAP_SYS_RAWIO",
	18: "CAP_SYS_CHROOT",
	19: "CAP_SYS_PTRACE",
	20: "CAP_SYS_PACCT",
	21: "CAP_SYS_ADMIN",
	22: "CAP_SYS_BOOT",
	23: "CAP_SYS_NICE",
	24: "CAP_SYS_RESOURCE",
	25: "CAP_SYS_TIME",
	26: "CAP_SYS_TTY_CONFIG",
	27: "CAP_MKNOD",
	28: "CAP_LEASE",
	29: "CAP_AUDIT_WRITE",
	30: "CAP_AUDIT_CONTROL",
	31: "CAP_SETFCAP",
	32: "CAP_MAC_OVERRIDE",
	33: "CAP_MAC_ADMIN",
	34: "CAP_SYSLOG",
	35: "CAP_WAKE_ALARM",
	36: "CAP_BLOCK_SUSPEND",
	37: "CAP_AUDIT_READ",
	38: "CAP_PERFMON",
	39: "CAP_BPF",
	40: "CAP_CHECKPOINT_RESTORE",
}

CapabilityNameByNumber maps capability bit numbers to their capability (symbolic) names.

Functions

func KernelCapabilityVersion 

func KernelCapabilityVersion() uint32

KernelCapabilityVersion returns the version of the capabilities user-space data structure that the Linux kernel we're just running on "natively" uses. In case the version could not properly be detected, 0 is returned instead.

func LastCapability 

func LastCapability() int

LastCapability returns the number of the highest capability supported by the kernel we're now running on. This value might differ from MaxCapabilityNumber that is known to this package.

func Reverse 

func Reverse[S ~[]E, E any](s S) S

Reverse returns a copy of the specified slice with the sequence of elements reversed.

func SetForTask 

func SetForTask(tid int, taskcaps TaskCapabilities) error

SetForTask sets the capability sets (effective, permitted and inheritable) for the specified task.

func SetForThisTask 

func SetForThisTask(taskcaps TaskCapabilities) error

SetForThisTask sets the capability sets (effective, permitted and inheritable) for the current task.

Types

type CapabilitiesSet 

type CapabilitiesSet []uint32

CapabilitiesSet is a set of capabilities.

CapabilitiesSet is independent of any kernel version and its particular set width. Instead, it manages capabilities in a dynamically (re)sizing set (actually a slice).

func AllCapabilities 

func AllCapabilities() CapabilitiesSet

AllCapabilities returns a new set with all capabilities that the kernel supports we're currently running on.

func CapabilitiesFromHex 

func CapabilitiesFromHex(h string) (CapabilitiesSet, error)

CapabilitiesFromHex parses the given hexadecimal string into a capabilities set. If the string representation is invalid then an error is returned instead, together with a zero capabilities set.

func NewCapabilitiesSet 

func NewCapabilitiesSet() CapabilitiesSet

NewCapabilitiesSet returns a new capabilities set. This is more of a convenience for those who prefer the "New..." pattern.

func (*CapabilitiesSet) Add 

func (c *CapabilitiesSet) Add(capno int, morecapnos ...int)

Add (set) one or more effective capabilities identified by their numbers to a set.

func (*CapabilitiesSet) Clear 

func (c *CapabilitiesSet) Clear()

Clear clears all capabilities from this set.

func (CapabilitiesSet) Clone 

func (c CapabilitiesSet) Clone() CapabilitiesSet

Clone a set of capabilities into a new and independent set.

func (*CapabilitiesSet) Drop 

func (c *CapabilitiesSet) Drop(capno int, morecapnos ...int)

Drop (remove) one or more capabilities identified by their numbers to a set.

func (CapabilitiesSet) Has 

func (c CapabilitiesSet) Has(capno int) bool

Has returns true if the set contains the specified capability (as identified by its number).

func (CapabilitiesSet) Hex 

func (c CapabilitiesSet) Hex() string

Hex returns the hexadecimal representation of this capabilities set.

func (CapabilitiesSet) Names 

func (c CapabilitiesSet) Names() []string

Names returns the names of the capabilities in this set, sorted by increasing bit number.

func (CapabilitiesSet) SortedNames added in v0.9.1 

func (c CapabilitiesSet) SortedNames() []string

SortedNames returns the names of the capabilities in this set in lexicographic order, but with "anonymous" capabilities (CAP_ddd) always sorted last.

func (CapabilitiesSet) String 

func (c CapabilitiesSet) String() string

String returns a textual representation of the capabilities in this set, alphabetically sorted by capability (symbol) names.

type TaskCapabilities 

type TaskCapabilities struct {
	Effective   CapabilitiesSet
	Permitted   CapabilitiesSet
	Inheritable CapabilitiesSet
}

TaskCapabilities represents the effective, permitted and inheritable capabilities sets.

The three capabilities sets (effective, permitted, inherited) of a task can be retrieved using [TaskCaps] and all three sets set with [SetTaskCaps].

Often, only the effective capabilities of a task are to be changed, this can be done by first obtaining suitable task capabilities via AddEffectiveCaps and SetEffectiveCaps, and with the result obtained then calling [SetTaskCaps].

func AddEffectiveCaps 

func AddEffectiveCaps(capno int, morecapsno ...int) (capsbefore TaskCapabilities, err error)

AddEffectiveCaps retrieves the current task's capabilities sets, adds the specified effective capabilities and sets them as the new current task's capabilities. AddEffectiveCaps returns the previous capabilities sets when successful. For more complex use cases where also the permitted capabilities are to be changed, please use [TaskCaps] first, then change the permitted capabilities in the task capabilities acquired, and finally call [SetTaskCaps].

func OfTask 

func OfTask(tid int) (taskcaps TaskCapabilities, err error)

OfTask returns the effective, permitted and inheritable capability sets for the specified task. If the sets cannot be queried from the Linux kernel, then an error is returned instead with a zero set of capabilities.

func OfThisTask 

func OfThisTask() (taskcaps TaskCapabilities, err error)

OfThisTask returns the effective, permitted and inheritable capability sets for the current task. If the sets cannot be queried from the Linux kernel, then an error is returned instead with a zero set of capabilities.

func SetEffectiveCaps 

func SetEffectiveCaps(capno int, morecapsno ...int) (capsbefore TaskCapabilities, err error)

SetEffectiveCaps retrieves the current task's capabilities sets, then sets only the specified effective capabilities and then sets them as the new current task's capabilities. SetEffectiveCaps returns the previous capabilities sets when successful.

func (TaskCapabilities) Clone 

func (t TaskCapabilities) Clone() TaskCapabilities

Clone returns an independent clone of the task capabilities. Modifications to the source task capabilities won't change the cloned task capabilities.

Source Files

View all Source files

Directories

Path Synopsis
Package errno converts error number values into error-type values.
 Package errno converts error number values into error-type values.
internal
updatecaps

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.