Skip to content
Back to search

SkillWard

Security scanner for Agent Skills — uncover hidden threats before deployment.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/fangcun-ai--skillward/badge.svg)](/listings/fangcun-ai--skillward)

HTML

<a href="/listings/fangcun-ai--skillward"><img src="/api/listings/fangcun-ai--skillward/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Requirements:** Python 3.10+ / Docker (sandbox) / Node.js 18+ (UI mode)

1. Install & Configure

# Clone the repository
git clone https://github.com/Fangcun-AI/SkillWard.git
cd SkillWard

# Install dependencies
pip install -r requirements.txt && pip install -e ./skill-scanner

# Pull Docker sandbox image
docker pull fangcunai/skillward:amd64    # Intel/AMD
docker pull fangcunai/skillward:arm64    # Apple Silicon/ARM

# Configure environment variables (.env.example lists all available options — fill in as needed)
cp guardian-api/.env.example guardian-api/.env

> For detailed configuration, see [Configuration Guide](docs/configuration.md)

2. Run Scans

# Full pipeline (static + LLM + sandbox)
python guardian-api/guardian.py /path/to/skills-dir -o ./output --enable-after-tool --parallel 4 -v

# Stage A + B only (static + LLM, no Docker required)
python guardian-api/guardian.py /path/to/skills-dir --stage pre-scan -o ./output -v

# Stage C only (Docker sandbox)
python guardian-api/guardian.py /path/to/skills-dir --stage runtime -o ./output --enable-after-tool --parallel 4

3. Common Scenarios

# Scan specific Skills only
python guardian-api/guardian.py /path/to/skills-dir -s skill-a,skill-b -o ./output

# Quick test run (first 10 Skills)
python guardian-api/guardian.py /path/to/skills-dir -n 10 -o ./output

# Increase sandbox timeout for complex Skills
python guardian-api/guardian.py /path/to/skills-dir --timeout 900 --prep-timeout 600 -o ./output

> For more options and usage details, see [CLI Guide](docs/cli.md)

