Pinocchio-Scanner-Skill: AI Skill Safety Guard


Pinocchio-Scanner-Skill is a security scanner for AI agent skill files. It performs static analysis across code and documentation to detect command injection, unsafe file access, hardcoded secrets, prompt injection patterns, and risky MCP definitions before they reach production.

---

Why pinocchio-scan

Community-made skills often run with high privileges (filesystem, shell, network, tokens). pinocchio-scan helps you validate that skills align with your security posture and highlights high-risk behavior early.

$3

- Multi-language scanning for TypeScript/JavaScript, Python, Go, and Rust
- MCP manifest and tool schema risk detection
- LLM-assisted semantic analysis for intent and prompt-injection signals
- Malware and dependency auditing (VirusTotal + NodeSecure + package audit checks)
- Optional AI-powered auto-remediation suggestions
- SARIF export for CI and GitHub Security integration

---

Installation

$3

``bash
npx @jonusnattapong/pinocchio-scan ./path-to-skill
`

$3

`bash
npm install -g @jonusnattapong/pinocchio-scan
`

$3

`bash
docker build -t pinocchio-scan .
docker run -v $(pwd):/src -e GEMINI_API_KEY="your_key" pinocchio-scan /src --report
`

---

CLI usage

`bash
pinocchio-scan [options]
`

$3

| Flag | Description | Default |
| :--- | :--- | :--- |
| | Path to the directory or file to scan. | (Required) |
| -h, --help | Show help. | |
| -v, --verbose | Verbose output (includes errors from checks). | false |
| --json | Print JSON output to stdout. | false |
| --report | Auto-export a timestamped JSON report to reports/. | false |
| --sarif | Export SARIF to reports/ for GitHub Security. | false |
| --tui | Launch interactive TUI mode for configuring and running scans. | false |
| --severity | Minimum severity (low, medium, high, critical). | low |
| --checks | Comma-separated list of checks to run. | All |
| --ignore | Comma-separated glob patterns to ignore. | node_modules,dist,build,.git,.test.,.spec. |
| --fix | Enable AI auto-remediation suggestions (experimental). | false |
| --provider | AI provider (gemini, opencode, molt, openrouter, openai). | gemini |
| --model | Override the provider model name. | Provider default |
| --web-search | Enable AI web search capability (if supported). | false |

$3

`bash
pinocchio-scan ./skills
pinocchio-scan ./agent --severity high
pinocchio-scan ./repo --checks command-injection,hardcoded-secret
pinocchio-scan ./repo --json > report.json
pinocchio-scan ./skills --fix --provider openrouter --model "meta-llama/llama-3.1-8b-instruct:free"
pinocchio-scan --tui
`

---

Checks and detections

These checks map to --checks values:

- command-injection - Unsafe shell command execution
- code-injection - eval, Function, obfuscation, dynamic execution (includes NodeSecure signals)
- file-system - Unsafe file operations and path traversal patterns
- hardcoded-secret - API keys, tokens, and secrets in code
- semantic-analysis - LLM-assisted intent analysis and prompt-injection signals
- malware-scan - VirusTotal lookup for suspicious artifacts
- dependency-audit - Dependency risk signals for package.json
- cisco-defense - Risky binaries and suspicious skill text in SKILL.md
- mcp-definition - MCP manifest risks and global permissive flags
- tool-schema - Overly permissive tool schemas in MCP manifests
- excessive-agency - Execution-like behavior in MCP definitions
- python-security, go-security, rust-security - Language-specific heuristics

---

Outputs

$3

`bash
pinocchio-scan ./skills --json
`

$3

`bash
pinocchio-scan ./skills --report
`

$3

`bash
pinocchio-scan ./skills --sarif
`

---

AI providers

Semantic analysis and remediation require an AI provider. Configure via environment variables:

| Provider | Required env vars | Default model |
| :--- | :--- | :--- |
| Gemini | GEMINI_API_KEY | gemini-pro |
| OpenRouter | OPENROUTER_API_KEY | meta-llama/llama-3.1-8b-instruct:free |
| OpenAI | OPENAI_API_KEY | gpt-4o-mini |
| Opencode | OPENCODE_API_BASE, optional OPENCODE_API_KEY | opencode-model |
| Molt | MOLT_API_BASE, optional MOLT_API_KEY | molt-model |

Notes:
- --web-search currently augments prompts for providers that support search or grounding.
- If no provider is configured, semantic analysis and auto-remediation are skipped.

---

Programmatic usage

`bash
npm install @jonusnattapong/pinocchio-scan
`

`typescript
import { scanCode } from "@jonusnattapong/pinocchio-scan";

const code = "exec('rm -rf ' + path);";
const findings = await scanCode(code, {
severityThreshold: "high",
});

console.log(findings);
`

---

Exit codes

- 0 - Scan completed with no high or critical findings
- 1 - High or critical findings detected
- 2 - Error (invalid path, parsing failure, or runtime error)

---

CI/CD integration

$3

`yaml
- name: AI Skill Security Scan
uses: JonusNattapong/Skill-Scanner@main
with:
path: "./skills"
gemini_api_key: ${{ secrets.GEMINI_API_KEY }}
severity: "high"
`

---

Security and contributing

Please see CONTRIBUTING.md and CODE_OF_CONDUCT.md. For security issues, follow SECURITY.md` and avoid public disclosure.

---

CC BY-NC-ND 4.0. Developed by JonusNattapong and the Secure AI Community.