Documentation
¶
Overview ¶
Package capabilities provides a ring-based Linux capabilities management system for Tracee. It implements a singleton pattern to manage process capabilities through different execution protection rings:
- Full: All capabilities are effective (least secure)
- EBPF: eBPF needed capabilities + Base capabilities
- Specific: Specific requested capabilities + Base capabilities
- Base: Capabilities that are always effective (most secure)
The package supports a bypass mode (Bypass=true) where capability changes are tracked in memory but not applied to the actual process, allowing testing and development without root privileges.
Index ¶
- func Initialize(cfg Config) error
- func ListAvailCaps() []string
- func ReqByString(values ...string) ([]cap.Value, error)
- type Capabilities
- func (c *Capabilities) BaseRingAdd(values ...cap.Value) error
- func (c *Capabilities) BaseRingRemove(values ...cap.Value) error
- func (c *Capabilities) EBPF(cb func() error) error
- func (c *Capabilities) EBPFRingAdd(values ...cap.Value) error
- func (c *Capabilities) EBPFRingRemove(values ...cap.Value) error
- func (c *Capabilities) Full(cb func() error) error
- func (c *Capabilities) Specific(cb func() error, values ...cap.Value) error
- type Config
- type RingType
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Initialize ¶
Initialize initializes the capabilities singleton instance with the given configuration. This function is thread-safe and will only initialize once, even if called multiple times.
When Bypass is true, the capabilities manager operates in bypass mode where capability changes are tracked but not applied to the process.
Returns an error if initialization fails (e.g., unable to read process capabilities when Bypass is false).
func ListAvailCaps ¶
func ListAvailCaps() []string
ListAvailCaps lists available capabilities in the running environment
func ReqByString ¶
ReqByString converts capability string names to cap.Value types. It accepts one or more capability names (e.g., "CAP_SYS_ADMIN", "CAP_NET_ADMIN") and returns the corresponding cap.Value slice.
Returns an error if any of the provided capability names are invalid or not found. Example:
values, err := ReqByString("CAP_SYS_ADMIN", "CAP_NET_ADMIN")
if err != nil {
return err
}
Types ¶
type Capabilities ¶
type Capabilities struct {
// contains filtered or unexported fields
}
Capabilities manages Linux capabilities through a ring-based execution model. It provides methods to temporarily elevate capabilities for specific operations and automatically return to the base ring afterward.
The struct uses a singleton pattern and should be accessed via GetInstance() or Initialize(). When Bypass is true, capability changes are tracked in memory but not applied to the actual process.
func GetInstance ¶
func GetInstance() *Capabilities
GetInstance returns the current capabilities instance, initializing it if needed. If the instance doesn't exist, it auto-initializes with Bypass=true and BaseEbpf=false.
This is the recommended way to access the capabilities manager for most use cases. Returns nil if initialization fails.
func (*Capabilities) BaseRingAdd ¶
func (c *Capabilities) BaseRingAdd(values ...cap.Value) error
BaseRingAdd adds the specified capabilities to the base ring and propagates them to all other rings (EBPF and Specific). Base ring capabilities are always effective regardless of the current ring.
Internal state is always updated and changes are immediately applied. In bypass mode, system calls are skipped but state tracking continues. Returns an error if any of the specified capabilities are invalid.
func (*Capabilities) BaseRingRemove ¶
func (c *Capabilities) BaseRingRemove(values ...cap.Value) error
BaseRingRemove removes the specified capabilities from the base ring and all other rings (EBPF and Specific). Base ring capabilities are always effective, so removing them affects all rings.
Internal state is always updated and changes are immediately applied. In bypass mode, system calls are skipped but state tracking continues. Returns an error if any of the specified capabilities are invalid.
func (*Capabilities) EBPF ¶
func (c *Capabilities) EBPF(cb func() error) error
EBPF temporarily elevates to the EBPF ring (eBPF capabilities + base), executes the callback, then returns to the Base ring.
When baseEbpf is true, this method executes the callback without switching rings (since eBPF caps are already available). In bypass mode, system calls are skipped but state tracking continues.
The callback's error is returned. If an error occurs during ring switching, it is wrapped and returned.
func (*Capabilities) EBPFRingAdd ¶
func (c *Capabilities) EBPFRingAdd(values ...cap.Value) error
EBPFRingAdd adds the specified capabilities to the EBPF ring. These capabilities will be available when switching to the EBPF ring.
Returns an error if any of the specified capabilities are invalid.
func (*Capabilities) EBPFRingRemove ¶
func (c *Capabilities) EBPFRingRemove(values ...cap.Value) error
EBPFRingRemove removes the specified capabilities from the EBPF ring. These capabilities will no longer be available when switching to the EBPF ring.
Returns an error if any of the specified capabilities are invalid.
func (*Capabilities) Full ¶
func (c *Capabilities) Full(cb func() error) error
Full temporarily elevates to the Full ring (all capabilities enabled), executes the callback, then returns to the Base ring.
When bypass mode is enabled, this method executes the callback without actually changing capabilities.
The callback's error is returned. If an error occurs during ring switching, it is wrapped and returned.
func (*Capabilities) Specific ¶
func (c *Capabilities) Specific(cb func() error, values ...cap.Value) error
Specific temporarily enables the specified capabilities in the Specific ring, executes the callback, then returns to the Base ring and cleans up the Specific ring.
The Specific ring is cleaned up before the callback executes (internal state only). The process capabilities remain active during the callback, but the internal state is cleared to ensure it doesn't affect subsequent calls. In bypass mode, system calls are skipped but state tracking continues.
The callback's error is returned. If an error occurs during ring operations, it is wrapped and returned.
type Config ¶
type Config struct {
// Bypass, when true, disables actual capability changes and operates
// entirely in memory. Useful for testing and development without root.
Bypass bool
// BaseEbpf, when true, adds eBPF-related capabilities to the base ring
// instead of the eBPF ring. This means eBPF capabilities are always
// available without needing to switch to the EBPF ring.
BaseEbpf bool
}
Config holds configuration options for initializing the capabilities manager.
type RingType ¶
type RingType int
RingType represents the execution protection ring level for capabilities. Rings provide different levels of capability access, with Base being the most restrictive and Full being the least restrictive.
const ( // Full ring enables all capabilities. This is the least secure mode // and should only be used when necessary. Full RingType = iota // EBPF ring enables eBPF-related capabilities plus base capabilities. // Used for eBPF operations that require specific Linux capabilities. EBPF // Specific ring enables only the requested capabilities plus base capabilities. // Used for operations that need temporary access to specific capabilities. Specific // Base ring contains capabilities that are always effective. // This is the default and most secure ring. Base )
Source Files