> [!TIP] > **Optional: Launch Web UI** > ```bash > cd guardian-api && python guardian_api.py # API server > cd guardian-ui && npm install && npm run dev # Frontend > ```

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 268 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ·<p align="center">
  2. <img src="./resources/banner.png" alt="SkillWard Banner" width="100%" />
  3. </p>
  4. <h1 align="center">SkillWard</h1>
  5. <p align="center">
  6. <a href="https://github.com/Fangcun-AI"><img src="./resources/skillward-badge.svg" alt="SkillWard" height="20" /></a>
  7. <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-4B8BBE?style=flat-square&logo=apache&logoColor=white" alt="License" /></a>
  8. <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python" /></a>
  9. <img src="https://img.shields.io/badge/Docker-Ready-2496ED?style=flat-square&logo=docker&logoColor=white" alt="Docker" />
  10. <img src="https://img.shields.io/badge/Version-1.0.0-32CD32?style=flat-square" alt="Version" />
  11. </p>
  12. <p align="center"><i>SkillWard is a security scanner for AI Agent Skills that combines static analysis, LLM evaluation, and sandbox verification to comprehensively identify potential risks in Agent Skills.</i></p>
  13. <p align="center">
  14. <a href="#highlights">Highlights</a> ·
  15. <a href="#architecture">Architecture</a> ·
  16. <a href="#skillward-ui">UI</a> ·
  17. <a href="#benchmark">Benchmark</a> ·
  18. <a href="#quick-start">Quick Start</a> ·
  19. <a href="#repository-structure">Structure</a> ·
  20. English | <a href="./README_CN.md">中文</a>
  21. </p>
  22. > **"Five scanners on 238,180 Skills showed highly inconsistent results, only 0.12% were flagged by all five, with individual flag rates ranging from 3.79% to 41.93%."**
  23. > — Holzbauer et al., [*Malicious Or Not: Adding Repository Context to Agent Skill Classification*](https://arxiv.org/abs/2603.16572), 2026
  24. **SkillWard** enables security review of AI Agent Skills before they are published or deployed, reducing the potential risks of Agent usage. Beyond static analysis and LLM evaluation, it executes suspicious Skills in **isolated Docker sandboxes**, replacing uncertain warnings with runtime evidence. Across 5,000 real-world Skills, ~**25%** were flagged as unsafe; among the ~**38%** suspicious samples that entered the sandbox, ~**one-third** revealed runtime threats that review-only pipelines could not catch.
  25. ## 🔥 News
  26. - **2026-07-10** — 🚀🚀🚀 **SkillWard is now available on the Dify Marketplace!** Add SkillWard to a Dify Workflow, Chatflow, or Agent to scan AI Agent Skills and MCP projects and receive structured security reports. [Install the plugin →](https://marketplace.dify.ai/plugin/fangcunai/skillward)
  27. ## How does SkillWard address this challenge?
  28. We ran two existing open-source scanning tools on the same dataset as reference baselines (see [Comparison](docs/comparison.md) for details). Here are three real-world cases:
  29. - **Unique Detection:** Threats missed by other tools, precisely caught by SkillWard — see [ai-skill-scanner](docs/cases/ai-skill-scanner.md)
  30. - **Low False Positives:** Compliant content wrongly blocked by other tools, correctly cleared by SkillWard — see [roku](docs/cases/roku.md)
  31. - **Deeper Analysis:** For threats all tools detect, SkillWard provides more complete risk tracing and evidence — see [amber-hunter](docs/cases/amber-hunter.md)
  32. ---
  33. ## Highlights
  34. - **Three-Stage Security Coverage** - Static analysis, LLM evaluation, and sandbox execution turn obvious threats and ambiguous warnings into high-confidence decisions
  35. - **Autonomous Sandbox Execution** - An in-container Agent provisions environments, installs dependencies, repairs common failures, and drives Skills end-to-end with up to **99% deployment success**
  36. - **Runtime Security Guard** - A purpose-built Guard monitors Agent runtime behavior, capturing clear evidence for exfiltration, suspicious network access, sensitive writes, and hidden credential risks
  37. - **Ready Out of the Box, Extensible on Demand** - Single-skill or batch scans, Quick Scan / Sandbox Scan / Deep Trace modes, tunable via environment variables, LLM provider configuration, and Docker settings
  38. - **Evidence-Rich Results** - Every scan returns real-time logs, three-stage findings, threat evidence, and remediation guidance that security and platform teams can act on immediately
  39. ---
  40. ## Architecture
  41. <img src="./resources/architecture.png" width="100%" alt="System Architecture" />
  42. SkillWard uses a static + dynamic three-stage analysis approach:
  43. <details>
  44. <summary><b>Stage A · Static Analysis</b>: Runs in seconds, catches known malicious patterns and suspicious signals</summary>
  45. Scans Skill code and configuration using YARA rules and regex to identify known malicious patterns (credential theft, code injection, etc.), validates that a Skill's declared permissions and capabilities match its actual code behavior, and detects hidden files, encoding obfuscation, prompt poisoning, and other suspicious characteristics.
  46. </details>
  47. <details>
  48. <summary><b>Stage B · LLM Evaluation</b>: Semantic reasoning to judge intent and assign safety confidence</summary>
  49. Adds semantic reasoning on top of static signals. Skills that can be confidently classified are resolved here; Skills that remain uncertain advance to Stage C for sandbox verification.
  50. </details>
  51. <details>
  52. <summary><b>Stage C · Sandbox Verification</b>: Actually runs suspicious Skills, leaving hidden risks nowhere to hide</summary>
  53. An in-container Agent executes the Skill end-to-end, with a custom Guard monitoring throughout. Pre-planted honeypot decoys lure malicious Skills into revealing credential theft, data exfiltration, supply chain attacks, and other hidden behavior.
  54. </details>
  55. ---
  56. ## SkillWard UI
  57. > **Try it online:** [skillward.fangcunleap.com](https://skillward.fangcunleap.com/)
  58. SkillWard UI provides a clean, intuitive web interface, supporting single or batch Skill submission, three scan modes (Quick Scan / Sandbox Scan / Deep Trace), and comprehensive scan results display.
  59. <table>
  60. <tr>
  61. <td width="50%" align="center"><b>Single Skill Scan</b></td>
  62. <td width="50%" align="center"><b>Batch Scan</b></td>
  63. </tr>
  64. <tr>
  65. <td><img src="./resources/demo.webp" width="100%" alt="Single Skill Scan Demo" /></td>
  66. <td><img src="./resources/batch-demo.webp" width="100%" alt="Batch Scan Demo" /></td>
  67. </tr>
  68. </table>
  69. ### Detailed Analysis Report
  70. <table>
  71. <tr>
  72. <td width="50%" align="center"><b>Report Overview + Three-Stage Analysis</b></td>
  73. <td width="50%" align="center"><b>Threat Details + Detection Evidence + Recommendations</b></td>
  74. </tr>
  75. <tr>
  76. <td><img src="./resources/screenshot-detail.png" width="100%" alt="Analysis Report Details" /></td>
  77. <td><img src="./resources/screenshot-detail2.png" width="100%" alt="Analysis Report - Threats & Recommendations" /></td>
  78. </tr>
  79. </table>
  80. Each report includes: **Analysis Results** (three-stage verdicts, confidence scores, threat levels), **Issue Location** (file path, line number, highlighted code snippets), and **Remediation Suggestions** (actionable security recommendations).
  81. ---
  82. ## Benchmark
  83. We evaluated SkillWard on a real-world AI Agent Skills dataset containing Skills collected from [ClawHub](https://clawhub.ai/) and known-malicious samples curated from security communities.
  84. ### Pipeline Results
  85. #### Stage A + B: Static Scan + LLM Evaluation
  86. Combining **YARA rules, regex-based static analysis, and LLM semantic evaluation**, all Skills are quickly triaged: safe ~49%, unsafe ~13%, suspicious ~38%, where suspicious Skills are escalated to Stage C for sandbox verification.
  87. #### Stage C: Sandbox Verification
  88. After executing this batch of suspicious Skills end-to-end inside an isolated Docker sandbox, roughly **one-third** revealed potential threats that **neither static analysis nor LLM evaluation could catch**, including:
  89. - **Credential exfiltration** that only surfaces along the execution path
  90. - **Persistence backdoors** via `crontab` / `SSH` / startup scripts
  91. - **Postinstall supply-chain attacks** triggered during package installation
  92. - **Outbound exfiltration chains** identifiable only after correlating multi-step operations
  93. Stage C verdict breakdown for these suspicious Skills:
  94. | Level | Meaning | % of suspicious |
  95. |---|---|---|
  96. | **safe** | Confirmed safe after sandbox verification | **~69%** |
  97. | **medium risk** | Medium-risk behavior (undeclared external requests, env-var harvesting, etc.) | **~17%** |
  98. | **high risk** | High-risk behavior (credential theft, persistence backdoors, remote code execution, etc.) | **~14%** |
  99. #### Overall
  100. Across all stages: Stage A + B directly blocked ~**13%** unsafe Skills, and ~**38%** suspicious Skills entered the sandbox; among those suspicious Skills, ~**17%** were judged medium risk and ~**14%** were judged high risk.
  101. #### Common Threat Patterns (% of unsafe Skills)
  102. | Pattern | Occurrences |
  103. |---------|------------|
  104. | Credential theft (API keys, passwords, private keys) | 36% |
  105. | Undeclared external network requests | 24% |
  106. | Env var / `.env` harvesting | 15% |
  107. | Remote code download and execution | 9% |
  108. | Persistence backdoor (crontab / SSH / startup) | 8% |
  109. | Supply chain and privilege escalation | 8% |
  110. > For detailed case studies and comparison, see [How does SkillWard address this challenge?](#how-does-skillward-address-this-challenge) above.
  111. ---
  112. ## Quick Start
  113. **Requirements:** Python 3.10+ / Docker (sandbox) / Node.js 18+ (UI mode)
  114. ### 1. Install & Configure
  115. ```bash
  116. # Clone the repository
  117. git clone https://github.com/Fangcun-AI/SkillWard.git
  118. cd SkillWard
  119. # Install dependencies
  120. pip install -r requirements.txt && pip install -e ./skill-scanner
  121. # Pull Docker sandbox image
  122. docker pull fangcunai/skillward:amd64 # Intel/AMD
  123. docker pull fangcunai/skillward:arm64 # Apple Silicon/ARM
  124. # Configure environment variables (.env.example lists all available options — fill in as needed)
  125. cp guardian-api/.env.example guardian-api/.env
  126. ```
  127. > For detailed configuration, see [Configuration Guide](docs/configuration.md)
  128. ### 2. Run Scans
  129. ```bash
  130. # Full pipeline (static + LLM + sandbox)
  131. python guardian-api/guardian.py /path/to/skills-dir -o ./output --enable-after-tool --parallel 4 -v
  132. # Stage A + B only (static + LLM, no Docker required)
  133. python guardian-api/guardian.py /path/to/skills-dir --stage pre-scan -o ./output -v
  134. # Stage C only (Docker sandbox)
  135. python guardian-api/guardian.py /path/to/skills-dir --stage runtime -o ./output --enable-after-tool --parallel 4
  136. ```
  137. ### 3. Common Scenarios
  138. ```bash
  139. # Scan specific Skills only
  140. python guardian-api/guardian.py /path/to/skills-dir -s skill-a,skill-b -o ./output
  141. # Quick test run (first 10 Skills)
  142. python guardian-api/guardian.py /path/to/skills-dir -n 10 -o ./output
  143. # Increase sandbox timeout for complex Skills
  144. python guardian-api/guardian.py /path/to/skills-dir --timeout 900 --prep-timeout 600 -o ./output
  145. ```
  146. > For more options and usage details, see [CLI Guide](docs/cli.md)
  147. > [!TIP]
  148. > **Optional: Launch Web UI**
  149. > ```bash
  150. > cd guardian-api && python guardian_api.py # API server
  151. > cd guardian-ui && npm install && npm run dev # Frontend
  152. > ```
  153. ---
  154. ## Repository Structure
  155. ```
  156. SkillWard/
  157. ├── docs/ # Documentation (config, CLI, cases, comparison)
  158. ├── guardian-api/ # Backend: scanning pipeline & API server
  159. │ ├── guardian.py # Core three-stage scanning engine
  160. │ └── guardian_api.py # FastAPI server (SSE streaming)
  161. ├── guardian-ui/ # Frontend: Next.js web dashboard
  162. ├── skill-scanner/ # Static analysis engine (15 analyzers)
  163. ├── models/ # Data model definitions
  164. ├── services/ # Business logic services
  165. ├── utils/ # Utility functions
  166. ├── resources/ # Banner, screenshots, demo assets
  167. ├── requirements.txt
  168. ├── README.md
  169. └── README_CN.md
  170. ```
  171. | Guide | Description |
  172. |-------|-------------|
  173. | [Configuration](docs/configuration.md) | Quick start, LLM model providers, sandbox security monitoring, optional tuning |
  174. | [CLI Guide](docs/cli.md) | Full command-line reference, common usage, and output files |
  175. | [Showcase](docs/showcase.md) | Real-world detection cases, how SkillWard catches threats in public Skills |
  176. | [Comparison](docs/comparison.md) | Side-by-side analysis with two open-source scanning tools |
  177. ---
  178. ## 📋 Changelog
  179. | Date | Summary | Details |
  180. |------|---------|---------|
  181. | 2026-07-17 | 🔌 **MCP scanning support** — added security scanning for local MCP source, Git repositories, packages, archives, and unauthenticated remote MCP servers, with malicious-intent detection and protocol-level inspection | [docs/UPDATE_REPORT_2026-07-17.md](docs/UPDATE_REPORT_2026-07-17.md) |
  182. | 2026-04-24 | 🧰 **Skill release** — published `skillward-audit-skill`, a Claude Code / OpenClaw skill that lets agents audit any skill bundle (folder / `.zip` / `.tar.gz`) directly through the SkillWard service | [docs/UPDATE_REPORT_2026-04-24.md](docs/UPDATE_REPORT_2026-04-24.md) |
  183. | 2026-04-22 | 🛑 **UI refresh** — batch-scan progress is persisted automatically; added a scan-result reuse mechanism | [docs/UPDATE_REPORT_2026-04-21.md](docs/UPDATE_REPORT_2026-04-21.md) |
  184. | 2026-04-14 | 🧠 **Stage B prompt redesign** — Stage B LLM triage prompt upgraded to a structured System + User two-part prompt | [docs/UPDATE_REPORT_2026-04-14.md](docs/UPDATE_REPORT_2026-04-14.md) |
  185. | 2026-04-10 | 🔒 **Sandbox gateway stability fix** — fixed the OpenClaw Gateway daemon not starting, resolving the exec-approval failure | [docs/UPDATE_REPORT_2026-04-10.md](docs/UPDATE_REPORT_2026-04-10.md) |
  186. ---
  187. ## License
  188. [Apache License 2.0](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.