cap

package module
v0.2.46 Latest Latest
Warning

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

 Go to latest Published: Dec 12, 2020 License: GPL-2.0 Imports: 14 Imported by: 107

README 

Package cap is the libcap API for Linux Capabilities written in
Go. The official release announcement site for libcap is:

   https://sites.google.com/site/fullycapable/

Like libcap, the cap package is distributed with a "you choose"
License. Specifically: BSD three clause, or GPL2. See the LICENSE
file.

Andrew G. Morgan <morgan@kernel.org>

Documentation

Overview

Package cap provides all the Linux Capabilities userspace library API bindings in native Go.

Capabilities are a feature of the Linux kernel that allow fine grain permissions to perform privileged operations. Privileged operations are required to do irregular system level operations from code. You can read more about how Capabilities are intended to work here: 

https://static.googleusercontent.com/media/research.google.com/en//pubs/archive/33528.pdf

This package supports native Go bindings for all the features described in that paper as well as supporting subsequent changes to the kernel for other styles of inheritable Capability.

Some simple things you can do with this package are: 

// Read and display the capabilities of the running process
c := cap.GetProc()
log.Printf("this process has these caps:", c)

// Drop any privilege a process might have (including for root,
// but note root 'owns' a lot of system files so a cap-limited
// root can still do considerable damage to a running system).
old := cap.GetProc()
empty := cap.NewSet()
if err := empty.SetProc(); err != nil {
    log.Fatalf("failed to drop privilege: %q -> %q: %v", old, empty, err)
}
now := cap.GetProc()
if cap.Differs(now.Compare(empty)) {
    log.Fatalf("failed to fully drop privilege: have=%q, wanted=%q", now, empty)
}

See https://sites.google.com/site/fullycapable/ for recent updates, some more complete walk-through examples of ways of using 'cap.Set's etc and information on how to file bugs.

For CGo linked binaries, behind the scenes, the package "kernel.org/pub/linux/libs/security/libcap/psx" is used to perform POSIX semantics system calls that manipulate thread state uniformly over the whole Go (and CGo linked) process runtime.

