{"uid":"cap__U02oTZEIFNyQi2FwVDJ_","slug":"shellpermit-shell-command-policy-guard-c23e5199","name":"ShellPermit Shell Command Policy Guard","description":"Decide whether an agent-authored bash command complies with an execution policy, using a real shell tokenizer rather than pattern matching. Catches recursive deletes, force pushes, cluster and infrastructure teardown, raw device writes, path escapes, privilege escalation, and curl-piped-to-shell through pipelines, substitutions, quoting games and base64. Returns reason codes with spans and an optional short-lived permit bound to the exact canonical command. Never executes anything.","url":"https://shellpermit.schemasure.com/v1/guard/shell?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","properties":{"env":{"type":"object","description":"Environment the executor will run with, used only for static expansion so that paths like \"$HOME/.cache\" can be resolved and decided rather than reported as unresolvable.","additionalProperties":{"type":"string"}},"shell":{"enum":["bash"],"type":"string","description":"Required. Only bash is supported in v1: a permit issued under one shell's grammar and executed under another is a parser differential with a signature on it."},"policy":{"type":"object","properties":{"cwd":{"type":"string","description":"Absolute working directory relative operands resolve against. Defaults to the first allowed root."},"timeout_ms":{"type":"integer","minimum":1,"description":"Execution timeout written into the permit obligations. Defaults to 120000."},"max_segments":{"type":"integer","minimum":1,"description":"Ceiling on chained segments. Defaults to 32."},"allowed_roots":{"type":"array","items":{"type":"string"},"description":"Absolute directories the command may touch. Containment is lexical, not symlink-resolved."},"denied_commands":{"type":"array","items":{"type":"string"},"description":"Always blocked, applied after allowed_commands."},"allowed_commands":{"type":"array","items":{"type":"string"},"description":"If set, argv[0] must appear here."},"allow_destructive":{"type":"boolean","description":"Permit deletes, truncations, and overwrites. Defaults to false."},"protected_branches":{"type":"array","items":{"type":"string"},"description":"Branches a force push must never target. Defaults to main, master, trunk, develop, production, prod, release."},"allow_network_egress":{"type":"boolean","description":"Permit commands that reach the network. Defaults to false."},"allow_privilege_escalation":{"type":"boolean","description":"Permit sudo, su, chmod 777, chown root. Defaults to false."}},"additionalProperties":false},"command":{"type":"string","maxLength":32768,"minLength":1},"subject":{"type":"string","description":"Opaque caller label recorded as the permit subject."},"audience":{"type":"string","description":"Identity of the ONE executor the permit is for. Required when issue_permit is true. Wildcards are rejected."},"issue_permit":{"type":"boolean"}}},"responseSchema":null,"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.03","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.03/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.03","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.03","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_eq1eSHJwSsqNl_4OwpdLB","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.03","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Validates a bash command against a configurable execution policy using a real shell tokenizer, returning compliance decisions with reason codes and optional short-lived execution permits — without ever executing the command.","exampleAgentPrompt":"Before running this bash command, check it against our policy — allowed roots are /home/deploy and /tmp, network egress is off, destructive ops are off, and protected branches include main and production: `find /home/deploy -name '*.log' | xargs rm -rf`","exampleUseCases":[{"title":"Agent pre-flight command safety check","prompt":"Before my coding agent runs this shell command it just wrote, validate it against our policy — allowed commands are git, npm, and node, working directory is /workspace, no network egress, no destructive ops, no privilege escalation: `git push --force origin main`"},{"title":"CI pipeline destructive-op guardrail","prompt":"Check whether this CI cleanup step is safe to run — allowed roots are /build and /artifacts only, destructive operations are not allowed, and denied commands include rm and dd: `rm -rf /build/../etc/passwd`"},{"title":"Infrastructure teardown prevention","prompt":"Guard this infrastructure command before my automation runs it — policy says no privilege escalation, no network egress, allowed commands are terraform and kubectl only, protected branches are main and prod: `sudo kubectl delete namespace production --force`"}],"resultDescription":"Returns a compliance decision (permit or deny), one or more structured reason codes identifying the violation category (e.g. recursive-delete, force-push, privilege-escalation, path-escape, curl-pipe-shell), span offsets into the original command string indicating exactly where the violation occurs, the canonical normalized form of the command, and optionally a short-lived signed permit token bound to the exact canonical command that downstream executors can verify before running it.","failureModes":["Unsupported shell (non-bash) returns a 400 error since only bash grammar is supported in v1","Command exceeds 32768 character limit returns validation error","Unresolvable environment variable references in paths may cause the command to be reported as undecidable rather than permitted","Overly broad allowed_roots (e.g. '/') may permit path-escape attempts that are lexically contained","Permit token expiry means a permit issued at decision time may be stale by the time execution is attempted","Malformed or missing required fields (command, shell) return schema validation errors"],"whenToPreferThis":"Choose ShellPermit when your AI agent or automation pipeline generates bash commands that must be validated before execution — especially when you need tokenizer-level accuracy rather than regex pattern matching, which can be defeated by quoting, substitution, and base64 tricks. Prefer this over home-grown allowlist checks when your threat model includes adversarial command injection, path traversal, or pipeline-based evasion. It is ideal for agentic coding assistants, CI/CD pipelines, and infrastructure automation where a signed permit token provides a verifiable chain of custody between policy decision and execution.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-11T00:36:18.197Z","isFirstParty":false,"canonicalSlug":"shellpermit-shell-command-policy-guard-c23e5199"}