centicodehelp 0.2.0__py3-none-any.whl

centicodehelp/__init__.py

@@ -0,0 +1,3 @@
+"""CentiCodeHelp - Dein Code. Besser. Sauber."""
+
+__version__ = "0.2.0"

centicodehelp/ai/llm_client.py

@@ -0,0 +1,150 @@
+import os
+import json
+import time
+import logging
+from typing import Optional, Dict, Any, List
+from pydantic import BaseModel, Field
+from centicodehelp.core.config import load_config, centicodehelpConfig
+from centicodehelp.ai.providers import SUPPORTED_PROVIDERS, get_provider
+
+logger = logging.getLogger(__name__)
+
+class LLMResponse(BaseModel):
+    content: str
+    model: str
+    duration_seconds: float = 0.0
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+    raw_response: Optional[Any] = None
+
+
+class LLMClient:
+    """Unified client wrapping LiteLLM for all AI providers."""
+
+    def __init__(
+        self,
+        provider: Optional[str] = None,
+        model: Optional[str] = None,
+        api_key: Optional[str] = None,
+        api_base: Optional[str] = None,
+        config: Optional[centicodehelpConfig] = None,
+    ):
+        self.config = config or load_config()
+        self.provider_id = (provider or self.config.default_provider).lower()
+        self.provider_info = get_provider(self.provider_id)
+
+        # Resolve model name
+        if model:
+            self.model = model
+        elif self.provider_info:
+            self.model = self.provider_info.default_model
+        else:
+            self.model = self.config.default_model
+
+        # Determine full LiteLLM model identifier
+        self.litellm_model = self._resolve_litellm_model(self.provider_id, self.model)
+
+        # Resolve API Key
+        self.api_key = api_key or self._resolve_api_key(self.provider_id)
+
+        # Resolve API Base
+        self.api_base = api_base or self._resolve_api_base(self.provider_id)
+
+    def _resolve_litellm_model(self, provider_id: str, model: str) -> str:
+        """Resolve to litellm standard format (e.g. openai/gpt-4o, ollama/llama3.2)."""
+        if "/" in model:
+            return model
+
+        if self.provider_info:
+            for m in self.provider_info.models:
+                if m.name.lower() == model.lower():
+                    return m.litellm_id
+
+        # Fallback convention: <provider>/<model>
+        return f"{provider_id}/{model}"
+
+    def _resolve_api_key(self, provider_id: str) -> Optional[str]:
+        if provider_id in self.config.api_keys:
+            return self.config.api_keys[provider_id]
+
+        if self.provider_info:
+            for env_var in self.provider_info.env_keys:
+                val = os.getenv(env_var)
+                if val:
+                    return val
+
+        return os.getenv(f"{provider_id.upper()}_API_KEY")
+
+    def _resolve_api_base(self, provider_id: str) -> Optional[str]:
+        if provider_id in self.config.api_bases:
+            return self.config.api_bases[provider_id]
+
+        if provider_id == "ollama":
+            return os.getenv("OLLAMA_API_BASE") or self.config.ollama_base_url
+
+        if self.provider_info and self.provider_info.default_api_base:
+            return self.provider_info.default_api_base
+
+        return None
+
+    def complete_with_metadata(
+        self, prompt: str, system: Optional[str] = None, temperature: float = 0.2
+    ) -> LLMResponse:
+        """Send completion request via LiteLLM and return rich telemetry."""
+        try:
+            import litellm
+            litellm.suppress_debug_info = True
+        except ImportError:
+            raise RuntimeError("LiteLLM is not installed. Run 'pip install litellm' first.")
+
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+
+        kwargs: Dict[str, Any] = {
+            "model": self.litellm_model,
+            "messages": messages,
+            "temperature": temperature,
+        }
+
+        if self.api_key:
+            kwargs["api_key"] = self.api_key
+        if self.api_base:
+            kwargs["api_base"] = self.api_base
+
+        start_time = time.time()
+        try:
+            response = litellm.completion(**kwargs)
+            duration = round(time.time() - start_time, 2)
+
+            content = response.choices[0].message.content or ""
+            usage = getattr(response, "usage", None)
+
+            p_tokens = getattr(usage, "prompt_tokens", 0) if usage else 0
+            c_tokens = getattr(usage, "completion_tokens", 0) if usage else 0
+            t_tokens = getattr(usage, "total_tokens", 0) if usage else (p_tokens + c_tokens)
+
+            return LLMResponse(
+                content=content,
+                model=self.litellm_model,
+                duration_seconds=duration,
+                prompt_tokens=p_tokens,
+                completion_tokens=c_tokens,
+                total_tokens=t_tokens,
+                raw_response=response,
+            )
+        except Exception as e:
+            err_str = str(e)
+            if self.provider_id == "ollama" and ("Connection" in err_str or "10061" in err_str or "ConnectError" in err_str):
+                raise RuntimeError(
+                    "❌ Ollama läuft nicht. Starte es mit 'ollama serve' oder nutze 'ct setup' für einen Cloud-Anbieter."
+                ) from e
+            logger.error(f"LiteLLM completion error for model {self.litellm_model}: {e}")
+            raise
+
+    def complete(self, prompt: str, system: Optional[str] = None, temperature: float = 0.2) -> str:
+        """Backward-compatible complete method returning pure text."""
+        return self.complete_with_metadata(prompt, system=system, temperature=temperature).content
+

