# How it works

The parts of Straza, and how Straza decides each tool call before the tool runs.

In short: Your IGA, or an admin on standalone, decides who holds which role. Straza decides what each role may do. It checks each governed tool call before the tool runs, on the agent's machine or at the gateway in front of your MCP servers. A rule can ask a person first. Straza writes an audit record of every decision.


Diagram:ThecorepartsofStraza.Eachconceptpageopenswiththisdiagramandhighlightsthepartitexplains.ThepartsofStraza.Apersonsponsorsanagent,andtheagentcallsatool.Strazachecksthecallagainsttheagent’srolesandthepolicy,andarulecanaskapersontoapproveit.Anallowedcallrunsthetool,ontheagent’smachineforalocaltoolsuchasashellcommand,oronanMCPserver,whereatoolactsonanobject.Youridentityprovidercheckssign-in,yourIGAsayswhoholdswhichrole,anagentorapersonproposesachangeasadraftandapersonpublishesit,andeverydecisionbecomesanauditrecord.Eachpartlinkstoitspage.1.YourIGA,oranadminonstandalone,tellsStrazawhothepeopleandagentsareandwhichrolestheyhold.Apersonsignsinatyouridentityprovider,oratstrazaditselfonthestandaloneprofile.2.Anagentaskstocallatool.Atoolonitsownmachine,suchasashellcommand,isdecidedtherebytheStrazaservice,whichthestrazahookasks.AtoolofanMCPserverbehindStrazaisdecidedatthegateway.3.Therolesofthesessionsetwhatitreaches.Atthegatewayarolenamesthetoolsitmaycalland,onaserverthatdeclaresobjects,whichobjects.Onamachinetherolespickwhichpolicyapplies.4.Thepolicythenallowsthecall,deniesit,orasksaperson.Onthemachinetheagentreadsthereason,andatthegatewayatooldeniedforthewholesessionisleftoutofitslist.5.Aheldcallwaitsforaperson:aholderofanapproverrolethattherulenames,orelsetherequester’ssponsor.Apersonwithnosponsorsaysyesthemselvesonanenrolledphoneorbrowser.6.Anallowedcallruns.Atthegateway,Strazaaddstheserver’scredential,sotheagentneverholdsit.7.Everydecisionbecomesanauditrecordinahashchain,whichStrazacansendtoyourSIEM.8.Achangetoservers,rolesorpolicyisadraft.Anagentcanproposeone,anditwaitsuntilapersonpublishesit.Bydefaultanadmin’sownchangepublishesatonce.Ontheenterpriseprofile,youridentityprovidercheckswhosignsin,andyourIGAsayswhoholdswhichrole.Onstandalone,strazadsignspeoplein,andanadmininStrazaassignstheroles.##Theparts|Part|Whatitis|Whereitcomesfrom||---|---|---||[Person](https://docs.straza.ai/concepts/identities/index.md)|Ahumanuser.Onenterprisetheysigninatyouridentityprovider,andonstandalonestrazadsignstheminwithapassword.|YourIGAoverSCIM,oranadminonstandalone||[Agent](https://docs.straza.ai/concepts/identities/index.md)|AnAIagent.AcodingagentsuchasClaudeCoderunsasitsperson.Anagentwithitsownidentityisauserofitsown,withakeyinsteadofapassword.|YourIGAoverSCIM,oranadminonstandalone||[Sponsor](https://docs.straza.ai/concepts/identities/index.md)|Thepersonaccountableforanagent,orforanyuserwhohasone.Aheldcallwhoserulenamesnoapproverrolegoestotherequester'ssponsor.|YourIGA,oranadminonstandalone||[Role](https://docs.straza.ai/concepts/roles-and-access/index.md)|Whatitsholdersmaydo.Anapplicationrolegrantstoolsononeserver,orpickswhichpolicyappliestolocaltools.Businessrolesgroupapplicationroles,approverrolesdecideheldcalls,andStrazarolescarryrightsinStrazaitself.|MadeinStraza.YourIGA,oranadminonstandalone,assignsit||[Server](https://docs.straza.ai/concepts/mcp-apps-and-the-gateway/index.md)|AnMCPserverbehindStraza'sgateway,describedbyitsmanifest.|AddedinStraza||Tool|Oneactionanagentcantake:atoolofaserver,oralocalonesuchasashellcommand.|Theserver,ortheagent'scodingtool||[Object](https://docs.straza.ai/concepts/objects/index.md)|Onethingaserver'stoolsacton,suchasarepositoryoradatabase,onaserverthatdeclaresthem.|Theserver'sownlist||[Policy](https://docs.straza.ai/concepts/policy-model/index.md)|Rulesthatallowacall,denyit,oraskapersonfirst.|WritteninStraza||[Approval](https://docs.straza.ai/concepts/approvals-model/index.md)|Aperson'syesornoonaheldcall.|Theconsole,abrowser,aphoneorSlack||[Draft](https://docs.straza.ai/concepts/drafts/index.md)|Aproposedchangetoservers,rolesorpolicy.Adraftanagentproposeswaitsuntilapersonpublishesit.|Apersonoranagent||[Auditrecord](https://docs.straza.ai/concepts/evidence/index.md)|Onerecordforeachdecision,sign-inandchange,linkedtotheonebeforeitinahashchain.|WrittenbyStraza,andsentontoyourSIEM|##HowatoolcallisdecidedStrazadecideseachgovernedtoolcallbeforethetoolruns.Thesamepolicyenginedecidesontheagent'smachineandatthegateway,soarulemeansthesamethinginbothplaces.||Ontheagent'smachine|Atthegateway||---|---|---||Thetool|Alocaltool,suchasashellcommandorafilewrite|AtoolofanMCPserverbehindStraza||Whoasks|Thecodingtoolasksthestrazahook|Theagent'sMCPclientcallsStraza'sgatewayinsteadoftheserver||Whodecides|TheStrazaserviceonthesamemachine,fromasignedcopyofyourpolicy,sothedecisiondoesnotwaitonthenetwork|strazad,whichlistsonlythetoolsthesession'srolesreachandcheckstheobjectacallnamesbeforethepolicyruns||Afteranallow|Thetoolruns|strazadaddstheserver's[credential](https://docs.straza.ai/concepts/credentials/index.md)andpassesthecallon,sotheagentneverholdsit||Afteradeny|Theagentreadstherule'sreason|Bydefaultatooldeniedforthewholesessionishiddenandreadsasunknown|Acalltoaserverbehindthegatewayalsopassesthehook.Thehookleavesthewholedecisiontothegateway,sothecallisnotdecidedtwice.Anagentwithnohookscanruneachcommandthrough`strazaexec`,whichdecidesthatcommandthesamewaybeforeitruns.Itdoesnotdecidewhatthecommandthenstarts.Strazadoesnotseeanactionthattakesnoneofthesepaths,as[Thesecuritymodel](https://docs.straza.ai/evaluate/security-model/index.md)setsout.##WhenStrazacannotdecideStrazafailsclosed.Acallendsinadenywhentheservicedoesnotanswer,orwhenaruleneedsstrazadandstrazadcannotbereached.Thedenynamesthecauseandthenextstep.Whenstrazadcannotbereached,asessionkeepsdecidingfromitsverifiedcopyofthepolicyuntilitstokenrunsout.Standalonethenaddsagraceperiodof15minutes,andenterpriseaddsnone.Afterthat,thesessiondeniesitscalls.Abaddeployofstrazadthereforestopseveryenterpriseagentwithinfiveminutes.Allowingcallsonerrorwouldleaveagentsungovernedforthewholeoutage.##WhenaccessistakenawayDisablingauser,overSCIMfromyourIGAorbyanadmininStraza,revokeseverysessionofthatuserandrefusesnewones.Thegatewayrefusesarevokedsessiononitsnextcall.Ontheagent'smachine,theservicelearnsofitatonceoverthesession'spushstream.Whilethatstreamisdown,itlearnsatthenextrenewalofthesession's300-secondtoken.Theoutcomesarulecanpick:Therulethatwinsdecidesthecall.Adenyisfinal.Awinningallowcancarryamodethataddsonemorestepbeforethetoolruns.|Outcome|Whathappens|Whattheagentsees||---|---|---||<spanclass="chipallow">allow</span>|Thetoolruns.|Nothing.Thecallgoesthrough.||<spanclass="chipdeny">deny</span>|Thetooldoesnotrun.|Onthemachine,therule'sreason,whichitshouldpassontoyouinsteadofretrying.Atthegateway,bydefault,atoolthataruledeniesforthewholesessionismissingfromthesession'slist.||<spanclass="chiphold">approve</span>|Apersondecidesfirst:aholderofanapproverroletherulenames,orelsetherequester'ssponsor.Apersonwithnosponsordecidestheirownrequestonanenrolledphoneorbrowser.|Areferencetotherequest.Thegatewayholdsthecallopenfortherule'sdecisionwindowfirst,90secondsbydefaultandatmost120,andonahooktheagentcallsagainafterthedecision.||<spanclass="chiphold">confirm</span>|Onlythepersonbehindtherequestcansayyes.Anagentwithnopersonbehinditisdenied.|Thesameasforapprove,untilthatpersonconfirms.||<spanclass="chipplain">serverCheck</span>|strazaddecidesthecallagainwiththelivepolicy,andanunreachableservermeansadeny.|Allowordeny,asabove.||<spanclass="chipplain">classify</span>|Abuilt-incheckreadsthecommandfirst,suchasadownloadpipedintoashell,anddenieswhenitcannotanswerwithinonesecond.|Allow,oradenythatnamesthesignalitfound.|Whennorulefires,thedefaultdependsonwherethecallruns.Alocaltoolisallowedonstandaloneanddeniedonenterprise.Atthegateway,atoolarolegrantsrunsunlessaruledeniesitorholdsitforaperson.[Policies](https://docs.straza.ai/concepts/policy-model/index.md)explainshowrulesmatchandcombine,and[Approvals](https://docs.straza.ai/concepts/approvals-model/index.md)coverswhodecides.[Lifetimesandtimeouts](https://docs.straza.ai/reference/lifetimes-and-timeouts/index.md#approvals)listshowlongeachwaitlasts.Howthepolicyreacheseachmachine:Apersonpublishesachangetoapolicyset,oranadminactivatesone.strazadcompileseverylivesetintoasinglesnapshotandsignsitwithEd25519.Thesnapshot'sidistheSHA-256ofthesignedbytes,sotheidproveswhichbytesamachineholds.Theserviceoneachmachinefetchesthesnapshot.Itchecksthesignatureagainstthekeysitpinnedwhenthemachineenrolled,anditcheckstheidagainstthebytes.Itusesthesnapshotonlyafterbothcheckspass.Asnapshotthatfailsacheckisneverused.Theservicekeepsdecidingwiththelastonethatpasseduntilthesession'stimerunsout,andthenitdenies.Theservicelooksforanewsnapshotwhenasessionstarts,whenitstokenrenews,atoncewhenapolicyeventarrivesonthesession'spushstream,andafteradecisiononceitslastlookis30secondsold.Machinesandsessions:Apersonenrollsamachinewith`strazaenroll`.TheservicemakesanEd25519keythatneverleavesitandopenstheperson'sbrowseratyouridentityprovider,oratstrazad'sownsign-inonstandalone.strazadregistersthemachinewiththatkeyonlywhenthebrowsersign-innamesthekeyandisatmost10minutesold.Amachinewithnodisplaycansigninwithacodeinstead,whichnamesnokey,sotheenterpriseprofilerefusesitbydefault.Theenrollmentlasts7daysfromthesign-inbydefault,andthepersonthenenrollsagain.Whenasessionstarts,theservicechecksinwithaprooffromthatkeyoveranoncefromstrazad,acounterabovethelastoneandthehashesitmeasuredofitsinstall.strazadchecksitsdenylist,theuser'sstatusandthesign-indeadline,computestheattestationlevel,resolvestheuser'sroles,andmintsasessiontokensignedwithEd25519.Thelevelis`advisory`foraninstallintheuser'sownfiles,`managed`foraroot-ownedinstallwhosehashesmatchtheonesregistered,and`none`whentheclientsentnohashesoramanagedinstallreportedafilewhosehashstrazaddoesnothold.Bydefaulttheenterpriseprofilemintsnotokenbelow`managed`,exceptfortheconsoleandtheself-servicepage,whichcannotcallMCPtools.Thetokenbindstheuser,thesession,thedevice,theharness,theattestationlevel,ahashoftheroles,thesnapshotidandthekey'sthumbprint,soitworksonlywithafreshprooffromthatkey.Itlives300seconds,andeveryserverpathverifiesitwithoutadatabaseread.Theserviceholdsit,sothehookneverseesit,andrenewsitwhenacallfinds120secondsorlessleft.Thecheck-inansweralsocarriestheknowledgepacksboundtotheuser'sroles,andthehooktellstheagentinitsowncontextthatgovernanceisactive.AnAIagentwithitsownidentitystartsheadlesssessionswithitsownkeyandnoenrolleddevice.Onthemachine,thecodingtoolpassesthehookaneventinitsownformat.Thehookturnsitintoacanonicaleventandpassesittotheserviceoveralocalsocket,oranamedpipeonWindows.Onanallow,thehookexits0andthetoolruns.Onadeny,thehookwritesthereasontostandarderrorandexits2,sothecodingtooldoesnotrunthetoolandthemodelreadsthereason.GeminiCLIreadsaJSONdecisiononstandardoutputinstead.Ahookthatcannotreaditseventorreachtheservicedeniesthecall.[Credentialsandsessions](https://docs.straza.ai/security/credentials-and-sessions/index.md)describeseachcredentialfromenrollmenttolockout.[Machinesandsessions](https://docs.straza.ai/concepts/machines-and-sessions/index.md)coversthedetails.Whythedecisionislocal:AnAPIgatewayasksaserveroneverycall.Strazadecidesontheagent'smachineinstead,becauseatoolcallhappensinsideaperson'seditorandinsideloopsthatrunthousandsoftimesanhour.Aroundtriponeachcallwouldmakegovernancethesloweststepintheloop,andpeoplewouldturnitoff.Decidinglocallymeansthatpolicyandrevocationshavetoreacheverymachine.Policyissentasasignedsnapshot,andrevocationsarepushedaseventsintoin-memorydenylistsinsteadofbeinglookedup.strazadappliesthesameapproachonthepathsitowns.Nodecisiononthegatewayorthedecideendpointreadsthedatabase.Anystrazadinstancecanserveanysessiononcetheclienthascheckedinthere,andtheclientchecksinonitsown.Straza'sspeedbudgetforthelocaldecisionisunder100microsecondsatthe99thpercentileonasnapshotof10,000rules,andunder25millisecondsatthe95thpercentileforthewholehook,processstartincluded.Theloadrigunder`test/load`reproducesbothnumbersonyourownhardware.Classifyandapproverulesareexempt,becausetheyaremeantforafewchosencalls.Strazawritesauditrecordsafterthedecisionismade.Theservicespoolsitsrecordsanduploadstheminbatches,andstrazadpassesitsownrecordsthroughanin-memoryqueuetothedatabaseandintothehashchain.Arecordyoulookforrightafteradecisioncanthereforearriveamomentlater.Onenterpriseafullqueuecanmakeadecisionwait,andtheclient'sspoolisbounded.[Evidenceandaudit](https://docs.straza.ai/concepts/evidence/index.md)explainsthedeliverypath,and[Thesecuritymodelindepth](https://docs.straza.ai/security/security-model/index.md#audit-records-can-be-lost)listswhenarecordcanbelost.Atestintherepositoryfailswhenacallthroughthegatewayorthedecideendpointreadsthedatabase.Next:[Thesecuritymodel](https://docs.straza.ai/evaluate/security-model/index.md)