shellward

Purpose

ShellWard is "an AI Agent security and compliance tool / AI application compliance gateway built for Chinese regulation," with the goal of providing support at two stages of AI applications: first, compliance risk health checks at the project level, and second, runtime security protection. According to the official description, it targets the regulatory context of the Cybersecurity Law, PIPL, Classified Protection 2.0, cross-border data transfer, and AI labeling (GB45438), is Chinese-first, zero-dependency, and open source.

Main Capabilities

Compliance Scan (scan)

The official description is: zero-install, read-only, uploads no data, and with a single command (npx shellward scan) scans out the compliance red lines of an AI project, outputting a red-yellow-green scorecard mapped to the Cybersecurity Law / PIPL / Classified Protection 2.0 / cross-border data transfer / AI labeling, and pinpointing to file:line. Detection focuses include: overseas large model endpoints and SDK dependencies (cross-border data transfer), hardcoded keys, Chinese PII in files, and .env exposure. When overseas models are detected, it provides domestic compliant alternatives (Tongyi Qianwen / DeepSeek / Kimi / Zhipu) and their OpenAI-compatible base_url; the official note states that base_url refers to each vendor's publicly available OpenAI-compatible endpoint, which may be adjusted by the vendor, and the official documentation should prevail before migration. Overseas identification covers the endpoints of OpenAI / Anthropic / Gemini / Azure / Bedrock / Cohere / Mistral / Groq / Together / Perplexity / OpenRouter / HuggingFace / xAI / Replicate / AI21 / Fireworks / DeepInfra / Cerebras / Voyage / NVIDIA NIM, as well as npm / pip / Go SDK dependencies (including LangChain, LlamaIndex, and Vercel AI SDK adapter packages).

Agent Compliance Audit (Skill)

The official description points out that scan is a deterministic scan: it can report "there are overseas model endpoints in the project," but cannot determine whether personal information actually flows there, and 11 of the 14 regulatory control items can only be marked "requires manual confirmation." This part can be handed over to a coding agent that supports Agent Skills (Claude Code, Cursor, Codex, etc.). The installation command is npx skills add jnMetaCode/shellward --skill china-ai-compliance-audit. It first runs shellward scan to obtain a deterministic baseline, then gathers evidence item by item along the data flow, and finally produces .compliance/COMPLIANCE-REPORT.md. The official documentation states that its difference from "letting AI casually check whether something is compliant" lies in three gates:

Evidence gate: every finding requires file:line plus a verbatim quote, and a zero-dependency validator opens the file to verify that the quote actually exists; fabricated quotes will cause the run to fail.
Verification gate: every "gap" and every "measure already found" is handed to a fresh agent that has not seen the audit reasoning process to rebut it; findings that are overturned are retained in the record rather than deleted.
Honesty gate: facts not present in the repository (filing, impact assessment, actual log retention) cannot be guessed; the agent must raise a specific question that a human can answer, and without attaching a severity level. The official documentation also states: all 14 control items must have a conclusion, and none may be quietly skipped; the report itself must not contain full keys, phone numbers, or ID card numbers.

Runtime Protection (8 Layers of Defense)

The official documentation lists 8 defense layers: prompt guard, input auditor, tool blocker, output scanner, security gate, outbound guard, data flow guard, session guard, all enabled by default with zero configuration. The specific mechanisms include:

DLP model: data is returned in full (not redacted), and outbound sending is blocked when PII has been accessed recently.
PII detection: SSN, credit cards, API keys (OpenAI/GitHub/AWS), JWT, passwords, plus Chinese ID card numbers (GB 11643 check digit), carrier-verified phone numbers, and UnionPay bank cards (Luhn).
Injection rules: the counts given in the official Chinese and English documentation are inconsistent (the Chinese version says 18 Chinese + 14 English rules; the English version says 37 injection rules: 20 Chinese + 17 English); both support risk scoring and mixed Chinese-English detection.
MCP tool poisoning scan: detects hidden instructions in tool descriptions/parameters, invisible characters, concealed instructions of the "hide from the user" type, sensitive file access, and exfiltrationhints.
MCP rug-pull detection: records a description fingerprint when a tool is first seen, and raises an alert if it is later tampered with.
Data exfiltration chain: reading sensitive data followed by send_email / HTTP POST / curl outbound sending is blocked.
Bash bypass detection: catches curl -X POST, wget --post, nc, and Python/Node network exfiltration. The official documentation provides 7 real-world scenario examples: server destruction blocking, reverse shell, injection detection, DLP audit, data exfiltration chain, credential theft, APT attack chain.