centicodehelp/ai/prompts.py

@@ -0,0 +1,63 @@
+"""Prompt templates for AI-assisted code review and auto-fixing."""
+
+REVIEW_PROMPT_TEMPLATE = """You are an expert static analysis and code security auditor.
+Analyze the following source code file and the static analysis findings below.
+Your task:
+1. Validate whether the reported static findings are true positives.
+2. Identify any subtle logic bugs, unhandled edge cases, performance issues, or security flaws that were missed.
+3. Suggest concrete fixes for each issue.
+
+File: {file_path}
+Language: {language}
+
+--- STATIC ANALYSIS FINDINGS ---
+{static_findings}
+
+--- SOURCE CODE ---
+```{language}
+{source_code}
+```
+
+Format your response strictly as a JSON object with this structure:
+{{
+  "summary": "Brief summary of code health and key problems",
+  "issues": [
+    {{
+      "line": <line_number_or_null>,
+      "severity": "INFO" | "LOW" | "MEDIUM" | "HIGH" | "CRITICAL",
+      "rule_id": "<rule_identifier>",
+      "description": "<detailed problem description>",
+      "suggested_fix": "<how to fix it>"
+    }}
+  ]
+}}
+Only output valid JSON. Do not wrap in extra prose.
+"""
+
+FIX_SYSTEM_PROMPT = """Du bist ein erstklassiger Code-Sicherheitsexperte und Entwickler. Deine Aufgabe ist es, den fehlerhaften Quellcode strikt nach Sicherheits- und Qualitätsregeln zu reparieren. Gib ausschließlich den fertig korrigierten Quellcode zurück."""
+
+FIX_PROMPT_TEMPLATE = """Du bist ein Sicherheitsexperte. Behebe die folgenden Probleme im Code:
+1. SEC001: Ersetze hardcodierte Secrets durch os.environ.get().
+2. SEC101: Ersetze eval() IMMER durch ast.literal_eval(). Wenn das nicht möglich ist, entferne eval() komplett und wirf einen Fehler (ValueError). eval() darf unter KEINEN Umständen mehr im Code vorkommen! Stelle sicher, dass 'import ast' vorhanden ist.
+3. DEBUG002: Entferne ALLE print()-Debug-Statements KOMPLETT. Nicht auskommentieren, nicht ersetzen – LÖSCHEN. Die Zeile darf im Ergebnis nicht mehr vorkommen.
+4. ERR001/ERR003: Ersetze bare except durch except Exception as e.
+5. QUAL001: Implementiere die fehlende Logik (z. B. Validierung für negative Preise mit ValueError) und entferne das TODO.
+
+WICHTIGE ANWEISUNGEN:
+- Der Aufruf 'eval(...)' ist STRENG VERBOTEN. Verwende ausschließlich 'ast.literal_eval(...)'.
+- Debug-Prints mit 'DEBUG' MÜSSEN komplett gelöscht werden.
+- Gib NUR den korrigierten Code in einem Code-Block ``` zurück. Keine Erklärungen, kein Begleittext.
+
+Datei: {file_path}
+Sprache: {language}
+
+--- ZU BEHEBENDE PROBLEME ---
+{findings_text}
+
+--- ORIGINALER CODE ---
+```{language}
+{source_code}
+```
+
+Gib NUR den korrigierten Code zurück:
+"""

