{ "openapi": "3.1.0", "info": { "title": "ShellPermit", "version": "0.1.0", "summary": "Deterministic bash command policy checks with a signed, command-bound execution permit.", "description": "ShellPermit tokenizes a candidate bash command — quoting, escaping, pipelines, command and process substitution, heredocs, redirections — walks the result, and reports whether it complies with the policy you supply: allowed roots, network egress, destructive operations, privilege escalation, command allow and deny lists. Every segment of a chain is evaluated and the verdict is the worst across them. Detection is structural, so bundled flags, $IFS, base64, unicode look-alikes and quoting games cannot hide a construct from it. On a compliant command it can issue a signed Ed25519 permit, valid for 60 seconds, bound to the sha256 of the canonical command — which collapses quoting and flag order but preserves every operand, so a permit for `rm -rf /tmp/build` can never authorise `rm -rf /`. What it cannot do: it never runs anything and never sees your filesystem, so it cannot resolve a symlink, cannot know which files exist, and cannot see your aliases, shell functions, or PATH. It is defence in depth alongside a sandbox and a least-privilege user, not a replacement for either.", "contact": { "email": "security@schemasure.com" }, "x-policy-version": "shellpermit-policy-1.0.0" }, "servers": [ { "url": "https://shellpermit.schemasure.com" } ], "paths": { "/v1/guard/shell": { "post": { "operationId": "shellpermit_v1_guard_shell", "summary": "Check a bash command against an execution policy and optionally issue a signed permit", "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.", "x-payment-info": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amountAtomic": "15000", "priceUsd": 0.015, "payTo": "0x9876af0F6D8Ed5155Cd02d1ca56D128601612690", "policy": "charge only on a successful, usable result" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "shell", "command" ], "additionalProperties": false, "properties": { "shell": { "type": "string", "enum": [ "bash" ], "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." }, "command": { "type": "string", "minLength": 1, "maxLength": 32768 }, "policy": { "type": "object", "additionalProperties": false, "properties": { "allowed_roots": { "type": "array", "items": { "type": "string" }, "description": "Absolute directories the command may touch. Containment is lexical, not symlink-resolved." }, "cwd": { "type": "string", "description": "Absolute working directory relative operands resolve against. Defaults to the first allowed root." }, "allow_network_egress": { "type": "boolean", "description": "Permit commands that reach the network. Defaults to false." }, "allow_destructive": { "type": "boolean", "description": "Permit deletes, truncations, and overwrites. Defaults to false." }, "allow_privilege_escalation": { "type": "boolean", "description": "Permit sudo, su, chmod 777, chown root. 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." }, "allowed_commands": { "type": "array", "items": { "type": "string" }, "description": "If set, argv[0] must appear here." }, "denied_commands": { "type": "array", "items": { "type": "string" }, "description": "Always blocked, applied after allowed_commands." }, "max_segments": { "type": "integer", "minimum": 1, "description": "Ceiling on chained segments. Defaults to 32." }, "timeout_ms": { "type": "integer", "minimum": 1, "description": "Execution timeout written into the permit obligations. Defaults to 120000." } } }, "env": { "type": "object", "additionalProperties": { "type": "string" }, "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." }, "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" }, "subject": { "type": "string", "description": "Opaque caller label recorded as the permit subject." } } }, "example": { "shell": "bash", "command": "rm -rf ./dist && npm run build", "policy": { "allowed_roots": [ "/srv/app" ], "cwd": "/srv/app", "allow_destructive": true, "allow_network_egress": false }, "audience": "executor:acme-prod-01", "issue_permit": true } } } }, "responses": { "200": { "description": "Successful result envelope", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "verdict", "confidence", "risk_codes", "evidence", "result", "policy_version", "request_hash", "data_versions", "warnings" ], "properties": { "ok": { "type": "boolean" }, "verdict": { "type": "string", "enum": [ "pass", "warn", "unknown", "block" ], "description": "Worst across every segment, on the lattice pass < warn < unknown < block. `unknown` means the service could not read part of the command and is never a pass." }, "confidence": { "type": "number" }, "risk_codes": { "type": "array", "items": { "type": "string" } }, "evidence": { "type": "array", "items": { "type": "object", "required": [ "code", "severity", "detail", "disposition" ], "properties": { "code": { "type": "string", "description": "Stable reason code, e.g. REMOTE_CODE_EXECUTION." }, "severity": { "type": "string", "enum": [ "info", "low", "medium", "high", "critical" ] }, "disposition": { "type": "string", "enum": [ "block", "unknown", "warn", "info" ], "description": "What this finding does to the verdict, which is a different axis from how bad it is." }, "detail": { "type": "string" }, "source": { "type": "string" }, "span": { "type": "object", "properties": { "start": { "type": "integer" }, "end": { "type": "integer" } } }, "data": { "type": "object" } } } }, "policy_version": { "type": "string" }, "request_hash": { "type": "string" }, "data_versions": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "required": [ "shell", "command_count", "segment_count", "commands", "touched_paths", "destructive", "network", "findings", "canonical_command", "cmd_hash", "cmd_fingerprint", "policy_hash", "grammar", "obligations" ], "properties": { "shell": { "type": "string" }, "command_count": { "type": "integer" }, "segment_count": { "type": "integer" }, "commands": { "type": "array", "items": { "type": "string" } }, "touched_paths": { "type": "array", "items": { "type": "string" } }, "destructive": { "type": "boolean" }, "network": { "type": "boolean" }, "findings": { "type": "array", "items": { "type": "object", "required": [ "code", "severity", "detail", "disposition" ], "properties": { "code": { "type": "string", "description": "Stable reason code, e.g. REMOTE_CODE_EXECUTION." }, "severity": { "type": "string", "enum": [ "info", "low", "medium", "high", "critical" ] }, "disposition": { "type": "string", "enum": [ "block", "unknown", "warn", "info" ], "description": "What this finding does to the verdict, which is a different axis from how bad it is." }, "detail": { "type": "string" }, "source": { "type": "string" }, "span": { "type": "object", "properties": { "start": { "type": "integer" }, "end": { "type": "integer" } } }, "data": { "type": "object" } } } }, "canonical_command": { "type": "string", "description": "Quoting, whitespace, backtick syntax, and flag order collapsed; every operand preserved. This, not your original text, is what a permit binds." }, "cmd_hash": { "type": "string", "description": "BINDING. sha256 of canonical_command. The executor recomputes this from the command it is about to run." }, "cmd_fingerprint": { "type": "string", "description": "ADVISORY ONLY — never authorize on this. Every operand is discarded, so `rm -f -r /tmp/build` and `rm -f -r /` share one fingerprint." }, "policy_hash": { "type": "string" }, "grammar": { "type": "string" }, "obligations": { "type": "object", "required": [ "allowed_roots", "cwd", "network_egress_allowed", "destructive_allowed", "timeout_ms" ], "properties": { "allowed_roots": { "type": "array", "items": { "type": "string" } }, "cwd": { "type": [ "string", "null" ] }, "network_egress_allowed": { "type": "boolean" }, "destructive_allowed": { "type": "boolean" }, "timeout_ms": { "type": "integer" } } }, "permit": { "type": "string", "description": "Compact JWS. Present only when requested and the verdict is pass or warn." }, "permit_expires_at": { "type": "string" }, "permit_kid": { "type": "string" } } } } }, "example": { "ok": true, "verdict": "pass", "confidence": 1, "risk_codes": [], "evidence": [ { "code": "RECURSIVE_FORCED_DELETE", "severity": "critical", "disposition": "info", "detail": "\"rm\" deletes /srv/app/dist, recursively, without prompting. The policy permits destructive operations.", "source": "shellpermit/detect", "span": { "start": 0, "end": 13 } } ], "result": { "shell": "bash", "command_count": 2, "segment_count": 2, "commands": [ "npm", "rm" ], "touched_paths": [ "/srv/app/dist" ], "destructive": true, "network": false, "findings": [ { "code": "RECURSIVE_FORCED_DELETE", "severity": "critical", "disposition": "info", "detail": "\"rm\" deletes /srv/app/dist, recursively, without prompting. The policy permits destructive operations.", "source": "shellpermit/detect", "span": { "start": 0, "end": 13 }, "data": { "targets": [ "/srv/app/dist" ], "recursive": true, "forced": true } } ], "canonical_command": "rm -f -r ./dist && npm run build", "cmd_hash": "sha256:dbf92266aa4df1527e417b2750b330d560e6bce2b9c6962ce1008b5a5ba13ba7", "cmd_fingerprint": "bccaa66b5ba1bae6", "policy_hash": "sha256:d68a66fd0b6027805655642be61c913ecca490ae8e3c30eef350ee5992a6e2d9", "grammar": "bash/shellpermit-lexer@1.0.0", "obligations": { "allowed_roots": [ "/srv/app" ], "cwd": "/srv/app", "network_egress_allowed": false, "destructive_allowed": true, "timeout_ms": 120000 }, "permit": "eyJhbGciOiJFZDI1NTE5Iiwia2lkIjoi…", "permit_expires_at": "2026-09-19T12:01:00.000Z", "permit_kid": "uGzLTTwi4LTsOiBLgwf2wMU7ILTecj18Y_71Y37bVD8" }, "policy_version": "shellpermit-policy-1.0.0", "request_hash": "sha256:1c2d0f4c1d8e2b7a9c5d3e6f8a1b2c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b", "data_versions": { "grammar": "bash/shellpermit-lexer@1.0.0", "shell": "bash", "lexer": "shellpermit-lexer@1.0.0" }, "warnings": [ "cmd_fingerprint is ADVISORY and must not be used for authorization: it discards every operand, so `rm -f -r /tmp/build` and `rm -f -r /` share one fingerprint. cmd_hash is the binding value." ] } } } }, "400": { "description": "INPUT_INVALID", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "402": { "description": "Payment required. Body carries the x402 challenge; see PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "422": { "description": "UNSUPPORTED or INDETERMINATE. Not charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "502": { "description": "Upstream or facilitator unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "504": { "description": "UPSTREAM_TIMEOUT", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }