skill-sentry-cli 2.0.0__tar.gz

skill_sentry_cli-2.0.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.venv-laya/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# SkillSentry runtime state
+skillsentry.toml
+*.db
+*.db-wal
+*.db-shm
+reports/
+
+# Reports produced during local runs
+*.sarif
+stix-bundle.json
+
+# Frontend
+ui/node_modules/
+ui/dist/
+skill_sentry_cli/ui/dist/
+ui/.vite/
+
+# OS / editors
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/

skill_sentry_cli-2.0.0/CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing to SkillSentry
+
+Thanks for helping defend the agent skill supply chain! 🛡️ SkillSentry is MIT-licensed; by contributing you agree your contributions are licensed under the same terms.
+
+**Start here:** [Developer Guide](docs/10-developer-guide.md) — environment setup, module ownership, coding standards, and extension guides.
+
+---
+
+## Ground Rules
+
+1. **The Verdict JSON Contract v1 is frozen.** Backward-compatible additions (new optional fields) only; breaking changes require a `v2` + migration path and sign-off from all maintainers. See [docs/05-api-reference.md](docs/05-api-reference.md) §5.5.
+2. **Shared identifiers stay shared.** Stage names, WS event names, and severity enums live in one constants module — no stringly-typed duplicates in UI or backend.
+3. **No error path may produce `SAFE`.** Any degraded scan must carry explicit `*-unavailable` findings (fail-safe rule).
+4. **Fixtures are hazardous material.** Malicious fixtures run *only* through `skill-sentry-cli scan` (sandboxed), use fictional C2 domains (`evil-collector.net`, `evil-c2.com`), and never reference real credentials. See fixture safety rules in [docs/08-testing-and-evaluation.md](docs/08-testing-and-evaluation.md) §8.2.
+5. **Fusion-weight / prompt / anchor / masquerade changes must re-run the full fixture corpus** and update `tests/expected_verdicts.json` in the same PR.
+6. **Docs ship with behavior.** Public-facing changes update the relevant `docs/` file in the same PR.
+
+## Development Workflow
+
+```bash
+git clone https://github.com/<org>/skillsentry && cd skillsentry
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+skill-sentry-cli init
+# frontend:
+cd ui && npm install && npm run dev
+# no backend yet? build against the mock server:
+python -m skill_sentry_cli.server.demo_mode --port 8000
+```
+
+- **Branches:** `feat/<topic>`, `fix/<topic>`, `docs/<topic>` off `main`.
+- **Commits:** [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `test:`, `chore:`).
+- **Style:** Python — `ruff check` + `ruff format`, type hints, 3.11+ · TypeScript — `strict: true`, ESLint + Prettier.
+- **PR checklist:**
+  - [ ] Unit tests for new logic; contract tests pass against **both** real API and mock server
+  - [ ] Fixture regression green (`pytest tests/` + `tests/check_expected_verdicts.py`)
+  - [ ] No new dependencies without rationale (minimal-dep principle; pinned lockfile)
+  - [ ] Docs updated (or `docs:` follow-up issue linked)
+  - [ ] No secrets, no real credential formats in tests/fixtures
+
+## Good First Contributions
+
+| Area | Ideas |
+|:---|:---|
+| **Detection** | New AST anchor patterns (PowerShell, Node skills); new evasion-probe indicators; typosquat dictionary expansion |
+| **Fixtures** | Add benign/malicious fixtures toward the 20-skill Phase-1 corpus (with hand-annotated ground-truth lines) |
+| **Canary intents** | New context-aware canary sets (e.g., npm, PyPI, OpenAI keys) — guide: [docs/10-developer-guide.md](docs/10-developer-guide.md) §10.7 |
+| **UI** | Empty/loading/error state polish; accessibility passes (WCAG rules in [docs/06-ui-ux.md](docs/06-ui-ux.md) §6.6) |
+| **Docs** | Tutorials, troubleshooting recipes, translations |
+| **Reports** | SARIF rule-metadata enrichment; Markdown report theming |
+
+## Ownership Map (core team)
+
+Authoritative assignment: **[docs/11-team-and-workload.md](docs/11-team-and-workload.md)**.
+
+| Area | Owner | Modules |
+|:---|:---|:---|
+| Sandbox, deception, models, verdict/reports, server | Dev 1 · Backend + AI Integration | `core/sandbox/`, `core/poisoned_well/`, `core/evasion/`, `core/models/`, `core/verdict/`, `server/`, `cli.py` |
+| Malicious-instruction analysis | Dev 2 · Backend (Skill Analysis) | `core/parser/`, `core/semantic/`, `core/vision/`, `core/cache/`, analysis + benign fixtures |
+| UI + demo assets | Dev 3 · Frontend | `ui/`, README GIF, backup demo video |
+
+Cross-cutting changes (schemas, weights, stage list) need sign-off from all three owners.
+
+## Security Issues
+
+**Do not open public issues for vulnerabilities.** Follow [SECURITY.md](SECURITY.md) (private GitHub Security Advisory, 90-day embargo, safe harbor for good-faith research).
+
+## Community IOC Feed (Phase 2)
+
+Contributing indicators to the community blocklist is **opt-in**, strips all skill content/user identifiers, and is governed by a signed-feed + dispute process ([docs/04-security.md](docs/04-security.md) §4.10).
+
+---
+
+*Powered by Gemma 4 · open weights.*