centicodehelp/ai/providers.py

@@ -0,0 +1,195 @@
+from typing import Dict, List, Optional
+from pydantic import BaseModel, Field
+
+class ModelInfo(BaseModel):
+    name: str
+    litellm_id: str
+    description: str
+    is_default: bool = False
+    context_window: Optional[int] = None
+
+
+class ProviderInfo(BaseModel):
+    id: str
+    name: str
+    env_keys: List[str]
+    default_model: str
+    description: str
+    models: List[ModelInfo]
+    requires_api_base: bool = False
+    default_api_base: Optional[str] = None
+
+
+SUPPORTED_PROVIDERS: Dict[str, ProviderInfo] = {
+    "openai": ProviderInfo(
+        id="openai",
+        name="OpenAI",
+        env_keys=["OPENAI_API_KEY"],
+        default_model="gpt-4o",
+        description="OpenAI GPT-4o, GPT-4o-mini, o1, o3 models",
+        models=[
+            ModelInfo(name="gpt-4o", litellm_id="openai/gpt-4o", description="Flagship high-intelligence model", is_default=True),
+            ModelInfo(name="gpt-4o-mini", litellm_id="openai/gpt-4o-mini", description="Fast and cost-effective model"),
+            ModelInfo(name="o1-preview", litellm_id="openai/o1-preview", description="Reasoning model for hard problems"),
+            ModelInfo(name="o3-mini", litellm_id="openai/o3-mini", description="High-speed reasoning model"),
+        ]
+    ),
+    "anthropic": ProviderInfo(
+        id="anthropic",
+        name="Anthropic Claude",
+        env_keys=["ANTHROPIC_API_KEY"],
+        default_model="claude-3-5-sonnet",
+        description="Anthropic Claude 3.5 Sonnet / Haiku series",
+        models=[
+            ModelInfo(name="claude-3-5-sonnet", litellm_id="anthropic/claude-3-5-sonnet-20241022", description="State-of-the-art coding and analysis", is_default=True),
+            ModelInfo(name="claude-3-5-haiku", litellm_id="anthropic/claude-3-5-haiku-20241022", description="High-speed code reviewer"),
+        ]
+    ),
+    "gemini": ProviderInfo(
+        id="gemini",
+        name="Google Gemini",
+        env_keys=["GEMINI_API_KEY", "GOOGLE_API_KEY"],
+        default_model="gemini-1.5-pro",
+        description="Google Gemini 1.5 Pro and Flash with large context windows",
+        models=[
+            ModelInfo(name="gemini-1.5-pro", litellm_id="gemini/gemini-1.5-pro", description="Multimodal deep code reasoning", is_default=True),
+            ModelInfo(name="gemini-1.5-flash", litellm_id="gemini/gemini-1.5-flash", description="Ultra-fast code auditor"),
+            ModelInfo(name="gemini-2.0-flash-exp", litellm_id="gemini/gemini-2.0-flash-exp", description="Next-gen experimental Gemini"),
+        ]
+    ),
+    "deepseek": ProviderInfo(
+        id="deepseek",
+        name="DeepSeek",
+        env_keys=["DEEPSEEK_API_KEY"],
+        default_model="deepseek-coder",
+        description="Specialized code and reasoning models",
+        models=[
+            ModelInfo(name="deepseek-coder", litellm_id="deepseek/deepseek-coder", description="DeepSeek Coder V2 model", is_default=True),
+            ModelInfo(name="deepseek-chat", litellm_id="deepseek/deepseek-chat", description="General DeepSeek V3 chat model"),
+            ModelInfo(name="deepseek-reasoner", litellm_id="deepseek/deepseek-reasoner", description="DeepSeek R1 reasoning model"),
+        ]
+    ),
+    "ollama": ProviderInfo(
+        id="ollama",
+        name="Ollama (Local)",
+        env_keys=[],
+        default_model="qwen2.5-coder:7b",
+        description="Locally run open models without cloud API keys",
+        requires_api_base=True,
+        default_api_base="http://localhost:11434",
+        models=[
+            ModelInfo(name="qwen2.5-coder:7b", litellm_id="ollama/qwen2.5-coder:7b", description="High performance open coding LLM", is_default=True),
+            ModelInfo(name="qwen2.5-coder", litellm_id="ollama/qwen2.5-coder:7b", description="High performance open coding LLM"),
+            ModelInfo(name="llama3.2", litellm_id="ollama/llama3.2", description="Meta Llama 3.2 lightweight local model"),
+            ModelInfo(name="deepseek-coder-v2", litellm_id="ollama/deepseek-coder-v2", description="Local DeepSeek coder model"),
+            ModelInfo(name="mistral", litellm_id="ollama/mistral", description="Mistral 7B local model"),
+        ]
+    ),
+    "openrouter": ProviderInfo(
+        id="openrouter",
+        name="OpenRouter",
+        env_keys=["OPENROUTER_API_KEY"],
+        default_model="anthropic/claude-3.5-sonnet",
+        description="Universal router for hundreds of models with unified credits",
+        models=[
+            ModelInfo(name="claude-3.5-sonnet", litellm_id="openrouter/anthropic/claude-3.5-sonnet", description="Claude 3.5 Sonnet via OpenRouter", is_default=True),
+            ModelInfo(name="deepseek-v3", litellm_id="openrouter/deepseek/deepseek-chat", description="DeepSeek V3 via OpenRouter"),
+            ModelInfo(name="meta-llama-3.3-70b", litellm_id="openrouter/meta-llama/llama-3.3-70b-instruct", description="Llama 3.3 70B via OpenRouter"),
+        ]
+    ),
+    "groq": ProviderInfo(
+        id="groq",
+        name="Groq (LPU Inference)",
+        env_keys=["GROQ_API_KEY"],
+        default_model="llama-3.3-70b-versatile",
+        description="Ultra-fast LPU hardware accelerated inference",
+        models=[
+            ModelInfo(name="llama-3.3-70b-versatile", litellm_id="groq/llama-3.3-70b-versatile", description="Fast Llama 3.3 70B inference", is_default=True),
+            ModelInfo(name="mixtral-8x7b-32768", litellm_id="groq/mixtral-8x7b-32768", description="Mixtral 8x7B high speed"),
+        ]
+    ),
+    "mistral": ProviderInfo(
+        id="mistral",
+        name="Mistral AI",
+        env_keys=["MISTRAL_API_KEY"],
+        default_model="codestral-latest",
+        description="Mistral AI European enterprise models & Codestral",
+        models=[
+            ModelInfo(name="codestral-latest", litellm_id="mistral/codestral-latest", description="Dedicated code generation/fixing model", is_default=True),
+            ModelInfo(name="mistral-large-latest", litellm_id="mistral/mistral-large-latest", description="Mistral flagship model"),
+        ]
+    ),
+    "cohere": ProviderInfo(
+        id="cohere",
+        name="Cohere",
+        env_keys=["COHERE_API_KEY"],
+        default_model="command-r-plus",
+        description="Cohere Command R / Command R+ models",
+        models=[
+            ModelInfo(name="command-r-plus", litellm_id="cohere/command-r-plus", description="Enterprise reasoning and search", is_default=True),
+            ModelInfo(name="command-r", litellm_id="cohere/command-r", description="Fast Command R model"),
+        ]
+    ),
+    "xai": ProviderInfo(
+        id="xai",
+        name="xAI (Grok)",
+        env_keys=["XAI_API_KEY"],
+        default_model="grok-beta",
+        description="xAI Grok models",
+        models=[
+            ModelInfo(name="grok-beta", litellm_id="xai/grok-beta", description="xAI Grok Beta LLM", is_default=True),
+            ModelInfo(name="grok-2-latest", litellm_id="xai/grok-2-latest", description="xAI Grok 2 reasoning"),
+        ]
+    ),
+    "together": ProviderInfo(
+        id="together",
+        name="Together AI",
+        env_keys=["TOGETHERAI_API_KEY", "TOGETHER_API_KEY"],
+        default_model="meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo",
+        description="Together AI cloud inference for open weights",
+        models=[
+            ModelInfo(name="llama-3.1-70b-turbo", litellm_id="together_ai/meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo", description="Llama 3.1 70B Turbo", is_default=True),
+            ModelInfo(name="qwen-2.5-coder-32b", litellm_id="together_ai/Qwen/Qwen2.5-Coder-32B-Instruct", description="Qwen 2.5 Coder 32B Turbo"),
+        ]
+    ),
+    "perplexity": ProviderInfo(
+        id="perplexity",
+        name="Perplexity AI",
+        env_keys=["PERPLEXITYAI_API_KEY", "PPLX_API_KEY"],
+        default_model="sonar-pro",
+        description="Perplexity Sonar online search models",
+        models=[
+            ModelInfo(name="sonar-pro", litellm_id="perplexity/sonar-pro", description="Sonar Pro online search model", is_default=True),
+            ModelInfo(name="sonar", litellm_id="perplexity/sonar", description="Standard Sonar search model"),
+        ]
+    ),
+    "azure": ProviderInfo(
+        id="azure",
+        name="Azure OpenAI",
+        env_keys=["AZURE_API_KEY"],
+        default_model="azure-gpt-4o",
+        description="Microsoft Azure OpenAI enterprise deployments",
+        requires_api_base=True,
+        models=[
+            ModelInfo(name="azure-gpt-4o", litellm_id="azure/gpt-4o", description="Azure deployed GPT-4o", is_default=True),
+        ]
+    ),
+    "bedrock": ProviderInfo(
+        id="bedrock",
+        name="AWS Bedrock",
+        env_keys=["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"],
+        default_model="anthropic.claude-3-5-sonnet",
+        description="Amazon Web Services Bedrock foundation models",
+        models=[
+            ModelInfo(name="claude-3-5-sonnet", litellm_id="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0", description="Claude 3.5 Sonnet on AWS Bedrock", is_default=True),
+        ]
+    ),
+}
+
+
+def get_provider(provider_id: str) -> Optional[ProviderInfo]:
+    return SUPPORTED_PROVIDERS.get(provider_id.lower())
+
+
+def list_providers() -> List[ProviderInfo]:
+    return list(SUPPORTED_PROVIDERS.values())

