Osy#betaRun it on Osyrin: osyrin.com

Reference / Local

Checking what a workflow's actor would be refused — osy validate --runs-as

osy validate --runs-as [--json]

`osy validate --runs-as` is a read-only report for the move from "a workflow body runs as the system" to "a workflow declares who it runs as". For each workflow, `[On]` handler and `[OnStart]` hook it names the actor the body runs as — the declared `RunsAs`, or a proposed actor that holds no role when there is none — and every write or `[Authorize]` call, through the functions the body calls, that actor's roles would be refused. Each row is a grant you owe the actor, or a line to look at by hand. It changes nothing and is not an error.

previewlocalclivalidateworkflow

Summary#

A workflow that declares RunsAs = BillingRobot; answers to what BillingRobot may do under your security { } rules (Who a workflow body runs as — and what it may write). Before you name the actor you want to know what it will be refused; after, whether the roles you gave it are enough. osy validate --runs-as answers both from the compiled model, and the answer is the security engine's own: the model is loaded for a caller who holds the actor's roles, and every write the body can make is put to the same check a request would be.

$ cd demo/release-canary && osy validate --runs-as
start-hook EnsureCanaryAccount runs as proposed EnsureCanaryAccountActor (no role): 2 write/authorize site(s), 2 refused, 0 maybe
    refused create Osysharp.Identity.RoleGrant.Member,Role  (line 43) — Create of 'Osysharp.Identity.RoleGrant' denied — no `create` rule is active for this caller. It grants `create` under: `IsAuthenticator`. …
    refused create Osysharp.UserAccounts.User.Email,DisplayName,PasswordHash,EmailVerifiedAt  (line 41) — Create of 'Osysharp.UserAccounts.User' denied — `deny create when !IsAuthenticator`, … 
workflow CanaryFlow runs as proposed CanaryFlowActor (no role): 1 write/authorize site(s), 0 refused, 0 maybe
runs-as: 1 workflows, 0 handlers, 2 start hooks; 5 refused writes, 0 maybes; 7 workflows from used packages not counted (report on the package)

Signature#

osy validate --runs-as           # the report as text, one block per workflow, handler and start hook
osy validate --runs-as --json    # { items: [{ kind, name, package, actor, proposed, roles, writes, rows: [{ verdict, kind, entity, fields, via, why, line }] }], workflowsFromOtherPackages }

Exit code: 0 the report was made, whatever it says · 1 the project does not validate and compile (fix what osy validate reports first, then ask again).

Description#

What is reported?#

One item per workflow, per [On] handler and per [OnStart] hook of the project. Its heading line says who the body runs as and how many write or [Authorize] sites it reaches:

the heading saysmeaning
runs as BillingRobot [Billing]the declared RunsAs, and the roles its declaration names
runs as proposed XActor (no role)nothing is declared (also for a handler or hook that names none), so the report takes an actor that holds no role: every refused row is a grant the move owes it
runs as System []RunsAs = System;: the body is not judged as anyone, so no rows are listed

Under it, a row per distinct site — one entity, its fields and the operation, collapsed over the functions the body calls (via, with the line):

verdictmeaning
refusedthe actor's roles would be refused here. The why is the refusal the security engine gives, which says what to grant
maybethe report cannot decide: the grant holds only over some rows (a where), the call carries [Authorize(SomePolicy)] (a policy is not evaluated), or the call cannot be followed (a virtual or unresolved one)

A write inside runas (Other) { … } is the other actor's and is not listed as a refusal of the body. A kit's own workflow is judged with the kit's plain denies waived, as it runs ([[workflow-body-security#kit-deny]]). The last line sums the project; workflows that belong to a package the project uses are counted there, not listed — run the report on the package.

How do I use it?#

  1. Run it on an app that has no RunsAs yet. The proposed actor holds no role, so the list is everything the bodies write.
  2. Declare the actor with the narrowest roles that make sense ([Actor] — a principal that code may run as), or grant by identity — allow create when user == Actor.Of<BillingRobot>() — for a row only that actor writes.
  3. Name it in the workflow, and run the report again. What is still refused is a body that does something its author did not mean it to; maybe rows are read by hand.
  4. A body that names a member its actor cannot read is warned separately (WORKFLOW_ACTOR_READS_A_HIDDEN_MEMBER, [[security-declared-actor#hidden-reads]]), and a workflow with no RunsAs in an app that has a [Principal] carries WORKFLOW_RUNS_AS_THE_SYSTEM ([[workflow-body-security#system]]).

What it does not see#

  • Roles only: a rule the roles pass but that also asks the data (where Owner == user) is maybe.
  • It does not run anything. A write reached through a call it cannot follow, or one decided by a value, may be missing or listed as maybe.

See also#

Related

Who a workflow body runs as — and what it may write

A workflow names who its bodies run as: `RunsAs = BillingRobot;`, a class marked `[Actor]`. Every body — `enter`…

[Actor] — a principal that code may run as

A class marked `[Actor]` declares a principal that code may run as: a robot, a nightly job, an integration, a digital…

Checking your app

Checks your app against production best-practice rules and reports where it falls short — the maturity signal, beside…

Checking every project at once — osy validate --all / --affected

One command, one verdict, for a repository that holds many projects: `osy validate --all` finds every app and package…

role grants (and the first admin)

A role is granted by an ordinary entity you mark `[RoleGrant]` — one that holds a reference to your `[Principal]` and a…