Security Scanner

SkillKit includes a built-in security scanner that analyzes skills for prompt injection, command injection, data exfiltration, hardcoded secrets, and other threats before installation.

Quick Start

skillkit scan ./my-skill

The scanner runs automatically during skillkit install. Use --no-scan to skip or --force to install despite findings.

CLI Usage

skillkit scan <path>                       # Scan skill directory
skillkit scan <path> --format json         # JSON output
skillkit scan <path> --format table        # Tabular output
skillkit scan <path> --format sarif        # SARIF v2.1 for GitHub Code Scanning
skillkit scan <path> --fail-on high        # Exit code 1 if HIGH+ findings
skillkit scan <path> --skip-rules UC001    # Skip specific rules
skillkit scan <path> --skip-rules PI001,PI002  # Skip multiple rules

Threat Categories

The scanner detects 46+ patterns across 6 threat categories:

Prompt Injection (PI001–PI015)

Detects attempts to override, bypass, or manipulate agent instructions.

Command Injection (CI001–CI010)

Detects code execution, shell injection, and path traversal patterns.

Data Exfiltration (DE001–DE008)

Detects network requests, webhook URLs, and credential access patterns.

Tool Abuse (TA001–TA006)

Detects tool shadowing, autonomy escalation, and capability manipulation.

Hardcoded Secrets (SK001–SK013)

Detects API keys, tokens, and credentials embedded in skill files.

Unicode Steganography (UC001–UC007)

Detects invisible characters and obfuscation techniques.

Manifest Validation (MF001–MF008)

Validates SKILL.md frontmatter and skill structure.

Analyzers

The scanner uses three analyzers that run in parallel:

Output Formats

Summary (default)

Colored terminal output with severity indicators, file locations, snippets, and remediation advice.

JSON

Machine-readable JSON with all findings, stats, and verdict.

skillkit scan ./my-skill --format json | jq '.findings[] | {ruleId, severity, title}'

Table

Tabular format for quick review:

skillkit scan ./my-skill --format table

SARIF

SARIF v2.1 for GitHub Code Scanning and IDE integration:

skillkit scan ./my-skill --format sarif > results.sarif

Upload to GitHub:

gh api repos/{owner}/{repo}/code-scanning/sarifs \
  -f "sarif=$(gzip -c results.sarif | base64)"

CI/CD Integration

GitHub Actions

- name: Scan skills
  run: npx skillkit scan ./skills --format sarif --fail-on high > results.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Pre-commit Hook

skillkit scan . --fail-on medium

Programmatic Usage

import { SkillScanner, formatResult } from '@skillkit/core';

const scanner = new SkillScanner({
  failOnSeverity: 'high',
  skipRules: ['UC001', 'MF004'],
});

const result = await scanner.scan('./my-skill');

console.log(formatResult(result, 'summary'));
console.log(`Verdict: ${result.verdict}`);
console.log(`Findings: ${result.findings.length}`);

Severity Levels

False Positive Handling

The scanner automatically filters:

• Placeholder patterns: your-api-key, example, sample, dummy, xxx
• Test files: *.test.ts, *.spec.ts, __tests__/
• Import statements: import ... from '../' (not path traversal)
• Comments: Code comments mentioning patterns
• Security discussions: Text discussing jailbreaks or vulnerabilities (uses negative lookbehind)

To skip specific rules:

skillkit scan . --skip-rules UC001,UC002,MF004