perms

Documentation

Overview

Package perms defines permissions used to control access to LUCI Analysis resources, and related methods.

Index

• Variables
• func HasProjectPermission(ctx context.Context, project string, permission realms.Permission) (bool, error)
• func QueryRealms(ctx context.Context, project string, attrs realms.Attrs, ...) ([]string, error)
• func QueryRealmsNonEmpty(ctx context.Context, project string, attrs realms.Attrs, ...) ([]string, error)
• func QuerySubRealmsNonEmpty(ctx context.Context, project, subRealm string, attrs realms.Attrs, ...) ([]string, error)
• func SplitRealm(realm string) (proj string, subRealm string, err error)
• func SplitRealms(realms []string) (proj string, subRealms []string, err error)
• func VerifyPermissions(ctx context.Context, realm string, attrs realms.Attrs, ...) error
• func VerifyProjectPermissions(ctx context.Context, project string, permissions ...realms.Permission) error

Variables

var (
	// Grants access to reading individual LUCI Analysis rules in a LUCI
	// project, except for the rule definition (i.e.
	// 'reason LIKE "%criteria%"'.).
	//
	// This also permits the user to see the identity of the configured
	// issue tracker for a project. (This is available via the URL
	// provided for bugs on a rule and via a separate config RPC.)
	PermGetRule = realms.RegisterPermission("analysis.rules.get")

	// Grants access to listing all rules in a LUCI project,
	// except for the rule definition (i.e. 'reason LIKE "%criteria%"'.).
	//
	// This also permits the user to see the identity of the configured
	// issue tracker for a project. (This is available via the URL
	// provided for bugs on a rule.)
	PermListRules = realms.RegisterPermission("analysis.rules.list")

	// Grants permission to get a cluster in a project.
	// This encompasses the cluster ID and aggregated impact for
	// the cluster (over all failures, not just those the user can see).
	//
	// Seeing failures in a cluster is contingent on also having
	// having "resultdb.testResults.list" permission in ResultDB
	// for the realm of the test result.
	//
	// This permission also allows the user to obtain LUCI Analysis's
	// progress reclustering failures to reflect new rules, configuration
	// and algorithms.
	PermGetCluster = realms.RegisterPermission("analysis.clusters.get")

	// Grants permission to list all clusters in a project.
	// This encompasses the cluster identifier and aggregated impact for
	// the clusters (over all failures, not just those the user can see).
	// More detailed cluster information, including cluster definition
	// and failures is contingent on being able to see failures in the
	// cluster.
	PermListClusters = realms.RegisterPermission("analysis.clusters.list")

	// PermGetClustersByFailure allows the user to obtain the cluster
	// identit(ies) matching a given failure.
	PermGetClustersByFailure = realms.RegisterPermission("analysis.clusters.getByFailure")

	// Grants permission to get project configuration, such
	// as the configured monorail issue tracker. Controls the
	// visibility of the project in the LUCI Analysis main page.
	//
	// Can be assumed this is also granted wherever the user has
	// been granted one of the analysis.rules.* or analysis.clusters.*
	// create/update/list/get permissions for a project;
	// many parts of LUCI Analysis rely on LUCI Analysis configuration and
	// there is no need to perform gratuitous access checks.
	PermGetConfig = realms.RegisterPermission("analysis.config.get")
)

Permissions that should usually be granted to all users that can view a project.

var (
	// Grants permission to create a rule.
	// Should be granted only to trusted project contributors.
	PermCreateRule = realms.RegisterPermission("analysis.rules.create")

	// Grants permission to update all rules in a project.
	// Permission to update a rule also implies permission to get the rule
	// and view the rule definition as the modified rule is returned in the
	// response to the UpdateRule RPC.
	// Should be granted only to trusted project contributors.
	PermUpdateRule = realms.RegisterPermission("analysis.rules.update")
)

Mutating permissions.

