skillscan 0.1.0

package/src/output/formatters.ts

@@ -0,0 +1,296 @@
+import { ScanResult, ScanOptions, Severity, Finding } from '../types';
+import { getRatingEmoji } from '../scoring/trust-score';
+
+export function formatOutput(result: ScanResult, options: ScanOptions): string {
+  switch (options.format) {
+    case 'json':
+      return formatJson(result);
+    case 'ci':
+      return formatCi(result);
+    case 'text':
+    default:
+      return formatText(result, options.verbose || false);
+  }
+}
+
+function formatJson(result: ScanResult): string {
+  return JSON.stringify(result, null, 2);
+}
+
+function formatCi(result: ScanResult): string {
+  const lines: string[] = [];
+  
+  for (const finding of result.findings) {
+    // Format: file:line:column: severity: message
+    const location = finding.line ? `${finding.file}:${finding.line}` : finding.file;
+    lines.push(`${location}: ${finding.severity}: [${finding.ruleId}] ${finding.message}`);
+  }
+  
+  lines.push('');
+  lines.push(`Score: ${result.score}/100 (${result.rating})`);
+  
+  return lines.join('\n');
+}
+
+function formatText(result: ScanResult, verbose: boolean): string {
+  const lines: string[] = [];
+  
+  if (result.findings.length === 0) {
+    return formatSafeResult(result);
+  }
+  
+  return formatUnsafeResult(result, verbose);
+}
+
+function formatSafeResult(result: ScanResult): string {
+  const lines: string[] = [];
+  
+  lines.push('');
+  lines.push('╔═══════════════════════════════════════════════════════════════╗');
+  lines.push(`║  ✅ SAFE TO INSTALL                                           ║`);
+  lines.push(`║  ${padRight(result.skillName, 20)} • Score: ${result.score}/100${' '.repeat(20)}║`);
+  lines.push('╚═══════════════════════════════════════════════════════════════╝');
+  lines.push('');
+  lines.push('No security issues detected. This skill looks safe!');
+  lines.push('');
+  
+  return lines.join('\n');
+}
+
+function formatUnsafeResult(result: ScanResult, verbose: boolean): string {
+  const lines: string[] = [];
+  const recommendation = getRecommendation(result.rating);
+  const tldr = generateTldr(result);
+  
+  // Header with clear verdict
+  lines.push('');
+  lines.push('╔═══════════════════════════════════════════════════════════════╗');
+  lines.push(`║  ${recommendation.icon} ${padRight(recommendation.text, 55)}║`);
+  lines.push(`║  ${padRight(result.skillName, 20)} • Score: ${result.score}/100${' '.repeat(20)}║`);
+  lines.push('╚═══════════════════════════════════════════════════════════════╝');
+  lines.push('');
+  
+  // TL;DR
+  lines.push(`TL;DR: ${recommendation.icon} ${tldr}`);
+  lines.push('');
+  
+  // Group findings by rule for cleaner display
+  const groupedFindings = groupByRule(result.findings);
+  
+  lines.push('⚠️  Issues Found:');
+  lines.push('');
+  
+  // Show CRITICAL and HIGH issues (skip LOW in non-verbose mode)
+  const severityOrder: Severity[] = verbose 
+    ? ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW']
+    : ['CRITICAL', 'HIGH', 'MEDIUM'];
+  
+  // Sort groups by highest severity (CRITICAL first)
+  const sortedGroups = Object.entries(groupedFindings).sort(([, a], [, b]) => {
+    const severityRank: Record<Severity, number> = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3 };
+    const aRank = severityRank[getHighestSeverity(a)];
+    const bRank = severityRank[getHighestSeverity(b)];
+    return aRank - bRank;
+  });
+  
+  for (const [ruleId, findings] of sortedGroups) {
+    // Filter to relevant severities
+    const relevantFindings = findings.filter(f => severityOrder.includes(f.severity));
+    if (relevantFindings.length === 0) continue;
+    
+    const highestSeverity = getHighestSeverity(relevantFindings);
+    const icon = getSeverityIcon(highestSeverity);
+    const description = getUserFriendlyDescription(ruleId, relevantFindings);
+    const example = getBestExample(relevantFindings);
+    
+    // Show grouped issue with count if multiple
+    const countSuffix = relevantFindings.length > 1 ? ` (${relevantFindings.length} instances)` : '';
+    lines.push(`  ${icon} ${description}${countSuffix}`);
+    
+    // Show the most relevant code snippet (full in verbose, truncated in default)
+    if (example) {
+      const snippet = verbose ? example : truncate(example, 80);
+      lines.push(`     "${snippet}"`);
+    }
+    
+    // In verbose mode, show all locations
+    if (verbose) {
+      for (const finding of relevantFindings) {
+        const location = finding.line 
+          ? `${getFileName(finding.file)}:${finding.line}`
+          : getFileName(finding.file);
+        lines.push(`     └─ ${location} [${finding.ruleId}]`);
+      }
+    }
+    
+    lines.push('');
+  }
+  
+  // What this means section
+  lines.push('💡 What this means:');
+  lines.push(`   ${getExplanation(result)}`);
+  lines.push('');
+  
+  // Final recommendation
+  lines.push(`${recommendation.icon} Recommendation: ${recommendation.advice}`);
+  lines.push('');
+  
+  if (verbose) {
+    lines.push(`📊 Details: ${result.findings.length} findings in ${result.scanDuration}ms`);
+    lines.push(`   Path: ${result.skillPath}`);
+    lines.push('');
+  }
+  
+  return lines.join('\n');
+}
+
+// Group findings by ruleId for cleaner display
+function groupByRule(findings: Finding[]): Record<string, Finding[]> {
+  const groups: Record<string, Finding[]> = {};
+  
+  for (const finding of findings) {
+    if (!groups[finding.ruleId]) {
+      groups[finding.ruleId] = [];
+    }
+    groups[finding.ruleId].push(finding);
+  }
+  
+  return groups;
+}
+
+function getHighestSeverity(findings: Finding[]): Severity {
+  const order: Severity[] = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'];
+  for (const severity of order) {
+    if (findings.some(f => f.severity === severity)) {
+      return severity;
+    }
+  }
+  return 'LOW';
+}
+
+function getUserFriendlyDescription(ruleId: string, findings: Finding[]): string {
+  // Map technical rule IDs to user-friendly descriptions
+  const descriptions: Record<string, string> = {
+    'prompt-injection': 'Asks the AI to ignore its safety rules',
+    'hidden-instructions': 'Contains hidden text you cannot see',
+    'sensitive-paths': 'Tries to access your private files',
+    'file-access': 'Suspicious file access patterns detected'
+  };
+  
+  // Try to give more specific description based on findings
+  const finding = findings[0];
+  if (ruleId === 'sensitive-paths') {
+    if (finding.message.includes('SSH')) return 'Tries to access your SSH keys';
+    if (finding.message.includes('AWS')) return 'Tries to access your AWS credentials';
+    if (finding.message.includes('env')) return 'Tries to read your environment secrets';
+    return 'Tries to access your private credentials';
+  }
+  
+  if (ruleId === 'prompt-injection') {
+    if (finding.message.includes('override')) return 'Asks the AI to ignore its safety rules';
+    if (finding.message.includes('system prompt')) return 'Tries to extract AI system instructions';
+    if (finding.message.includes('jailbreak')) return 'Contains known jailbreak patterns';
+    if (finding.message.includes('Role')) return 'Tries to manipulate the AI identity';
+    if (finding.message.includes('base64')) return 'Contains hidden encoded commands';
+  }
+  
+  return descriptions[ruleId] || 'Suspicious pattern detected';
+}
+
+function getBestExample(findings: Finding[]): string | null {
+  // Prefer findings with context
+  const withContext = findings.find(f => f.context && f.context.length > 10);
+  if (withContext?.context) {
+    return withContext.context;
+  }
+  
+  // Fall back to extracting from message
+  const first = findings[0];
+  const match = first.message.match(/"([^"]+)"/);
+  return match ? match[1] : null;
+}
+
+function generateTldr(result: ScanResult): string {
+  const grouped = groupByRule(result.findings);
+  const issues: string[] = [];
+  
+  if (grouped['prompt-injection']) {
+    issues.push('manipulate AI behavior');
+  }
+  if (grouped['sensitive-paths']) {
+    issues.push('steal your credentials');
+  }
+  if (grouped['hidden-instructions']) {
+    issues.push('hide malicious instructions');
+  }
+  if (grouped['file-access']) {
+    issues.push('access sensitive files');
+  }
+  
+  if (issues.length === 0) {
+    return 'Review before installing';
+  }
+  
+  if (result.rating === 'WARNING') {
+    return `Don't install - this skill may ${issues.slice(0, 2).join(' and ')}`;
+  }
+  
+  return `Review carefully - found attempts to ${issues[0]}`;
+}
+
+function getExplanation(result: ScanResult): string {
+  if (result.rating === 'WARNING') {
+    return 'This skill shows signs of malicious behavior. It may attempt to steal sensitive data or manipulate AI responses in harmful ways.';
+  }
+  
+  if (result.rating === 'CAUTION') {
+    return 'This skill has some concerning patterns that should be reviewed. It might be safe, but verify the flagged items before installing.';
+  }
+  
+  return 'Some minor issues were detected. Review them to ensure they are expected behavior.';
+}
+
+function getRecommendation(rating: 'VERIFIED' | 'CAUTION' | 'WARNING'): { icon: string; text: string; advice: string } {
+  switch (rating) {
+    case 'WARNING':
+      return {
+        icon: '🔴',
+        text: 'DO NOT INSTALL',
+        advice: 'Do not install this skill. It shows signs of malicious behavior.'
+      };
+    case 'CAUTION':
+      return {
+        icon: '🟡',
+        text: 'REVIEW BEFORE INSTALLING',
+        advice: 'Review the flagged items carefully before deciding to install.'
+      };
+    default:
+      return {
+        icon: '🟢',
+        text: 'LIKELY SAFE',
+        advice: 'This skill appears safe, but always review what you install.'
+      };
+  }
+}
+
+function getSeverityIcon(severity: Severity): string {
+  switch (severity) {
+    case 'CRITICAL': return '🔴';
+    case 'HIGH': return '🟠';
+    case 'MEDIUM': return '🟡';
+    case 'LOW': return '🔵';
+  }
+}
+
+function padRight(str: string, length: number): string {
+  return str.length >= length ? str.slice(0, length) : str + ' '.repeat(length - str.length);
+}
+
+function truncate(str: string, maxLength: number): string {
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength - 3) + '...';
+}
+
+function getFileName(filePath: string): string {
+  return filePath.split('/').pop() || filePath;
+}

