What AIShell-Gate covers, what it explicitly does not, what is known not to be perfect, and what remains unverified — consolidated into one document instead of scattered across four.
External Edition
aishell-gate-policy 1.29 · aishell-gate-exec 0.57 · aishell-gate-mcp 0.27
The White Paper explains why AIShell-Gate is built the way it is. The man pages explain every flag. This document answers a narrower, faster question: what does AIShell-Gate actually cover, what does it not, and what is known to fall short of ideal — in one place, without requiring a read of either of the other two first. Anything stated here is a summary of a fuller treatment elsewhere; where precision matters more than speed, follow the cross-reference.
A deterministic command validation engine. It evaluates a proposed shell command against a declared policy and returns exactly one of two decisions — ALLOW or DENY — with every ALLOW carrying a confirmation level (none, plan, action, or typed) escalated automatically by a risk score. It does not execute commands by interpreting intent, and it does not rely on AI to judge risk; every decision traces to a declared rule. Full mechanics, including the risk-scoring formula, are in the White Paper §3–§4.
| Not this | Why, and how the two relate |
|---|---|
| A sandbox | A sandbox constrains a running process via kernel mechanisms (seccomp, namespaces, chroot, containers). AIShell-Gate decides whether execution should begin at all, before any process starts. Complementary, not competing — the --sandbox flag records an intended mode for a wrapping executor to enforce. |
sudoers | sudoers makes a binary, identity-based decision: can this user run this command as this other user. AIShell-Gate evaluates the specific invocation — arguments, path, network target, session context — and can permit git status while requiring confirmation for git push and denying git clone from an external URL, all for the same user. The two coexist. |
| A full intrusion prevention system | An IPS inspects running traffic or syscalls in real time and can interrupt mid-execution. AIShell-Gate operates at the command level, before execution begins. It does not observe a command while it runs. |
| A guarantee against malicious behavior | A sufficiently determined attacker with system access can attempt to bypass any software policy layer. AIShell-Gate raises the cost and visibility of unsafe AI-generated actions and records every attempt — it is not a proof. |
Full discussion: White Paper §9.
AIShell-Gate assumes the AI agent generating commands is probabilistic and may produce dangerous, incorrect, or adversarially influenced output — not that it is malicious in the traditional sense. The threat addressed is structural, not intentional.
| Threat category | Response |
|---|---|
| Dangerous command generation | DENY or CONFIRM_TYPED via catalog + argument rules |
| Shell metacharacter injection | Rejected before tokenisation — no shell exists anywhere in the execution path |
| Argument-level bypass | Blocked by argument rules (e.g. find -exec denied) |
Interpreter bypass via env | env is unconditionally denied by the policy engine itself — not a configurable rule |
| Path traversal / persistence / kernel memory access | Path rules deny protected directories, cron spool paths, and /proc/PID/mem explicitly |
| Cloud metadata access | Net rules deny all cloud IMDS endpoints unconditionally, regardless of policy layer |
| Self-Referential API Access (an AI recruiting a second inference system, including its own model provider, during a gated session) | Port and hostname catalogs cover local, remote, and same-model cases; CONFIRM_ACTION minimum on match — see White Paper §11 for the full taxonomy |
| Audit trail falsification / timestamp forgery | Flag catalog entries flag known forensic-risk invocations (e.g. make -t, touch -t) |
In scope: AI-generated shell command evaluation, argument-level bypass attempts, path traversal within the execution environment, network target manipulation, AI self-referential API access, audit chain integrity.
Out of scope: Kernel exploits and privilege escalation below the process level, network-layer attacks, physical access, vulnerabilities in the AI model itself, and compromise of the operator's terminal or confirmation channel. AIShell-Gate operates at command evaluation time; it does not monitor running processes or intercept system calls after execution begins.
Full discussion: White Paper §10–§11.
Documented in the policy engine's own man page, not discovered externally. Each is a deliberate tradeoff with a stated reason, not an oversight.
| Limitation | Detail |
|---|---|
| Whitespace-only parsing | Quoted arguments containing spaces cannot be expressed; quote characters are rejected outright by the shell-metacharacter check. Deliberate: a shell grammar subset would introduce ambiguity and bypass surface. Policy rules match against naive whitespace tokens. |
| Network rules match strings, not resolved addresses | Rules blocking hostnames or IP ranges can be bypassed by DNS aliases, URL encoding, or HTTP redirects. Best-effort intent capture, not strong enforcement. |
| JSON token limit | 4,096 tokens per parse. Very large policy files or plan envelopes are rejected with a clear parse-failure message, not silently truncated. |
| Path canonicalization | Resolves existing path components and allows nonexistent leaf components; symlinks within the existing portion of a path are resolved, symlinks in nonexistent components are not checked. |
| Time-window granularity | Hour-level only. Minutes in time_window_start/time_window_end are parsed and validated but not enforced. |
| Structural limits | Max 16 entries per uid/gid/user list in session policy; max 63 arguments per command; max 8 allowed_commands and 8 allowed_paths in suggestion output. |
Full discussion: aishell-gate-policy man page, KNOWN LIMITATIONS.
Every deployment pattern — local MCP, SSH-delivered plans, or MCP tunneled over SSH — reaches the same two binaries and the same policy decision. Coverage and enforcement do not vary by pattern. Three specific guarantees do, and the difference is the confirmation mechanism in use, not the transport:
| Guarantee | --confirm-pipe (Pattern B) | confirm_mode: relay (MCP, any pattern) |
|---|---|---|
| Policy decision authority | Same two binaries, same evaluation | Identical |
typed-level confirmation is human-only | Structural — the challenge code is generated and displayed only on a separate operator process the AI's own session has no path to | Not preserved — the exact-match check is real, but get_execution_result returns the challenge in the same session the AI is already operating in; nothing stops the AI from reading and self-confirming |
| Self-installing capability on the gated entry point | Not present — the forced command never makes an outbound network connection on its own initiative | Present — install_engine downloads and installs binaries when called with confirm=true |
| OS-level account hardening | Present — no login shell, no PATH, no binary reachable except the gate itself | No equivalent — runs with whatever privileges the local or connecting process already has |
typed tier's human-only guarantee is load-bearing should use --confirm-pipe, not MCP relay mode, for that class of action. This applies equally whether the MCP session is local (Pattern A1) or tunneled over SSH — tunneling MCP over SSH does not restore the guarantee, because the confirmation mechanism, not the transport, is what determines it.Full discussion: White Paper §17; Remote Deployment Guide §03, §05b.
| Capability | Standard | Enterprise |
|---|---|---|
| Presets | read_only, ops_safe, dev_sandbox | Adds ci_build, ci_deploy, ci_admin, danger_zone |
| Policy override layers | policy_user only | Adds policy_base, policy_project |
| Audit chain | SHA-256 chain | Upgrades to HMAC-SHA256 via --audit-key |
| MCP tools | 9 of 11 tools | Adds verify_policy, verify_audit_log |
Switching to an Enterprise-only preset on a Standard install fails outright (exit code 2, "not available in the standard edition") — no commands are evaluated. get_version reports the active edition and which tools this install makes available; check it before assuming a capability is present.
| Code | Meaning |
|---|---|
| 0 | All actions allowed, confirmed, and executed |
| 1 | Policy DENY on one or more actions |
| 2 | Human confirmation refused |
| 3 | Policy engine process error |
| 4 | JSON parse error |
| 5 | Usage / argument error |
| 6 | execve() failure — binary not found in safe PATH, or exec error |
The automated test suite passes cleanly: 55 policy unit tests, 87 executor unit tests, 35 end-to-end tests, 34 catalog tests, and 12 standard-edition smoke tests, across all five build variants (standard policy, enterprise policy, standard exec, enterprise exec, evaluation exec), compiling clean under C11 with -Wall -Wextra.
What that suite does not yet cover, stated plainly rather than left implicit: the current beta test plan explicitly places live autonomous AI agent integration and security penetration testing out of scope for this beta cycle. Beta testers submit JSON plans they construct themselves or via the reference pipeline script, not through a live agent operating independently. Multi-session concurrent remote deployment and performance/load testing are similarly out of scope for the current cycle.
| Topic | Document |
|---|---|
| Architecture, design rationale, full threat taxonomy | AIShell-Gate White Paper |
| Every policy flag, file format, presets, sandbox modes | aishell-gate-policy man page |
| Plan format, executor flags, exit codes, audit events | aishell-gate-exec man page |
| Remote/SSH deployment, MCP tunneling, seeding an unconfigured AI | Remote Deployment Guide |
| Claude Code / Cursor integration, MCP tool reference | Using the MCP |
| Installation and first use | Getting Started Guide |
| Beta testing process and current test coverage | Beta Tester Guide and Test Plan |