pinocscan

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.

Core capabilities

• 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

Use instantly with npx

npx pinocscan ./path-to-skill

Install globally

npm install -g pinocscan

Docker

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

CLI usage

pinocchio-scan <path> [options]

Options

Flag	Description	Default
<path>	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 <level>	Minimum severity (low, medium, high, critical).	low
--checks <types>	Comma-separated list of checks to run.	All
--ignore <patterns>	Comma-separated glob patterns to ignore.	node_modules,dist,build,.git,*.test.*,*.spec.*
--fix	Enable AI auto-remediation suggestions (experimental).	false
--provider <name>	AI provider (gemini, opencode, molt, openrouter, openai, kilocode).	gemini
--model <name>	Override the provider model name.	Provider default
--web-search	Enable AI web search capability (if supported).	false

Examples

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

TUI flow

The TUI now acts as the primary interactive workflow:

• Enter a file or directory path.
• Choose a scan profile, including severity, check set, AI options, and export toggles.
• Watch live progress during directory scans.
• Inspect findings with a split detail panel and re-export reports from the results screen.

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

JSON (stdout)

pinocchio-scan ./skills --json

Report export

pinocchio-scan ./skills --report

SARIF export

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
Kilocode	KILO_API_KEY	anthropic/claude-sonnet-4.5
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.
• Kilocode is a unified gateway to 500+ models (Claude, GPT-4, Gemini, Grok, etc.). Switch models without code changes. Setup guide →

Programmatic usage

npm install pinocscan

import { scanCode } from "pinocscan";

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

GitHub Actions

- 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.