prompting

package
v0.0.0-...-e4d0a0c Latest Latest
Warning

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

 Go to latest Published: Jan 8, 2025 License: GPL-3.0 Imports: 13 Imported by: 4

Documentation

Overview

Package prompting provides common types and functions related to AppArmor prompting.

Index

Constants

This section is empty.

Variables

View Source 
var (

	// SupportedRuleLifespans is exported so interfaces/promptin/requestrules
	// can use it when constructing a ErrRuleLifespanSingle
	SupportedRuleLifespans = []string{string(LifespanForever), string(LifespanTimespan)}
)

Functions

func AbstractPermissionsFromAppArmorPermissions 

func AbstractPermissionsFromAppArmorPermissions(iface string, permissions any) ([]string, error)

AbstractPermissionsFromAppArmorPermissions returns the list of permissions corresponding to the given AppArmor permissions for the given interface.

func AbstractPermissionsToAppArmorPermissions 

func AbstractPermissionsToAppArmorPermissions(iface string, permissions []string) (any, error)

AbstractPermissionsToAppArmorPermissions returns AppArmor permissions corresponding to the given permissions for the given interface.

func AvailablePermissions 

func AvailablePermissions(iface string) ([]string, error)

AvailablePermissions returns the list of available permissions for the given interface.

func EnsureStateDir 

func EnsureStateDir() error

EnsureStateDir creates the state directory with appropriate permissions.

func StateDir 

func StateDir() string

StateDir returns the path to the prompting state directory.

Types

type Constraints 

type Constraints struct {
	PathPattern *patterns.PathPattern `json:"path-pattern"`
	Permissions PermissionMap         `json:"permissions"`
}

Constraints hold information about the applicability of a new rule to particular paths and permissions. When creating a new rule, snapd converts Constraints to RuleConstraints.

func (*Constraints) ContainPermissions 

func (c *Constraints) ContainPermissions(permissions []string) bool

ContainPermissions returns true if the permission map in the constraints includes every one of the given permissions.

This method is only intended to be called on constraints which have just been created from a reply, to check that the reply covers the request.

func (*Constraints) Match 

func (c *Constraints) Match(path string) (bool, error)

Match returns true if the constraints match the given path, otherwise false.

If the constraints or path are invalid, returns an error.

This method is only intended to be called on constraints which have just been created from a reply, to check that the reply covers the request.

func (*Constraints) ToRuleConstraints 

func (c *Constraints) ToRuleConstraints(iface string, currTime time.Time) (*RuleConstraints, error)

ToRuleConstraints validates the receiving Constraints and converts it to RuleConstraints. If the constraints are not valid with respect to the given interface, returns an error.

type IDType 

type IDType uint64

func IDFromString 

func IDFromString(idStr string) (IDType, error)

func (*IDType) MarshalJSON 

func (i *IDType) MarshalJSON() ([]byte, error)

func (IDType) String 

func (i IDType) String() string

func (*IDType) UnmarshalJSON 

func (i *IDType) UnmarshalJSON(b []byte) error

type LifespanType 

type LifespanType string

LifespanType describes the temporal scope for which a reply or rule applies. 

const (
	// LifespanUnset indicates that no lifespan was specified, and should only
	// be used while unmarshalling lifespan fields marked as omitempty.
	LifespanUnset LifespanType = ""
	// LifespanForever indicates that the reply/rule should never expire.
	LifespanForever LifespanType = "forever"
	// LifespanSingle indicates that a reply should only apply once, and should
	// not be used to create a rule.
	LifespanSingle LifespanType = "single"
	// LifespanTimespan indicates that a reply/rule should apply for a given
	// duration or until a given expiration timestamp.
	LifespanTimespan LifespanType = "timespan"
)

func (LifespanType) ParseDuration 

func (lifespan LifespanType) ParseDuration(duration string, currTime time.Time) (time.Time, error)

ParseDuration checks that the given duration is valid for the receiver lifespan and parses it into an expiration timestamp.

