jarvis-sec 0.1.0__tar.gz

jarvis_sec-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: jarvis-sec
+Version: 0.1.0
+Summary: Jarvis Security Scanner: C/C++/Rust security audit tool with heuristic scan and taint analysis
+Author: skyfireitdiy
+License-Expression: MIT
+Keywords: security,scan,c,cpp,rust,audit,jarvis
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: jarvis-ai-assistant>=7.0.1
+Requires-Dist: typer
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: joern
+
+# jarvis-sec
+
+Jarvis 安全扫描工具：面向 C/C++/Rust 代码仓的安全审计 CLI。
+
+`jarvis-sec`（别名 `jsec`）是 [Jarvis](https://github.com/skyfireitdiy/Jarvis) 生态中的独立安全扫描工具，从主仓库拆分而来。它直接以 `jarvis-ai-assistant` 作为运行时依赖，复用其 `PrettyOutput` / `Agent` / `ToolRegistry` 等基础设施。
+
+## 安装
+
+```bash
+pip install jarvis-sec
+```
+
+> 依赖 `jarvis-ai-assistant>=7.0.1`，安装时会自动带上。
+
+## 使用
+
+```bash
+# 查看帮助
+jarvis-sec --help
+jsec --help
+
+# 配置安全扫描
+jarvis-sec config
+
+# 执行安全扫描（启发式 + 单Agent验证）
+jarvis-sec scan --path ./target_project
+
+# 从 JSON 分析安全问题
+jarvis-sec analyze --input issues.json
+
+# 仅启发式直扫
+jarvis-sec heuristic --path ./target_project
+```
+
+配置文件路径为相对当前工作目录的 `.jarvis/sec/config.json`。
+
+## 能力
+
+- **启发式扫描**：基于正则与规则模板快速定位候选问题（C/C++/Rust）
+- **污点传播分析**：追踪数据从 source 到 sink 的传播路径
+- **调用图分析**：跨函数/跨文件分析
+- **单 Agent 验证**：对候选问题逐条交由 Agent 验证，降低误报
+- **Joern（可选）**：若系统安装了 [Joern](https://joern.io/)，自动启用更精确的代码属性图分析；未安装时自动降级为内置分析器
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -m "not slow"
+ruff check src/
+```
+
+## 编排
+
+`orchestration/jsec_adversarial.yaml` 是对抗式自进化编排配置：`jsec_adversary` 主动搜索漏洞并驱动 `jsec_rule_developer` 改进检测规则。
+
+## License
+
+MIT

jarvis_sec-0.1.0/README.md

@@ -0,0 +1,59 @@
+# jarvis-sec
+
+Jarvis 安全扫描工具：面向 C/C++/Rust 代码仓的安全审计 CLI。
+
+`jarvis-sec`（别名 `jsec`）是 [Jarvis](https://github.com/skyfireitdiy/Jarvis) 生态中的独立安全扫描工具，从主仓库拆分而来。它直接以 `jarvis-ai-assistant` 作为运行时依赖，复用其 `PrettyOutput` / `Agent` / `ToolRegistry` 等基础设施。
+
+## 安装
+
+```bash
+pip install jarvis-sec
+```
+
+> 依赖 `jarvis-ai-assistant>=7.0.1`，安装时会自动带上。
+
+## 使用
+
+```bash
+# 查看帮助
+jarvis-sec --help
+jsec --help
+
+# 配置安全扫描
+jarvis-sec config
+
+# 执行安全扫描（启发式 + 单Agent验证）
+jarvis-sec scan --path ./target_project
+
+# 从 JSON 分析安全问题
+jarvis-sec analyze --input issues.json
+
+# 仅启发式直扫
+jarvis-sec heuristic --path ./target_project
+```
+
+配置文件路径为相对当前工作目录的 `.jarvis/sec/config.json`。
+
+## 能力
+
+- **启发式扫描**：基于正则与规则模板快速定位候选问题（C/C++/Rust）
+- **污点传播分析**：追踪数据从 source 到 sink 的传播路径
+- **调用图分析**：跨函数/跨文件分析
+- **单 Agent 验证**：对候选问题逐条交由 Agent 验证，降低误报
+- **Joern（可选）**：若系统安装了 [Joern](https://joern.io/)，自动启用更精确的代码属性图分析；未安装时自动降级为内置分析器
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -m "not slow"
+ruff check src/
+```
+
+## 编排
+
+`orchestration/jsec_adversarial.yaml` 是对抗式自进化编排配置：`jsec_adversary` 主动搜索漏洞并驱动 `jsec_rule_developer` 改进检测规则。
+
+## License
+
+MIT

jarvis_sec-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "jarvis-sec"
+version = "0.1.0"
+description = "Jarvis Security Scanner: C/C++/Rust security audit tool with heuristic scan and taint analysis"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [
+    { name = "skyfireitdiy" },
+]
+keywords = ["security", "scan", "c", "cpp", "rust", "audit", "jarvis"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+]
+dependencies = [
+    "jarvis-ai-assistant>=7.0.1",
+    "typer",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "ruff",
+]
+joern = []
+
+[project.scripts]
+jarvis-sec = "jarvis.jarvis_sec.cli:main"
+jsec = "jarvis.jarvis_sec.cli:main"
+
+[tool.setuptools]
+packages = ["jarvis.jarvis_sec"]
+package-dir = { "" = "src" }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+# 锁定规则集为经典默认（E4/E7/E9/F），避免新版本 ruff 引入的 UP/BLE 等
+# 规则导致 CI 与本地检查结果不一致（与主仓库 jarvis-ai-assistant 保持一致）。
+select = ["E4", "E7", "E9", "F"]

jarvis_sec-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

jarvis_sec-0.1.0/src/jarvis/jarvis_sec/__init__.py

@@ -0,0 +1,228 @@
+# -*- coding: utf-8 -*-
+"""
+Jarvis 安全分析套件
+
+当前版本概述：
+- 关键路径：直扫（direct_scan）→ 单Agent逐条验证（只读工具：read_code/execute_script）→ 聚合输出（JSON + Markdown）
+- 目标范围：内存管理、缓冲区操作、错误处理等基础安全问题识别
+- 约束：不修改核心框架文件，保持最小侵入；严格只读分析
+
+集成方式：
+- 复用 jarvis.jarvis_agent.Agent 与工具注册系统（jarvis.jarvis_tools.registry.ToolRegistry）
+- 提供入口：
+  - run_security_analysis(entry_path, ...)：直扫 + 单Agent逐条验证 + 聚合
+
+  - workflow.direct_scan(entry_path, ...)：仅启发式直扫
+
+说明：
+- 已移除 MultiAgent 编排与相关提示词；不存在"阶段一"等表述
+- 模块化重构：将功能拆分为多个模块（prompts, parsers, utils, agents, clustering, analysis, verification, review）
+"""
+
+from jarvis.jarvis_utils.exception_utils import save_exception
+from typing import Any, Dict, List, Optional
+
+from jarvis.jarvis_utils.output import PrettyOutput
+
+from jarvis.jarvis_agent import Agent  # noqa: F401
+from jarvis.jarvis_sec.utils import (
+    initialize_analysis_context as _initialize_analysis_context,
+)
+from jarvis.jarvis_sec.utils import (
+    load_or_run_heuristic_scan as _load_or_run_heuristic_scan,
+)
+from jarvis.jarvis_sec.utils import prepare_candidates as _prepare_candidates
+from jarvis.jarvis_sec.utils import (
+    group_candidates_by_file as _group_candidates_by_file,
+)
+from jarvis.jarvis_sec.utils import create_report_writer as _create_report_writer
+from jarvis.jarvis_sec.clustering import (  # type: ignore[attr-defined]
+    process_clustering_phase as _process_clustering_phase,
+)
+from jarvis.jarvis_sec.verification import (
+    process_verification_phase as _process_verification_phase,
+)
+
+from jarvis.jarvis_sec.workflow import direct_scan
+from jarvis.jarvis_sec.workflow import run_with_agent
+
+# 注：当前版本不使用 MultiAgent 编排，已移除默认多智能体配置与创建函数。
+# 请使用 run_security_analysis（单Agent逐条验证）或 workflow.direct_scan + format_markdown_report（直扫基线）。
+# 注意：部分函数已迁移到模块化文件中（prompts.py, parsers.py, utils.py, agents.py, clustering.py, analysis.py, verification.py, review.py），
+# 本文件中保留了这些函数的别名导入，以便向后兼容。
+
+
+def run_security_analysis(
+    entry_path: str,
+    languages: Optional[List[str]] = None,
+    report_file: Optional[str] = None,
+    cluster_limit: int = 50,
+    exclude_dirs: Optional[List[str]] = None,
+    enable_verification: bool = True,
+    force_save_memory: bool = False,
+    output_file: Optional[str] = None,
+) -> str:
+    """
+    运行安全分析工作流（混合模式）。
+
+    改进：
+    - 即使在 agent 模式下，也先进行本地正则/启发式直扫，生成候选问题；
+      然后将候选问题拆分为子任务，交由多Agent进行深入分析与聚合。
+
+    注意：此函数会在发生异常时更新状态文件为 error 状态。
+
+    参数：
+    - entry_path: 待分析的根目录路径
+    - languages: 限定扫描的语言扩展（例如 ["c", "cpp", "h", "hpp", "rs"]），为空则使用默认
+
+    返回：
+    - 最终报告（字符串），由 Aggregator 生成（JSON + Markdown）
+
+    其他：
+    - report_file: 增量报告文件路径（JSONL）。当每个子任务检测到 issues 时，立即将一条记录追加到该文件；
+      若未指定，则默认写入 entry_path/.jarvis/sec/agent_issues.jsonl
+    - cluster_limit: 聚类时每批次最多处理的告警数（默认 50），当单个文件告警过多时按批次进行聚类
+    - exclude_dirs: 要排除的目录列表（可选），默认已包含测试目录（test, tests, __tests__, spec, testsuite, testdata）
+    - enable_verification: 是否启用二次验证（默认 True），关闭后分析Agent确认的问题将直接写入报告
+    - 断点续扫: 默认开启。会基于 .jarvis/sec/candidates.jsonl、clusters.jsonl 和 analysis.jsonl 文件进行状态恢复。
+    """
+
+    langs = languages or ["c", "cpp", "h", "hpp", "rs"]
+
+    # 状态管理器（不再使用 status.json，使用空对象）
+    class DummyStatusManager:
+        def update_pre_scan(self, **kwargs: Any) -> None:
+            pass
+
+        def update_clustering(self, **kwargs: Any) -> None:
+            pass
+
+        def update_review(self, **kwargs: Any) -> None:
+            pass
+
+        def update_verification(self, **kwargs: Any) -> None:
+            pass
+
+        def mark_completed(self, **kwargs: Any) -> None:
+            pass
+
+        def mark_error(self, **kwargs: Any) -> None:
+            pass
+
+    status_mgr = DummyStatusManager()
+
+    # 初始化分析上下文
+    sec_dir, progress_path, _progress_append = _initialize_analysis_context(
+        entry_path, status_mgr
+    )
+
+    # 1) 启发式扫描（支持断点续扫）
+    candidates, summary = _load_or_run_heuristic_scan(
+        entry_path, langs, exclude_dirs, sec_dir, status_mgr, _progress_append
+    )
+
+    # 2) 将候选问题精简为子任务清单，控制上下文长度
+    compact_candidates = _prepare_candidates(candidates)
+
+    # 3) 保存候选到新的 candidates.jsonl 文件（包含gid）
+    from jarvis.jarvis_sec.file_manager import get_candidates_file
+    from jarvis.jarvis_sec.file_manager import save_candidates
+
+    try:
+        save_candidates(sec_dir, compact_candidates)
+        _progress_append(
+            {
+                "event": "candidates_saved",
+                "path": str(get_candidates_file(sec_dir)),
+                "issues_count": len(compact_candidates),
+            }
+        )
+    except Exception as e:
+        save_exception(e, module="jarvis.jarvis_sec.__init__", function="mark_error")
+        pass
+
+    # 记录批次选择信息（可选，用于日志）
+    try:
+        groups = _group_candidates_by_file(compact_candidates)
+        if groups:
+            selected_file, items = max(groups.items(), key=lambda kv: len(kv[1]))
+            try:
+                PrettyOutput.auto_print(
+                    f"[jarvis-sec] 批次选择: 文件={selected_file} 数量={len(items)}"
+                )
+            except Exception as e:
+                save_exception(e, module="jarvis.jarvis_sec.__init__", function="mark_error")
+                pass
+            _progress_append(
+                {
+                    "event": "batch_selection",
+                    "selected_file": selected_file,
+                    "selected_count": len(items),
+                    "total_in_file": len(items),
+                }
+            )
+    except Exception as e:
+        save_exception(e, module="jarvis.jarvis_sec.__init__", function="mark_error")
+        pass
+
+    # 创建报告写入函数
+    _append_report = _create_report_writer(sec_dir, report_file)
+
+    # 3) 处理聚类阶段
+    cluster_batches, invalid_clusters_for_review = _process_clustering_phase(
+        compact_candidates,
+        entry_path,
+        langs,
+        cluster_limit,
+        sec_dir,
+        status_mgr,
+        _progress_append,
+        force_save_memory=force_save_memory,
+    )
+
+    # 4) 处理验证阶段
+    meta_records: List[Dict[str, Any]] = []
+    all_issues = _process_verification_phase(
+        cluster_batches,
+        entry_path,
+        langs,
+        sec_dir,
+        status_mgr,
+        _progress_append,
+        _append_report,
+        enable_verification=enable_verification,
+        force_save_memory=force_save_memory,
+    )
+
+    # 5) 使用统一聚合器生成最终报告（JSON + Markdown）
+    try:
+        from jarvis.jarvis_sec.report import build_json_and_markdown
+
+        result = build_json_and_markdown(
+            all_issues,  # type: ignore
+            scanned_root=summary.get("scanned_root"),
+            scanned_files=summary.get("scanned_files"),
+            meta=meta_records or None,
+            output_file=output_file,
+        )
+        # 标记分析完成
+        status_mgr.mark_completed(
+            total_issues=len(all_issues),
+            message=f"安全分析完成，共发现 {len(all_issues)} 个问题",
+        )
+        return result
+    except Exception as e:
+        # 发生错误时更新状态
+        error_msg = str(e)
+        status_mgr.mark_error(error_message=error_msg, error_type=type(e).__name__)
+        raise
+    finally:
+        # 清理资源
+        pass
+
+
+__all__ = [
+    "run_security_analysis",
+    "direct_scan",
+    "run_with_agent",
+]

jarvis_sec-0.1.0/src/jarvis/jarvis_sec/agents.py

@@ -0,0 +1,141 @@
+# -*- coding: utf-8 -*-
+"""Agent创建和订阅模块"""
+
+from jarvis.jarvis_utils.exception_utils import save_exception
+from typing import Any, Dict
+
+from jarvis.jarvis_agent import Agent
+from jarvis.jarvis_sec.prompts import build_summary_prompt
+from jarvis.jarvis_sec.prompts import get_cluster_summary_prompt
+from jarvis.jarvis_sec.prompts import get_cluster_system_prompt
+from jarvis.jarvis_sec.prompts import get_review_summary_prompt
+from jarvis.jarvis_sec.prompts import get_review_system_prompt
+from jarvis.jarvis_tools.registry import ToolRegistry
+from jarvis.jarvis_utils.tag import ot
+
+
+def subscribe_summary_event(agent: Agent) -> Dict[str, str]:
+    """订阅Agent摘要事件"""
+    summary_container: Dict[str, str] = {"text": ""}
+    try:
+        from jarvis.jarvis_agent.events import AFTER_SUMMARY as _AFTER_SUMMARY
+    except Exception:
+        _AFTER_SUMMARY = None  # type: ignore
+
+    if _AFTER_SUMMARY:
+
+        def _on_after_summary(**kwargs: Any) -> None:
+            try:
+                summary_container["text"] = str(kwargs.get("summary", "") or "")
+            except Exception:
+                summary_container["text"] = ""
+
+        try:
+            agent.event_bus.subscribe(_AFTER_SUMMARY, _on_after_summary)
+        except Exception as e:
+            save_exception(e, module="jarvis.jarvis_sec.agents", function="_on_after_summary")
+            pass
+    return summary_container
+
+
+def create_analysis_agent(task_id: str, force_save_memory: bool = False) -> Agent:
+    """创建分析Agent"""
+    system_prompt = f"""
+# 单Agent安全分析约束
+- 你的核心任务是评估代码的安全问题，目标：针对本候选问题进行证据核实、风险评估与修复建议补充，查找漏洞触发路径，确认在某些条件下会触发；以此来判断是否是漏洞。
+- **必须进行调用路径推导**：
+  - 对于每个候选问题，必须明确推导从可控输入到缺陷代码的完整调用路径。
+  - 调用路径推导必须包括：
+    1. 识别可控输入的来源（例如：用户输入、网络数据、文件读取、命令行参数等）
+    2. 追踪数据流：从输入源开始，逐步追踪数据如何传递到缺陷代码位置
+    3. 识别调用链：明确列出从入口函数到缺陷代码的所有函数调用序列（例如：main() -> parse_input() -> process_data() -> vulnerable_function()）
+    4. 分析每个调用点的数据校验情况：检查每个函数是否对输入进行了校验、边界检查或安全检查
+    5. 确认触发条件：明确说明在什么条件下，未校验或恶意输入能够到达缺陷代码位置
+  - 如果无法推导出完整的调用路径，或者所有调用路径都有充分的保护措施，则应该判定为误报。
+  - 调用路径推导必须在分析过程中明确展示，不能省略或假设。
+- 工具优先：使用 read_code 读取目标文件附近源码（行号前后各 ~50 行），必要时用 execute_script 辅助检索。
+- **调用路径追溯要求**：
+  - 必须向上追溯所有可能的调用者，查看完整的调用路径，以确认风险是否真实存在。
+  - 使用 read_code 和 execute_script 工具查找函数的调用者（例如：使用 grep 搜索函数名，查找所有调用该函数的位置）。
+  - 对于每个调用者，必须检查其是否对输入进行了校验。
+  - 如果发现任何调用路径未做校验，必须明确记录该路径。
+  - 例如：一个函数存在空指针解引用风险，必须检查所有调用者。如果所有调用者均能确保传入的指针非空，则该风险在当前代码库中可能不会实际触发；但如果存在任何调用者未做校验，则风险真实存在。
+- 若多条告警位于同一文件且行号相距不远，可一次性读取共享上下文，对这些相邻告警进行联合分析与判断；但仍需避免无关扩展与大范围遍历。
+- 禁止修改任何文件或执行写操作命令（rm/mv/cp/echo >、sed -i、git、patch、chmod、chown 等）；仅进行只读分析与读取。
+- 每次仅执行一个操作；等待工具结果后再进行下一步。
+- **记忆使用**：
+  - 分析过程中，善用 memory 工具（action=retrieve）检索已有的记忆，特别是与当前分析函数相关的记忆。
+  - 若有需要，用 memory 工具（action=save）保存每个函数的分析要点，以函数名为 tag（例如：函数名、文件名等）。
+  - 记忆内容示例：某函数的指针已判空、某函数已有输入校验、某函数的调用路径分析结果等。
+  - 这样可以避免重复分析，提高效率，并保持分析的一致性。
+- 完成对本批次候选问题的判断后，主输出仅打印结束符 {ot("!!!COMPLETE!!!")}，不要输出其他任何内容。任务总结将在后续交互中给出。
+""".strip()
+
+    agent_kwargs: Dict[str, Any] = dict(
+        system_prompt=system_prompt,
+        name=task_id,
+        auto_complete=True,
+        need_summary=True,
+        summary_prompt=build_summary_prompt(),
+        non_interactive=True,
+        in_multi_agent=False,
+        use_methodology=False,
+        use_analysis=False,
+        output_handler=[ToolRegistry()],
+        force_save_memory=force_save_memory,
+        use_tools=["read_code", "execute_script", "memory"],
+        quick_mode=True,
+    )
+    return Agent(**agent_kwargs)
+
+
+def create_review_agent(
+    current_review_num: int,
+) -> Agent:
+    """创建复核Agent"""
+    review_system_prompt = get_review_system_prompt()
+    review_summary_prompt = get_review_summary_prompt()
+
+    review_task_id = f"JARVIS-SEC-Review-Batch-{current_review_num}"
+    review_agent_kwargs: Dict[str, Any] = dict(
+        system_prompt=review_system_prompt,
+        name=review_task_id,
+        auto_complete=True,
+        need_summary=True,
+        summary_prompt=review_summary_prompt,
+        non_interactive=True,
+        in_multi_agent=False,
+        use_methodology=False,
+        use_analysis=False,
+        output_handler=[ToolRegistry()],
+        use_tools=["read_code", "execute_script", "memory"],
+        quick_mode=True,
+    )
+    return Agent(**review_agent_kwargs)
+
+
+def create_cluster_agent(
+    file: str,
+    chunk_idx: int,
+    force_save_memory: bool = False,
+) -> Agent:
+    """创建聚类Agent"""
+    cluster_system_prompt = get_cluster_system_prompt()
+    cluster_summary_prompt = get_cluster_summary_prompt()
+
+    agent_kwargs_cluster: Dict[str, Any] = dict(
+        system_prompt=cluster_system_prompt,
+        name=f"JARVIS-SEC-Cluster::{file}::batch{chunk_idx}",
+        auto_complete=True,
+        need_summary=True,
+        summary_prompt=cluster_summary_prompt,
+        non_interactive=True,
+        in_multi_agent=False,
+        use_methodology=False,
+        use_analysis=False,
+        output_handler=[ToolRegistry()],
+        force_save_memory=force_save_memory,
+        use_tools=["read_code", "execute_script", "memory"],
+        quick_mode=True,
+    )
+    return Agent(**agent_kwargs_cluster)