cogniumhq/cognium

# cognium [](https://www.npmjs.com/package/cognium) [](https://github.com/cogniumhq/cognium/blob/main/LICENSE) [](https://github.com/cogniumhq/cognium#benchmark-results) [](https://github.com/marketplace/actions/cognium-security-scan)   通过污点追踪检测安全漏洞的语义静态分析引擎。 ## 安装 ### npm (推荐) ``` npm install -g cognium ``` ### 独立二进制文件 从 [GitHub Releases](https://github.com/cogniumhq/cognium/releases) 下载。 **注意：** 使用独立二进制文件时，请将 `wasm/` 目录放在与二进制文件相同的位置。 ## 快速开始 ``` # 扫描单个文件 cognium scan src/app.java # 扫描目录 cognium scan ./src # 使用特定语言扫描 cognium scan api.py --language python # 输出为 JSON cognium scan ./src --format json # 仅显示严重漏洞 cognium scan ./src --severity critical # 仅显示安全发现（跳过质量/可靠性检查） cognium scan ./src --category security # 排除特定 CWE（例如弱加密噪音） cognium scan ./src --exclude-cwe CWE-327,CWE-330 # 排除测试文件 cognium scan ./src --exclude-tests # 软件质量指标 cognium metrics ./src cognium metrics ./src --category complexity,coupling --format json ``` ## 命令 ### `cognium scan ` 扫描文件或目录以查找安全漏洞。 ``` cognium scan [options] Options: -l, --language Force language (java|javascript|typescript|python|rust|bash|html) -f, --format Output format (text|json|sarif) [default: text] --threads Parallel analysis threads [default: 4] --severity Filter by severity: - Single level: minimum severity (e.g., "high" shows high+critical) - Multiple levels: exact match (e.g., "critical,high" shows only those) - Valid levels: low, medium, high, critical --category Filter by ISO 25010 category (comma-separated): security, reliability, performance, maintainability, architecture --exclude-cwe Exclude specific CWEs (comma-separated, e.g. CWE-330,CWE-327) --exclude-tests Exclude test files and directories -o, --output Write results to file -q, --quiet Suppress progress output -v, --verbose Show detailed output ``` **示例：** ``` # 扫描整个项目 cognium scan ./src # 仅显示严重和高危问题 cognium scan ./src --severity critical,high # 排除测试文件并仅显示严重问题 cognium scan ./src --exclude-tests --severity critical # 仅显示安全发现（跳过质量/可靠性检查） cognium scan ./src --category security # 仅显示可靠性和性能发现 cognium scan ./src --category reliability,performance # 排除 weak-crypto 和 weak-random 发现 cognium scan ./src --exclude-cwe CWE-327,CWE-330 # 为 CI/CD 生成 SARIF 报告 cognium scan ./src --format sarif --output results.sarif # 使用详细输出进行扫描 cognium scan ./src -v # 安静模式（无进度，仅显示结果） cognium scan ./src -q ``` ### `cognium init` 在您的项目中初始化一个配置文件。 ``` cognium init ``` 创建一个带有可自定义规则的 `cognium.config.json`。 ### `cognium metrics ` 报告文件或目录的软件质量指标。 ``` cognium metrics [options] Options: -l, --language Analyze only files for the given language -f, --format Output format (text|json) [default: text] --category Filter metric categories (comma-separated): complexity, size, coupling, inheritance, cohesion, documentation, duplication --exclude-tests Skip test files and directories -o, --output Write results to file -q, --quiet Suppress per-file progress output ``` **示例：** ``` # 显示目录的所有指标 cognium metrics ./src # 仅显示复杂度和耦合度指标 cognium metrics ./src --category complexity,coupling # 用于工具集成的 JSON 输出 cognium metrics ./src --format json --output metrics.json # 仅 Java 文件，跳过测试 cognium metrics ./src --language java --exclude-tests ``` **示例输出：** ``` src/UserController.java Complexity cyclomatic_complexity : 8.2 WMC : 41 halstead_volume : 3820.4 Size LOC : 182 NLOC : 156 function_count : 9 Coupling CBO : 6 RFC : 22 Composite Scores maintainability_index : 68.4 / 100 code_quality_index : 71.2 / 100 bug_hotspot_score : 32.1 / 100 refactoring_roi : 45.0 / 100 ``` 可用指标：`cyclomatic_complexity`、`WMC`、`halstead_volume`、`halstead_difficulty`、`halstead_effort`、`halstead_bugs`、`LOC`、`NLOC`、`comment_density`、`function_count`、`CBO`、`RFC`、`DIT`、`NOC`、`LCOM`、`doc_coverage`、`maintainability_index`、`code_quality_index`、`bug_hotspot_score`、`refactoring_roi`。 ### `cognium version` 显示版本信息。 ``` cognium version ``` ## 输出格式 Cognium 会为发现的每个漏洞提供有用且可操作的输出： ``` /path/to/VulnerableApp.java [!!!] sql_injection (Critical) [CWE-89] Line 45: sql_injection vulnerability: tainted data flows from line 42 to line 45 User input is used in SQL query without sanitization → Fix: Use PreparedStatement with parameterized queries instead of string concatenation [!!] xss (High) [CWE-79] Line 78: xss vulnerability: tainted data flows from line 76 to line 78 User input is rendered in HTML without proper encoding → Fix: Use HTML encoding/escaping functions before rendering user input in web pages Found 2 vulnerability(ies) in 1 file(s) ``` **整洁代码 = 静默输出：** 当未发现漏洞时，cognium 保持安静（Unix 哲学：没有消息就是好消息）。 使用 `-v` 标志可查看所有已扫描的文件，包括干净的文件。 ## 已检测的漏洞 | 类型 | CWE | 严重程度 | 描述 | |------|-----|----------|-------------| | SQL 注入 | CWE-89 | 严重 (Critical) | SQL 查询中的用户输入 | | 命令注入 | CWE-78 | 严重 (Critical) | 系统命令中的用户输入 | | 反序列化 | CWE-502 | 严重 (Critical) | 不受信任的反序列化 | | XXE | CWE-611 | 严重 (Critical) | XML 外部实体注入 | | 跨站脚本攻击 (XSS) | CWE-79 | 高危 | HTML 输出中的用户输入 | | 路径穿越 | CWE-22 | 高危 | 文件路径中的用户输入 | | SSRF | CWE-918 | 高危 | 服务器端请求伪造 | | LDAP 注入 | CWE-90 | 高危 | LDAP 查询中的用户输入 | | XPath 注入 | CWE-643 | 高危 | XPath 查询中的用户输入 | | NoSQL 注入 | CWE-943 | 高危 | NoSQL 查询中的用户输入 | | 代码注入 | CWE-94 | 严重 (Critical) | 动态代码执行 | | 开放重定向 | CWE-601 | 中危 | 用户控制重定向目标 | | 日志注入 | CWE-117 | 中危 | 日志中的用户输入 | | 信任边界 | CWE-501 | 中危 | 数据跨越信任边界 | | 外部污点逃逸 | CWE-20 | 中危 | 外部输入到达敏感汇聚点 | | 弱随机数 | CWE-330 | 低危 | 弱随机数生成器 | | 弱哈希 | CWE-327 | 低危 | 弱哈希算法 | | 弱加密 | CWE-327 | 低危 | 弱加密算法 | | 不安全 Cookie | CWE-614 | 低危 | 没有安全标志的 Cookie | ## 代码质量分析 除了安全漏洞之外，`cognium scan` 还会运行 17 个代码质量检查通道，并在五个 ISO 25010 类别中报告结果： | 类别 | 规则 ID | 示例问题 | |----------|----------|----------------| | **可靠性** | `null-deref`、`resource-leak`、`unchecked-return`、`dead-code`、`variable-shadowing`、`leaked-global`、`unused-variable`、`infinite-loop`、`double-close`、`use-after-close`、`unhandled-exception`、`broad-catch`、`swallowed-exception`、`missing-guard-dom`、`cleanup-verify` | 空指针解引用、未关闭的流、被吞噬的异常 | | **性能** | `n-plus-one`、`redundant-loop-computation`、`unbounded-collection`、`serial-await`、`react-inline-jsx` | N+1 数据库查询、循环内不必要的工作 | | **可维护性** | `missing-public-doc`、`todo-in-prod`、`stale-doc-ref` | 缺少 Javadoc/JSDoc、生产代码中的 TODO 注释 | | **架构** | `circular-dependency`、`orphan-module`、`dependency-fan-out`、`deep-inheritance`、`missing-override`、`unused-interface-method` | 循环导入、过深的类层次结构 | 质量发现与安全发现一起以文本形式输出，并附带其类别标签： ``` src/UserService.java [!!] sql_injection (Critical) [CWE-89] ... [!] null-deref [reliability] (High) [CWE-476] Line 34: Return value of findById() is dereferenced without a null check → Fix: Check for null before dereferencing or use Optional [i] missing-public-doc [maintainability] (Low) Line 12: Public method processRequest() has no Javadoc Found 1 security finding(s) in 1 file(s) Also found 2 code quality finding(s) in 1 file(s) ``` **退出代码：** CLI 仅在出现**安全**发现时才退出并返回代码 `1`（因此 CI 流水线会因漏洞而被拦截，但不会被文档或样式发现阻止）。仅包含质量问题的扫描将返回代码 `0`。 仅筛选安全发现：`cognium scan ./src --category security` ## 支持的语言 | 语言 | 扩展名 | 框架 | |----------|------------|------------| | Java | `.java` | Spring, JAX-RS, Servlet | | JavaScript | `.js`, `.mjs` | Express, Fastify, Node.js | | TypeScript | `.ts`, `.tsx` | Express, Fastify, Node.js | | Python | `.py` | Flask, Django, FastAPI | | Rust | `.rs` | Actix-web, Rocket, Axum | | Bash | `.sh`, `.bash` | Shell 脚本 | | HTML | `.html`, `.htm` | Web 提取预处理器 | ## 配置 在您的项目根目录中创建 `cognium.config.json`： ``` { "include": ["src/**/*.java", "src/**/*.ts"], "exclude": ["**/test/**", "**/node_modules/**"], "severity": "medium", "rules": { "sql-injection": "error", "xss": "error", "command-injection": "error", "path-traversal": "warn" } } ``` ## 严重程度筛选 Cognium 支持灵活的严重程度筛选，让您能够专注于重要的问题： ### 最低严重程度 (单一值) 显示达到或超过指定级别的漏洞： ``` # 仅显示严重 cognium scan ./src --severity critical # 显示高和严重 cognium scan ./src --severity high # 显示中、高和严重 cognium scan ./src --severity medium ``` ### 精确严重程度匹配 (逗号分隔) 仅显示指定的严重程度级别： ``` # 仅显示严重和高 cognium scan ./src --severity critical,high # 仅显示中 cognium scan ./src --severity medium # 显示低和中 cognium scan ./src --severity low,medium ``` ## CI/CD 集成 ### GitHub Actions ``` name: Security Scan on: [push, pull_request] jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install cognium run: npm install -g cognium - name: Run security scan run: cognium scan ./src --format sarif --output results.sarif --severity high - name: Upload SARIF uses: github/codeql-action/upload-sarif@v3 with: sarif_file: results.sarif ``` ### GitLab CI ``` security-scan: image: node:20 script: - npm install -g cognium - cognium scan ./src --format json --output gl-sast-report.json --severity high artifacts: reports: sast: gl-sast-report.json ``` ### Pre-commit Hook 防止带有严重漏洞的代码被提交： ``` #!/bin/sh # .git/hooks/pre-commit if ! cognium scan . --severity critical --quiet; then echo "❌ Commit blocked: Critical security vulnerabilities found" exit 1 fi ``` ## 退出代码 | 代码 | 含义 | |------|---------| | 0 | 无安全发现（仅包含质量问题的发现不会触发退出代码 1） | | 1 | 发现一个或多个安全漏洞 | | 2 | 分析期间发生错误 | 在 CI/CD 中使用退出代码，可以在检测到安全漏洞时中断构建： ``` # 在任何安全发现上中断构建 cognium scan ./src || exit 1 # 仅在严重/高危安全发现上中断构建 cognium scan ./src --severity high || exit 1 # 仅在严重安全发现上中断构建 cognium scan ./src --severity critical || exit 1 # 从不因仅质量问题而中断构建（对于 docs/style 发现始终以退出代码 0 退出） cognium scan ./src --category reliability,performance,maintainability,architecture; echo "Quality scan done (exit $?)" ``` ## 性能 Cognium 专为速度而构建： - **并行分析**：并发处理多个文件（可通过 `--threads` 配置） - **零依赖**：只有一个运行时依赖 (`circle-ir`) - **原生性能**：由 tree-sitter WASM 解析器驱动 - **精简二进制文件**：约 58MB 的独立二进制文件包含所有依赖项 ## 架构 - **CLI**：带有零依赖工具的轻量级包装器 - **核心引擎**：[circle-ir](https://github.com/cogniumhq/circle-ir) - 高性能 SAST 库 - **依赖**：仅有 1 个运行时依赖 ## LLM 增强 (可选) 核心静态分析引擎完全确定性地运行，无需任何 LLM。您可以选择启用基于 LLM 的发现模式以增强检测能力： - **发现模式**：LLM 从头开始阅读源代码，以定位易受攻击的方法 - **验证模式**：确认静态发现是否确实可被利用 - **语义提取**：提取设计意图以进行自动化差距分析 有关 LLM 集成和基准测试改进的详细信息（使用 Claude Opus 在 CWE-Bench 上从 42.5% 提升至 78.3%），请访问 [cognium.net](https://cognium.net)。 ## 基准测试结果 **以下所有分数均来自静态分析引擎** —— 完全确定性，无需 LLM： | 基准测试 | 分数 | 详情 | |-----------|-------|---------| | OWASP Benchmark | +100% | TPR 100%, FPR 0% (1415 个测试用例) | | Juliet Test Suite | +100% | 156/156 个测试用例，9 个 CWE | | SecuriBench Micro | 97.7% TPR | 105/108 个漏洞被检测到，6.7% FPR | | CWE-Bench-Java | 42.5% | 51/120 个真实世界的 CVE | ### 复现基准测试 基准测试分数是可验证且可复现的： ``` # 安装 cognium npm install -g cognium # 克隆基准测试仓库 git clone https://github.com/OWASP-Benchmark/BenchmarkJava git clone https://github.com/juliet-test-suite/juliet-test-suite-for-java git clone https://github.com/CWE-Bench/cwe-bench-java # 运行扫描 cognium scan BenchmarkJava/src --format json -o owasp-results.json cognium scan juliet-test-suite-for-java --format json -o juliet-results.json cognium scan cwe-bench-java --format json -o cwe-bench-results.json ``` 有关详细的基准测试方法以及与其他工具的比较，请参阅 [cognium.dev](https://cognium.dev)。 ## 链接 - [GitHub](https://github.com/cogniumhq/cognium) - [circle-ir (核心引擎)](https://github.com/cogniumhq/circle-ir) - [网站](https://cognium.dev) ## 许可证 MIT

标签：AI工具, DevSecOps, GitHub Action, IPv6支持, MITM代理, npm, Python, SAST, TLS抓取, Wasm, 上游代理, 云安全监控, 代码安全, 安全检测引擎, 无后门, 暗色界面, 源码审计, 漏洞枚举, 盲注攻击, 网络安全, 自动化攻击, 质量评估, 软件安全, 错误基检测, 隐私保护, 静态代码分析, 静态分析