package/src/scanner/engine.ts

@@ -0,0 +1,99 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { ScanOptions, ScanResult, Finding, SkillMetadata } from '../types';
+import { parseSkillMd } from './parsers/skillmd';
+import { parseSkillJson } from './parsers/skilljson';
+import { getAllRules } from './rules';
+import { calculateScore, getRating } from '../scoring/trust-score';
+
+export class ScanEngine {
+  async scan(options: ScanOptions): Promise<ScanResult> {
+    const startTime = Date.now();
+    const { path: skillPath } = options;
+    
+    const stats = fs.statSync(skillPath);
+    const isDirectory = stats.isDirectory();
+    
+    const filesToScan = isDirectory 
+      ? this.discoverFiles(skillPath)
+      : [skillPath];
+    
+    const allFindings: Finding[] = [];
+    let skillName = path.basename(skillPath);
+    
+    for (const file of filesToScan) {
+      const content = fs.readFileSync(file, 'utf-8');
+      const metadata = this.parseFile(file, content);
+      
+      if (metadata.name) {
+        skillName = metadata.name;
+      }
+      
+      const rules = getAllRules();
+      for (const rule of rules) {
+        const findings = rule.check(content, metadata, file);
+        allFindings.push(...findings);
+      }
+    }
+    
+    const score = calculateScore(allFindings);
+    const rating = getRating(score);
+    
+    return {
+      skillPath,
+      skillName,
+      findings: allFindings,
+      score,
+      rating,
+      scannedAt: new Date().toISOString(),
+      scanDuration: Date.now() - startTime
+    };
+  }
+  
+  private discoverFiles(dirPath: string): string[] {
+    const files: string[] = [];
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      const fullPath = path.join(dirPath, entry.name);
+      
+      if (entry.isDirectory()) {
+        // Skip node_modules and hidden directories
+        if (!entry.name.startsWith('.') && entry.name !== 'node_modules') {
+          files.push(...this.discoverFiles(fullPath));
+        }
+      } else {
+        // Include relevant skill files
+        const ext = path.extname(entry.name).toLowerCase();
+        const name = entry.name.toLowerCase();
+        
+        if (name === 'skill.md' || name === 'skill.json' || 
+            ext === '.md' || ext === '.json' || ext === '.yaml' || ext === '.yml') {
+          files.push(fullPath);
+        }
+      }
+    }
+    
+    return files;
+  }
+  
+  private parseFile(filePath: string, content: string): SkillMetadata {
+    const ext = path.extname(filePath).toLowerCase();
+    const name = path.basename(filePath).toLowerCase();
+    
+    if (name === 'skill.md' || ext === '.md') {
+      return parseSkillMd(content);
+    }
+    
+    if (name === 'skill.json' || ext === '.json') {
+      return parseSkillJson(content);
+    }
+    
+    // Default metadata for other files
+    return {
+      name: path.basename(filePath),
+      rawContent: content,
+      frontmatter: {}
+    };
+  }
+}

