husk-scanner 0.1.0__tar.gz

husk_scanner-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam
+
+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.

husk_scanner-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: husk-scanner
+Version: 0.1.0
+Summary: Static security scanner for AI agent skill packages — built and adversarially self-tested against documented bypass techniques, validated against real confirmed-malicious samples.
+Author: Adam
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/YOUR-USERNAME/husk
+Project-URL: Repository, https://github.com/YOUR-USERNAME/husk
+Project-URL: Benchmark, https://github.com/YOUR-USERNAME/husk/blob/main/BENCHMARK.md
+Project-URL: Bug Tracker, https://github.com/YOUR-USERNAME/husk/issues
+Keywords: security,ai-agents,skill-packages,static-analysis,malware-detection,mcp,claude,llm-security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Environment :: Console
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# Husk
+
+[![Tests](https://github.com/YOUR-USERNAME/husk/actions/workflows/tests.yml/badge.svg)](https://github.com/YOUR-USERNAME/husk/actions/workflows/tests.yml)
+
+A static security scanner for AI agent skill packages — built to specifically defend against bypass techniques that were shown, in published 2026 security research, to defeat production scanners from Snyk, Cisco, and Vercel's skills.sh.
+
+## Benchmark — how it compares
+
+Real numbers, real datasets, no cherry-picking: full results and
+methodology in [BENCHMARK.md](BENCHMARK.md).
+
+![Husk vs. competitors, matched precision](assets/benchmark_comparison.png)
+
+At matched precision (each tool's strictest reading), Husk has the
+best combination of recall and precision of every real competitor
+tested — and it's the only tool near the "usable as an automated gate"
+corner:
+
+![Precision vs. recall tradeoff](assets/precision_recall_tradeoff.png)
+
+| | Recall (real malicious) | Precision (real legitimate) |
+|---|---|---|
+| **Husk** | **61.5–64.4% (full datasets, 11,470 real samples)** | **98.0%** |
+| Best competitor at matched precision | ~57% | 81–94% |
+| Best competitor raw recall (loose mode, high false positives) | 92.5% | 22–59% |
+
+Snyk's own Agent Scan is excluded from the numeric comparison — its
+real analysis endpoint returns 403 even with a valid account token
+(documented in BENCHMARK.md), so no real detection number was
+obtainable, not because it performed worse.
+
+## Why this exists
+
+AI agents can now install "skills" — reusable packages that tell an agent how to accomplish tasks, often bundling instructions with executable code. This is a fast-growing, under-protected attack surface: research published by Cisco (January 2026) found that roughly a quarter of agent skills across major registries contained at least one security vulnerability, and coordinated malicious-skill campaigns have already compromised thousands of skills across registries like ClawHub.
+
+In June 2026, Trail of Bits researchers (published via the Cloud Security Alliance) demonstrated that the existing detection tools protecting these registries — including tools from Snyk, Cisco, and Vercel — could be bypassed using well-understood obfuscation techniques, in most cases in under an hour of effort. Some of these tools rely on an LLM to judge whether a skill is safe, which introduces a further weakness: the judge itself can be talked out of flagging something dangerous.
+
+Husk is a response to that specific finding — not a general-purpose scanner, but one built and tested against the exact documented bypass techniques that beat the existing tools.
+
+## What it defends against
+
+| Technique | What it does | Status |
+|---|---|---|
+| Whitespace inflation | Pads a file with blank content to push malicious code past a scanner's context limit | Detected |
+| Bytecode / base64 hiding | Encodes the payload so plain-text pattern matching can't read it | Detected, decoded, and recursively re-scanned |
+| Archive indirection | Hides the payload inside a nested archive disguised with an innocent file extension | Detected via real file signatures, not filenames — recurses through nested archives |
+| Prompt-injection against the scanner itself | Talks an LLM-based judge into approving a malicious skill | Not applicable by design — Husk never uses an LLM to make a safety decision; all detection is deterministic pattern analysis |
+| Hidden instructions (prompt injection *targeting the agent*) | Directive language hidden in markdown/HTML comments, invisible on render, instructing the AI agent to act against the user's interest | Detected — verified against a real published example from academic research on 98,380 real-world skills |
+| Credential harvesting | Scans for `.env`, `.pem`, `credentials.json`, SSH keys, etc. and exfiltrates them, often disguised as a backup/CI step | Detected — requires both file-access-to-a-credential-pattern AND network-send capability present, specifically to avoid flagging normal setup docs that just mention `.env` |
+| Fake-prerequisite social engineering | Plain-English instructions telling a human to manually download and run a "required utility" — the actual dominant real-world pattern (86.3% of wild malicious skills per published research) | Detected — added after real-dataset testing revealed modules 1-6 caught 0/8 real malicious samples; now 8/8 |
+| Exfiltration chains | The specific documented sequence: read a file, base64-encode it, send it over the network | Detected as a three-step chain, not a single pattern |
+
+## Validated against real-world research, not just self-built test cases
+
+Beyond the self-built test suite, Husk's hidden-instruction detector has been verified against an actual documented attack published in "*'Do Not Mention This to the User': Detecting and Understanding Malicious Agent Skills in the Wild*" — a large-scale academic study that confirmed 157 malicious skills out of a 98,380-skill snapshot. The paper's title comes directly from a real malicious skill instructing an agent to silently exfiltrate data. Husk correctly flags that exact pattern, and correctly leaves a normal, honest code comment unflagged.
+
+## How detection works, honestly
+
+Husk does not use machine learning or an LLM to decide whether something is safe. Every check is deterministic: opcode inspection for pickle files, pattern matching against known-dangerous constructs, real binary signature checks for archives, and a lightweight constant-propagation pass that resolves simple string concatenation before pattern matching, specifically to catch payloads split across variables to dodge plain-text detection.
+
+This is a first version. It has been adversarially self-tested — evasion variants were built specifically to try to defeat each check, two real gaps were found in that process (Unicode whitespace padding, and base64 payloads split across multiple short fragments), and both were fixed and re-verified. That process is ongoing; no static scanner is ever a finished, unbeatable thing, and Husk does not claim to be one.
+
+## Install
+
+```bash
+pip install git+https://github.com/YOUR-USERNAME/husk.git
+```
+
+Or, for development (editable install, includes the test suite):
+
+```bash
+git clone https://github.com/YOUR-USERNAME/husk.git
+cd husk
+pip install -e ".[dev]"
+python3 -m pytest tests/test_scanner.py -v   # 13 passed, 2 xfailed (see below)
+```
+
+## Usage
+
+```bash
+# Scan a single skill file
+husk skill path/to/SKILL.md
+
+# Scan a whole skill package (handles nested/disguised archives)
+husk package path/to/skill_package/
+
+# Scan a pickle-based model file
+husk model path/to/model.pkl
+```
+
+Exit code is `0` for SAFE, `1` for FLAGGED — safe to use directly in CI.
+
+## Optional: basic dynamic sandbox
+
+```bash
+husk package path/to/skill_package/ --sandbox
+```
+
+For the strongest isolation level (real filesystem isolation, not just
+network/process), install `bubblewrap` — optional, not a Python
+dependency, and the sandbox degrades gracefully without it:
+
+```bash
+sudo apt-get install bubblewrap   # Debian/Ubuntu
+```
+
+Static analysis and the LLM-review layer both READ a skill before
+anything runs. Some real attacks are specifically built to defeat
+that — logic bombs that stay dormant until a condition is met, so
+nothing in the file's text ever reveals the dangerous behavior. This
+flag actually **runs** the package's Python scripts in a restricted,
+observed environment and reports what they did, not just what they say.
+
+**Real, honest limits — read this before trusting it**: network and
+filesystem isolation are genuinely kernel-enforced when bubblewrap is
+available (the same underlying technology Flatpak uses in production
+to sandbox untrusted applications) — a real network namespace with no
+route out, and a real filesystem view where unbound paths are
+genuinely invisible (verified directly: a real `FileNotFoundError`,
+not a permission error). Falls back honestly to weaker levels when
+bubblewrap isn't available (network+process isolation via `unshare`,
+or resource-limits-only as a last resort) — every result reports
+exactly which level actually ran via `isolation_level`, never silently
+claiming protection that isn't there. Observation is
+limited to exit code, stdout/stderr, and a filesystem diff — no deep
+syscall tracing. Python, JavaScript, shell, Ruby, Rust, and Go scripts
+are sandboxed (Rust/Go are compiled to a binary first, outside the
+sandbox — the compiler itself needs broader access than a script
+should get — then only the resulting binary's runtime behavior is
+sandboxed; only standalone single-file source with no external crate/
+module dependencies compiles this way, a real v1 limitation reported
+plainly as a compilation note, not silently skipped or treated as a
+security finding either way — the languages an interpreter/compiler is
+actually verified available for in the running environment; an
+unsupported or missing one is skipped cleanly, not silently ignored or
+crashed on). A clean run means
+nothing bad happened *this time*, under *these* inputs — not a
+guarantee the script is safe.
+
+## Optional: LLM semantic review — a backup, not the main event
+
+Static analysis (above) is Husk's real, primary, measured discipline —
+every number in this README's headline results comes from static
+analysis alone, tested against thousands of real payloads (see
+BENCHMARK.md). That's deliberate: this project's purpose is to prove
+static detection can be built well and reinforced honestly against real
+data, not to lean on a model to do the hard part.
+
+That said, static analysis has a real, honest ceiling — some attacks use
+no code and no recognizable pattern at all, only manipulated intent in
+plain language (see `tests/known_misses/`). For exactly those cases,
+and only as a last resort, Husk can optionally ask an LLM for a second
+opinion:
+
+```bash
+export ANTHROPIC_API_KEY=your-key-here
+husk skill path/to/SKILL.md --llm-review
+```
+
+**To be clear about where credit belongs**: when this catches something
+static analysis can't, that result reflects Anthropic's Claude model's
+own reasoning ability, not engineering work done in this project. Husk's
+job here is limited to building the prompt and calling the API — the
+judgment itself is Claude's, and it should be credited as such rather
+than folded into this project's own detection claims.
+
+**The honest tradeoff, stated up front**: this is not free, not local,
+and not private. It costs tokens and sends the skill's content to
+Anthropic's API. It never runs unless you explicitly pass `--llm-review`,
+and if no API key is set, it skips cleanly — the free static result is
+never affected either way.
+
+### Why this uses your own API key, not a hosted service
+
+Husk will never ask for payment, an account, or a login — and this isn't
+an accident or a limitation, it's a deliberate design choice. Your
+`ANTHROPIC_API_KEY` goes straight from your machine to Anthropic's API;
+Husk (and its author) never sees your key, your usage, your bill, or
+your skill content at any point. There's no server in the middle to
+breach, no proprietary code of yours passing through infrastructure
+someone else runs.
+
+This is also, honestly, a deliberate non-business decision. Husk isn't
+trying to become a company — it's meant to be the most useful, most
+transparent, most honestly-documented free tool it can be in this space.
+If that changes something might get built on top of this later, but the
+free, local-first, BYOK core described in this README is meant to stay
+exactly that.
+
+## What v1 does NOT do yet
+
+- No packaged CLI install (`pip install` support) yet
+- No large-scale false-positive testing against a broad set of legitimate skills yet (currently 11 hand-built test cases, 3 clean / 8 flagged, zero false positives so far — but this is a small sample)
+- Archive extraction currently supports ZIP; GZIP/7z/RAR extraction is detected but not yet unpacked
+- Credential-harvesting detection only covers a fixed list of filename patterns (.env, .pem, credentials.json, etc.) — a renamed or unlisted credential file type would be missed
+- Exfiltration-chain detection currently checks for presence of all three steps anywhere in the file, not strict call-order — a coincidental combination could theoretically false-positive, though none has been observed yet
+- **Does not reliably catch novel, semantically-disguised attacks with no code and no recognizable keywords** — tested directly against an independent academic dataset (AgentTrap) with genuinely different attack styles than the campaign used for the "8/8" validation elsewhere in this README, and missed both samples tried (a subtle instruction-blurring attack, and a fake "compliance auditor" that asks in plain prose for secrets to be sent to an external endpoint). This matches independent published research (see BENCHMARK.md) showing static pattern-matching tops out around 13-32% recall on novel/disguised attacks generally — not a Husk-specific flaw, but a real, honest limit of this entire approach. Husk is a fast, free, local first-pass filter, not a complete security boundary.
+
+## Research this project is grounded in
+
+- Trail of Bits / Cloud Security Alliance, *"AI Agent Skill Scanners: Bypassed Across the Board"* (June 2026)
+- OWASP Agentic Skills Top 10 (v0.5, June 2026)
+- Cisco skill registry security research (January 2026)
+- *"'Do Not Mention This to the User': Detecting and Understanding Malicious Agent Skills in the Wild"* — 98,380-skill academic study, 157 confirmed malicious
+
+## License
+
+MIT

husk_scanner-0.1.0/README.md

@@ -0,0 +1,208 @@
+# Husk
+
+[![Tests](https://github.com/YOUR-USERNAME/husk/actions/workflows/tests.yml/badge.svg)](https://github.com/YOUR-USERNAME/husk/actions/workflows/tests.yml)
+
+A static security scanner for AI agent skill packages — built to specifically defend against bypass techniques that were shown, in published 2026 security research, to defeat production scanners from Snyk, Cisco, and Vercel's skills.sh.
+
+## Benchmark — how it compares
+
+Real numbers, real datasets, no cherry-picking: full results and
+methodology in [BENCHMARK.md](BENCHMARK.md).
+
+![Husk vs. competitors, matched precision](assets/benchmark_comparison.png)
+
+At matched precision (each tool's strictest reading), Husk has the
+best combination of recall and precision of every real competitor
+tested — and it's the only tool near the "usable as an automated gate"
+corner:
+
+![Precision vs. recall tradeoff](assets/precision_recall_tradeoff.png)
+
+| | Recall (real malicious) | Precision (real legitimate) |
+|---|---|---|
+| **Husk** | **61.5–64.4% (full datasets, 11,470 real samples)** | **98.0%** |
+| Best competitor at matched precision | ~57% | 81–94% |
+| Best competitor raw recall (loose mode, high false positives) | 92.5% | 22–59% |
+
+Snyk's own Agent Scan is excluded from the numeric comparison — its
+real analysis endpoint returns 403 even with a valid account token
+(documented in BENCHMARK.md), so no real detection number was
+obtainable, not because it performed worse.
+
+## Why this exists
+
+AI agents can now install "skills" — reusable packages that tell an agent how to accomplish tasks, often bundling instructions with executable code. This is a fast-growing, under-protected attack surface: research published by Cisco (January 2026) found that roughly a quarter of agent skills across major registries contained at least one security vulnerability, and coordinated malicious-skill campaigns have already compromised thousands of skills across registries like ClawHub.
+
+In June 2026, Trail of Bits researchers (published via the Cloud Security Alliance) demonstrated that the existing detection tools protecting these registries — including tools from Snyk, Cisco, and Vercel — could be bypassed using well-understood obfuscation techniques, in most cases in under an hour of effort. Some of these tools rely on an LLM to judge whether a skill is safe, which introduces a further weakness: the judge itself can be talked out of flagging something dangerous.
+
+Husk is a response to that specific finding — not a general-purpose scanner, but one built and tested against the exact documented bypass techniques that beat the existing tools.
+
+## What it defends against
+
+| Technique | What it does | Status |
+|---|---|---|
+| Whitespace inflation | Pads a file with blank content to push malicious code past a scanner's context limit | Detected |
+| Bytecode / base64 hiding | Encodes the payload so plain-text pattern matching can't read it | Detected, decoded, and recursively re-scanned |
+| Archive indirection | Hides the payload inside a nested archive disguised with an innocent file extension | Detected via real file signatures, not filenames — recurses through nested archives |
+| Prompt-injection against the scanner itself | Talks an LLM-based judge into approving a malicious skill | Not applicable by design — Husk never uses an LLM to make a safety decision; all detection is deterministic pattern analysis |
+| Hidden instructions (prompt injection *targeting the agent*) | Directive language hidden in markdown/HTML comments, invisible on render, instructing the AI agent to act against the user's interest | Detected — verified against a real published example from academic research on 98,380 real-world skills |
+| Credential harvesting | Scans for `.env`, `.pem`, `credentials.json`, SSH keys, etc. and exfiltrates them, often disguised as a backup/CI step | Detected — requires both file-access-to-a-credential-pattern AND network-send capability present, specifically to avoid flagging normal setup docs that just mention `.env` |
+| Fake-prerequisite social engineering | Plain-English instructions telling a human to manually download and run a "required utility" — the actual dominant real-world pattern (86.3% of wild malicious skills per published research) | Detected — added after real-dataset testing revealed modules 1-6 caught 0/8 real malicious samples; now 8/8 |
+| Exfiltration chains | The specific documented sequence: read a file, base64-encode it, send it over the network | Detected as a three-step chain, not a single pattern |
+
+## Validated against real-world research, not just self-built test cases
+
+Beyond the self-built test suite, Husk's hidden-instruction detector has been verified against an actual documented attack published in "*'Do Not Mention This to the User': Detecting and Understanding Malicious Agent Skills in the Wild*" — a large-scale academic study that confirmed 157 malicious skills out of a 98,380-skill snapshot. The paper's title comes directly from a real malicious skill instructing an agent to silently exfiltrate data. Husk correctly flags that exact pattern, and correctly leaves a normal, honest code comment unflagged.
+
+## How detection works, honestly
+
+Husk does not use machine learning or an LLM to decide whether something is safe. Every check is deterministic: opcode inspection for pickle files, pattern matching against known-dangerous constructs, real binary signature checks for archives, and a lightweight constant-propagation pass that resolves simple string concatenation before pattern matching, specifically to catch payloads split across variables to dodge plain-text detection.
+
+This is a first version. It has been adversarially self-tested — evasion variants were built specifically to try to defeat each check, two real gaps were found in that process (Unicode whitespace padding, and base64 payloads split across multiple short fragments), and both were fixed and re-verified. That process is ongoing; no static scanner is ever a finished, unbeatable thing, and Husk does not claim to be one.
+
+## Install
+
+```bash
+pip install git+https://github.com/YOUR-USERNAME/husk.git
+```
+
+Or, for development (editable install, includes the test suite):
+
+```bash
+git clone https://github.com/YOUR-USERNAME/husk.git
+cd husk
+pip install -e ".[dev]"
+python3 -m pytest tests/test_scanner.py -v   # 13 passed, 2 xfailed (see below)
+```
+
+## Usage
+
+```bash
+# Scan a single skill file
+husk skill path/to/SKILL.md
+
+# Scan a whole skill package (handles nested/disguised archives)
+husk package path/to/skill_package/
+
+# Scan a pickle-based model file
+husk model path/to/model.pkl
+```
+
+Exit code is `0` for SAFE, `1` for FLAGGED — safe to use directly in CI.
+
+## Optional: basic dynamic sandbox
+
+```bash
+husk package path/to/skill_package/ --sandbox
+```
+
+For the strongest isolation level (real filesystem isolation, not just
+network/process), install `bubblewrap` — optional, not a Python
+dependency, and the sandbox degrades gracefully without it:
+
+```bash
+sudo apt-get install bubblewrap   # Debian/Ubuntu
+```
+
+Static analysis and the LLM-review layer both READ a skill before
+anything runs. Some real attacks are specifically built to defeat
+that — logic bombs that stay dormant until a condition is met, so
+nothing in the file's text ever reveals the dangerous behavior. This
+flag actually **runs** the package's Python scripts in a restricted,
+observed environment and reports what they did, not just what they say.
+
+**Real, honest limits — read this before trusting it**: network and
+filesystem isolation are genuinely kernel-enforced when bubblewrap is
+available (the same underlying technology Flatpak uses in production
+to sandbox untrusted applications) — a real network namespace with no
+route out, and a real filesystem view where unbound paths are
+genuinely invisible (verified directly: a real `FileNotFoundError`,
+not a permission error). Falls back honestly to weaker levels when
+bubblewrap isn't available (network+process isolation via `unshare`,
+or resource-limits-only as a last resort) — every result reports
+exactly which level actually ran via `isolation_level`, never silently
+claiming protection that isn't there. Observation is
+limited to exit code, stdout/stderr, and a filesystem diff — no deep
+syscall tracing. Python, JavaScript, shell, Ruby, Rust, and Go scripts
+are sandboxed (Rust/Go are compiled to a binary first, outside the
+sandbox — the compiler itself needs broader access than a script
+should get — then only the resulting binary's runtime behavior is
+sandboxed; only standalone single-file source with no external crate/
+module dependencies compiles this way, a real v1 limitation reported
+plainly as a compilation note, not silently skipped or treated as a
+security finding either way — the languages an interpreter/compiler is
+actually verified available for in the running environment; an
+unsupported or missing one is skipped cleanly, not silently ignored or
+crashed on). A clean run means
+nothing bad happened *this time*, under *these* inputs — not a
+guarantee the script is safe.
+
+## Optional: LLM semantic review — a backup, not the main event
+
+Static analysis (above) is Husk's real, primary, measured discipline —
+every number in this README's headline results comes from static
+analysis alone, tested against thousands of real payloads (see
+BENCHMARK.md). That's deliberate: this project's purpose is to prove
+static detection can be built well and reinforced honestly against real
+data, not to lean on a model to do the hard part.
+
+That said, static analysis has a real, honest ceiling — some attacks use
+no code and no recognizable pattern at all, only manipulated intent in
+plain language (see `tests/known_misses/`). For exactly those cases,
+and only as a last resort, Husk can optionally ask an LLM for a second
+opinion:
+
+```bash
+export ANTHROPIC_API_KEY=your-key-here
+husk skill path/to/SKILL.md --llm-review
+```
+
+**To be clear about where credit belongs**: when this catches something
+static analysis can't, that result reflects Anthropic's Claude model's
+own reasoning ability, not engineering work done in this project. Husk's
+job here is limited to building the prompt and calling the API — the
+judgment itself is Claude's, and it should be credited as such rather
+than folded into this project's own detection claims.
+
+**The honest tradeoff, stated up front**: this is not free, not local,
+and not private. It costs tokens and sends the skill's content to
+Anthropic's API. It never runs unless you explicitly pass `--llm-review`,
+and if no API key is set, it skips cleanly — the free static result is
+never affected either way.
+
+### Why this uses your own API key, not a hosted service
+
+Husk will never ask for payment, an account, or a login — and this isn't
+an accident or a limitation, it's a deliberate design choice. Your
+`ANTHROPIC_API_KEY` goes straight from your machine to Anthropic's API;
+Husk (and its author) never sees your key, your usage, your bill, or
+your skill content at any point. There's no server in the middle to
+breach, no proprietary code of yours passing through infrastructure
+someone else runs.
+
+This is also, honestly, a deliberate non-business decision. Husk isn't
+trying to become a company — it's meant to be the most useful, most
+transparent, most honestly-documented free tool it can be in this space.
+If that changes something might get built on top of this later, but the
+free, local-first, BYOK core described in this README is meant to stay
+exactly that.
+
+## What v1 does NOT do yet
+
+- No packaged CLI install (`pip install` support) yet
+- No large-scale false-positive testing against a broad set of legitimate skills yet (currently 11 hand-built test cases, 3 clean / 8 flagged, zero false positives so far — but this is a small sample)
+- Archive extraction currently supports ZIP; GZIP/7z/RAR extraction is detected but not yet unpacked
+- Credential-harvesting detection only covers a fixed list of filename patterns (.env, .pem, credentials.json, etc.) — a renamed or unlisted credential file type would be missed
+- Exfiltration-chain detection currently checks for presence of all three steps anywhere in the file, not strict call-order — a coincidental combination could theoretically false-positive, though none has been observed yet
+- **Does not reliably catch novel, semantically-disguised attacks with no code and no recognizable keywords** — tested directly against an independent academic dataset (AgentTrap) with genuinely different attack styles than the campaign used for the "8/8" validation elsewhere in this README, and missed both samples tried (a subtle instruction-blurring attack, and a fake "compliance auditor" that asks in plain prose for secrets to be sent to an external endpoint). This matches independent published research (see BENCHMARK.md) showing static pattern-matching tops out around 13-32% recall on novel/disguised attacks generally — not a Husk-specific flaw, but a real, honest limit of this entire approach. Husk is a fast, free, local first-pass filter, not a complete security boundary.
+
+## Research this project is grounded in
+
+- Trail of Bits / Cloud Security Alliance, *"AI Agent Skill Scanners: Bypassed Across the Board"* (June 2026)
+- OWASP Agentic Skills Top 10 (v0.5, June 2026)
+- Cisco skill registry security research (January 2026)
+- *"'Do Not Mention This to the User': Detecting and Understanding Malicious Agent Skills in the Wild"* — 98,380-skill academic study, 157 confirmed malicious
+
+## License
+
+MIT

husk_scanner-0.1.0/pyproject.toml

@@ -0,0 +1,99 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "husk-scanner"
+version = "0.1.0"
+description = "Static security scanner for AI agent skill packages — built and adversarially self-tested against documented bypass techniques, validated against real confirmed-malicious samples."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    {name = "Adam"},
+]
+keywords = [
+    "security", "ai-agents", "skill-packages", "static-analysis",
+    "malware-detection", "mcp", "claude", "llm-security",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Operating System :: OS Independent",
+    "Topic :: Security",
+    "Topic :: Software Development :: Quality Assurance",
+    "Environment :: Console",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-cov>=4.0", "ruff>=0.6.0", "mypy>=1.10"]
+
+[project.urls]
+Homepage = "https://github.com/YOUR-USERNAME/husk"
+Repository = "https://github.com/YOUR-USERNAME/husk"
+Benchmark = "https://github.com/YOUR-USERNAME/husk/blob/main/BENCHMARK.md"
+"Bug Tracker" = "https://github.com/YOUR-USERNAME/husk/issues"
+
+[project.scripts]
+husk = "husk.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "SIM", "S", "BLE", "PL"]
+ignore = [
+    # Deliberately, consistently allowed project-wide: this tool needs
+    # to degrade gracefully rather than crash on unexpected failures -
+    # LLM API calls, sandbox subprocess execution, pickle/base64
+    # decoding of untrusted content. Each site is already documented
+    # with a comment explaining why a broad catch is the right choice
+    # there specifically, not a one-off shortcut.
+    "BLE001",
+    # Also deliberate: every long line here is a regex pattern or a
+    # long, explicit description string for a finding message.
+    # Mechanically wrapping these to fit a line-length limit risks
+    # introducing a real bug (a misplaced line break inside a regex
+    # pattern is exactly the class of mistake this project has been
+    # careful to avoid throughout - several real precision bugs this
+    # session came from exactly this kind of subtle regex error).
+    # Explicit over terse is the deliberate style choice here.
+    "E501",
+    # Also deliberate: every flagged "magic value" here is either a
+    # well-known network/protocol constant (127, 169, 254, 172,
+    # 16-31, 192, 168 - the actual RFC 1918 private-IP-range octets,
+    # genuinely MORE readable as literals matching the real spec than
+    # behind an arbitrarily-named local constant) or a small,
+    # self-explanatory detection threshold with surrounding context
+    # explaining it. Wrapping each in a locally-scoped constant name
+    # would add indirection without adding real clarity.
+    "PLR2004",
+    # Also deliberate: PLR0911/0912/0915 flag functions with many
+    # return statements/branches/lines - expected and appropriate for
+    # this project's orchestrator functions (scan_skill_file legitimately
+    # chains ~28 sequential detection checks; that's the whole point of
+    # the function). Splitting it into artificial sub-functions purely
+    # to satisfy a line-count metric, on a 2000+ line file with
+    # extensive existing test coverage validating current behavior,
+    # would add real refactor risk for no correctness or security
+    # benefit - a genuine architectural simplification is a larger,
+    # deliberate undertaking, not a lint-driven one.
+    "PLR0911", "PLR0912", "PLR0915",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Test files: sys.path manipulation before imports is the established
+# pattern across this test suite (no installed-package assumption),
+# and S101 (no-assert) is a false positive here - pytest's whole
+# mechanism relies on bare assert statements in tests, this rule
+# exists for production code where asserts get stripped in optimized
+# mode.
+"tests/*" = ["E402", "S101"]

husk_scanner-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

husk_scanner-0.1.0/src/husk/__init__.py

@@ -0,0 +1,15 @@
+"""
+Husk — a static security scanner for AI agent skill packages.
+
+Built and adversarially self-tested against documented 2026 bypass
+techniques, then validated against real confirmed-malicious samples.
+See README.md and BENCHMARK.md for the full story, including honest
+limitations.
+"""
+
+from .package_scanner import scan_package
+from .pickle_scanner import scan_file as scan_pickle_file
+from .skill_scanner import scan_skill_file
+
+__version__ = "0.1.0"
+__all__ = ["scan_skill_file", "scan_package", "scan_pickle_file"]