If the lifespan is LifespanTimespan, then duration must be a string parsable by time.ParseDuration(), representing the duration of time for which the rule should be valid. Otherwise, it must be empty. Returns an error if any of the above are invalid, otherwise computes the expiration time of the rule based on the given currTime and the given duration and returns it.

func (*LifespanType) UnmarshalJSON 

func (lifespan *LifespanType) UnmarshalJSON(data []byte) error

func (LifespanType) ValidateExpiration 

func (lifespan LifespanType) ValidateExpiration(expiration time.Time) error

ValidateExpiration checks that the given expiration is valid for the receiver lifespan.

If the lifespan is LifespanTimespan, then expiration must be non-zero. Otherwise, it must be zero. Returns an error if any of the above are invalid.

type Metadata 

type Metadata struct {
	// User is the UID of the subject (user) triggering the applicable requests.
	User uint32
	// Snap is the instance name of the snap for which the prompt or rule applies.
	Snap string
	// Interface is the interface for which the prompt or rule applies.
	Interface string
}

Metadata stores information about the origin or applicability of a prompt or rule.

type OutcomeType 

type OutcomeType string

OutcomeType describes the outcome associated with a reply or rule. 

const (
	// OutcomeUnset indicates that no outcome was specified, and should only
	// be used while unmarshalling outcome fields marked as omitempty.
	OutcomeUnset OutcomeType = ""
	// OutcomeAllow indicates that a corresponding request should be allowed.
	OutcomeAllow OutcomeType = "allow"
	// OutcomeDeny indicates that a corresponding request should be denied.
	OutcomeDeny OutcomeType = "deny"
)

func (OutcomeType) AsBool 

func (outcome OutcomeType) AsBool() (bool, error)

AsBool returns true if the outcome is OutcomeAllow, false if the outcome is OutcomeDeny, or an error if it cannot be parsed.

func (*OutcomeType) UnmarshalJSON 

func (outcome *OutcomeType) UnmarshalJSON(data []byte) error

type PermissionEntry 

type PermissionEntry struct {
	Outcome  OutcomeType  `json:"outcome"`
	Lifespan LifespanType `json:"lifespan"`
	Duration string       `json:"duration,omitempty"`
}

PermissionEntry holds the outcome associated with a particular permission and the lifespan for which that outcome is applicable.

PermissionEntry is used when replying to a prompt, creating a new rule, or modifying an existing rule.

type PermissionMap 

type PermissionMap map[string]*PermissionEntry

PermissionMap is a map from permissions to their corresponding entries, which contain information about the outcome and lifespan for those permissions.

type ReplyConstraints 

type ReplyConstraints struct {
	PathPattern *patterns.PathPattern `json:"path-pattern"`
	Permissions []string              `json:"permissions"`
}

ReplyConstraints hold information about the applicability of a reply to particular paths and permissions. Upon receiving the reply, snapd converts ReplyConstraints to Constraints.

func (*ReplyConstraints) ToConstraints 

func (c *ReplyConstraints) ToConstraints(iface string, outcome OutcomeType, lifespan LifespanType, duration string) (*Constraints, error)

ToConstraints validates the receiving ReplyConstraints with respect to the given interface, along with the given outcome, lifespan, and duration, and constructs an equivalent Constraints from the ReplyConstraints.

type RuleConstraints 

type RuleConstraints struct {
	PathPattern *patterns.PathPattern `json:"path-pattern"`
	Permissions RulePermissionMap     `json:"permissions"`
}