skill_sentry_cli-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Team SkillSentry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skill_sentry_cli-2.0.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.5
+Name: skill-sentry-cli
+Version: 2.0.0
+Summary: A context-aware firewall for the agent skill supply chain with Poisoned Well active defense.
+Project-URL: Homepage, https://github.com/EmberPhantom/SkillSentry
+Project-URL: Source, https://github.com/EmberPhantom/SkillSentry
+Project-URL: Issues, https://github.com/EmberPhantom/SkillSentry/issues
+Project-URL: Changelog, https://github.com/EmberPhantom/SkillSentry/blob/main/docs/CHANGELOG.md
+Author: Team SkillSentry
+License: MIT
+License-File: LICENSE
+Keywords: agent-skills,local-llm,sandbox,security,supply-chain
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: docker<8.0,>=7.0
+Requires-Dist: fastapi<1.0,>=0.115
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: jinja2<4.0,>=3.1
+Requires-Dist: pillow<13.0,>=10.0
+Requires-Dist: pydantic<3.0,>=2.9
+Requires-Dist: python-frontmatter<2.0,>=1.1
+Requires-Dist: pyyaml<7.0,>=6.0.1
+Requires-Dist: rich<15.0,>=13.7
+Requires-Dist: typer<1.0,>=0.16
+Requires-Dist: uvicorn[standard]<1.0,>=0.30
+Requires-Dist: watchdog<7.0,>=4.0
+Provides-Extra: dev
+Requires-Dist: hypothesis<7.0,>=6.100; extra == 'dev'
+Requires-Dist: jsonschema<5.0,>=4.22; extra == 'dev'
+Requires-Dist: pytest-asyncio<2.0,>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov<8.0,>=5.0; extra == 'dev'
+Requires-Dist: pytest<9.0,>=8.2; extra == 'dev'
+Requires-Dist: respx<1.0,>=0.21; extra == 'dev'
+Requires-Dist: ruff<1.0,>=0.6; extra == 'dev'
+Provides-Extra: laya
+Requires-Dist: laya<0.5,>=0.4.17; extra == 'laya'
+Description-Content-Type: text/markdown
+
+# SkillSentry
+
+**Audit agent skills before you install them.** SkillSentry checks a skill's text and scripts, runs its entrypoint inside a locked-down Docker sandbox, and returns one verdict: `SAFE`, `SUSPICIOUS`, `MALICIOUS`, or `UNSCANNED` when the scan could not finish. Analysis runs on your machine through a local model, and nothing is uploaded.
+
+## Install
+
+```bash
+pipx install skill-sentry-cli        # or: python -m pip install skill-sentry-cli
+skill-sentry-cli setup              # checks Docker and the local model, builds the sandbox
+skill-sentry-cli doctor             # confirms the setup is ready
+```
+
+Requirements: Python 3.11 to 3.13, Docker (for the sandbox), and [Ollama](https://ollama.com) for the local model. `skill-sentry-cli doctor` tells you the exact command for anything missing.
+
+## First scan
+
+```bash
+skill-sentry-cli scan path/to/my-skill
+skill-sentry-cli scan path/to/skills-folder --format sarif --sarif-out results.sarif
+```
+
+Exit codes: `0` below the gate, `1` at or above it, `2` a usage error, `3` an operational error. The default gate is `--fail-on suspicious`.
+
+## Documentation
+
+- [User guide](https://github.com/EmberPhantom/SkillSentry/blob/main/docs/16-user-guide.md): install, first scans, reports, dashboard, CI, troubleshooting.
+- [CLI reference](https://github.com/EmberPhantom/SkillSentry/blob/main/docs/07-cli-reference.md)
+- [Security model](https://github.com/EmberPhantom/SkillSentry/blob/main/docs/04-security.md)
+- [Source and issues](https://github.com/EmberPhantom/SkillSentry)
+
+MIT licensed.

skill_sentry_cli-2.0.0/README.md

@@ -0,0 +1,174 @@
+<div align="center">
+
+# 🛡️ SkillSentry
+
+**A Context-Aware Firewall for the Agent Skill Supply Chain with "Poisoned Well" Active Defense**
+
+*Your proprietary skills never leave your machine for auditing. We don't just block attackers; we follow them home.*
+
+![License: MIT](https://img.shields.io/badge/license-MIT-emerald) ![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue) ![Docker](https://img.shields.io/badge/sandbox-Docker-2496ED?logo=docker&logoColor=white)
+
+**⚡ Runs fully on your machine · open weights ⚡**
+
+<!-- Record the 30-sec demo GIF during M4 (docs/08-testing-and-evaluation.md §8.7) -->
+
+</div>
+
+---
+
+## 🔎 30-Second Pitch
+
+Agent Skills execute code **and** inject instructions into AI agents — the newest supply-chain attack surface. Snyk's Feb 2026 *ToxicSkills* audit found **~1,467 malicious skills** (prompt injection in **36%** of ClawHub skills examined); the *ClawHavoc* campaign pushed **1,184+ malicious skills** in six weeks. OWASP now lists **AST01 — Malicious Skills** as a formal risk category.
+
+**SkillSentry** audits any skill **before it installs — 100% locally**: local multimodal language-model reasoning (text + vision) fused with deterministic AST anchors and a hardened Docker sandbox featuring **context-aware honeypots**, **sandbox-evasion detection**, and the **☠️ Poisoned Well** — fake, intent-matched credentials that let us catch the thief, decode our canary marker out of their exfil traffic, and map their C2 infrastructure. Clean skills install with zero friction (⚡ < 2 s cached re-scans). Malicious skills are blocked with hard, line-cited evidence and a STIX IOC export.
+
+## 🏴‍☠️ Threat Model
+
+```mermaid
+flowchart LR
+    subgraph Threat_Actors["🏴‍☠️ Threat Actors"]
+        A1["Compromised Dev Account"]
+        A2["Typosquatter"]
+        A3["Supply Chain Poisoner<br/>(benign → malicious update)"]
+    end
+    subgraph Registry["📦 Public Registry (ClawHub)"]
+        R1["Malicious Skill Package"]
+    end
+    subgraph Local_Env["💻 Developer Local Environment"]
+        L1["Agent IDE / CLI"] --> L2["SkillSentry<br/>Pre-Install Gate"]
+        L2 -->|"✅ CLEAN"| L3["Agent Runtime"]
+        L2 -->|"🚫 MALICIOUS"| L4["Block & Map C2"]
+    end
+    A1 --> R1
+    A2 --> R1
+    A3 --> R1
+    R1 -->|"1. Download"| L1
+    L1 -->|"2. Audit"| L2
+```
+
+Attack vectors covered: credential theft · image-hidden prompt injection (white-on-white payloads) · typosquatting · tool poisoning · obfuscation (`eval`, base64 bombs) · sandbox evasion · post-install supply-chain poisoning. Full model: [docs/04-security.md](docs/04-security.md).
+
+## 🏗️ Architecture — the 8-Stage Pipeline
+
+```mermaid
+flowchart TD
+    A["📦 Skill Package (SKILL.md + scripts/ + assets/)"] --> S0
+    S0["0 · Incremental Cache — SHA-256 → SQLite, hit = ⚡ <2s"] --> S1
+    S1["1 · Spec Validation + Typosquat (Levenshtein ≤ 2)"] --> S2
+    S2["2 · Deterministic AST Anchors → local model semantic analysis"] --> S3
+    S3["3 · Multimodal Vision Scan — OCR hidden image payloads"] --> S4
+    S4["4 · Context-Aware Sandbox — masquerade, canary FS, DNS sinkhole, fake HTTP (60s/512MB/1CPU)"] --> S45
+    S45["4.5 · ☠️ Poisoned Well — fake intent-matched creds → track exfil → profile C2"] --> S5
+    S5["5 · Sandbox Evasion Detection — probe ⇒ auto-MALICIOUS"] --> S6
+    S6["6 · Verdict Engine — weighted fusion → 0–100 → SARIF 2.1.0"] --> OUT["✅ Install / 🚫 Block / 🖥️ Triage Dashboard"]
+```
+
+| Why it's different | |
+|:---|:---|
+| **Pre-install + runtime (MCP, Phase 2)** | not just post-install network watching |
+| **LLM + Vision + Sandbox + Active Defense** | not just regex/text scanning |
+| **Deterministic anchoring** | the LLM cannot contradict hard AST facts — credible, not vibes |
+| **Hard-evidence overrides** | canary-marker correlation or evasion probe ⇒ `MALICIOUS`, confidence 1.0 |
+| **100% local** | A quantized local model via Ollama; opt-in cloud fallback; no telemetry |
+| **Fights back** | Poisoned Well deception + C2 tracking + STIX IOC export |
+
+Deep-dives: [Architecture](docs/02-architecture.md) · [Database](docs/03-database.md) · [Security](docs/04-security.md) · [API](docs/05-api-reference.md) · [UI/UX](docs/06-ui-ux.md).
+
+> **Original code:** the sandbox runner, canary filesystem, DNS sinkhole, context-aware honeypot system, sandbox evasion detector, and Poisoned Well correlation engine are original code.
+
+## 🚀 How to Run
+
+Install with `pipx install skill-sentry-cli`, or with the install script in the latest release. Then run `skill-sentry-cli setup`. The step-by-step guide covers first scans, reports, the dashboard, CI, and troubleshooting: **[docs/16-user-guide.md](docs/16-user-guide.md)**.
+
+**Prereqs:** Python 3.11 to 3.13 · Docker (for the sandbox) · [Ollama](https://ollama.com) with a local model. `skill-sentry-cli setup` checks all of these and asks before anything is downloaded.
+
+```bash
+# From a checkout (a PyPI release is planned, not yet published)
+pip install -e .
+cd ui && npm ci && npm run build && cd ..   # builds the dashboard into the package
+skill-sentry-cli init                             # writes skillsentry.toml
+skill-sentry-cli sandbox build                    # builds the sandbox image (needs Docker)
+
+skill-sentry-cli doctor                      # tells you the exact `ollama pull` command for the local model
+
+skill-sentry-cli scan ./fixtures/benign/pdf-summarizer        # ✅ SAFE
+skill-sentry-cli scan ./fixtures/malicious/cloud-sync-pro     # 🚫 MALICIOUS + ☠️ C2 mapped
+skill-sentry-cli scan ./fixtures/benign/pdf-summarizer        # ⚡ cached
+
+skill-sentry-cli serve                    # Dashboard → http://127.0.0.1:8000
+skill-sentry-cli scan cloud-sync-pro --demo-mode  # offline canned demo (skill names), no Docker or model needed
+skill-sentry-cli export <scan_id> --format sarif   # re-render a stored report
+skill-sentry-cli cache stats              # inspect the verdict cache
+```
+
+**Server image:** `docker build -t skillsentry/server:2.0.0 .` then
+`docker run -p 127.0.0.1:8000:8000 skillsentry/server:2.0.0`. The container does not
+mount the Docker socket, so the sandbox is unavailable inside it by default. Mounting
+`/var/run/docker.sock` gives the container root-equivalent control of the host, so only do
+that deliberately.
+
+**Release build and local checks** (CI is blocked while the GitHub account has a billing issue):
+
+```bash
+scripts/check.sh          # lint, format, tests, schema drift, demo smoke
+scripts/build_release.sh  # dashboard, wheel, and a fresh-venv install check
+```
+
+**CI / PR gate (planned):** a `skillsentry/scan` GitHub Action is planned and is not yet published. The intended interface is:
+
+```yaml
+- uses: skillsentry/scan@v1   # planned
+  with:
+    path: ./skills/
+    fail-on: suspicious     # the CLI default is suspicious
+    upload-sarif: true      # GitHub Security tab
+    cache: true             # incremental re-scans
+```
+
+Full CLI reference: [docs/07-cli-reference.md](docs/07-cli-reference.md) · Deployment: [docs/09-deployment-and-production.md](docs/09-deployment-and-production.md) (the whole team server fits a **$12 DigitalOcean droplet**).
+
+## 📊 Evaluation (7+1 fixture corpus)
+
+| Skill | Behavior | Expected | Caught by |
+|:---|:---|:---|:---|
+| `pdf-summarizer` | pure text processing | ✅ SAFE < 30 | — |
+| `git-helper` | local git ops | ✅ SAFE < 30 | — |
+| `image-resizer` | file ops only | ✅ SAFE < 30 | — |
+| `weather-fetch` | **declared** network call | ✅ SAFE < 30 | — (no false positives) |
+| `cloud-sync-pro` | steals `~/.aws/credentials` → DNS tunnel | 🚫 MALICIOUS > 90 | Sandbox + ☠️ Poisoned Well |
+| `invoice-helper` | white-on-white injection in `logo.png` | 🚫 MALICIOUS > 85 | The local vision model (👁 Eye View) |
+| `slack-notif-mal` | probes `/.dockerenv`, steals Slack token | 🚫 MALICIOUS 100 | Evasion detection + context honeypot |
+| `g1t-translate`* | typosquat of `git-translate` | ⚠️ SUSPICIOUS 30–70 | Levenshtein detector |
+
+**Targets:** malicious detection 2/2 (+stretch 3/3) · benign false positives 0/4 · cached re-scan < 2 s · uncached local scan < 90 s · citation accuracy ≥ 80%. Run sheet + metrics methodology: [docs/08-testing-and-evaluation.md](docs/08-testing-and-evaluation.md).
+
+## 📚 Documentation
+
+| Doc | | Doc | |
+|:---|:---|:---|:---|
+| [Project Overview](docs/01-project-overview.md) | problem, positioning, glossary | [API Reference](docs/05-api-reference.md) | REST/WS, verdict contract v1 |
+| [Architecture](docs/02-architecture.md) | 8-stage pipeline, scoring | [UI/UX Design](docs/06-ui-ux.md) | screens, wireframes, UX rules |
+| [Database](docs/03-database.md) | SQLite schema, caching | [CLI Reference](docs/07-cli-reference.md) | commands, config, exit codes |
+| [Security](docs/04-security.md) | threat model, hardening | [Testing & Evaluation](docs/08-testing-and-evaluation.md) | fixtures, Chaos Run, demo script |
+| [Deployment & Production](docs/09-deployment-and-production.md) | pip/Docker/Action, MCP proxy | [Developer Guide](docs/10-developer-guide.md) | setup, contracts, roadmap |
+| [Team & Workload](docs/11-team-and-workload.md) | roles, ownership, milestones M0–M5 | | |
+
+Also: [CHANGELOG](docs/CHANGELOG.md) · [CONTRIBUTING](CONTRIBUTING.md) · [SECURITY](SECURITY.md)
+
+## 🙏 Prior Art (honest citations)
+
+- [Snyk — ToxicSkills: malicious AI agent skills on ClawHub](https://snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub/)
+- Pipelock (OSS runtime network monitoring for agents)
+- AIR Security (enterprise cloud AI-agent firewall)
+- MCP prompt-injection research (tool poisoning / rug-pull literature)
+- [Agent Skill Open Standard](https://agentskills.io/specification) · [Ollama](https://ollama.com)
+
+## 📄 License
+
+MIT — see [LICENSE](LICENSE). Built by Team SkillSentry — Dev 1 (Backend + AI Integration) · Dev 2 (Backend — Skill Analysis) · Dev 3 (Frontend). Roles & workload: [docs/11-team-and-workload.md](docs/11-team-and-workload.md).
+
+<div align="center">
+
+**⚡ Runs fully on your machine · open weights ⚡**
+
+</div>

skill_sentry_cli-2.0.0/SECURITY.md

@@ -0,0 +1,59 @@
+# Security Policy
+
+SkillSentry is a security tool that **executes untrusted code by design** (inside a hardened, sinkhole-only Docker sandbox). We take its own security seriously and welcome responsible disclosure.
+
+> Full security architecture — threat model, sandbox hardening, Poisoned Well ethics, prompt-injection defenses, and known limitations: **[docs/04-security.md](docs/04-security.md)**.
+
+## Supported Versions
+
+| Version | Supported | Notes |
+|:---|:---|:---|
+| 2.0.x | ✅ | Current; receives security fixes |
+| < 2.0 | ❌ | Pre-release concepts; do not use |
+
+## Reporting a Vulnerability
+
+**Please report privately — do NOT open a public issue.**
+
+- **Channel:** GitHub Security Advisories → *"Report a vulnerability"* on this repository.
+- **Include:** reproduction steps, affected version/commit, impact, and (for sandbox issues) whether the escape requires special host configuration.
+- **SLA (target):** acknowledge ≤ 72 h · triage ≤ 7 days · coordinated disclosure with a **90-day default embargo** · reporters credited in release notes.
+
+## Scope
+
+**High-priority (in scope):**
+
+- Sandbox escape from the analysis container (host filesystem write/read, host network access, process breakout)
+- Leakage of **real** (non-canary) host credentials or data to a scanned skill
+- Cache poisoning that yields false `SAFE` verdicts (e.g., forged `scan_cache` rows surviving version checks)
+- Remote code execution in parsers via crafted skill packages (YAML bombs, path traversal, image/SVG handlers)
+- Signature-verification bypass: signed verdicts (sigstore/cosign), community IOC feed, or release artifacts
+- Sinkhole/egress failure that lets sandbox traffic reach the real internet
+- Verdict downgrade attacks: any input that makes the engine emit `SAFE` when hard evidence (Poisoned Well correlation, evasion probe) says `MALICIOUS`
+
+**Out of scope:**
+
+- Demo fixtures being detected (that is the product working)
+- `--demo-mode` canned responses
+- Cloud-fallback (Gemini API) latency or availability
+- Findings that require the user to have disabled documented hardening (e.g., mounting the Docker socket into untrusted containers against our guidance)
+- Social engineering of maintainers
+
+## Design Guarantees You Can Hold Us To
+
+1. **Fail-safe verdicts:** no error path may produce `SAFE`; degraded scans carry explicit `*-unavailable` findings.
+2. **Sinkhole-only egress:** analysis containers have no route to the internet — DNS and HTTP are answered locally.
+3. **Fake-by-construction credentials:** Poisoned Well canaries are generated fake (`SKS-<8hex>` markers); no real secret material is ever created, served, or stored.
+4. **No hack-back:** SkillSentry never connects to attacker infrastructure; C2 indicators are harvested from logs only.
+5. **Local-first privacy:** no telemetry, no phone-home; skill content leaves the machine only if you explicitly enable the Gemini API fallback (the UI always shows the active backend).
+
+## Safe Harbor & Fixture Warning
+
+Good-faith research against **your own** installations and the `fixtures/` corpus is welcome and covered by safe harbor. Never point SkillSentry's deception outputs at third-party infrastructure.
+
+⚠️ `fixtures/malicious/` contains intentionally malicious skill code for testing. It must only ever be executed **through `skill-sentry-cli scan`** (which sandboxes it) — never run fixture scripts directly on a host.
+
+## Secure Distribution
+
+- Phase 2: signed release tags and **sigstore keyless-signed verdicts** (`cosign verify-blob`); until then, prefer installing from source at a reviewed commit or the published Docker image digest.
+- Verify Ollama model digests (`model_version` is recorded with every verdict — see [docs/03-database.md](docs/03-database.md)).

skill_sentry_cli-2.0.0/docs/01-project-overview.md

@@ -0,0 +1,132 @@
+# 1 · Project Overview
+
+> **SkillSentry v2.0** — A Context-Aware Firewall for the Agent Skill Supply Chain with "Poisoned Well" Active Defense.
+
+**One-liner:** An open-source, fully-local gatekeeper that audits Agent Skills *before* installation — fusing Gemma 4 multimodal reasoning (text + vision) with deterministic sandbox telemetry, dynamically adapting honeypots to the skill's declared intent, detecting sandbox evasion, and actively deceiving malicious skills by feeding them fake credentials to track exfiltration back to attacker infrastructure.
+
+**Tagline:** *"Your proprietary skills never leave your machine for auditing. We don't just block attackers; we follow them home."*
+
+---
+
+## 1.1 Why Now — Market Validation
+
+Agent Skills execute code **and** inject instructions into AI agents. They are the newest supply-chain attack surface, and the ecosystem is currently building skills far faster than it is defending them:
+
+- **Snyk's Feb 2026 "ToxicSkills" audit** found **~1,467 malicious skills**, with prompt injection present in **36%** of ClawHub skills examined. ([snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub](https://snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub/))
+- The related **"ClawHavoc"** campaign pushed **1,184+ malicious skills** into OpenClaw's ClawHub registry in six weeks.
+- The **OWASP Agentic Skills Top 10** now lists **AST01 — Malicious Skills** as a formal risk category.
+- Capital is flowing into the space: AI-agent-firewall startup **AIR Security raised $50M** (Sept 2026) — but its product is enterprise/cloud/closed.
+
+**Conclusion:** the threat is real and documented, the market is validated, and the open-source/local-first niche is unoccupied.
+
+## 1.2 The Problem
+
+Attack vectors SkillSentry targets:
+
+| Vector | Example |
+|:---|:---|
+| **Credential theft** | Scripts reading `~/.aws/credentials`, `~/.ssh/id_rsa`, environment variables |
+| **Image-hidden prompt injection** | Payloads in white-on-white text inside bundled images (documented real-world vector) |
+| **Typosquatting** | `g1t-translate` impersonating `git-translate` |
+| **Tool poisoning** | Malicious instructions hidden in skill descriptions/frontmatter |
+| **Obfuscation** | base64-encoded payloads, `eval()` bombs |
+| **Sandbox evasion** | Malware probing for Docker artifacts (`/.dockerenv`) and going dormant |
+| **Supply-chain poisoning** | A benign skill updated with a malicious payload post-install |
+
+## 1.3 The Solution
+
+Before any skill installs, SkillSentry runs an **8-stage inspection pipeline**:
+
+0. **Incremental Cache** — SHA-256 directory hash → cached SARIF verdict in < 2 s
+1. **Spec Validation + Typosquat Detection** — frontmatter rules, Levenshtein distance ≤ 2 against known skill names
+2. **Deterministic Anchor + Semantic Analysis** — AST/regex pre-scan produces *hard facts* ("anchors") fed to Gemma 4 E4B as ground truth
+3. **Multimodal Vision Scan** — Gemma 4 vision OCRs bundled images (white-on-white text, stego-style instructions; SVG scanned as text *and* rendered)
+4. **Context-Aware Behavioral Sandbox** — Docker execution with masquerade layer, intent-matched canary filesystem, DNS sinkhole, fake HTTP responder
+4.5. **☠️ Poisoned Well** — on canary credential read: serve intent-matched *fake* secrets, harvest exfil into the sinkhole, profile the C2
+5. **Sandbox Evasion Detection** — probing for Docker/VM artifacts ⇒ auto-`MALICIOUS`
+6. **Verdict Engine** — weighted signal fusion → risk score 0–100 → SARIF 2.1.0 JSON with line-accurate citations → cached to SQLite
+
+Clean skills install with **zero friction**; malicious skills are blocked with **hard evidence**, and their C2 infrastructure is mapped and exportable as STIX IOCs.
+
+Full pipeline detail: [02-architecture.md](02-architecture.md).
+
+## 1.4 Key Differentiators (Competitive Positioning)
+
+| Feature | Pipelock (OSS) | AIR Security | Text-only Scanners | **SkillSentry v2.0** |
+|:---|:---|:---|:---|:---|
+| **When it acts** | Runtime (post-install) | Cloud policy | Pre-scan | **Pre-install + Runtime (MCP)** |
+| **Detection method** | Network heuristics | Enterprise rules | Regex / LLM text | **LLM + Vision + Sandbox + Active Defense** |
+| **Image-hidden payloads** | ✗ | ✗ | ✗ | **✓ (Gemma 4 Vision)** |
+| **Context-Aware Honeypots** | ✗ | ✗ | ✗ | **✓ (Dynamic Intent Matching)** |
+| **Sandbox Evasion Detection** | ✗ | ✗ | ✗ | **✓ (Anti-Anti-Sandbox)** |
+| **Deterministic Anchoring** | ✗ | ✗ | ✗ | **✓ (AST pre-scan → LLM ground truth)** |
+| **Incremental Scanning** | ✗ | ✗ | ✗ | **✓ (SHA-256 SQLite Cache)** |
+| **Privacy** | Local | Cloud | Varies | **100% local (Ollama)** |
+| **Fights back** | ✗ | ✗ | ✗ | **✓ Poisoned Well + C2 Tracking** |
+| **Cost** | Free | Enterprise $$$ | Free/cheap | **Free & open-source** |
+
+**The wedge:** Pipelock watches the network *after* install. Text scanners are blind to image payloads. AIR is cloud-only. **SkillSentry catches threats pre-install, sees hidden image payloads, never sends your skills off-machine, dynamically adapts its deception to the attacker's intent, detects sandbox-evasion attempts, and actively counter-attacks.**
+
+## 1.5 Success Metrics
+
+| Metric | Target |
+|:---|:---|
+| Malicious fixture detection | 2/2 (+ optional typosquat = 3/3) |
+| Benign false-positive rate | 0/4 |
+| Image-hidden payload catch | ✓ |
+| Context-Aware Poisoned Well | ✓ (matches skill's declared intent) |
+| Sandbox Evasion Detection | ✓ (probing triggers auto-fail) |
+| Scan latency (cached) | < 2 s (SHA-256 SQLite cache) |
+| Poisoned Well activation on credential thief | ✓ with C2 domain captured |
+| Citation accuracy (right source line) | ≥ 80% |
+| Local scan time per skill (E4B, Q4, uncached) | < 90 s |
+
+Evaluation procedure and fixture corpus: [08-testing-and-evaluation.md](08-testing-and-evaluation.md).
+
+## 1.6 Design Principles
+
+1. **Local-first, private by default.** Auditing runs entirely on the user's machine via Ollama. The Gemini API fallback is opt-in. No telemetry, ever.
+2. **Credible, not vibes.** Every LLM judgment is anchored to deterministic evidence (AST/regex findings the model may not contradict) and every `MALICIOUS` verdict ships with `file:line` citations.
+3. **Hard evidence overrides uncertainty.** A confirmed Poisoned Well correlation (canary marker observed in outbound traffic) or a sandbox-evasion probe forces `MALICIOUS` with `confidence: 1.0`, regardless of what the LLM thinks.
+4. **Defense without friction.** Benign skills pass with zero added steps and instant cached re-scans.
+5. **Contract-first.** The Verdict JSON schema is frozen early (milestone M0) so frontend, backend, and AI workstreams integrate without drift.
+6. **Fail safe, demo safe.** `--demo-mode` canned responses guarantee the product story survives network/Docker/model outages (Chaos Run doctrine).
+
+## 1.7 Distribution Surfaces
+
+- `pip install skill-sentry-cli` — CLI + library
+- Published Docker image — server/CI usage
+- `skillsentry/scan@v1` GitHub Action — PR gates, SARIF upload to GitHub Code Scanning, scheduled registry re-scans
+- Phase 2: **MCP runtime proxy** for post-install behavioral enforcement
+
+See [09-deployment-and-production.md](09-deployment-and-production.md).
+
+## 1.8 Glossary
+
+| Term | Definition |
+|:---|:---|
+| **Agent Skill** | A package (`SKILL.md` + scripts + assets) that extends an AI agent with instructions and executable code; the unit SkillSentry audits. |
+| **Deterministic Anchor** | A hard, reproducible static finding (regex/AST) injected into the LLM prompt as ground truth the model must not contradict. |
+| **Canary** | A fake-but-plausible credential (or file) seeded in the sandbox, embedded with a unique marker `SKS-<8hex>`. |
+| **Context-Aware Honeypot** | Canary seeding adapted to the skill's *declared intent* (e.g., fake Slack tokens for a "Slack integration"). |
+| **Poisoned Well** | The active-defense subsystem: serves fake credentials to a detected thief, sinkholes the exfiltration, correlates the canary marker, and profiles the attacker's C2. |
+| **Masquerade** | The layer that hides sandbox artifacts (`/.dockerenv`, `/proc/1/cgroup`, …) so evasion-probing malware behaves normally and reveals itself. |
+| **Sandbox Evasion Probe** | A skill's attempt to detect the analysis environment; treated as hard proof of malice (auto-`MALICIOUS`). |
+| **IOC** | Indicator of Compromise (C2 domain, IP, exfil channel, encoding) harvested during a Poisoned Well engagement; exportable as STIX 2.1. |
+| **Gemma's Eye View** | UI mode showing what Gemma 4 vision actually saw in an image: OCR text + bounding-box overlay + contrast enhancement. |
+| **Verdict** | One of `SAFE` / `SUSPICIOUS` / `MALICIOUS`, with risk score 0–100 and confidence. |
+| **SARIF** | Static Analysis Results Interchange Format 2.1.0 — the standard machine-readable report SkillSentry emits. |
+
+## 1.9 Key Links
+
+| Resource | URL |
+|:---|:---|
+| Gemma 4 docs | https://ai.google.dev/gemma/docs/core |
+| Gemini API | https://ai.google.dev/gemini-api/docs |
+| Agent Skill Open Standard | https://agentskills.io/specification |
+| Snyk ToxicSkills audit | https://snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub/ |
+| Ollama (local serving) | https://ollama.com |
+
+---
+
+**Prior art (honest citations):** Snyk ToxicSkills audit · Pipelock · AIR Security · MCP prompt-injection research.