package/src/scanner/parsers/skilljson.ts

@@ -0,0 +1,37 @@
+import { SkillMetadata, ToolDefinition } from '../../types';
+
+export function parseSkillJson(content: string): SkillMetadata {
+  try {
+    const json = JSON.parse(content);
+    
+    const tools: ToolDefinition[] = [];
+    if (json.tools && Array.isArray(json.tools)) {
+      for (const tool of json.tools) {
+        if (typeof tool === 'object' && tool.name) {
+          tools.push({
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.parameters
+          });
+        }
+      }
+    }
+    
+    return {
+      name: json.name || '',
+      description: json.description,
+      version: json.version,
+      author: json.author,
+      tools,
+      rawContent: content,
+      frontmatter: json
+    };
+  } catch {
+    // Invalid JSON, return minimal metadata
+    return {
+      name: '',
+      rawContent: content,
+      frontmatter: {}
+    };
+  }
+}

package/src/scanner/parsers/skillmd.ts

@@ -0,0 +1,46 @@
+import matter from 'gray-matter';
+import { SkillMetadata, ToolDefinition } from '../../types';
+
+export function parseSkillMd(content: string): SkillMetadata {
+  const { data: frontmatter, content: bodyContent } = matter(content);
+  
+  // Extract tools from frontmatter if present
+  const tools: ToolDefinition[] = [];
+  if (frontmatter.tools && Array.isArray(frontmatter.tools)) {
+    for (const tool of frontmatter.tools) {
+      if (typeof tool === 'object' && tool.name) {
+        tools.push({
+          name: tool.name,
+          description: tool.description,
+          parameters: tool.parameters
+        });
+      }
+    }
+  }
+  
+  return {
+    name: frontmatter.name || frontmatter.title || '',
+    description: frontmatter.description || extractFirstParagraph(bodyContent),
+    version: frontmatter.version,
+    author: frontmatter.author,
+    tools,
+    rawContent: content,
+    frontmatter
+  };
+}
+
+function extractFirstParagraph(content: string): string {
+  const lines = content.split('\n');
+  const paragraphLines: string[] = [];
+  
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('#')) continue; // Skip headers
+    if (trimmed === '' && paragraphLines.length > 0) break;
+    if (trimmed !== '') {
+      paragraphLines.push(trimmed);
+    }
+  }
+  
+  return paragraphLines.join(' ').slice(0, 200);
+}

