cisco-ai-skill-scanner 1.0.1__py3-none-any.whl → 1.0.2__py3-none-any.whl

skill_scanner/core/analyzers/meta_analyzer.py

@@ -787,29 +787,42 @@ def apply_meta_analysis_to_results(
     meta_result: MetaAnalysisResult,
     skill: Skill,
 ) -> list[Finding]:
-    """Apply meta-analysis results to filter and enrich findings.
+    """Apply meta-analysis results to enrich all findings with metadata.
 
     This function:
-    1. Filters out false positives identified by meta-analysis
+    1. Marks false positives with metadata (but keeps them in output)
     2. Adds meta-analysis enrichments to validated findings
     3. Adds any new threats detected by meta-analyzer
 
+    All findings are retained in the output with metadata indicating whether
+    they were identified as false positives. This allows downstream consumers
+    (like VS Code extensions) to filter or display them as needed.
+
     Args:
         original_findings: Original findings from all analyzers
         meta_result: Results from meta-analysis
         skill: The skill being analyzed
 
     Returns:
-        Filtered and enriched list of findings
+        All findings with meta-analysis metadata added
     """
-    # Build set of false positive indices
-    fp_indices = set()
+    # Build false positive lookup with reasons and metadata
+    fp_data: dict[int, dict[str, Any]] = {}
     for fp in meta_result.false_positives:
         if "_index" in fp:
-            fp_indices.add(fp["_index"])
+            fp_data[fp["_index"]] = {
+                "reason": fp.get("reason") or fp.get("false_positive_reason") or "Identified as likely false positive",
+                "confidence": fp.get("confidence"),
+            }
 
     # Build enrichment lookup from validated findings
-    enrichments = {}
+    enrichments: dict[int, dict[str, Any]] = {}
+    priority_lookup: dict[int, int] = {}
+
+    # Build priority rank lookup from priority_order
+    for rank, idx in enumerate(meta_result.priority_order, start=1):
+        priority_lookup[idx] = rank
+
     for vf in meta_result.validated_findings:
         idx = vf.get("_index")
         if idx is not None:
@@ -821,25 +834,44 @@ def apply_meta_analysis_to_results(
                 "meta_impact": vf.get("impact"),
             }
 
-    # Filter and enrich original findings
+    # Enrich all findings (do not filter out false positives)
     result_findings = []
     for i, finding in enumerate(original_findings):
-        # Skip false positives
-        if i in fp_indices:
-            continue
-
-        # Add enrichments if available
-        if i in enrichments:
-            for key, value in enrichments[i].items():
-                if value is not None:
-                    finding.metadata[key] = value
+        # Ensure metadata dict exists
+        if finding.metadata is None:
+            finding.metadata = {}
+
+        # Mark false positives with metadata (but keep them in output)
+        if i in fp_data:
+            finding.metadata["meta_false_positive"] = True
+            finding.metadata["meta_reason"] = fp_data[i]["reason"]
+            if fp_data[i].get("confidence") is not None:
+                finding.metadata["meta_confidence"] = fp_data[i]["confidence"]
         else:
-            finding.metadata["meta_reviewed"] = True
+            # Mark as validated (not a false positive)
+            finding.metadata["meta_false_positive"] = False
+
+            # Add enrichments if available for validated findings
+            if i in enrichments:
+                for key, value in enrichments[i].items():
+                    if value is not None:
+                        finding.metadata[key] = value
+            else:
+                finding.metadata["meta_reviewed"] = True
+
+        # Add priority rank if available
+        if i in priority_lookup:
+            finding.metadata["meta_priority"] = priority_lookup[i]
 
         result_findings.append(finding)
 
     # Add missed threats as new findings
     missed_findings = meta_result.get_missed_threats(skill)
+    for mf in missed_findings:
+        # Ensure missed threats are marked as validated (not false positives)
+        if mf.metadata is None:
+            mf.metadata = {}
+        mf.metadata["meta_false_positive"] = False
     result_findings.extend(missed_findings)
 
     return result_findings

skill_scanner/core/analyzers/static.py

@@ -24,6 +24,7 @@ import re
 from pathlib import Path
 from typing import Any
 
+from ...config.yara_modes import DEFAULT_YARA_MODE, YaraModeConfig
 from ...core.models import Finding, Severity, Skill, ThreatCategory
 from ...core.rules.patterns import RuleLoader, SecurityRule
 from ...core.rules.yara_scanner import YaraScanner
@@ -91,28 +92,93 @@ _RM_TARGET_PATTERN = re.compile(r"rm\s+-r[^;]*?\s+([^\s;]+)")
 class StaticAnalyzer(BaseAnalyzer):
     """Static pattern-based security analyzer."""
 
-    def __init__(self, rules_file: Path | None = None, use_yara: bool = True):
+    def __init__(
+        self,
+        rules_file: Path | None = None,
+        use_yara: bool = True,
+        yara_mode: YaraModeConfig | str | None = None,
+        custom_yara_rules_path: str | Path | None = None,
+        disabled_rules: set[str] | None = None,
+    ):
         """
         Initialize static analyzer.
 
         Args:
-            rules_file: Optional custom rules file
+            rules_file: Optional custom YAML rules file
             use_yara: Whether to use YARA scanning (default: True)
+            yara_mode: YARA detection mode - can be:
+                - YaraModeConfig instance
+                - Mode name string: "strict", "balanced", "permissive"
+                - None for default (balanced)
+            custom_yara_rules_path: Path to directory containing custom YARA rules
+                (.yara files). If provided, uses these instead of built-in rules.
+            disabled_rules: Set of rule names to disable. Rules can be YARA rule
+                names (e.g., "YARA_script_injection") or static rule IDs
+                (e.g., "COMMAND_INJECTION_EVAL").
         """
         super().__init__("static_analyzer")
 
         self.rule_loader = RuleLoader(rules_file)
         self.rule_loader.load_rules()
 
+        # Configure YARA mode
+        if yara_mode is None:
+            self.yara_mode = DEFAULT_YARA_MODE
+        elif isinstance(yara_mode, str):
+            self.yara_mode = YaraModeConfig.from_mode_name(yara_mode)
+        else:
+            self.yara_mode = yara_mode
+
+        # Store disabled rules (merge with mode-based disabled rules)
+        self.disabled_rules = set(disabled_rules or set())
+        self.disabled_rules.update(self.yara_mode.disabled_rules)
+
+        # Store custom YARA rules path
+        self.custom_yara_rules_path = Path(custom_yara_rules_path) if custom_yara_rules_path else None
+
         self.use_yara = use_yara
         self.yara_scanner = None
         if use_yara:
             try:
-                self.yara_scanner = YaraScanner()
+                # Use custom rules path if provided
+                if self.custom_yara_rules_path:
+                    self.yara_scanner = YaraScanner(rules_dir=self.custom_yara_rules_path)
+                    logger.info("Using custom YARA rules from: %s", self.custom_yara_rules_path)
+                else:
+                    self.yara_scanner = YaraScanner()
             except Exception as e:
                 logger.warning("Could not load YARA scanner: %s", e)
                 self.yara_scanner = None
 
+    def _is_rule_enabled(self, rule_name: str) -> bool:
+        """
+        Check if a rule is enabled.
+
+        A rule is enabled if:
+        1. It's enabled in the current YARA mode
+        2. It's not in the explicitly disabled rules set
+
+        Args:
+            rule_name: Name of the rule to check (e.g., "YARA_script_injection")
+
+        Returns:
+            True if the rule is enabled, False otherwise
+        """
+        # Check mode-based enable/disable first
+        if not self.yara_mode.is_rule_enabled(rule_name):
+            return False
+
+        # Check if explicitly disabled via --disable-rule
+        if rule_name in self.disabled_rules:
+            return False
+
+        # Also check without YARA_ prefix for convenience
+        base_name = rule_name.replace("YARA_", "") if rule_name.startswith("YARA_") else rule_name
+        if base_name in self.disabled_rules:
+            return False
+
+        return True
+
     def analyze(self, skill: Skill) -> list[Finding]:
         """
         Analyze skill using static pattern matching.
@@ -144,6 +210,10 @@ class StaticAnalyzer(BaseAnalyzer):
 
         findings.extend(self._scan_asset_files(skill))
 
+        # Filter out disabled rules
+        if self.disabled_rules:
+            findings = [f for f in findings if self._is_rule_enabled(f.rule_id)]
+
         return findings
 
     def _check_manifest(self, skill: Skill) -> list[Finding]:
@@ -157,7 +227,7 @@ class StaticAnalyzer(BaseAnalyzer):
                     id=self._generate_finding_id("MANIFEST_INVALID_NAME", "manifest"),
                     rule_id="MANIFEST_INVALID_NAME",
                     category=ThreatCategory.POLICY_VIOLATION,
-                    severity=Severity.LOW,
+                    severity=Severity.INFO,
                     title="Skill name does not follow agent skills naming rules",
                     description=(
                         f"Skill name '{manifest.name}' is invalid. Agent skills require lowercase letters, numbers, "
@@ -246,7 +316,7 @@ class StaticAnalyzer(BaseAnalyzer):
                     id=self._generate_finding_id("MANIFEST_MISSING_LICENSE", "manifest"),
                     rule_id="MANIFEST_MISSING_LICENSE",
                     category=ThreatCategory.POLICY_VIOLATION,
-                    severity=Severity.LOW,
+                    severity=Severity.INFO,
                     title="Skill does not specify a license",
                     description="Skill manifest does not include a 'license' field. Specifying a license helps users understand usage terms.",
                     file_path="SKILL.md",
@@ -553,7 +623,7 @@ class StaticAnalyzer(BaseAnalyzer):
         ]
 
         socket_external_indicators = ["socket.connect", "socket.create_connection"]
-        socket_localhost_indicators = ["localhost", "127.0.0.1", "0.0.0.0"]
+        socket_localhost_indicators = ["localhost", "127.0.0.1", "::1"]
 
         for skill_file in skill.get_scripts():
             content = skill_file.read_content()
@@ -622,8 +692,8 @@ class StaticAnalyzer(BaseAnalyzer):
                     Finding(
                         id=self._generate_finding_id("ALLOWED_TOOLS_WRITE_VIOLATION", skill.name),
                         rule_id="ALLOWED_TOOLS_WRITE_VIOLATION",
-                        category=ThreatCategory.UNAUTHORIZED_TOOL_USE,
-                        severity=Severity.HIGH,
+                        category=ThreatCategory.POLICY_VIOLATION,
+                        severity=Severity.MEDIUM,
                         title="Skill declares no Write tool but bundled scripts write files",
                         description=(
                             f"Skill restricts tools to {skill.manifest.allowed_tools} but bundled scripts appear to "
@@ -651,22 +721,11 @@ class StaticAnalyzer(BaseAnalyzer):
                     )
                 )
 
-        if "python" not in allowed_tools_lower:
-            python_scripts = [f for f in skill.files if f.file_type == "python" and f.relative_path != "SKILL.md"]
-            if python_scripts:
-                findings.append(
-                    Finding(
-                        id=self._generate_finding_id("ALLOWED_TOOLS_PYTHON_VIOLATION", skill.name),
-                        rule_id="ALLOWED_TOOLS_PYTHON_VIOLATION",
-                        category=ThreatCategory.UNAUTHORIZED_TOOL_USE,
-                        severity=Severity.HIGH,
-                        title="Python scripts present but Python tool not in allowed-tools",
-                        description=f"Skill restricts tools to {skill.manifest.allowed_tools} but includes Python scripts",
-                        file_path=None,
-                        remediation="Add 'Python' to allowed-tools or remove Python scripts",
-                        analyzer="static",
-                    )
-                )
+        # Note: ALLOWED_TOOLS_PYTHON_VIOLATION removed - too many false positives
+        # Many skills include Python helper scripts that are NOT invoked directly by the agent
+        # (e.g., build scripts, test files, utilities). The allowed-tools list controls what
+        # the AGENT can use, not what helper scripts exist in the repo.
+        # If direct Python execution is a concern, COMMAND_INJECTION_EVAL catches actual risks.
 
         if "grep" not in allowed_tools_lower:
             if self._code_uses_grep(skill):
@@ -927,6 +986,10 @@ class StaticAnalyzer(BaseAnalyzer):
 
         yara_matches = self.yara_scanner.scan_content(skill.instruction_body, "SKILL.md")
         for match in yara_matches:
+            rule_name = match.get("rule_name", "")
+            # Check if rule is enabled in current mode and not explicitly disabled
+            if not self._is_rule_enabled(rule_name):
+                continue
             findings.extend(self._create_findings_from_yara_match(match, skill))
 
         for skill_file in skill.get_scripts():