RuleConstraints hold information about the applicability of an existing rule to particular paths and permissions. A request will be matched by the rule constraints if the requested path is matched by the path pattern (according to bash's globstar matching) and one or more requested permissions are denied in the permission map, or all of the requested permissions are allowed in the map.

func (*RuleConstraints) Match 

func (c *RuleConstraints) Match(path string) (bool, error)

Match returns true if the constraints match the given path, otherwise false.

If the constraints or path are invalid, returns an error.

func (*RuleConstraints) ValidateForInterface 

func (c *RuleConstraints) ValidateForInterface(iface string, currTime time.Time) (expired bool, err error)

ValidateForInterface checks that the rule constraints are valid for the given interface. Any permissions which have expired relative to the given current time are pruned. If all permissions have expired, then returns true. If the rule is invalid, returns an error.

type RuleConstraintsPatch 

type RuleConstraintsPatch struct {
	PathPattern *patterns.PathPattern `json:"path-pattern,omitempty"`
	Permissions PermissionMap         `json:"permissions,omitempty"`
}

RuleConstraintsPatch hold partial rule contents which will be used to modify an existing rule. When snapd modifies the rule using RuleConstraintsPatch, it converts the RuleConstraintsPatch to RuleConstraints, using the rule's existing constraints wherever a field is omitted from the RuleConstraintsPatch.

Any permissions which are omitted from the new permission map are left unchanged from the existing rule. To remove an existing permission from the rule, the permission should map to null.

func (*RuleConstraintsPatch) PatchRuleConstraints 

func (c *RuleConstraintsPatch) PatchRuleConstraints(existing *RuleConstraints, iface string, currTime time.Time) (*RuleConstraints, error)

PatchRuleConstraints validates the receiving RuleConstraintsPatch and uses the given existing rule constraints to construct a new RuleConstraints.

If the path pattern or permissions fields are omitted, they are left unchanged from the existing rule. If the permissions field is present in the patch, then any permissions which are omitted from the patch's permission map are left unchanged from the existing rule. To remove an existing permission from the rule, the permission should map to null in the permission map of the patch.

The existing rule constraints should never be modified.

type RulePermissionEntry 

type RulePermissionEntry struct {
	Outcome    OutcomeType  `json:"outcome"`
	Lifespan   LifespanType `json:"lifespan"`
	Expiration time.Time    `json:"expiration,omitempty"`
}

RulePermissionEntry holds the outcome associated with a particular permission and the lifespan for which that outcome is applicable.

RulePermissionEntry is derived from a PermissionEntry after it has been used along with the rule's timestamp to define the expiration timeouts for any permissions which have a lifespan of "timespan". RulePermissionEntry is what is returned when retrieving rule contents, but PermissionEntry is used when replying to prompts, creating new rules, or modifying existing rules.

func (*RulePermissionEntry) Expired 

func (e *RulePermissionEntry) Expired(currTime time.Time) bool

Expired returns true if the receiving permission entry has expired and should no longer be considered when matching requests.

This is the case if the permission has a lifespan of timespan and the current time is after its expiration time.

type RulePermissionMap 

type RulePermissionMap map[string]*RulePermissionEntry

RulePermissionMap is a map from permissions to their corresponding entries, which contain information about the outcome and lifespan for those permissions.

func (RulePermissionMap) Expired 

func (pm RulePermissionMap) Expired(currTime time.Time) bool

Expired returns true if all permissions in the map have expired.

Source Files

View all Source files

Directories

Path Synopsis
The errors package defines common error types which are used across the prompting subsystems, along with constructors for specific errors based on those broader types.
 The errors package defines common error types which are used across the prompting subsystems, along with constructors for specific errors based on those broader types.
internal
maxidmmap
Package maxidmmap provides a type for working with atomically unique prompting-related IDs, backed by a memory mapped file.
 Package maxidmmap provides a type for working with atomically unique prompting-related IDs, backed by a memory mapped file.
Package patterns provides types and functions for working with path patterns for request rules related to AppArmor Prompting.
 Package patterns provides types and functions for working with path patterns for request rules related to AppArmor Prompting.
Package requestrules provides support for holding outstanding request prompts for AppArmor prompting.
 Package requestrules provides support for holding outstanding request prompts for AppArmor prompting.
Package requestrules provides support for storing request rules for AppArmor prompting.
 Package requestrules provides support for storing request rules for AppArmor prompting.

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.