package/src/scanner/rules/file-access.ts

@@ -0,0 +1,78 @@
+import { Rule, Finding, SkillMetadata, Severity } from '../../types';
+
+export class FileAccessRule implements Rule {
+  id = 'file-access';
+  name = 'Suspicious File Access Detection';
+  description = 'Detects suspicious file access patterns that could exfiltrate data';
+  severity: Severity = 'HIGH';
+
+  private patterns = [
+    {
+      name: 'path-traversal',
+      regex: /\.\.\/|\.\.\\|\.\.[\/\\]/gi,
+      severity: 'HIGH' as Severity,
+      message: 'Path traversal pattern detected - may access files outside intended directory'
+    },
+    {
+      name: 'home-directory-access',
+      regex: /~\/|%HOME%|%USERPROFILE%|\$HOME/gi,
+      severity: 'HIGH' as Severity,
+      message: 'Home directory access pattern detected'
+    },
+    {
+      name: 'wildcard-read',
+      regex: /\*\.\w{2,4}|\*\*\/\*|glob\s*\(/gi,
+      severity: 'MEDIUM' as Severity,
+      message: 'Wildcard file pattern detected - may sweep multiple files'
+    },
+    {
+      name: 'sensitive-file-extensions',
+      regex: /\.(pem|key|crt|pfx|p12|jks|keystore|env|credentials)\b/gi,
+      severity: 'HIGH' as Severity,
+      message: 'Reference to sensitive file type detected'
+    },
+    {
+      name: 'read-file-operations',
+      regex: /readFile|readFileSync|fs\.read|open\s*\(|fopen|file_get_contents/gi,
+      severity: 'LOW' as Severity,
+      message: 'File read operation detected - verify intended behavior'
+    },
+    {
+      name: 'network-after-read',
+      regex: /(fetch|axios|request|http\.|https\.|XMLHttpRequest|curl|wget)/gi,
+      severity: 'MEDIUM' as Severity,
+      message: 'Network operation detected - check if combined with file access'
+    }
+  ];
+
+  check(content: string, _metadata: SkillMetadata, filePath: string): Finding[] {
+    const findings: Finding[] = [];
+    const lines = content.split('\n');
+
+    for (const pattern of this.patterns) {
+      let match;
+      const regex = new RegExp(pattern.regex.source, pattern.regex.flags);
+      
+      while ((match = regex.exec(content)) !== null) {
+        const lineNumber = this.getLineNumber(content, match.index);
+        const contextLine = lines[lineNumber - 1] || '';
+        
+        findings.push({
+          ruleId: this.id,
+          ruleName: this.name,
+          severity: pattern.severity,
+          message: `${pattern.message}: "${match[0]}"`,
+          file: filePath,
+          line: lineNumber,
+          context: contextLine.trim().slice(0, 100)
+        });
+      }
+    }
+
+    return findings;
+  }
+
+  private getLineNumber(content: string, index: number): number {
+    return content.slice(0, index).split('\n').length;
+  }
+}

package/src/scanner/rules/hidden-instructions.ts

@@ -0,0 +1,92 @@
+import { Rule, Finding, SkillMetadata, Severity } from '../../types';
+
+export class HiddenInstructionsRule implements Rule {
+  id = 'hidden-instructions';
+  name = 'Hidden Instructions Detection';
+  description = 'Detects instructions hidden using whitespace, Unicode tricks, or HTML comments';
+  severity: Severity = 'HIGH';
+
+  // Zero-width characters that can hide text
+  private zeroWidthChars = [
+    '\u200B', // Zero-width space
+    '\u200C', // Zero-width non-joiner
+    '\u200D', // Zero-width joiner
+    '\u2060', // Word joiner
+    '\uFEFF', // Zero-width no-break space
+    '\u00AD', // Soft hyphen
+  ];
+
+  // Patterns for hidden instructions
+  private patterns = [
+    {
+      name: 'zero-width-characters',
+      regex: /[\u200B\u200C\u200D\u2060\uFEFF\u00AD]+/g,
+      severity: 'HIGH' as Severity,
+      message: 'Zero-width characters detected - may hide malicious instructions'
+    },
+    {
+      name: 'html-comments',
+      regex: /<!--[\s\S]*?-->/g,
+      severity: 'MEDIUM' as Severity,
+      message: 'HTML comment found - may contain hidden instructions'
+    },
+    {
+      name: 'excessive-whitespace',
+      regex: /[^\S\n]{20,}/g, // 20+ consecutive whitespace chars (not newlines)
+      severity: 'MEDIUM' as Severity,
+      message: 'Excessive whitespace detected - may hide text visually'
+    },
+    {
+      name: 'unicode-homoglyphs',
+      regex: /[\u0400-\u04FF\u0370-\u03FF]/g, // Cyrillic/Greek chars that look like Latin
+      severity: 'MEDIUM' as Severity,
+      message: 'Unicode homoglyphs detected - characters that look like ASCII but are different'
+    },
+    {
+      name: 'rtl-override',
+      regex: /[\u202E\u202D\u202C\u2066\u2067\u2068\u2069]/g, // RTL/LTR override characters
+      severity: 'HIGH' as Severity,
+      message: 'Text direction override character detected - can reverse visible text'
+    }
+  ];
+
+  check(content: string, _metadata: SkillMetadata, filePath: string): Finding[] {
+    const findings: Finding[] = [];
+    const lines = content.split('\n');
+
+    for (const pattern of this.patterns) {
+      let match;
+      const regex = new RegExp(pattern.regex.source, pattern.regex.flags);
+      
+      while ((match = regex.exec(content)) !== null) {
+        const lineNumber = this.getLineNumber(content, match.index);
+        const contextLine = lines[lineNumber - 1] || '';
+        
+        findings.push({
+          ruleId: this.id,
+          ruleName: this.name,
+          severity: pattern.severity,
+          message: pattern.message,
+          file: filePath,
+          line: lineNumber,
+          context: this.sanitizeContext(contextLine)
+        });
+      }
+    }
+
+    return findings;
+  }
+
+  private getLineNumber(content: string, index: number): number {
+    return content.slice(0, index).split('\n').length;
+  }
+
+  private sanitizeContext(line: string): string {
+    // Replace zero-width chars with visible markers for display
+    let sanitized = line;
+    for (const char of this.zeroWidthChars) {
+      sanitized = sanitized.replace(new RegExp(char, 'g'), '[ZW]');
+    }
+    return sanitized.slice(0, 100);
+  }
+}

package/src/scanner/rules/index.ts

@@ -0,0 +1,20 @@
+import { Rule } from '../../types';
+import { HiddenInstructionsRule } from './hidden-instructions';
+import { FileAccessRule } from './file-access';
+import { PromptInjectionRule } from './prompt-injection';
+import { SensitivePathsRule } from './sensitive-paths';
+
+const rules: Rule[] = [
+  new HiddenInstructionsRule(),
+  new FileAccessRule(),
+  new PromptInjectionRule(),
+  new SensitivePathsRule()
+];
+
+export function getAllRules(): Rule[] {
+  return rules;
+}
+
+export function getRuleById(id: string): Rule | undefined {
+  return rules.find(r => r.id === id);
+}