centicodehelp/ai/reviewer.py

@@ -0,0 +1,139 @@
+import json
+import logging
+from pathlib import Path
+from typing import List, Tuple, Optional
+from pydantic import BaseModel, Field
+from centicodehelp.core.models import Finding, Severity
+from centicodehelp.ai.llm_client import LLMClient, LLMResponse
+from centicodehelp.ai.prompts import REVIEW_PROMPT_TEMPLATE
+
+logger = logging.getLogger(__name__)
+
+class AIReviewResult(BaseModel):
+    findings: List[Finding] = Field(default_factory=list)
+    summary: str = ""
+    raw_response: str = ""
+    model: str = ""
+    provider: str = ""
+    duration_seconds: float = 0.0
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+    error: Optional[str] = None
+
+
+class AIReviewer:
+    """Combines static findings with LLM reasoning for deep analysis."""
+
+    def __init__(self, llm_client: LLMClient):
+        self.llm = llm_client
+
+    def review_with_details(
+        self, file_path: Path, language: str, static_findings: List[Finding]
+    ) -> AIReviewResult:
+        """Run AI review and return structured telemetry and findings."""
+        result = AIReviewResult(
+            model=self.llm.model,
+            provider=self.llm.provider_id,
+        )
+
+        if not file_path.exists():
+            result.error = f"Datei {file_path} existiert nicht."
+            return result
+
+        try:
+            source_code = file_path.read_text(encoding="utf-8", errors="replace")
+        except Exception as e:
+            result.error = f"Fehler beim Lesen der Datei: {e}"
+            return result
+
+        # Format static findings for prompt
+        findings_str = "\n".join([
+            f"- Line {f.line or '?'}: [{f.rule_id}] ({f.severity.value}) {f.description}"
+            for f in static_findings
+        ]) or "Keine statischen Regelverletzungen gefunden."
+
+        prompt = REVIEW_PROMPT_TEMPLATE.format(
+            file_path=str(file_path),
+            language=language,
+            static_findings=findings_str,
+            source_code=source_code,
+        )
+
+        try:
+            resp: LLMResponse = self.llm.complete_with_metadata(
+                prompt, system="Du bist ein erfahrener Sicherheits- und Code-Qualitäts-Auditor."
+            )
+            result.raw_response = resp.content
+            result.duration_seconds = resp.duration_seconds
+            result.prompt_tokens = resp.prompt_tokens
+            result.completion_tokens = resp.completion_tokens
+            result.total_tokens = resp.total_tokens
+
+            ai_findings, summary = self._parse_ai_response(resp.content, str(file_path), language)
+            result.findings = ai_findings
+            result.summary = summary or "KI-Codeanalyse abgeschlossen."
+            return result
+        except Exception as e:
+            result.error = str(e)
+            return result
+
+    def review(self, file_path: Path, language: str, static_findings: List[Finding]) -> List[Finding]:
+        """Backward compatible review method merging static and AI findings."""
+        res = self.review_with_details(file_path, language, static_findings)
+        if res.findings:
+            return self._merge_findings(static_findings, res.findings)
+        return static_findings
+
+    def _parse_ai_response(
+        self, response_text: str, file_path: str, language: str
+    ) -> Tuple[List[Finding], str]:
+        findings: List[Finding] = []
+        summary = ""
+        cleaned = response_text.strip()
+
+        # Strip markdown wrapping if model output was enclosed
+        if "```json" in cleaned:
+            parts = cleaned.split("```json")
+            if len(parts) > 1:
+                cleaned = parts[1].split("```")[0].strip()
+        elif cleaned.startswith("```"):
+            parts = cleaned.split("```")
+            if len(parts) > 1:
+                cleaned = parts[1].strip()
+
+        try:
+            data = json.loads(cleaned)
+            summary = str(data.get("summary", ""))
+            issues = data.get("issues", [])
+            for item in issues:
+                sev_str = str(item.get("severity", "MEDIUM")).upper()
+                sev = Severity.__members__.get(sev_str, Severity.MEDIUM)
+                rule = str(item.get("rule_id", "AI_ANALYSIS"))
+                desc = str(item.get("description", "Von KI identifiziertes Problem"))
+                fix = item.get("suggested_fix")
+                line = item.get("line")
+
+                findings.append(Finding(
+                    file_path=file_path,
+                    line=line,
+                    rule_id=rule,
+                    severity=sev,
+                    description=desc,
+                    suggested_fix=fix,
+                    language=language,
+                ))
+        except Exception as e:
+            logger.debug(f"JSON parsing error from LLM response: {e}")
+            summary = cleaned[:200]
+
+        return findings, summary
+
+    def _merge_findings(self, static_findings: List[Finding], ai_findings: List[Finding]) -> List[Finding]:
+        merged = list(static_findings)
+        existing_rules = {(f.line, f.rule_id) for f in static_findings}
+        for af in ai_findings:
+            if (af.line, af.rule_id) not in existing_rules:
+                merged.append(af)
+        return merged
+