var (
	// Grants permission to get a test variant branch in a project.
	PermGetTestVariantBranch = realms.RegisterPermission("analysis.testvariantbranches.get")

	// Grants permission to list all test variant branches in a project.
	// This includes the test ID, variant definition, source ref definition
	// and segments identified by changepoint analysis.
	PermListTestVariantBranches = realms.RegisterPermission("analysis.testvariantbranches.list")

	// Grants permission to get a changepoint group in a project.
	// A changepoint group is a set of changepoints with similar
	// test id and regression range.
	PermGetChangepointGroup = realms.RegisterPermission("analysis.changepointgroups.get")

	// Grants permission to list all changepoint groups in a project.
	// A changepoint group is a set of changepoints with similar
	// test id and regression range.
	PermListChangepointGroups = realms.RegisterPermission("analysis.changepointgroups.list")
)

Permissions for viewing changepoint analysis. These are granted at the project-level. They allow the user to enumerate all test variant branches (including variant definition and source ref definition) in a project as well as their segments.

var (
	ErrInvalidRealm     = errors.New("realm must be in the format <project>:<realm>")
	ErrMultipleProjects = errors.New("all realms must be from the same projects")
)

var ListTestResultsAndExonerations = []realms.Permission{
	rdbperms.PermListTestResults,
	rdbperms.PermListTestExonerations,
}

Permissions used to control access to test results.

var (
	// Grants access to reading the rule definition of LUCI Analysis rules.
	PermGetRuleDefinition = realms.RegisterPermission("analysis.rules.getDefinition")
)

The following permission grants view access to the rule definition, which could be sensitive if test names or failure reasons reveal sensitive product or hardware data.

Functions

func HasProjectPermission

func HasProjectPermission(ctx context.Context, project string, permission realms.Permission) (bool, error)

HasProjectPermission returns if the caller has the given permission in the @project realm of the given project. This method only returns an error if there is some AuthDB issue.

func QueryRealms

func QueryRealms(ctx context.Context, project string, attrs realms.Attrs, permissions ...realms.Permission) ([]string, error)

QueryRealms is a wrapper around luci/server/auth.QueryRealms that returns a list of realms where the current caller has all the listed permissions.

A project is required.

The permissions should be flagged in the process with UsedInQueryRealms flag, which lets the runtime know it must prepare indexes for the corresponding QueryRealms call.

func QueryRealmsNonEmpty

func QueryRealmsNonEmpty(ctx context.Context, project string, attrs realms.Attrs, permissions ...realms.Permission) ([]string, error)

QueryRealmsNonEmpty is similar to QueryRealms but it returns an appstatus annotated error if there are no realms that the user has all of the given permissions in.

func QuerySubRealmsNonEmpty

func QuerySubRealmsNonEmpty(ctx context.Context, project, subRealm string, attrs realms.Attrs, permissions ...realms.Permission) ([]string, error)

QuerySubRealmsNonEmpty is similar to QueryRealmsNonEmpty with the following differences:

1. an optional subRealm argument allows results to be limited to a specific realm (matching `<project>:<subRealm>`).
2. a list of subRealms is returned instead of a list of realms (e.g. ["realm1", "realm2"] instead of ["project:realm1", "project:realm2"])

func SplitRealm

func SplitRealm(realm string) (proj string, subRealm string, err error)

SplitRealm splits the realm into the LUCI project name and the (sub)realm. Returns ErrInvalidRealm if the provided realm doesn't have a valid format.

func SplitRealms

func SplitRealms(realms []string) (proj string, subRealms []string, err error)

SplitRealms splits the realms into the LUCI project name and the (sub)realms. All realms must belong to the same project.

Returns ErrInvalidRealm if any of the realm doesn't have a valid format. Returns ErrMultipleProjects if not all realms are from the same project.

func VerifyPermissions

func VerifyPermissions(ctx context.Context, realm string, attrs realms.Attrs, permissions ...realms.Permission) error

VerifyPermissions is a wrapper around luci/server/auth.HasPermission that checks whether the user has all the listed permissions and return an appstatus annotated error if users have no permission.

func VerifyProjectPermissions

func VerifyProjectPermissions(ctx context.Context, project string, permissions ...realms.Permission) error

VerifyProjectPermissions verifies the caller has the given permissions in the @project realm of the given project. If the caller does not have permission, an appropriate appstatus error is returned, which should be returned immediately to the RPC caller.