@@ -935,7 +998,7 @@ class StaticAnalyzer(BaseAnalyzer):
                 yara_matches = self.yara_scanner.scan_content(content, skill_file.relative_path)
                 for match in yara_matches:
                     rule_name = match.get("rule_name", "")
-                    if rule_name == "skill_discovery_abuse":
+                    if rule_name == "capability_inflation_generic":
                         continue
                     findings.extend(self._create_findings_from_yara_match(match, skill, content))
 
@@ -1006,8 +1069,28 @@ class StaticAnalyzer(BaseAnalyzer):
             ".cache",
         }
 
+        PLACEHOLDER_MARKERS = {
+            "your-",
+            "your_",
+            "your ",
+            "example",
+            "sample",
+            "dummy",
+            "placeholder",
+            "replace",
+            "changeme",
+            "change_me",
+            "<your",
+            "<insert",
+        }
+
         for string_match in match["strings"]:
-            if rule_name == "code_execution":
+            # Skip exclusion patterns (these are used in YARA conditions but shouldn't create findings)
+            string_identifier = string_match.get("identifier", "")
+            if string_identifier.startswith("$documentation") or string_identifier.startswith("$safe"):
+                continue
+
+            if rule_name == "code_execution_generic":
                 line_content = string_match.get("line_content", "").lower()
                 matched_data = string_match.get("matched_data", "").lower()
 
@@ -1028,7 +1111,7 @@ class StaticAnalyzer(BaseAnalyzer):
                 if is_safe_command:
                     continue
 
-            if rule_name == "system_manipulation":
+            if rule_name == "system_manipulation_generic":
                 line_content = string_match.get("line_content", "").lower()
 
                 if "rm -rf" in line_content or "rm -r" in line_content:
@@ -1040,6 +1123,73 @@ class StaticAnalyzer(BaseAnalyzer):
                         if all_safe:
                             continue
 
+            # Credential harvesting post-filters (controlled by mode)
+            if rule_name == "credential_harvesting_generic":
+                if self.yara_mode.credential_harvesting.filter_placeholder_patterns:
+                    line_content = string_match.get("line_content", "")
+                    matched_data = string_match.get("matched_data", "")
+                    combined = f"{line_content} {matched_data}".lower()
+
+                    if any(marker in combined for marker in PLACEHOLDER_MARKERS):
+                        continue
+
+                    if "export " in combined and "=" in combined:
+                        _, value = combined.split("=", 1)
+                        if any(marker in value for marker in PLACEHOLDER_MARKERS):
+                            continue
+
+            # Tool chaining post-filters (controlled by mode)
+            if rule_name == "tool_chaining_abuse_generic":
+                line_content = string_match.get("line_content", "")
+                lower_line = line_content.lower()
+                exfil_hints = ("send", "upload", "transmit", "webhook", "slack", "exfil", "forward")
+
+                if self.yara_mode.tool_chaining.filter_generic_http_verbs:
+                    if (
+                        "get" in lower_line
+                        and "post" in lower_line
+                        and not any(hint in lower_line for hint in exfil_hints)
+                    ):
+                        continue
+
+                if self.yara_mode.tool_chaining.filter_api_documentation:
+                    if any(
+                        token in line_content for token in ("@app.", "app.", "router.", "route", "endpoint")
+                    ) and not any(hint in lower_line for hint in exfil_hints):
+                        continue
+
+                if self.yara_mode.tool_chaining.filter_email_field_mentions:
+                    if "by email" in lower_line or "email address" in lower_line or "email field" in lower_line:
+                        continue
+
+            # Unicode steganography post-filters
+            if rule_name == "prompt_injection_unicode_steganography":
+                line_content = string_match.get("line_content", "")
+                matched_data = string_match.get("matched_data", "")
+                has_ascii_letters = any("A" <= char <= "Z" or "a" <= char <= "z" for char in line_content)
+
+                # Filter short matches in non-Latin context (likely legitimate i18n)
+                if len(matched_data) <= 2 and not has_ascii_letters:
+                    continue
+
+                # Filter if context suggests legitimate internationalization
+                i18n_markers = ("i18n", "locale", "translation", "lang=", "charset", "utf-8", "encoding")
+                if any(marker in line_content.lower() for marker in i18n_markers):
+                    continue
+
+                # Filter Cyrillic, CJK, Arabic, Hebrew text (legitimate non-Latin content)
+                # These are indicated by presence of those scripts without zero-width chars
+                cyrillic_cjk_pattern = any(
+                    ("\u0400" <= char <= "\u04ff")  # Cyrillic
+                    or ("\u4e00" <= char <= "\u9fff")  # CJK Unified
+                    or ("\u0600" <= char <= "\u06ff")  # Arabic
+                    or ("\u0590" <= char <= "\u05ff")  # Hebrew
+                    for char in line_content
+                )
+                # If the line has legitimate non-Latin text but matched only 1-2 zero-width chars, skip
+                if cyrillic_cjk_pattern and len(matched_data) < 10:
+                    continue
+
             finding_id = self._generate_finding_id(f"YARA_{rule_name}", f"{file_path}:{string_match['line_number']}")
 
             description = meta.get("description", f"YARA rule {rule_name} matched")