centicodehelp/analysis/binary_analyzer.py

@@ -0,0 +1,124 @@
+import math
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+from centicodehelp.core.models import Finding, Severity
+
+class BinaryAnalyzer:
+    """Analyzer for PE, ELF, Mach-O binaries utilizing NusantaraScan or fallback heuristics."""
+
+    def __init__(self):
+        self.nusantara_available = self._check_nusantara()
+
+    def _check_nusantara(self) -> bool:
+        try:
+            import nusantarascan  # type: ignore
+            return True
+        except ImportError:
+            return False
+
+    def analyze_binary(self, file_path: Path) -> List[Finding]:
+        findings: List[Finding] = []
+        if not file_path.exists():
+            return findings
+
+        # Run NusantaraScan if present
+        if self.nusantara_available:
+            try:
+                import nusantarascan  # type: ignore
+                scanner = nusantarascan.Scanner()
+                result = scanner.scan_file(str(file_path))
+                # Map nusantara results to findings
+                if hasattr(result, "detections"):
+                    for d in result.detections:
+                        findings.append(Finding(
+                            file_path=str(file_path),
+                            rule_id=getattr(d, "rule_id", "BIN_NUSANTARA"),
+                            severity=Severity.HIGH,
+                            description=str(getattr(d, "description", "Suspicious binary signature detected")),
+                            language="binary"
+                        ))
+                return findings
+            except Exception:
+                pass
+
+        # Heuristic analysis: entropy, headers, suspicious strings
+        findings.extend(self._heuristic_scan(file_path))
+        return findings
+
+    def _heuristic_scan(self, file_path: Path) -> List[Finding]:
+        findings = []
+        try:
+            with open(file_path, "rb") as f:
+                data = f.read()
+
+            entropy = self._calculate_entropy(data)
+            if entropy > 7.2:
+                findings.append(Finding(
+                    file_path=str(file_path),
+                    rule_id="BIN_ENTROPY_HIGH",
+                    severity=Severity.HIGH,
+                    description=f"High Shannon entropy detected ({entropy:.2f} / 8.0). Binary is likely packed, compressed, or encrypted (UPX/Themida/Custom).",
+                    suggested_fix="Unpack binary before performing deep disassembly or vulnerability scanning.",
+                    language="binary"
+                ))
+
+            # Inspect common packers / debug strings
+            packer_signatures = [
+                (b"UPX0", "UPX packer section detected"),
+                (b"UPX1", "UPX packer section detected"),
+                (b".aspack", "Aspack packer signature detected"),
+                (b".themida", "Themida protector signature detected"),
+            ]
+            for sig, desc in packer_signatures:
+                if sig in data:
+                    findings.append(Finding(
+                        file_path=str(file_path),
+                        rule_id="BIN_PACKER_DETECTED",
+                        severity=Severity.MEDIUM,
+                        description=desc,
+                        suggested_fix="Use specific unpacker tool.",
+                        language="binary"
+                    ))
+
+            # Suspicious Windows API imports / strings
+            suspicious_apis = [
+                (b"VirtualProtect", "Dynamic memory permission change (VirtualProtect) - commonly used for code injection/shellcode execution"),
+                (b"CreateRemoteThread", "Process injection capability (CreateRemoteThread) found"),
+                (b"WriteProcessMemory", "Memory modification capability (WriteProcessMemory) found"),
+                (b"URLDownloadToFile", "Binary contains direct external download capability"),
+            ]
+            for api, desc in suspicious_apis:
+                if api in data:
+                    findings.append(Finding(
+                        file_path=str(file_path),
+                        rule_id="BIN_SUSPICIOUS_API",
+                        severity=Severity.LOW,
+                        description=desc,
+                        suggested_fix="Inspect cross-references in a disassembler (Ghidra / IDA Pro).",
+                        language="binary"
+                    ))
+
+        except Exception as e:
+            findings.append(Finding(
+                file_path=str(file_path),
+                rule_id="BIN_READ_ERR",
+                severity=Severity.INFO,
+                description=f"Error reading binary: {e}",
+                language="binary"
+            ))
+
+        return findings
+
+    def _calculate_entropy(self, data: bytes) -> float:
+        if not data:
+            return 0.0
+        entropy = 0.0
+        data_len = len(data)
+        freq: Dict[int, int] = {}
+        for b in data:
+            freq[b] = freq.get(b, 0) + 1
+        for count in freq.values():
+            p = count / data_len
+            entropy -= p * math.log2(p)
+        return entropy
+