Skill Security Scanner

Why Skill Security Scanning is Necessary

Skill packages (.zip or directories) are essentially bundles of executable code and configurations. When installed or updated from third-party sources (skill hubs, GitHub, etc.), they can inadvertently introduce malicious scripts, backdoors, data leakage vulnerabilities, or content that violates platform policies. An uncontrolled skill can compromise workspace stability, exfiltrate sensitive information, or lead to privilege escalation. The core issue is the chain of trust. Users and platforms often cannot thoroughly audit an entire package at install time, necessitating an automated security gateway.

How SkillScan Works

SkillScan is a pre- and post-installation scanner designed to activate automatically at critical points in a skill's lifecycle.

• Trigger Points: It activates whether invoked via commands like install, load, add, use, or in response to user actions such as uploading .zip/.skill files, pasting a SKILL.md, or mentioning an unknown skill name. This includes scanning .zip files before installation, directories after they land on disk, and remote installs immediately post-fetch.
• Core Scanning Process:
  1. Local Quick Scan: Executes scripts/scanner.py to analyze the skill directory or files locally.
  2. Remote Result Lookup & Reporting: Local scan results (or file hashes) interact with a remote API (https://skillscan.tokauth.com). It first attempts a cache lookup, then uploads if necessary, and polls for the final result to ensure the latest security rule sets are applied.
  3. Action Based on Verdict: The scanner communicates result severity via exit codes (0 to 3: UNKNOWN/SAFE, LOW/MEDIUM, HIGH/CRITICAL, scan failed), which dictates the next step: proceed, warn and ask for user confirmation, or block installation entirely.
• Deep Integration with Agents: On first run, it appends a ## Skill Security rule to the SOUL.md file. This forces all agents to enforce scanning, maintaining a security baseline even when SkillScan isn't actively loaded. This rule is automatically removed upon uninstallation.
• Silent Maintenance: The scanner checks for updates daily without requiring user interaction.

Boundaries and Caveats

• Scan Scope: Focuses solely on the skill package (code, configuration files). It does not analyze runtime behavior or the host environment.
• Result Interpretation: Installation proceeds only after an exit code of 0 (safe) or 1 (low/medium risk, with user confirmation). Code 2 (high/critical) results in a direct block. Accuracy depends on the underlying rule sets.
• File Handling: The scanning process must not generate any report files inside the skill directory to avoid polluting the workspace. All temporary data and remote interactions are handled via the API.
• Customization: The environment variable SKILL_SCANNER_UPDATE_URL can be set to point to a private update source, making it suitable for corporate intranets or customized scenarios.
• Limitations: Scanning is static code and pattern analysis and cannot fully replace manual auditing. It may have false negatives against highly obfuscated or novel zero-day attacks.