jarvis-ai-assistant 0.3.30__py3-none-any.whl → 0.7.0__py3-none-any.whl

jarvis/jarvis_sec/cli.py

@@ -0,0 +1,116 @@
+# -*- coding: utf-8 -*-
+"""
+Jarvis 安全演进套件 —— 命令行入口（Typer 版本）
+
+用法示例：
+- Agent模式（单Agent，逐条子任务分析）
+  python -m jarvis.jarvis_sec.cli agent --path ./target_project
+
+可选参数：
+
+- --output: 最终Markdown报告输出路径（默认 ./report.md）
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+from jarvis.jarvis_utils.utils import init_env
+# removed: set_config import（避免全局覆盖模型组配置）
+from jarvis.jarvis_sec.workflow import run_with_agent, direct_scan, format_markdown_report
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="Jarvis 安全演进套件（单Agent逐条子任务分析）",
+)
+
+
+
+
+@app.command("agent", help="Agent模式（单Agent逐条子任务分析）")
+def agent(
+    path: str = typer.Option(..., "--path", "-p", help="待分析的根目录"),
+
+    llm_group: Optional[str] = typer.Option(
+        None, "--llm-group", "-g", help="使用的模型组（仅对本次运行生效，不修改全局配置）"
+    ),
+    output: Optional[str] = typer.Option(
+        "report.md", "--output", "-o", help="最终Markdown报告输出路径（默认 ./report.md）"
+    ),
+
+    cluster_limit: int = typer.Option(
+        50, "--cluster-limit", "-c", help="聚类每批最多处理的告警数（按文件分批聚类，默认50）"
+    ),
+) -> None:
+    # 初始化环境，确保平台/模型等全局配置就绪（避免 NoneType 平台）
+    try:
+        init_env("欢迎使用 Jarvis 安全套件！", None)
+    except Exception:
+        # 环境初始化失败不应阻塞CLI基础功能，继续后续流程
+        pass
+
+    # 若指定了模型组：仅对本次运行生效，透传给 Agent；不修改全局配置（无需 set_config）
+
+
+    text: Optional[str] = None
+    try:
+        text = run_with_agent(
+            path,
+            llm_group=llm_group,
+            cluster_limit=cluster_limit,
+        )
+    except Exception as e:
+        try:
+            typer.secho(f"[jarvis_sec] Agent 分析过程出错，将回退到直扫基线（fast）：{e}", fg=typer.colors.YELLOW, err=True)
+        except Exception:
+            pass
+        text = None
+
+    if not text or not str(text).strip():
+        try:
+            typer.secho("[jarvis_sec] Agent 无输出，回退到直扫基线（fast）。", fg=typer.colors.YELLOW, err=True)
+        except Exception:
+            pass
+        result = direct_scan(path)
+        text = format_markdown_report(result)
+
+    if output:
+        try:
+            md_text = text or ""
+            try:
+                lines = (text or "").splitlines()
+                idx = -1
+                for i, ln in enumerate(lines):
+                    if ln.strip().startswith("# Jarvis 安全问题分析报告"):
+                        idx = i
+                        break
+                if idx >= 0:
+                    md_text = "\n".join(lines[idx:])
+            except Exception:
+                md_text = text or ""
+            p = Path(output)
+            p.parent.mkdir(parents=True, exist_ok=True)
+            p.write_text(md_text, encoding="utf-8")
+            try:
+                typer.secho(f"[jarvis_sec] Markdown 报告已写入: {p}", fg=typer.colors.GREEN)
+            except Exception:
+                pass
+        except Exception as e:
+            try:
+                typer.secho(f"[jarvis_sec] 写入Markdown报告失败: {e}", fg=typer.colors.RED, err=True)
+            except Exception:
+                pass
+    typer.echo(text)
+
+
+def main() -> int:
+    app()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

jarvis/jarvis_sec/report.py

@@ -0,0 +1,257 @@
+# -*- coding: utf-8 -*-
+"""
+安全分析套件 —— 报告聚合与评分模块
+
+目标：
+- 将启发式检查器输出的结构化问题列表进行聚合与评分，生成统一的 JSON 与 Markdown 报告。
+- 与 workflow.direct_scan / 多Agent Aggregator 保持输出结构一致，便于评测解析与专家审阅。
+
+输出结构（JSON示例）：
+{
+  "summary": {
+    "total": 0,
+    "by_language": {"c/cpp": 0, "rust": 0},
+    "by_category": {
+      "buffer_overflow": 0, "unsafe_api": 0, "memory_mgmt": 0, "error_handling": 0,
+      "unsafe_usage": 0, "concurrency": 0, "ffi": 0
+    },
+    "top_risk_files": ["path1", "path2"]
+  },
+  "issues": [
+    {
+      "id": "C001",
+      "language": "c/cpp",
+      "category": "unsafe_api",
+      "pattern": "strcpy",
+      "file": "src/foo.c",
+      "line": 123,
+      "evidence": "strcpy(dst, src);",
+      "preconditions": "N/A",
+      "trigger_path": "函数 foobar 调用 strcpy 时，其输入 src 来自于未经校验的网络数据包",
+      "consequences": "可能导致缓冲区溢出",
+      "suggestions": "使用 strncpy_s 或其他安全函数替代",
+      "confidence": 0.85,
+      "severity": "high | medium | low",
+      "score": 2.55
+    }
+  ]
+}
+
+提供的函数：
+- aggregate_issues(issues: List[Union[Issue, Dict]], scanned_root: Optional[str] = None, scanned_files: Optional[int] = None) -> Dict
+- format_markdown_report(report_json: Dict) -> str
+- build_json_and_markdown(issues: List[Union[Issue, Dict]], scanned_root: Optional[str] = None, scanned_files: Optional[int] = None) -> str
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Dict, List, Optional, Union
+
+# 依赖 Issue 结构，但本模块不直接导入 dataclass，接受 dict/Issue 两种形态
+try:
+    from jarvis.jarvis_sec.types import Issue  # 类型提示用，避免循环依赖
+except Exception:
+    Issue = dict  # type: ignore
+
+
+# ---------------------------
+# 内部工具
+# ---------------------------
+
+_CATEGORY_ORDER = [
+    "unsafe_api",
+    "buffer_overflow",
+    "memory_mgmt",
+    "error_handling",
+    "unsafe_usage",
+    "concurrency",
+    "ffi",
+]
+
+_SEVERITY_WEIGHT = {
+    "high": 3.0,
+    "medium": 2.0,
+    "low": 1.0,
+}
+
+def _as_dict(item: Union[Issue, Dict]) -> Dict:
+    """
+    将 Issue/dataclass 或 dict 统一为 dict。
+    """
+    if isinstance(item, dict):
+        return item
+    # dataclass: 尝试属性访问
+    d: Dict = {}
+    for k in (
+        "language",
+        "category",
+        "pattern",
+        "file",
+        "line",
+        "evidence",
+        "preconditions",
+        "trigger_path",
+        "consequences",
+        "suggestions",
+        "confidence",
+        "severity",
+    ):
+        v = getattr(item, k, None)
+        if v is not None:
+            d[k] = v
+    return d
+
+
+def _normalize_issue(i: Dict) -> Dict:
+    """
+    归一化字段并补充缺省值。
+    """
+    j = {
+        "language": i.get("language", "c/cpp" if str(i.get("file", "")).endswith((".c", ".cpp", ".h", ".hpp")) else "rust"),
+        "category": i.get("category", "error_handling"),
+        "pattern": i.get("pattern", ""),
+        "file": i.get("file", ""),
+        "line": int(i.get("line", 0) or 0),
+        "evidence": i.get("evidence", ""),
+        "preconditions": i.get("preconditions", ""),
+        "trigger_path": i.get("trigger_path", ""),
+        "consequences": i.get("consequences", ""),
+        "suggestions": i.get("suggestions", ""),
+        "confidence": float(i.get("confidence", 0.6)),
+        "severity": i.get("severity", "medium"),
+    }
+    # 计算稳定ID（基于文件/行/类别/模式哈希）
+    base = f"{j['file']}:{j['line']}:{j['category']}:{j['pattern']}"
+    j["id"] = _make_issue_id(base, j["language"])
+    # 评分：confidence * severity_weight
+    j["score"] = round(j["confidence"] * _SEVERITY_WEIGHT.get(j["severity"], 1.0), 2)
+    return j
+
+
+def _make_issue_id(base: str, lang: str) -> str:
+    h = hashlib.sha1(base.encode("utf-8")).hexdigest()[:6]
+    prefix = "C" if lang.startswith("c") else "R"
+    return f"{prefix}{h.upper()}"
+
+
+# ---------------------------
+# 聚合与评分
+# ---------------------------
+
+def aggregate_issues(
+    issues: List[Union[Issue, Dict]],
+    scanned_root: Optional[str] = None,
+    scanned_files: Optional[int] = None,
+) -> Dict:
+    """
+    聚合问题列表并生成 JSON 报告。
+    """
+    items = [_normalize_issue(_as_dict(it)) for it in issues]
+
+    summary: Dict = {
+        "total": len(items),
+        "by_language": {"c/cpp": 0, "rust": 0},
+        "by_category": {k: 0 for k in _CATEGORY_ORDER},
+        "top_risk_files": [],
+    }
+    if scanned_root is not None:
+        summary["scanned_root"] = scanned_root
+    if scanned_files is not None:
+        summary["scanned_files"] = scanned_files
+
+    file_score: Dict[str, float] = {}
+    for it in items:
+        lang = it["language"]
+        summary["by_language"][lang] = summary["by_language"].get(lang, 0) + 1
+        cat = it["category"]
+        summary["by_category"][cat] = summary["by_category"].get(cat, 0) + 1
+        file_score[it["file"]] = file_score.get(it["file"], 0.0) + it["score"]
+
+    # Top 风险文件按累计分排序，更稳定、可解释
+    summary["top_risk_files"] = [
+        f for f, _ in sorted(file_score.items(), key=lambda x: x[1], reverse=True)[:10]
+    ]
+
+    report = {
+        "summary": summary,
+        "issues": items,
+    }
+    return report
+
+
+# ---------------------------
+# Markdown 渲染
+# ---------------------------
+
+def format_markdown_report(report_json: Dict) -> str:
+    """
+    将聚合后的 JSON 报告渲染为 Markdown。
+    """
+    s = report_json.get("summary", {})
+    issues: List[Dict] = report_json.get("issues", [])
+    lines: List[str] = []
+
+    lines.append("# 安全问题分析报告（聚合）")
+    lines.append("")
+    if "scanned_root" in s:
+        lines.append(f"- 扫描根目录: {s.get('scanned_root')}")
+    if "scanned_files" in s:
+        lines.append(f"- 扫描文件数: {s.get('scanned_files')}")
+    lines.append(f"- 检出问题总数: {s.get('total', 0)}")
+    lines.append("")
+
+    # 概览
+    lines.append("## 统计概览")
+    by_lang = s.get("by_language", {})
+    lines.append(f"- 按语言: c/cpp={by_lang.get('c/cpp', 0)}, rust={by_lang.get('rust', 0)}")
+    lines.append("- 按类别：")
+    by_cat = s.get("by_category", {})
+    for k in _CATEGORY_ORDER:
+        v = by_cat.get(k, 0)
+        lines.append(f"  - {k}: {v}")
+    if s.get("top_risk_files"):
+        lines.append("- Top 风险文件：")
+        for f in s["top_risk_files"]:
+            lines.append(f"  - {f}")
+    lines.append("")
+
+    # 详细问题
+    lines.append("## 详细问题")
+    for i, it in enumerate(issues, start=1):
+        lines.append(f"### [{i}] {it.get('file')}:{it.get('line')} ({it.get('language')}, {it.get('category')})")
+        lines.append(f"- 模式: {it.get('pattern')}")
+        lines.append(f"- 证据: `{it.get('evidence')}`")
+        lines.append(f"- 前置条件: {it.get('preconditions')}")
+        lines.append(f"- 触发路径: {it.get('trigger_path')}")
+        lines.append(f"- 后果: {it.get('consequences')}")
+        lines.append(f"- 建议: {it.get('suggestions')}")
+        lines.append(f"- 置信度: {it.get('confidence')}, 严重性: {it.get('severity')}, 评分: {it.get('score')}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def build_json_and_markdown(
+    issues: List[Union[Issue, Dict]],
+    scanned_root: Optional[str] = None,
+    scanned_files: Optional[int] = None,
+    meta: Optional[List[Dict]] = None,
+) -> str:
+    """
+    一次性生成报告文本（仅 Markdown）。
+    """
+    report = aggregate_issues(issues, scanned_root=scanned_root, scanned_files=scanned_files)
+    if meta is not None:
+        try:
+            report["meta"] = meta  # 注入可选审计信息（仅用于JSON时保留，为兼容未来需要）
+        except Exception:
+            pass
+    return format_markdown_report(report)
+
+
+__all__ = [
+    "aggregate_issues",
+    "format_markdown_report",
+    "build_json_and_markdown",
+]