skill_scanner/core/models.py

@@ -49,6 +49,7 @@ class ThreatCategory(str, Enum):
     RESOURCE_ABUSE = "resource_abuse"
     POLICY_VIOLATION = "policy_violation"
     MALWARE = "malware"
+    HARMFUL_CONTENT = "harmful_content"
     # New threat categories
     SKILL_DISCOVERY_ABUSE = "skill_discovery_abuse"
     TRANSITIVE_TRUST_ABUSE = "transitive_trust_abuse"

skill_scanner/core/reporters/markdown_reporter.py

@@ -18,6 +18,8 @@
 Markdown format reporter for scan results.
 """
 
+import re
+
 from ...core.models import Finding, Report, ScanResult, Severity
 
 
@@ -137,6 +139,7 @@ class MarkdownReporter:
         lines.append("")
 
         for result in report.scan_results:
+            lines.append("\n---\n")
             status_icon = "[OK]" if result.is_safe else "[FAIL]"
             lines.append(f"### {status_icon} {result.skill_name}")
             lines.append("")
@@ -186,9 +189,12 @@ class MarkdownReporter:
             if finding.snippet:
                 lines.append(f"{indent_str}")
                 lines.append(f"{indent_str}**Code Snippet:**")
-                lines.append(f"{indent_str}```")
-                lines.append(f"{indent_str}{finding.snippet}")
-                lines.append(f"{indent_str}```")
+                if not re.search(r"```", finding.snippet):
+                    lines.append(f"{indent_str}```")
+                for line in finding.snippet.splitlines():
+                    lines.append(f"{indent_str}{line}")
+                if not re.search(r"```", finding.snippet):
+                    lines.append(f"{indent_str}```")
 
             if finding.remediation:
                 lines.append(f"{indent_str}")

skill_scanner/core/static_analysis/context_extractor.py

@@ -141,18 +141,68 @@ class SkillFunctionContext:
 class ContextExtractor:
     """Extract comprehensive security context from skill scripts."""
 
-    SUSPICIOUS_DOMAINS = ["attacker.com", "evil.com", "malicious.com", "pastebin.com"]
+    # ONLY flag URLs to explicitly suspicious domains - not all unknown URLs
+    # Reference: https://lots-project.com/ (Living Off Trusted Sites)
+    SUSPICIOUS_DOMAINS = [
+        # Known exfil/C2/paste services (LOTS: Download, Exfiltration, C&C)
+        "pastebin.com",
+        "hastebin.com",
+        "paste.ee",
+        "rentry.co",
+        "zerobin.net",
+        "textbin.net",
+        "termbin.com",
+        "sprunge.us",
+        "clbin.com",
+        "ix.io",
+        "pastetext.net",
+        "pastie.org",
+        "ideone.com",
+        # File sharing services (LOTS: Download, Exfiltration)
+        "transfer.sh",
+        "filebin.net",
+        "gofile.io",
+        "anonfiles.com",
+        "mediafire.com",
+        "mega.nz",
+        "wetransfer.com",
+        "filetransfer.io",
+        "ufile.io",
+        "4sync.com",
+        "uplooder.net",
+        "filecloudonline.com",
+        "sendspace.com",
+        "siasky.net",
+        # Tunneling/webhook services (LOTS: C&C, Exfiltration)
+        "webhook.site",
+        "requestbin",
+        "ngrok.io",
+        "pipedream.net",
+        "localhost.run",
+        "trycloudflare.com",
+        # Code execution services (LOTS: C&C, Download)
+        "codepen.io",
+        "repl.co",
+        "glitch.me",
+        # Explicitly malicious example domains
+        "attacker.example.com",
+        "evil.example.com",
+        "malicious.com",
+        "c2-server.com",
+    ]
 
-    # Legitimate domains that should NOT be flagged as suspicious
+    # Domains that are always safe (not flagged even if matched by SUSPICIOUS_DOMAINS pattern)
+    # NOTE: We intentionally exclude file-hosting/messaging services that appear in LOTS
+    # (https://lots-project.com/) with Download/C&C capabilities, even if commonly used.
     LEGITIMATE_DOMAINS = [
-        # AI provider services
+        # AI provider services (API endpoints only, not user content)
         "api.anthropic.com",
         "statsig.anthropic.com",
-        # Code repositories
-        "github.com",
-        "gitlab.com",
-        "bitbucket.org",
-        # Package registries
+        "api.openai.com",
+        "api.together.xyz",
+        "api.cohere.ai",
+        "generativelanguage.googleapis.com",
+        # Package registries (read-only, no user-uploaded executables)
         "registry.npmjs.org",
         "npmjs.com",
         "npmjs.org",
@@ -161,18 +211,43 @@ class ContextExtractor:
         "pypi.org",
         "files.pythonhosted.org",
         "pythonhosted.org",
+        "crates.io",
+        "rubygems.org",
+        "pkg.go.dev",
         # System packages
         "archive.ubuntu.com",
         "security.ubuntu.com",
+        "debian.org",
         # XML schemas (for OOXML document processing)
         "schemas.microsoft.com",
         "schemas.openxmlformats.org",
         "www.w3.org",
         "purl.org",
+        "json-schema.org",
         # Localhost and development
         "localhost",
         "127.0.0.1",
         "0.0.0.0",
+        "::1",
+        # Common safe services (API-focused, not file hosting)
+        "stripe.com",
+        "zoom.us",
+        "twilio.com",
+        "mailgun.com",
+        "sentry.io",
+        "datadog.com",
+        "newrelic.com",
+        "elastic.co",
+        "mongodb.com",
+        "redis.io",
+        "postgresql.org",
+        # NOTE: The following are intentionally NOT in this list due to LOTS risk:
+        # - github.com, gitlab.com, bitbucket.org (Download, C&C)
+        # - raw.githubusercontent.com (Download, C&C)
+        # - discord.com, telegram.org, slack.com (C&C, Exfil)
+        # - amazonaws.com, googleapis.com, azure.com, cloudflare.com (wildcard hosting)
+        # - google.com, microsoft.com (too broad, includes file hosting)
+        # - sendgrid.com (email tracking/download)
     ]
 
     def extract_context(self, file_path: Path, source_code: str) -> SkillScriptContext:
@@ -259,7 +334,8 @@ class ContextExtractor:
         # Also collect module-level strings (class attributes, etc.)
         all_strings.extend(parser.module_strings)
 
-        # Find suspicious URLs (filter out legitimate domains and docstrings)
+        # Find suspicious URLs - ONLY flag URLs to known-bad destinations
+        # Don't flag unknown URLs - that creates too many false positives
         suspicious_urls = []
         for s in all_strings:
             # Skip if not URL-like or contains newlines (docstrings)
@@ -271,12 +347,10 @@ class ContextExtractor:
             # Skip if contains legitimate domain
             if any(domain in s for domain in self.LEGITIMATE_DOMAINS):
                 continue
-            # Flag if contains known suspicious domain OR is generic http URL
+            # ONLY flag if URL contains a known suspicious domain
+            # Don't flag all unknown URLs - that's too aggressive
             if any(domain in s for domain in self.SUSPICIOUS_DOMAINS):
                 suspicious_urls.append(s)
-            # Generic URLs only if they look suspicious (not just schema URLs)
-            elif not any(schema in s for schema in ["schemas.", "www.w3.org", "xmlns"]):
-                suspicious_urls.append(s)
 
         # Create context
         context = SkillScriptContext(