ferret-scan 2.1.0 → 2.1.2

package/dist/analyzers/AstAnalyzer.d.ts

@@ -6,7 +6,7 @@ import type { SemanticFinding, DiscoveredFile, Rule } from '../types.js';
 /**
  * Analyze a single file for semantic patterns
  */
-export declare function analyzeFile(file: DiscoveredFile, content: string, rules: Rule[]): SemanticFinding[];
+export declare function analyzeFile(file: DiscoveredFile, content: string, rules: Rule[]): Promise<SemanticFinding[]>;
 /**
  * Check if semantic analysis should be performed
  */

package/dist/analyzers/AstAnalyzer.js

@@ -2,8 +2,20 @@
  * AST Analyzer - TypeScript/JavaScript semantic analysis for security scanning
  * Analyzes code blocks in markdown and TypeScript configurations for complex patterns
  */
-import * as ts from 'typescript';
 import logger from '../utils/logger.js';
+let _ts;
+async function getTS() {
+    if (!_ts) {
+        try {
+            _ts = await import('typescript');
+        }
+        catch {
+            throw new Error('The "typescript" package is required for semantic analysis. ' +
+                'Install it with: npm install -D typescript');
+        }
+    }
+    return _ts;
+}
 function escapeRegExp(input) {
     return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -80,13 +92,13 @@ function isAnalyzableLanguage(language) {
 /**
  * Create TypeScript AST from code
  */
-function createAST(code, fileName = 'analysis.ts') {
-    return ts.createSourceFile(fileName, code, ts.ScriptTarget.Latest, true, fileName?.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+function createAST(tsLib, code, fileName = 'analysis.ts') {
+    return tsLib.createSourceFile(fileName, code, tsLib.ScriptTarget.Latest, true, fileName?.endsWith('.tsx') ? tsLib.ScriptKind.TSX : tsLib.ScriptKind.TS);
 }
 /**
  * Extract semantic context from AST
  */
-function extractSemanticContext(sourceFile) {
+function extractSemanticContext(tsLib, sourceFile) {
     const context = {
         variables: [],
         imports: [],
@@ -94,28 +106,28 @@ function extractSemanticContext(sourceFile) {
     };
     function visit(node) {
         switch (node.kind) {
-            case ts.SyntaxKind.ImportDeclaration: {
+            case tsLib.SyntaxKind.ImportDeclaration: {
                 const importDecl = node;
-                if (importDecl.moduleSpecifier && ts.isStringLiteral(importDecl.moduleSpecifier)) {
+                if (importDecl.moduleSpecifier && tsLib.isStringLiteral(importDecl.moduleSpecifier)) {
                     context.imports.push(importDecl.moduleSpecifier.text);
                 }
                 break;
             }
-            case ts.SyntaxKind.VariableDeclaration: {
+            case tsLib.SyntaxKind.VariableDeclaration: {
                 const varDecl = node;
-                if (varDecl.name && ts.isIdentifier(varDecl.name)) {
+                if (varDecl.name && tsLib.isIdentifier(varDecl.name)) {
                     context.variables.push(varDecl.name.text);
                 }
                 break;
             }
-            case ts.SyntaxKind.CallExpression: {
+            case tsLib.SyntaxKind.CallExpression: {
                 const callExpr = node;
                 const callText = callExpr.expression.getText(sourceFile);
                 context.callChain.push(callText);
                 break;
             }
         }
-        ts.forEachChild(node, visit);
+        tsLib.forEachChild(node, visit);
     }
     visit(sourceFile);
     return context;
@@ -123,11 +135,11 @@ function extractSemanticContext(sourceFile) {
 /**
  * Find security patterns in AST
  */
-function findSecurityPatterns(sourceFile, patterns) {
+function findSecurityPatterns(tsLib, sourceFile, patterns) {
     const matches = [];
     function visit(node) {
         for (const pattern of patterns) {
-            const match = matchSemanticPattern(node, pattern, sourceFile);
+            const match = matchSemanticPattern(tsLib, node, pattern, sourceFile);
             if (match) {
                 matches.push({
                     pattern,
@@ -136,7 +148,7 @@ function findSecurityPatterns(sourceFile, patterns) {
                 });
             }
         }
-        ts.forEachChild(node, visit);
+        tsLib.forEachChild(node, visit);
     }
     visit(sourceFile);
     return matches;
@@ -144,12 +156,12 @@ function findSecurityPatterns(sourceFile, patterns) {
 /**
  * Match a semantic pattern against an AST node
  */
-function matchSemanticPattern(node, pattern, sourceFile) {
+function matchSemanticPattern(tsLib, node, pattern, sourceFile) {
     const nodeText = node.getText(sourceFile);
     let confidence = pattern.confidence ?? 0.8;
     switch (pattern.type) {
         case 'function-call':
-            if (ts.isCallExpression(node)) {
+            if (tsLib.isCallExpression(node)) {
                 const functionName = node.expression.getText(sourceFile);
                 if (matchesSymbolLike(functionName, pattern.pattern)) {
                     return { confidence };
@@ -157,7 +169,7 @@ function matchSemanticPattern(node, pattern, sourceFile) {
             }
             break;
         case 'property-access':
-            if (ts.isPropertyAccessExpression(node)) {
+            if (tsLib.isPropertyAccessExpression(node)) {
                 const fullAccess = node.getText(sourceFile);
                 if (matchesSymbolLike(fullAccess, pattern.pattern)) {
                     return { confidence };
@@ -165,34 +177,30 @@ function matchSemanticPattern(node, pattern, sourceFile) {
             }
             break;
         case 'dynamic-import':
-            if (ts.isCallExpression(node)) {
-                if (node.expression.kind === ts.SyntaxKind.ImportKeyword) {
-                    // Dynamic import detected - pattern for security analysis only
+            if (tsLib.isCallExpression(node)) {
+                if (node.expression.kind === tsLib.SyntaxKind.ImportKeyword) {
                     const arg = node.arguments[0];
-                    // Literal import paths are common and generally safe; focus on non-literals that could be user-controlled.
-                    if (arg && (ts.isStringLiteralLike(arg) || ts.isNoSubstitutionTemplateLiteral(arg))) {
+                    if (arg && (tsLib.isStringLiteralLike(arg) || tsLib.isNoSubstitutionTemplateLiteral(arg))) {
                         break;
                     }
                     if (pattern.pattern === 'dynamic-import' || nodeText.includes(pattern.pattern)) {
-                        confidence += 0.1; // Higher confidence for dynamic imports
+                        confidence += 0.1;
                         return { confidence };
                     }
                 }
             }
             break;
         case 'eval-chain':
-            if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+            if (tsLib.isCallExpression(node) || tsLib.isNewExpression(node)) {
                 const expr = node.expression;
                 const target = pattern.pattern;
-                // Direct calls: eval(...), Function(...)
-                if (ts.isIdentifier(expr) && expr.text === target) {
+                if (tsLib.isIdentifier(expr) && expr.text === target) {
                     confidence += 0.2;
                     return { confidence };
                 }
-                // Allow common globals: globalThis.eval(...), window.eval(...)
-                if (ts.isPropertyAccessExpression(expr) && expr.name.text === target) {
+                if (tsLib.isPropertyAccessExpression(expr) && expr.name.text === target) {
                     const receiver = expr.expression;
-                    if (ts.isIdentifier(receiver) && (receiver.text === 'globalThis' || receiver.text === 'window')) {
+                    if (tsLib.isIdentifier(receiver) && (receiver.text === 'globalThis' || receiver.text === 'window')) {
                         confidence += 0.2;
                         return { confidence };
                     }
@@ -200,7 +208,7 @@ function matchSemanticPattern(node, pattern, sourceFile) {
             }
             break;
         case 'object-structure':
-            if (ts.isObjectLiteralExpression(node)) {
+            if (tsLib.isObjectLiteralExpression(node)) {
                 if (nodeText.includes(pattern.pattern)) {
                     return { confidence };
                 }
@@ -212,26 +220,26 @@ function matchSemanticPattern(node, pattern, sourceFile) {
 /**
  * Create AST node info
  */
-function createASTNodeInfo(node, sourceFile) {
-    const nodeName = getNodeName(node);
+function createASTNodeInfo(tsLib, node, sourceFile) {
+    const nodeName = getNodeName(tsLib, node);
     return {
-        nodeType: ts.SyntaxKind[node.kind],
+        nodeType: tsLib.SyntaxKind[node.kind],
         ...(nodeName && { name: nodeName }),
-        ...(node.parent && { parent: ts.SyntaxKind[node.parent.kind] }),
-        children: node.getChildren(sourceFile).map(child => ts.SyntaxKind[child.kind])
+        ...(node.parent && { parent: tsLib.SyntaxKind[node.parent.kind] }),
+        children: node.getChildren(sourceFile).map(child => tsLib.SyntaxKind[child.kind])
     };
 }
 /**
  * Get node name/identifier
  */
-function getNodeName(node) {
-    if (ts.isIdentifier(node)) {
+function getNodeName(tsLib, node) {
+    if (tsLib.isIdentifier(node)) {
         return node.text;
     }
-    if (ts.isFunctionDeclaration(node) && node.name) {
+    if (tsLib.isFunctionDeclaration(node) && node.name) {
         return node.name.text;
     }
-    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+    if (tsLib.isVariableDeclaration(node) && tsLib.isIdentifier(node.name)) {
         return node.name.text;
     }
     return undefined;
@@ -269,7 +277,7 @@ function createContextLines(sourceFile, node, contextLines = 3) {
 /**
  * Analyze a single file for semantic patterns
  */
-export function analyzeFile(file, content, rules) {
+export async function analyzeFile(file, content, rules) {
     const findings = [];
     try {
         // Get rules with semantic patterns
@@ -277,6 +285,7 @@ export function analyzeFile(file, content, rules) {
         if (semanticRules.length === 0) {
             return findings;
         }
+        const tsLib = await getTS();
         logger.debug(`AST analysis for ${file.relativePath} with ${semanticRules.length} semantic rules`);
         let codeBlocksToAnalyze = [];
         // Extract code blocks from markdown files
@@ -290,16 +299,16 @@ export function analyzeFile(file, content, rules) {
         // Analyze each code block
         for (const codeBlock of codeBlocksToAnalyze) {
             try {
-                const sourceFile = createAST(codeBlock.code, `${file.relativePath}_block_${codeBlock.line}.${codeBlock.language}`);
-                const semanticContext = extractSemanticContext(sourceFile);
+                const sourceFile = createAST(tsLib, codeBlock.code, `${file.relativePath}_block_${codeBlock.line}.${codeBlock.language}`);
+                const semanticContext = extractSemanticContext(tsLib, sourceFile);
                 // Check each semantic rule
                 for (const rule of semanticRules) {
                     if (!rule.semanticPatterns)
                         continue;
-                    const patternMatches = findSecurityPatterns(sourceFile, rule.semanticPatterns);
+                    const patternMatches = findSecurityPatterns(tsLib, sourceFile, rule.semanticPatterns);
                     for (const match of patternMatches) {
                         const position = getPositionFromNode(match.node, sourceFile);
-                        const astNodeInfo = createASTNodeInfo(match.node, sourceFile);
+                        const astNodeInfo = createASTNodeInfo(tsLib, match.node, sourceFile);
                         const contextLines = createContextLines(sourceFile, match.node, 3);
                         const finding = {
                             ruleId: rule.id,

package/dist/rules/ai-specific.js

@@ -215,6 +215,27 @@ export const aiSpecificRules = [
             'https://owasp.org/www-project-top-10-for-large-language-model-applications/',
         ],
         enabled: true,
+        // Mirror INJ-003 semantic context suppression: a skill that discusses,
+        // documents, detects, or provides examples of these techniques is not
+        // itself a jailbreak attempt.
+        excludePatterns: [
+            // Line discusses detection/blocking rather than deployment
+            /\b(detect|catch|flag|block|prevent|scan\s+for|identify|reject|report)\b[^\n]{0,80}(jailbreak|DAN|bypass)/gi,
+            /\b(jailbreak|DAN|bypass)\b[^\n]{0,80}\b(detect|catch|flag|block|prevent|found|identified)/gi,
+            // Term appears inside a quoted string
+            /["'][^"'\n]{0,120}\b(jailbreak|DAN)\b[^"'\n]{0,120}["']/gi,
+            // Scanner rule-ID reference on the same line
+            /\[(?:INJ|AI|SEC|CRED)-\d+\]/gi,
+            // Markdown example label
+            /^\s*\*\*(?:Input|Output|Example|Finding|Result)\*\*\s*:/i,
+        ],
+        excludeContext: [
+            /\b(security\s+(rule|finding|scan|check|gate|scanner|score)|ferret.?scan|scan\s+result)/gi,
+            /\b(example\s+of|this\s+detects|used\s+to\s+(bypass|attack)|common\s+(attack|technique)|known\s+(jailbreak|attack))/gi,
+            /\b(security\s+scanner|vulnerability\s+scanner|threat\s+detect|scan\s+for\s+(injection|jailbreak))/gi,
+            /^\s*##\s+Example/im,
+            /publication\s+blocked/gi,
+        ],
     },
     {
         id: 'AI-011',

package/dist/rules/injection.js

@@ -59,6 +59,31 @@ export const injectionRules = [
         remediation: 'Remove jailbreak attempts. These patterns attempt to bypass safety measures.',
         references: [],
         enabled: true,
+        // Suppress findings when the matched term appears in security-discussion context:
+        // documentation explaining what these attacks are, scanner output examples,
+        // or skill files that detect/block these patterns rather than deploy them.
+        excludePatterns: [
+            // Line explicitly discusses detection/blocking of the pattern
+            /\b(detect|catch|flag|block|prevent|scan\s+for|identify|reject|report)\b[^\n]{0,80}(jailbreak|DAN|bypass)/gi,
+            /\b(jailbreak|DAN|bypass)\b[^\n]{0,80}\b(detect|catch|flag|block|prevent|found|identified)/gi,
+            // Term appears inside a quoted string (example output / documentation)
+            /["'][^"'\n]{0,120}\b(jailbreak|DAN)\b[^"'\n]{0,120}["']/gi,
+            // Markdown rule-ID reference on the same line (scanner output example)
+            /\[(?:INJ|AI|SEC|CRED)-\d+\]/gi,
+            // Line is a markdown example label
+            /^\s*\*\*(?:Input|Output|Example|Finding|Result)\*\*\s*:/i,
+        ],
+        excludeContext: [
+            // Surrounding text discusses security scanning, rules, or findings
+            /\b(security\s+(rule|finding|scan|check|gate|scanner|score)|ferret.?scan|scan\s+result)/gi,
+            // Surrounding text is clearly educational / explanatory
+            /\b(example\s+of|this\s+detects|used\s+to\s+(bypass|attack)|common\s+(attack|technique)|known\s+(jailbreak|attack))/gi,
+            // Context indicates the skill is a security tool or scanner itself
+            /\b(security\s+scanner|vulnerability\s+scanner|threat\s+detect|scan\s+for\s+(injection|jailbreak))/gi,
+            // Markdown example blocks
+            /^\s*##\s+Example/im,
+            /publication\s+blocked/gi,
+        ],
     },
     {
         id: 'INJ-004',

package/dist/scanner/Scanner.js

@@ -344,7 +344,7 @@ async function scanFile(file, config, rules, llmProvider, llmRuntime) {
             else {
                 try {
                     logger.debug(`Running semantic analysis on ${file.relativePath}`);
-                    const semanticFindings = analyzeFileSemantics(file, content, rules);
+                    const semanticFindings = await analyzeFileSemantics(file, content, rules);
                     // Convert SemanticFinding to Finding for compatibility
                     allFindings.push(...semanticFindings);
                     const memAfter = getMemoryUsage();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ferret-scan",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "Comprehensive AI Agent Security Platform - scan, monitor, and secure AI CLI configurations with IDE integrations, behavior analysis, and compliance frameworks",
   "type": "module",
   "main": "dist/index.js",
@@ -111,6 +111,14 @@
     "yaml": "^2.3.4",
     "zod": "^3.22.4"
   },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@eslint/js": "^9.26.0",
     "@types/jest": "^29.5.11",