jarvis/jarvis_sec/status.py

@@ -0,0 +1,264 @@
+# -*- coding: utf-8 -*-
+"""
+进度状态管理模块
+
+提供结构化的进度状态文件，准确反映当前所处的阶段和进度。
+状态文件格式：JSON，包含当前阶段、进度百分比、已完成/总数等信息。
+"""
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Optional, Any
+
+
+class StatusManager:
+    """进度状态管理器"""
+    
+    def __init__(self, entry_path: str):
+        """
+        初始化状态管理器
+        
+        Args:
+            entry_path: 待分析的根目录路径（可以是项目根目录或 .jarvis/sec 目录）
+        """
+        self.entry_path = Path(entry_path)
+        # 检查 entry_path 是否已经是 .jarvis/sec 目录
+        if self.entry_path.name == "sec" and self.entry_path.parent.name == ".jarvis":
+            sec_dir = self.entry_path
+        else:
+            sec_dir = self.entry_path / ".jarvis" / "sec"
+        self.status_path = sec_dir / "status.json"
+        self._ensure_dir()
+    
+    def _ensure_dir(self):
+        """确保状态文件目录存在"""
+        self.status_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    def _read_status(self) -> Dict[str, Any]:
+        """读取当前状态"""
+        if not self.status_path.exists():
+            return {}
+        try:
+            with self.status_path.open("r", encoding="utf-8") as f:
+                return json.load(f)
+        except Exception:
+            return {}
+    
+    def _write_status(self, status: Dict[str, Any]):
+        """写入状态文件"""
+        try:
+            status["last_updated"] = datetime.utcnow().isoformat() + "Z"
+            with self.status_path.open("w", encoding="utf-8") as f:
+                json.dump(status, f, ensure_ascii=False, indent=2)
+        except Exception:
+            # 状态文件写入失败不影响主流程
+            pass
+    
+    def update_stage(
+        self,
+        stage: str,
+        progress: Optional[float] = None,
+        current: Optional[int] = None,
+        total: Optional[int] = None,
+        message: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        """
+        更新当前阶段和进度
+        
+        Args:
+            stage: 阶段名称（pre_scan, clustering, verification, completed, error）
+            progress: 进度百分比（0-100），如果为None则根据current/total计算
+            current: 当前已完成数量
+            total: 总数量
+            message: 状态消息
+            details: 额外的详细信息
+        """
+        status = self._read_status()
+        
+        # 计算进度百分比
+        if progress is None and current is not None and total is not None and total > 0:
+            progress = (current / total) * 100
+        
+        # 更新状态
+        status["stage"] = stage
+        if progress is not None:
+            status["progress"] = round(progress, 2)
+        if current is not None:
+            status["current"] = current
+        if total is not None:
+            status["total"] = total
+        if message:
+            status["message"] = message
+        if details:
+            status["details"] = details
+        
+        # 设置阶段开始时间（如果是新阶段）
+        if "stage_history" not in status:
+            status["stage_history"] = []
+        
+        # 检查是否是阶段切换
+        last_stage = status.get("stage")
+        if last_stage != stage:
+            status["stage_history"].append({
+                "stage": stage,
+                "started_at": datetime.utcnow().isoformat() + "Z"
+            })
+        
+        self._write_status(status)
+    
+    def update_pre_scan(
+        self,
+        current_files: Optional[int] = None,
+        total_files: Optional[int] = None,
+        issues_found: Optional[int] = None,
+        message: Optional[str] = None,
+    ):
+        """更新启发式扫描阶段状态"""
+        details = {}
+        if issues_found is not None:
+            details["issues_found"] = issues_found
+        
+        progress = None
+        if current_files is not None and total_files is not None and total_files > 0:
+            progress = (current_files / total_files) * 100
+        
+        self.update_stage(
+            stage="pre_scan",
+            progress=progress,
+            current=current_files,
+            total=total_files,
+            message=message or "正在进行启发式扫描...",
+            details=details,
+        )
+    
+    def update_clustering(
+        self,
+        current_file: Optional[int] = None,
+        total_files: Optional[int] = None,
+        current_batch: Optional[int] = None,
+        total_batches: Optional[int] = None,
+        file_name: Optional[str] = None,
+        message: Optional[str] = None,
+    ):
+        """更新聚类阶段状态"""
+        details = {}
+        if file_name:
+            details["current_file"] = file_name
+        if current_batch is not None:
+            details["current_batch"] = current_batch
+        if total_batches is not None:
+            details["total_batches"] = total_batches
+        
+        # 计算总体进度（文件级别）
+        progress = None
+        if current_file is not None and total_files is not None and total_files > 0:
+            progress = (current_file / total_files) * 100
+        
+        self.update_stage(
+            stage="clustering",
+            progress=progress,
+            current=current_file,
+            total=total_files,
+            message=message or "正在进行聚类分析...",
+            details=details,
+        )
+    
+    def update_review(
+        self,
+        current_review: Optional[int] = None,
+        total_reviews: Optional[int] = None,
+        message: Optional[str] = None,
+    ):
+        """更新复核阶段状态"""
+        details = {}
+        
+        # 计算总体进度
+        progress = None
+        if current_review is not None and total_reviews is not None and total_reviews > 0:
+            progress = (current_review / total_reviews) * 100
+        
+        self.update_stage(
+            stage="review",
+            progress=progress,
+            current=current_review,
+            total=total_reviews,
+            message=message or "正在进行无效聚类复核...",
+            details=details,
+        )
+    
+    def update_verification(
+        self,
+        current_batch: Optional[int] = None,
+        total_batches: Optional[int] = None,
+        current_task: Optional[int] = None,
+        total_tasks: Optional[int] = None,
+        batch_id: Optional[str] = None,
+        file_name: Optional[str] = None,
+        issues_found: Optional[int] = None,
+        message: Optional[str] = None,
+    ):
+        """更新验证阶段状态"""
+        details = {}
+        if batch_id:
+            details["batch_id"] = batch_id
+        if file_name:
+            details["file"] = file_name
+        if issues_found is not None:
+            details["issues_found"] = issues_found
+        
+        # 计算总体进度（批次级别）
+        progress = None
+        if current_batch is not None and total_batches is not None and total_batches > 0:
+            progress = (current_batch / total_batches) * 100
+        
+        self.update_stage(
+            stage="verification",
+            progress=progress,
+            current=current_batch,
+            total=total_batches,
+            message=message or "正在进行安全验证...",
+            details=details,
+        )
+    
+    def mark_completed(
+        self,
+        total_issues: Optional[int] = None,
+        message: Optional[str] = None,
+    ):
+        """标记分析完成"""
+        details = {}
+        if total_issues is not None:
+            details["total_issues"] = total_issues
+        
+        self.update_stage(
+            stage="completed",
+            progress=100.0,
+            message=message or "安全分析已完成",
+            details=details,
+        )
+    
+    def mark_error(
+        self,
+        error_message: str,
+        error_type: Optional[str] = None,
+    ):
+        """标记错误状态"""
+        details = {"error_message": error_message}
+        if error_type:
+            details["error_type"] = error_type
+        
+        self.update_stage(
+            stage="error",
+            message=f"发生错误: {error_message}",
+            details=details,
+        )
+    
+    def get_status(self) -> Dict[str, Any]:
+        """获取当前状态"""
+        return self._read_status()
+
+
+__all__ = ["StatusManager"]
+

jarvis/jarvis_sec/types.py

@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+"""
+Shared types for jarvis.jarvis_sec to avoid circular imports.
+"""
+from dataclasses import dataclass
+
+@dataclass
+class Issue:
+    language: str
+    category: str
+    pattern: str
+    file: str
+    line: int
+    evidence: str
+    description: str
+    suggestion: str
+    confidence: float
+    severity: str = "medium"
+
+__all__ = ["Issue"]