Note, if the Go runtime syscall interface contains the Linux variant syscall.AllThreadsSyscall() API (it is not in go1.15 for example, but see https://github.com/golang/go/issues/1435 for current status) then this present package can use that to invoke Capability setting system calls in pure Go binaries. In such an enhanced Go runtime, to force this behavior, use the CGO_ENABLED=0 environment variable and, for now, a build tag: 

CGO_ENABLED=0 go build -tags allthreadssyscall ...

Copyright (c) 2019,20 Andrew G. Morgan <morgan@kernel.org>

The cap and psx packages are licensed with a (you choose) BSD 3-clause or GPL2. See LICENSE file for details.

Index

Constants

View Source 
const ExtMagic = uint32(0x5101c290)

ExtMagic is the 32-bit (little endian) magic for an external capability set. It can be used to transmit capabilities in binary format in a Linux portable way. The format is: <ExtMagic><byte:length><length-bytes*3-of-cap-data>.

View Source 
const LaunchSupported = true

LaunchSupported indicates that is safe to return from a locked OS Thread and have that OS Thread be terminated by the runtime. The Launch functionality really needs to rely on the fact that an excess of runtime.LockOSThread() vs. runtime.UnlockOSThread() calls in a returning go routine will cause the underlying locked OSThread to terminate. That feature was added to the Go runtime in version 1.10.

See these bugs for the discussion and feature assumed by the code in this Launch() functionality: 

https://github.com/golang/go/issues/20395
https://github.com/golang/go/issues/20458

A value of false for this constant causes the Launch functionality to fail with an error: cap.ErrNoLaunch. If this value is false you have two choices with respect to the Launch functionality:

  1. don't use cap.(*Launcher).Launch()
  2. upgrade your Go toolchain to 1.10+ (ie., do this one).
View Source 
const NamedCount = 41

NamedCount holds the number of capability values with official names known at the time this libcap/cap version, was released. The "../libcap/cap" package is fully able to manipulate higher numbered capability values by numerical value. However, if you find cap.NamedCount < cap.MaxBits(), it is probably time to upgrade this package on your system.

FWIW the userspace tool '/sbin/capsh' also contains a runtime check for the condition that libcap is behind the running kernel in this way.

Variables

View Source 
var ErrAmbiguousAmbient = errors.New("use Launcher for ambient caps")

ErrAmbiguousAmbient indicates that the Launcher is being used in addition callback supplied ambient set and the former should be used exclusively in a Launch call.

View Source 
var ErrAmbiguousChroot = errors.New("use Launcher for chroot")

ErrAmbiguousChroot indicates that the Launcher is being used in addition to callback supplied Chroot. The former should be used exclusively for this.

View Source 
var ErrAmbiguousIDs = errors.New("use Launcher for uids and gids")

ErrAmbiguousIDs indicates that the Launcher is being used in addition to callback supplied Credentials. The former should be used exclusively for this.

View Source 
var ErrBadMagic = errors.New("unsupported magic")

ErrBadMagic indicates that the kernel preferred magic number for capability Set values is not supported by this package. This generally implies you are using an exceptionally old "../libcap/cap" package. An upgrade is needed, or failing that see https://sites.google.com/site/fullycapable/ for how to file a bug.

View Source 
var ErrBadMode = errors.New("unsupported mode")

ErrBadMode is the error returned when an attempt is made to set an unrecognized libcap security mode.

View Source 
var ErrBadPath = errors.New("file is not a regular executable")

ErrBadPath indicates a failed attempt to set a file capability on an irregular (non-executable) file.

View Source 
var ErrBadSet = errors.New("bad capability set")

ErrBadSet indicates a nil pointer was used for a *Set, or the request of the Set is invalid in some way.

View Source 
var ErrBadSize = errors.New("filecap bad size")

ErrBadSize indicates the the loaded file capability has an invalid number of bytes in it.

View Source 
var ErrBadText = errors.New("bad text")

ErrBadText is returned if the text for a capability set cannot be parsed.

View Source 
var ErrBadValue = errors.New("bad capability value")

ErrBadValue indicates a bad capability value was specified.

View Source 
var ErrLaunchFailed = errors.New("launch failed")

ErrLaunchFailed is returned if a launch was aborted with no more specific error.

View Source 
var ErrNoLaunch = errors.New("launch not supported")

ErrNoLaunch indicates the go runtime available to this binary does not reliably support launching. See cap.LaunchSupported.

Functions

func Differs 

func Differs(cf uint, vec Flag) bool

Differs processes the result of Compare and determines if the Flag's components were different.

func DropBound 

func DropBound(val ...Value) error

DropBound attempts to suppress bounding set Values. The kernel will never allow a bounding set Value bit to be raised once successfully dropped. However, dropping requires the current process is sufficiently capable (usually via cap.SETPCAP being raised in the Effective flag of the process' Set). Note, the drops are performed in order and if one bounding value cannot be dropped, the function returns immediately with an error which may leave the system in an ill-defined state. The caller can determine where things went wrong using GetBound().

func GetAmbient 

func GetAmbient(val Value) (bool, error)

GetAmbient determines if a specific capability is currently part of the local ambient set. On systems where the ambient set Value is not present, this function returns an error.

func GetBound 

func GetBound(val Value) (bool, error)

GetBound determines if a specific capability is currently part of the local bounding set. On systems where the bounding set Value is not present, this function returns an error.

func ResetAmbient 

func ResetAmbient() error

ResetAmbient attempts to ensure the Ambient set is fully cleared. It works by first reading the set and if it finds any bits raised it will attempt a reset. The test before attempting a reset behavior is a workaround for situations where the Ambient API is locked, but a reset is not actually needed. No Ambient bit not already raised in both the Permitted and Inheritable Set is allowed to be raised by the kernel.

func SetAmbient 

func SetAmbient(enable bool, val ...Value) error

SetAmbient attempts to set a specific Value bit to the state, enable. This function will return an error if insufficient permission is available to perform this task. The settings are performed in order and the function returns immediately an error is detected. Use GetAmbient() to unravel where things went wrong. Note, the cap package manages an abstraction IAB that captures all three inheritable vectors in a single type. Consider using that.

func SetGroups 

func SetGroups(gid int, suppl ...int) error

SetGroups is a convenience function for robustly setting the GID and all other variants of GID (EGID etc) to the specified value, as well as setting all of the supplementary groups. This function will raise cap.SETGID in order to achieve this operation, and will completely lower the Effective Flag of the process Set before returning.

func SetUID 

func SetUID(uid int) error

SetUID is a convenience function for robustly setting the UID and all other variants of UID (EUID etc) to the specified value without dropping the privilege of the current process. This function will raise cap.SETUID in order to achieve this operation, and will completely lower the Effective vector of the process before returning. Unlike the traditional method of dropping privilege when changing from [E]UID=0 to some other UID, this function only performs a change of UID cap.SETUID is available, and the action does not alter the Permitted Flag of the process' Set.

Types

type Flag 

type Flag uint

Flag is the type of one of the three Value dimensions held in a Set. It is also used in the (*IAB).Fill() method for changing the Bounding and Ambient Vectors. 

const (
	Effective Flag = iota
	Permitted
	Inheritable
)

Effective, Permitted, Inheritable are the three Flags of Values held in a Set.

func (Flag) String added in v0.2.41 

func (f Flag) String() string

String identifies a Flag value by its conventional "e", "p" or "i" string abbreviation.

type IAB 

type IAB struct {
	// contains filtered or unexported fields
}

IAB holds a summary of all of the inheritable capability vectors: Inh, Amb and Bound. The Bound vector is the logical inverse (two's complement) of the process' Bounding set. That is, raising a Value in the Bound (think blocked) vector is equivalent to dropping that Value from the process' Bounding set. This convention is used to support the empty IAB as being mostly harmless.

func IABFromText 

func IABFromText(text string) (*IAB, error)

IABFromText parses a string representing an IAB, as generated by IAB.String(), to generate an IAB.

func IABGetProc 

func IABGetProc() *IAB

IABGetProc summarizes the Inh, Amb and Bound capabilty vectors of the current process.

func IABInit 

func IABInit() *IAB

IABInit returns an empty IAB.

func (*IAB) Fill 

func (iab *IAB) Fill(vec Vector, c *Set, flag Flag) error

Fill fills one of the Inh, Amb and Bound capability vectors from one of the flag vectors of a Set. Note, filling the Inh vector will mask the Amb vector, and filling the Amb vector may raise entries in the Inh vector. Further, when filling the Bound vector, the bits are inverted from what you might expect - that is lowered bits from the Set will be raised in the Bound vector.

func (*IAB) GetVector 

func (iab *IAB) GetVector(vec Vector, val Value) (bool, error)

GetVector returns the raised state of the specific capability bit of the indicated vector.

func (*IAB) SetProc 

func (iab *IAB) SetProc() error

SetProc attempts to change the Inheritable, Ambient and Bounding capabilty vectors of the current process using the content, iab. The Bounding vector strongly affects the potential for setting other bits, so this function carefully performs the the combined operation in the most flexible manner.

func (*IAB) SetVector 

func (iab *IAB) SetVector(vec Vector, raised bool, vals ...Value) error

SetVector sets all of the vals in the specified vector to the raised value. Note, the Ambient vector cannot contain values not raised in the Inh vector, so setting values directly in one vector may have the side effect of mirroring the value in the other vector to maintain this constraint. Note, raising a Bound vector bit is equivalent to lowering the Bounding vector of the process (when successfully applied with (*IAB).SetProc()).

func (*IAB) String 

func (iab *IAB) String() string

String serializes an IAB to a string format.

type Launcher 

type Launcher struct {
	// contains filtered or unexported fields
}

Launcher holds a configuration for launching a child process with capability state different from (generally more restricted than) the parent.

Note, go1.10 is the earliest version of the Go toolchain that can support this abstraction.

func NewLauncher 

func NewLauncher(path string, args []string, env []string) *Launcher

NewLauncher returns a new launcher for the specified program path and args with the specified environment.

func (*Launcher) Callback 

func (attr *Launcher) Callback(fn func(*syscall.ProcAttr, interface{}) error)

Callback specifies a callback for Launch() to call before changing privilege. The only thing that is assumed is that the OS thread in use to call this callback function at launch time will be the one that ultimately calls fork. Any returned error value of said function will terminate the launch process. A nil callback (the default) is ignored. The specified callback fn should not call any "cap" package functions since this may deadlock or generate undefined behavior for the parent process.

func (*Launcher) Launch 

func (attr *Launcher) Launch(data interface{}) (int, error)

Launch performs a new program launch with security state specified in the supplied attr settings.

func (*Launcher) SetChroot 

func (attr *Launcher) SetChroot(root string)

SetChroot specifies the chroot value to be used by the launched command. An empty value means no-change from the prevailing value.

func (*Launcher) SetGroups 

func (attr *Launcher) SetGroups(gid int, groups []int)

SetGroups specifies the GID and supplementary groups for the launched command.

func (*Launcher) SetIAB 

func (attr *Launcher) SetIAB(iab *IAB)

SetIAB specifies the AIB capability vectors to be inherited by the launched command. A nil value means the prevailing vectors of the parent will be inherited.

func (*Launcher) SetMode 

func (attr *Launcher) SetMode(mode Mode)

SetMode specifies the libcap Mode to be used by the launched command.

func (*Launcher) SetUID 

func (attr *Launcher) SetUID(uid int)

SetUID specifies the UID to be used by the launched command.

type Mode 

type Mode uint

Mode summarizes a complicated secure-bits and capability mode in a libcap preferred way. 

const (
	ModeUncertain Mode = iota
	ModeNoPriv
	ModePure1EInit
	ModePure1E
)

ModeUncertain etc are how libcap summarizes security modes involving capabilities and secure-bits.

func GetMode 

func GetMode() Mode

GetMode assesses the current process state and summarizes it as a Mode. This function always succeeds. Unfamiliar modes are declared ModeUncertain.

func (Mode) Set 

func (m Mode) Set() error

Set attempts to enter the specified mode. An attempt is made to enter the mode, so if you prefer this operation to be a no-op if entering the same mode, call only if CurrentMode() disagrees with the desired mode.

This function will raise cap.SETPCAP in order to achieve this operation, and will completely lower the Effective Flag of the process' Set before returning. This function may fail for lack of permission or because (some of) the Secbits are already locked for the current process.

func (Mode) String 

func (m Mode) String() string

String returns the libcap conventional string for this mode.

type Secbits 

type Secbits uint

Secbits capture the prctl settable secure-bits of a process. 

const (
	SecbitNoRoot Secbits = 1 << iota
	SecbitNoRootLocked
	SecbitNoSetUIDFixup
	SecbitNoSetUIDFixupLocked
	SecbitKeepCaps
	SecbitKeepCapsLocked
	SecbitNoCapAmbientRaise
	SecbitNoCapAmbientRaiseLocked
)

SecbitNoRoot etc are the bitmasks associated with the supported Secbit masks. Source: uapi/linux/securebits.h

func GetSecbits 

func GetSecbits() Secbits

GetSecbits returns the current setting of the process' Secbits.

func (Secbits) Set 

func (s Secbits) Set() error

Set attempts to force the process Secbits to a value. This function will raise cap.SETPCAP in order to achieve this operation, and will completely lower the Effective vector of the process returning.

type Set 

type Set struct {
	// contains filtered or unexported fields
}

Set is an opaque capabilities container for a set of system capbilities. It holds individually addressable capability Value's for the three capability Flag's. See GetFlag() and SetFlag() for how to adjust them individually, and Clear() and ClearFlag() for how to do bulk operations.

For admin tasks associated with managing namespace specific file capabilities, Set can also support a namespace-root-UID value which defaults to zero. See GetNSOwner() and SetNSOwner().

func FromText 

func FromText(text string) (*Set, error)

FromText converts the canonical text representation for a Set into a freshly allocated Set.

The format follows the following pattern: a set of space separated sequences. Each sequence applies over the previous sequence to build up a Set. The format of a sequence is: 

[comma list of cap_values][[ops][flags]]*

Examples: 

"all=ep"
"cap_chown,cap_setuid=ip cap_setuid+e"
"=p cap_setpcap-p+i"

Here "all" refers to all named capabilities known to the hosting kernel, and "all" is assumed if no capabilities are listed before an "=".

The ops values, "=", "+" and "-" imply "reset and raise", "raise" and "lower" respectively. The "e", "i" and "p" characters correspond to the capabilities of the corresponding Flag: "e" (Effective); "i" (Inheritable); "p" (Permitted).

This syntax is overspecified and there are many ways of building the same final Set state. Any sequence that includes a '=' resets the accumulated state of all Flags ignoring earlier sequences. On each of the following lines we give three or more examples of ways to specify a common Set. The last entry on each line is the one generated by (*cap.Set).String() from that Set. 

"=p all+ei"  "all=pie"   "=pi all+e"   "=eip"

"cap_chown=p cap_setuid=i"  "cap_chown=ip-p"   "cap_chown=i"

"cap_chown=-p"   "all="   "cap_setuid=pie-pie"   "="

Note: FromText() is tested at release time to completely match the import ability of the libcap:cap_from_text() function.

func GetFd 

func GetFd(file *os.File) (*Set, error)

GetFd returns the file capabilities of an open (*os.File).Fd().

func GetFile 

func GetFile(path string) (*Set, error)

GetFile returns the file capabilities of a named file.

func GetPID 

func GetPID(pid int) (*Set, error)

GetPID returns the capability set associated with the target process id; pid=0 is an alias for current.

func GetProc 

func GetProc() *Set

GetProc returns the capability Set of the current process. If the kernel is unable to determine the Set associated with the current process, the function panic()s.

func Import 

func Import(d []byte) (*Set, error)

Import imports a Set from a byte array where it has been stored in a portable (lossless) way.

func NewSet 

func NewSet() *Set

NewSet returns an empty capability set.

func (*Set) Clear 

func (c *Set) Clear() error

Clear fully clears a capability set.

func (*Set) ClearFlag 

func (c *Set) ClearFlag(vec Flag) error

ClearFlag clears a specific vector of Values associated with the specified Flag.

func (*Set) Compare 

func (c *Set) Compare(d *Set) (uint, error)

Compare returns 0 if c and d are identical in content. Otherwise, this function returns a non-zero value of 3 independent bits: (differE ? 1:0) | (differP ? 2:0) | (differI ? 4:0). The Differs() function can be used to test for a difference in a specific Flag.

func (*Set) Dup 

func (c *Set) Dup() (*Set, error)

Dup returns a copy of the specified capability set.

func (*Set) Export 

func (c *Set) Export() ([]byte, error)

Export exports a Set into a lossless byte array format where it is stored in a portable way. Note, any namespace owner in the Set content is not exported by this function.

func (*Set) GetFlag 

func (c *Set) GetFlag(vec Flag, val Value) (bool, error)

GetFlag determines if the requested bit is enabled in the Flag vector of the capability Set.

func (*Set) GetNSOwner 

func (c *Set) GetNSOwner() (int, error)

GetNSOwner returns the namespace owner UID of the capability Set.

func (*Set) SetFd 

func (c *Set) SetFd(file *os.File) error

SetFd attempts to set the file capabilities of an open (*os.File).Fd(). This function can also be used to delete a file's capabilities, by calling with c = nil.

Note, Linux does not store the full Effective Value Flag in the metadata for the file. Only a single Effective bit is stored in this metadata. This single bit is non-zero if the Permitted vector has any overlapping bits with the Effective or Inheritable vector of c. This may appear suboptimal, but the reasoning behind it is sound. Namely, the purpose of the Effective bit it to support capabability unaware binaries that will only work if they magically launch with the needed bits already raised (this bit is sometimes referred to simply as the 'legacy' bit). Without *full* support for capability manipulation, as it is provided in this "../libcap/cap" package, this was the only way for Go programs to make use of capabilities.

The preferred way a binary will actually manipulate its file-acquired capabilities is to carefully and deliberately using this package (or libcap, assisted by libpsx, for threaded C/C++ family code).

func (*Set) SetFile 

func (c *Set) SetFile(path string) error

SetFile attempts to set the file capabilities of the specfied filename. This function can also be used to delete a file's capabilities, by calling with c = nil.

Note, see the comment for SetFd() for some non-obvious behavior of Linux for the Effective Value vector on the modified file.

func (*Set) SetFlag 

func (c *Set) SetFlag(vec Flag, enable bool, val ...Value) error

SetFlag sets the requested bits to the indicated enable state. This function does not perform any security checks, so values can be set out-of-order. Only when the Set is used to SetProc() etc., will the bits be checked for validity and permission by the kernel. If the function returns an error, the Set will not be modified.

func (*Set) SetNSOwner added in v0.2.41 

func (c *Set) SetNSOwner(uid int)

SetNSOwner adds an explicit namespace owner UID to the capability Set. This is only honored when generating file capabilities, and is generally for use by a setup process when installing binaries that use file capabilities to become capable inside a namespace to be administered by that UID. If capability aware code within that namespace writes file capabilities without explicitly setting such a UID, the kernel will fixup the capabilities to be specific to that owner. In this way, the kernel prevents filesystem capabilities from leaking out of that restricted namespace.

func (*Set) SetProc 

func (c *Set) SetProc() error

SetProc attempts to set the capability Set of the current process. The kernel will perform permission checks and an error will be returned if the attempt fails. Should the attempt fail no process capabilities will have been modified.

func (*Set) String 

func (c *Set) String() string

String converts a full capability Set into a single short readable string representation (which may contain spaces). See the cap.FromText() function for an explanation of its return values.

Note (*cap.Set).String() may evolve to generate more compact strings representing the a given Set over time, but it should maintain compatibility with the libcap:cap_to_text() function for any given release. Further, it will always be an inverse of cap.FromText().

type Value 

type Value uint

Value is the type of a single capability (or permission) bit. 

const (
	// CHOWN allows a process to arbitrarily change the user and
	// group ownership of a file.
	CHOWN Value = iota

	// DAC_OVERRIDE allows a process to override of all Discretionary
	// Access Control (DAC) access, including ACL execute
	// access. That is read, write or execute files that the
	// process would otherwise not have access to. This
	// excludes DAC access covered by cap.LINUX_IMMUTABLE.
	DAC_OVERRIDE

	// DAC_READ_SEARCH allows a process to override all DAC restrictions
	// limiting the read and search of files and
	// directories. This excludes DAC access covered by
	// cap.LINUX_IMMUTABLE.
	DAC_READ_SEARCH

	// FOWNER allows a process to perform operations on files, even
	// where file owner ID should otherwise need be equal to
	// the UID, except where cap.FSETID is applicable. It
	// doesn't override MAC and DAC restrictions.
	FOWNER

	// FSETID allows a process to set the S_ISUID and S_ISUID bits of
	// the file permissions, even when the process' effective
	// UID or GID/supplementary GIDs do not match that of the
	// file.
	FSETID

	// KILL allows a process to sent a kill(2) signal to any other
	// process - overriding the limitation that there be a
	// [E]UID match between source and target process.
	KILL

	// SETGID allows a process to freely manipulate its own GIDs:
	//   - arbitrarily set the GID, EGID, REGID, RESGID values
	//   - arbitrarily set the supplementary GIDs
	//   - allows the forging of GID credentials passed over a
	//     socket
	SETGID

	// SETUID allows a process to freely manipulate its own UIDs:
	//   - arbitraily set the UID, EUID, REUID and RESUID
	//     values
	//   - allows the forging of UID credentials passed over a
	//     socket
	SETUID

	// SETPCAP allows a process to freely manipulate its inheritable
	// capabilities.  Linux supports the POSIX.1e Inheritable
	// set, as well as Bounding and Ambient Linux extension
	// vectors. This capability permits dropping bits from the
	// Bounding vector. It also permits the process to raise
	// Ambient vector bits that are both raised in the
	// Permitted and Inheritable sets of the process. This
	// capability cannot be used to raise Permitted bits, or
	// Effective bits beyond those already present in the
	// process' permitted set.
	//
	// [Historical note: prior to the advent of file
	// capabilities (2008), this capability was suppressed by
	// default, as its unsuppressed behavior was not
	// auditable: it could asynchronously grant its own
	// Permitted capabilities to and remove capabilities from
	// other processes arbitraily. The former leads to
	// undefined behavior, and the latter is better served by
	// the kill system call.]
	SETPCAP

	// LINUX_IMMUTABLE allows a process to modify the S_IMMUTABLE and
	// S_APPEND file attributes.
	LINUX_IMMUTABLE

	// NET_BIND_SERVICE allows a process to bind to privileged ports:
	//   - TCP/UDP sockets below 1024
	//   - ATM VCIs below 32
	NET_BIND_SERVICE

	// NET_BROADCAST allows a process to broadcast to the network and to
	// listen to multicast.
	NET_BROADCAST

	// NET_ADMIN allows a process to perform network configuration
	// operations:
	//   - interface configuration
	//   - administration of IP firewall, masquerading and
	//     accounting
	//   - setting debug options on sockets
	//   - modification of routing tables
	//   - setting arbitrary process, and process group
	//     ownership on sockets
	//   - binding to any address for transparent proxying
	//     (this is also allowed via cap.NET_RAW)
	//   - setting TOS (Type of service)
	//   - setting promiscuous mode
	//   - clearing driver statistics
	//   - multicasing
	//   - read/write of device-specific registers
	//   - activation of ATM control sockets
	NET_ADMIN

	// NET_RAW allows a process to use raw networking:
	//   - RAW sockets
	//   - PACKET sockets
	//   - binding to any address for transparent proxying
	//     (also permitted via cap.NET_ADMIN)
	NET_RAW

	// IPC_LOCK allows a process to lock shared memory segments for IPC
	// purposes.  Also enables mlock and mlockall system
	// calls.
	IPC_LOCK

	// IPC_OWNER allows a process to override IPC ownership checks.
	IPC_OWNER

	// SYS_MODULE allows a process to initiate the loading and unloading
	// of kernel modules. This capability can effectively
	// modify kernel without limit.
	SYS_MODULE

	// SYS_RAWIO allows a process to perform raw IO:
	//   - permit ioper/iopl access
	//   - permit sending USB messages to any device via
	//     /dev/bus/usb
	SYS_RAWIO

	// SYS_CHROOT allows a process to perform a chroot syscall to change
	// the effective root of the process' file system:
	// redirect to directory "/" to some other location.
	SYS_CHROOT

	// SYS_PTRACE allows a process to perform a ptrace() of any other
	// process.
	SYS_PTRACE

	// SYS_PACCT allows a process to configure process accounting.
	SYS_PACCT

	// SYS_ADMIN allows a process to perform a somewhat arbitrary
	// grab-bag of privileged operations. Over time, this
	// capability should weaken as specific capabilities are
	// created for subsets of cap.SYS_ADMINs functionality:
	//   - configuration of the secure attention key
	//   - administration of the random device
	//   - examination and configuration of disk quotas
	//   - setting the domainname
	//   - setting the hostname
	//   - calling bdflush()
	//   - mount() and umount(), setting up new SMB connection
	//   - some autofs root ioctls
	//   - nfsservctl
	//   - VM86_REQUEST_IRQ
	//   - to read/write pci config on alpha
	//   - irix_prctl on mips (setstacksize)
	//   - flushing all cache on m68k (sys_cacheflush)
	//   - removing semaphores
	//   - Used instead of cap.CHOWN to "chown" IPC message
	//     queues, semaphores and shared memory
	//   - locking/unlocking of shared memory segment
	//   - turning swap on/off
	//   - forged pids on socket credentials passing
	//   - setting readahead and flushing buffers on block
	//     devices
	//   - setting geometry in floppy driver
	//   - turning DMA on/off in xd driver
	//   - administration of md devices (mostly the above, but
	//     some extra ioctls)
	//   - tuning the ide driver
	//   - access to the nvram device
	//   - administration of apm_bios, serial and bttv (TV)
	//     device
	//   - manufacturer commands in isdn CAPI support driver
	//   - reading non-standardized portions of PCI
	//     configuration space
	//   - DDI debug ioctl on sbpcd driver
	//   - setting up serial ports
	//   - sending raw qic-117 commands
	//   - enabling/disabling tagged queuing on SCSI
	//     controllers and sending arbitrary SCSI commands
	//   - setting encryption key on loopback filesystem
	//   - setting zone reclaim policy
	SYS_ADMIN

	// SYS_BOOT allows a process to initiate a reboot of the system.
	SYS_BOOT

	// SYS_NICE allows a process to maipulate the execution priorities
	// of arbitrary processes:
	//   - those involving different UIDs
	//   - setting their CPU affinity
	//   - alter the FIFO vs. round-robin (realtime)
	//     scheduling for itself and other processes.
	SYS_NICE

	// SYS_RESOURCE allows a process to adjust resource related parameters
	// of processes and the system:
	//   - set and override resource limits
	//   - override quota limits
	//   - override the reserved space on ext2 filesystem
	//     (this can also be achieved via cap.FSETID)
	//   - modify the data journaling mode on ext3 filesystem,
	//     which uses journaling resources
	//   - override size restrictions on IPC message queues
	//   - configure more than 64Hz interrupts from the
	//     real-time clock
	//   - override the maximum number of consoles for console
	//     allocation
	//   - override the maximum number of keymaps
	//
	//
	SYS_RESOURCE

	// SYS_TIME allows a process to perform time manipulation of clocks:
	//   - alter the system clock
	//   - enable irix_stime on MIPS
	//   - set the real-time clock
	SYS_TIME

	// SYS_TTY_CONFIG allows a process to manipulate tty devices:
	//   - configure tty devices
	//   - perform vhangup() of a tty
	SYS_TTY_CONFIG

	// MKNOD allows a process to perform privileged operations with
	// the mknod() system call.
	MKNOD

	// LEASE allows a process to take leases on files.
	LEASE

	// AUDIT_WRITE allows a process to write to the audit log via a
	// unicast netlink socket.
	AUDIT_WRITE

	// AUDIT_CONTROL allows a process to configure audit logging via a
	// unicast netlink socket.
	AUDIT_CONTROL

	// SETFCAP allows a process to set capabilities on files.
	SETFCAP

	// MAC_OVERRIDE allows a process to override Manditory Access Control
	// (MAC) access. Not all kernels are configured with a MAC
	// mechanism, but this is the capability reserved for
	// overriding them.
	MAC_OVERRIDE

	// MAC_ADMIN allows a process to configure the Mandatory Access
	// Control (MAC) policy. Not all kernels are configured
	// with a MAC enabled, but if they are this capability is
	// reserved for code to perform administration tasks.
	MAC_ADMIN

	// SYSLOG allows a process to configure the kernel's syslog
	// (printk) behavior.
	SYSLOG

	// WAKE_ALARM allows a process to trigger something that can wake the
	// system up.
	WAKE_ALARM

	// BLOCK_SUSPEND allows a process to block system suspends - prevent the
	// system from entering a lower power state.
	BLOCK_SUSPEND

	// AUDIT_READ allows a process to read the audit log via a multicast
	// netlink socket.
	AUDIT_READ

	// PERFMON allows a process to enable observability of privileged
	// operations related to performance. The mechanisms
	// include perf_events, i915_perf and other kernel
	// subsystems.
	PERFMON

	// BPF allows a process to manipulate aspects of the kernel
	// enhanced Berkeley Packet Filter (BPF) system. This is
	// an execution subsystem of the kernel, that manages BPF
	// programs. cap.BPF permits a process to:
	//   - create 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
	//     - potentially other features
	//
	// Other capabilities can be used together with cap.BFP to
	// further manipulate the BPF system:
	//   - cap.PERFMON relaxes the verifier checks as follows:
	//     - BPF programs can use pointer-to-integer
	//       conversions
	//     - speculation attack hardening measures can be
	//       bypassed
	//     - bpf_probe_read to read arbitrary kernel memory is
	//       permitted
	//     - bpf_trace_printk to print the content of kernel
	//       memory
	//   - cap.SYS_ADMIN permits the following:
	//     - use of bpf_probe_write_user
	//     - iteration over the system-wide loaded programs,
	//       maps, links BTFs and convert their IDs to file
	//       descriptors.
	//   - cap.PERFMON is required to load tracing programs.
	//   - cap.NET_ADMIN is required to load networking
	//     programs.
	BPF

	// CHECKPOINT_RESTORE allows a process to perform checkpoint
	// and restore operations. Also permits
	// explicit PID control via clone3() and
	// also writing to ns_last_pid.
	CHECKPOINT_RESTORE
)

CHOWN etc., are the named capability values of the Linux kernel. The canonical source for each name is the "uapi/linux/capabilities.h" file. Some values may not be available (yet) where the kernel is older. The actual number of capabities supported by the running kernel can be obtained using the cap.MaxBits() function.

func FromName 

func FromName(name string) (Value, error)

FromName converts a named capability Value to its binary representation.

func MaxBits 

func MaxBits() Value

MaxBits returns the number of kernel-named capabilities discovered at runtime in the current system.

func (Value) String 

func (v Value) String() string

String converts a capability Value into its canonical text representation.

type Vector 

type Vector uint

Vector enumerates which of the inheritable IAB capability vectors is being manipulated. 

const (
	Inh Vector = iota
	Amb
	Bound
)

Inh, Amb, Bound enumerate the IAB vector components. (Vector) Inh is equivalent to (Flag) Inheritable. They are named differently for syntax/type checking reasons.

func (Vector) String added in v0.2.41 

func (v Vector) String() string

String identifies a Vector value by its conventional I A or B string abbreviation.

Source Files

  • cap.go
  • convenience.go
  • file.go
  • flags.go
  • iab.go
  • launch.go
  • modern.go
  • names.go
  • oslocks.go
  • syscalls.go
  • text.go

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.