How to Use

Browser Viewing and Web Mode

npx shellward scan --open: open the report directly after scanning; --serve: local http://localhost Provide reports, with official claims that data never leaves the local machine throughout.
shellward web: a public repository web scanner; you can paste a public repository URL in the web page or use the /scan?repo=URL link for a checkup (deployable, see Dockerfile).
shellward web --local: a local web GUI; fill in a local path to scan, private code is not uploaded and does not leave the local machine.

CI and policy as code

--json for CI; --ci makes the build fail when critical issues are found; --html report.html exports a report that can be printed to PDF (for filing/audit archiving); it can also be integrated as a GitHub Action for PR gating.
.shellward.json declarative gating: failOn (fail when matching secret / pii / overseas / env-perm categories or critical / high / medium severity), maxFindings, allowOverseas; supports per-path rules (path, failOn / maxFindings, allowOverseas; if allowOverseas is omitted it inherits the global setting, and setting it to an empty array can override it). The official statement says unknown fields, misspelled failOn values, and corrupted JSON are printed as ⚠️ warnings in CI rather than being silently ignored. Without this file, the default is "any critical fails".

MCP server and SDK integration

ShellWard can run as a standalone MCP server via stdio, with zero dependencies, and does not require @modelcontextprotocol/sdk. Add the configuration in the MCP config (claude_desktop_config.json, .cursor/mcp.json, OpenClaw, etc.); no install path is needed, and npx will pull the published shellward-mcp bin; if already installed globally (npm i -g shellward), directly use "command": "shellward-mcp". The official statement says it provides 8 MCP tools: command checking, injection detection, sensitive data scanning, path protection, tool policy, response auditing, MCP tool poisoning/rug-pull scanning, security status. It also supports use as an SDK (for any AI agent platform) and as an OpenClaw plugin, and supports custom rules via the SDK (fields are incremental, allowedTools always takes precedence; invalid regexes are skipped rather than throwing an error).

Vulnerability database

The official statement says it includes 17 built-in CVE / GitHub Security Advisories, /check-updates checks whether the current version is affected, for example CVE-2025-59536 (CVSS 8.7, a malicious repository executes commands via Hooks/MCP before the trust prompt), CVE-2026-21852 (CVSS 5.3, stealing API keys via settings.json), GHSA-ff64-7w26-62rf (persistent configuration injection, sandbox escape), plus 14 other confirmed vulnerabilities. The remote vulnerability database syncs every 24 hours, and falls back to the local database when offline.

Applicable scenarios

The official description is suitable for teams that need runtime security for AI agents: building autonomous coding assistants, customer-facing chatbots with tool access, or LLM-driven internal automation; common use cases include MCP security enforcement, tool call interception and filtering, and adding agent guardrails to any LLM workflow. If a team wants to do compliance self-checks across multiple AI projects or integrate into internal processes, they can contact jnMetaCode@qq.com (team size and scenario must be specified).

Limitations and cautions

The official statement makes clear: this is technical self-check material, not legal advice; responsibilities such as filing, grading, and PIA cannot be replaced by tools.
scan is a deterministic scan and cannot determine whether personal information actually flows overseas; among the 14 regulatory control items, 11 can only be marked "requires manual confirmation".
Regarding detection benchmarks, the official statement says npm run bench measures the precision/recall/F1 of each detector on annotated corpora, and CI handles regression failures; the scanner comes with a gating corpus of 41 annotated cases (24 real risks + 17 hard negatives). The official statement says there are currently 83 gating samples, and the principle is to be conservative by design (fail safe in enforce mode, for example echo "rm -rf /" will also be flagged), and it explicitly lists 5 bypasses not expected to be caught by regex/heuristics (leetspeak, base64,non-Chinese and non-English languages, indirect shell variable references), exclude them from the gate rather than hide them. The official statement emphasizes: the numbers are based on the corpus currently in the repository and are a lower bound rather than a universal guarantee.
The official documentation states that the behavior of MCP-related configurations, commands, and .shellward.json fields is governed by its documentation; other information not appearing in the materials (such as specific pricing, platform support scope, etc.) has not yet been provided.