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 says | meaning |
|---|---|
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):
| verdict | meaning |
|---|---|
refused | the actor's roles would be refused here. The why is the refusal the security engine gives, which says what to grant |
maybe | the 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?#
- Run it on an app that has no
RunsAsyet. The proposed actor holds no role, so the list is everything the bodies write. - 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. - Name it in the workflow, and run the report again. What is still
refusedis a body that does something its author did not mean it to;mayberows are read by hand. - 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 noRunsAsin an app that has a[Principal]carriesWORKFLOW_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) ismaybe. - 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#
- Who a workflow body runs as — and what it may write — who a workflow body runs as
- [Actor] — a principal that code may run as — declaring the actor and granting it
- Checking every project at once — osy validate --all / --affected —
osy validate --all, the same check over every project - Checking your app —
osy validatefor one project