Daksh SCRA（源代码审查助手）```

Author:

Debasis Mohanty ([email protected])
Twitter / X: @coffeensecurity
www.coffeeandsecurity.com

## 关于 Daksh SCRA

Daksh SCRA（源代码审查辅助）工具旨在提升源代码审查过程的效率，为代码审查人员提供一种结构清晰、组织有序的方法。

并非不加区分地将所有内容标记为潜在问题，Daksh SCRA 倡导深入分析，鼓励对潜在问题进行探究与确认。这种方法避免了将每一个可能的关注点都匆忙标记为漏洞，从而减少因误报带来的混乱与时间浪费。

## 首次亮相

Daksh SCRA 最初于 Black Hat USA 2022（2022年8月6日至9日）的一场源代码审查培训课程中亮相，面向特定受众低调呈现。其正式公开首秀则是在拉斯维加斯举行的 Black Hat USA 2023 上。

## 特性与功能

### 突出特性

- **识别源代码中的关注区域：** 鼓励重点调查与确认，而非不加区分地将所有内容标记为漏洞。
- **识别文件路径中的关注区域（全球首创）：** 识别文件路径中的模式，以定位需审查的相关部分。
- **软件层级侦察以识别所采用的技术：** 识别项目所用技术，使代码审查人员能够使用合适的规则进行精确扫描。
- **代码审查的科学工作量自动估算（全球首创）：** 提供一种可衡量的方法，用于估算代码审查流程所需的工作量。
- **框架感知扫描：** 当检测到项目框架时，自动应用框架特定规则。
- **污点分析报告：** 按平台生成的 HTML 污点流报告，支持黑客模式与专业模式主题。
- **RDL（规则描述语言）：** 通过 `rdl_ref` 引用的外部规则逻辑，由当前 `core/rdl_engine.py` 管道执行——支持文件感知门控、布尔表达式、项目观察信息以及报告中导出的逻辑元数据。
- **扫描状态/恢复：** 为长时间扫描设置检查点，并在中断后恢复。
- **抑制基线：** 生成并应用已知误报的基线，以在后续报告中将其抑制。
- **Web 界面：** 基于浏览器的扫描启动器，具备实时控制台反馈与任务产物浏览器。

> 持续加强功能中。多个新特性与改进计划在后续版本中推出。

欢迎为更新或添加新规则以及未来开发做出贡献。

如发现任何漏洞，请报告至 [[email protected]](mailto:[email protected])。

详细文档：[https://dakshlabs.com/#docs](https://dakshlabs.com/#docs)

---

## 工具设置

### 前提条件

- Python 3.8+
- 所有列于 `requirements.txt` 中的库

### 1. 下载 Daksh SCRA```bash
git clone https://github.com/coffeeandsecurity/DakshSCRA.git

或者从 https://github.com/coffeeandsecurity/DakshSCRA 下载最新的压缩包并解压。

2. 设置虚拟环境

💡 虚拟环境可以创建在任何目录中——不需要在 DakshSCRA 文件夹内。

选项 A：一键设置（推荐）```bash

python setup_env.py

这个脚本创建虚拟环境，安装所有依赖，并安装Playwright的Chromium浏览器（PDF导出需要）。

#### 选项B：手动设置

**Windows:**```bash
python -m venv daksh-env
.\daksh-env\Scripts\activate

macOS / Linux：```bash python3 -m venv daksh-env source daksh-env/bin/activate

然后安装依赖：```bash
cd path/to/DakshSCRA
pip install -r requirements.txt
playwright install chromium

工具使用

在虚拟环境中使用 python，或在虚拟环境外使用 python3。

命令行选项```

usage: dakshscra.py [-h] [-r RULES] [-f FILE_TYPES] [-v] [-t TARGET_DIR] [-l {R,RF}] [--recon] [--rs] [--estimate] [-rpt FORMATS] [--pdf-from-json] [--json-input-dir PATH] [--pdf-output PATH] [--pdf-multi-dir PATH] [--pdf-single-only] [--skip-analysis] [--loc] [--baseline-file PATH] [--baseline-generate] [--no-baseline] [--review-config PATH] [--resume-scan] [--state-file PATH] [--no-state] [--state]

| 选项 | 描述 |
|---|---|
| `-r RULES` | 平台规则（例如 `php`、`java`、`php,java`）或 `auto` 表示自动检测 |
| `-f FILE_TYPES` | 覆盖扫描的默认文件类型 |
| `-v` | 详细级别（`-v`、`-vv`、`-vvv`） |
| `-t TARGET_DIR` | 目标源代码目录 |
| `-l {R,RF}` | 列出平台规则 + 框架 `[R]` 或包含文件类型 `[RF]` |
| `--recon` | 运行侦察（平台/框架/语言检测） |
| `--rs`, `--recon-strict` | 严格侦察：仅高置信度检测（与 `--recon` 一起使用） |
| `--estimate` | 基于代码库规模估算代码审查工作量 |
| `-rpt`, `--report FORMATS` | 报告格式：`html`、`pdf` 或 `html,pdf`（默认：`html`） |
| `--pdf-from-json` | 从已有 JSON 输出生成 PDF 报告，无需重新扫描 |
| `--json-input-dir PATH` | JSON 报告目录（默认：`./reports/data`） |
| `--pdf-output PATH` | 单个 PDF 输出路径（默认：`./reports/scan/pdf/report.pdf`） |
| `--pdf-multi-dir PATH` | 多文件 PDF 输出目录（默认：`./reports/scan/pdf/multi-file`） |
| `--pdf-single-only` | 仅生成合并的单个 PDF 文件；跳过按平台生成的多文件集 |
| `--skip-analysis` | 本次运行禁用分析器阶段 |
| `--loc` | 统计有效代码行数 |
| `--baseline-file PATH` | 抑制基线文件（JSON） |
| `--baseline-generate` | 根据当前发现生成抑制基线 |
| `--no-baseline` | 本次运行禁用基线抑制 |
| `--review-config PATH` | 发现结果分类文件（JSON）；从报告中抑制之前审查过的误报 |
| `--resume-scan` | 从状态文件恢复之前中断的扫描 |
| `--state-file PATH` | 自定义扫描状态/检查点文件路径 |
| `--no-state` | 本次运行禁用扫描状态检查点 |
| `--state` | 本次运行强制启用扫描状态检查点 |

### 使用示例

> `-f`（文件类型）为可选项。若未指定，DakshSCRA 将使用所选平台的默认文件类型。```bash
# Single platform scan
python dakshscra.py -r php -t /path/to/source

# Multiple platforms
python dakshscra.py -r php,java,cpp -t /path/to/source

# Auto-detect platform and apply matching rules
python dakshscra.py -r auto -t /path/to/source

# Override filetypes
python dakshscra.py -r php -f dotnet -t /path/to/source

# Reconnaissance only (no scanning)
python dakshscra.py --recon -t /path/to/source

# Reconnaissance + scanning
python dakshscra.py --recon -r php -t /path/to/source

# Strict recon (high-confidence detections only)
python dakshscra.py --recon --rs -t /path/to/source

# Effort estimation
python dakshscra.py --estimate -t /path/to/source

# Scan with HTML + PDF report output
python dakshscra.py -r auto -t /path/to/source -rpt html,pdf

# Verbosity levels
python dakshscra.py -r php -v -t /path/to/source     # default
python dakshscra.py -r php -vvv -t /path/to/source   # show all pattern checks

# Generate suppression baseline from current findings
python dakshscra.py -r auto -t /path/to/source --baseline-generate

# Apply suppression baseline (suppress known FPs)
python dakshscra.py -r auto -t /path/to/source --baseline-file config/suppressions.json

# Disable baseline for this run
python dakshscra.py -r auto -t /path/to/source --no-baseline

# Apply findings triage / review config
python dakshscra.py -r auto -t /path/to/source --review-config config/review.json

# Scan with checkpoint state enabled
python dakshscra.py -r auto -t /path/to/source --state

# Resume an interrupted scan
python dakshscra.py -r auto -t /path/to/source --resume-scan

# Resume with a custom state file
python dakshscra.py -r auto -t /path/to/source --resume-scan --state-file runtime/scan_state.json

# Generate PDF from existing JSON outputs (no re-scan)
python dakshscra.py --pdf-from-json

# Generate PDF from a custom JSON directory
python dakshscra.py --pdf-from-json --json-input-dir ./custom/reports/data

# Custom output paths for PDF
python dakshscra.py --pdf-from-json --pdf-output ./reports/scan/pdf/custom.pdf --pdf-multi-dir ./reports/scan/pdf/multi-file

# Single combined PDF only (skip per-platform set)
python dakshscra.py --pdf-from-json --pdf-single-only

查看支持的平台规则与框架```bash

python dakshscra.py -l R # List platform rules and framework mappings python dakshscra.py -l RF # List platform rules, framework mappings, and filetypes

当前支持的平台和框架映射：

| 平台 | 框架 |
|---|---|
| dotnet | aspnetcore, entityframework |
| php | codeigniter, drupal, laravel, symfony, wordpress |
| java | hibernate, spring, springboot |
| javascript | angular, express, nestjs, nextjs, react, vue |
| kotlin | ktor, springkotlin |
| python | django, fastapi, flask |
| go | echo, fiber, gin |
| c | freertos |
| cpp | boost, qt |
| android | cordova-android, flutter-android, ionic-android, jetpack, nativescript-android, reactnative-android, xamarin-android |
| ios | cordova-ios, flutter-ios, ionic-ios, nativescript-ios, reactnative-ios, swiftui, uikit, xamarin-ios |
| reactnative | reactnative |
| flutter | flutter |
| xamarin | xamarin |
| ionic | ionic |
| nativescript | nativescript |
| cordova | cordova |
| ruby | rails, sinatra |
| rust | actix, axum, rocket |
| common | - |

要获取最新支持的平台和框架，请始终运行：```bash
python dakshscra.py -l R

配置参考

`config/tool.yaml`

Daksh SCRA 运行时默认值由 config/tool.yaml 控制。```yaml state_management: enabled: false resume_mode: manual persist_after_seconds: 300 persist_interval_seconds: 30 default_state_file: runtime/scan_state.json cleanup_on_success: false

analysis: run_by_default: true include_frameworks: true report_theme: hacker_mode

**分析器配置选项：**

- `analysis.run_by_default`
  - `true`：分析器在扫描期间自动运行
  - `false`：分析器禁用，除非在配置中或通过CLI重新启用
- `analysis.include_frameworks`
  - `true`：包含框架检测存在的框架级分析器条目
  - `false`：仅平台级分析器输出
- `analysis.report_theme`
  - `hacker_mode`：深色高对比度现代分析器主题（默认）
  - `professional_mode`：浅色现代分析器主题
  - `both`：同时生成两种主题变体并排

### RDL 规则编写

RDL（规则描述语言）是 DakshSCRA 的外部化规则逻辑层。在当前架构中：

- XML 规则仍然是规则清单，并携带元数据，如 `name`、`regex`、描述以及可选的 `scan_config`。
- RDL 逻辑由 [`core/rdl_engine.py`](https://github.com/coffeeandsecurity/dakshscra/blob/HEAD/mnt/c/_Source/Developement/DakshSCRA/core/rdl_engine.py) 执行。
- 规则逻辑文件位于 `rules/scanning/logic/...` 下，并通过 XML 中的 `<rdl_ref>` 引用。
- `rdl_ref` 值相对于 `rules/scanning/` 解析，例如：`logic/php/core/some_rule.rdl` -> `rules/scanning/logic/php/core/some_rule.rdl`
- 逻辑结果作为元数据导出到报告 JSON 中，例如 `logic_engine`、`logic_source`、`logic_reason`、`logic_trace`、`logic_consulted_files` 和 `logic_outcome`。

旧的内联 `<rdl>` 形式不再是活跃架构，不应用于新规则。

#### RDL 架构概览```text
XML rule
  -> regex / exclude / scan_config / descriptions
  -> rdl_ref
       -> rules/scanning/logic/<platform>/<scope>/<rule>.rdl
           -> core/rdl_engine.py
               -> pass / fail
               -> reason / fail_reason
               -> trace / consulted_files / outcome

扫描顺序

对于源规则，DakshSCRA 按以下顺序评估逻辑：

Recon 选择匹配的平台和框架。
从 rules/scanning/platform/... 加载 XML 规则。
如果存在，regex 查找候选行或整个文件匹配。
如果存在，exclude 移除该规则的明显噪声。
评估来自 rdl_ref 的外部 .rdl 文件，根据当前文件文本、当前文件路径和项目根目录。
如果 RDL 脚本通过，DakshSCRA 保留发现结果，并将导出的逻辑元数据合并到报告输出中。
如果 RDL 脚本失败，则抑制匹配，并附带 RDL 失败原因和决策跟踪元数据。

对于 filepaths.xml 中的文件路径规则，同样的 rdl_ref 模型适用，但匹配主体是标准化相对路径而不是源代码文本。在该模式下，RDL 接收相对路径字符串作为当前文件文本和路径上下文。

当前规则结构```xml

Rule Name logic/common/core/insecure_sql_query_unsafe_string_concatenation.rdl ... Short description of what the rule detects. Why the pattern matters. Fix guidance for developers. Manual confirmation guidance for reviewers. ``` #### 当前的 `.rdl` 结构```text VERSION 1 WHEN PRESENT /\\b(?:mysql_query|mysqli_query|->query)\\s*\\(/i WHEN EXPR PRESENT:\\$_(GET|POST|REQUEST|COOKIE) && MISSING:\\b(?:prepare|bindParam|bindValue|PDO::prepare)\\b REPORT AS area_of_interest REASON SQL query execution appears reachable without parameterisation in this file. FAIL_REASON Matching query API was found, but the file also contains prepared-statement indicators. TRACE SQLi gate: input source present and mitigation missing. ``` #### 当前布局```text rules/ └── scanning/ ├── platform/ │ ├── php/php.xml │ ├── java/java.xml │ └── ... └── logic/ ├── common/core/ ├── php/core/ ├── php/framework/laravel/ ├── mobile/android/core/ ├── filepaths/core/ └── ... ``` #### 执行语义

WHEN PRESENT、WHEN MISSING 和 WHEN CURRENT_FILE_MATCHES 根据当前文件文本进行评估。
WHEN FILE_NAME_IS 和 WHEN FILE_PATH_MATCHES 根据当前文件路径上下文进行评估。
WHEN EXPR 支持对 PRESENT:、MISSING: 和 EXISTS: 谓词进行布尔逻辑运算。
OBSERVE PROJECT_HAS_GLOB ... AS ... 不控制发现结果；它会在跟踪元数据中记录相关的项目文件。
REPORT AS、REASON、FAIL_REASON 和 TRACE 控制导出的报告元数据。

支持的 RDL 命令

WHEN EXPR 中的布尔表达式支持：

PRESENT:<regex>
MISSING:<regex>
EXISTS:<regex>
&&、||、!，以及括号

示例 1 - PHP SQL 注入门控

XML 规则：```xml Possible SQL Injection in Query Execution query)\s*\(]]> <rdl_ref>logic/common/core/insecure_sql_query_unsafe_string_concatenation.rdl</rdl_ref> <rule_desc>...</rule_desc>

外部 RDL：```text
VERSION 1
WHEN PRESENT /\b(?:mysql_query|mysqli_query|->query)\s*\(/i
WHEN EXPR PRESENT:\$_(GET|POST|REQUEST|COOKIE) && MISSING:\b(?:prepare|bindParam|bindValue|PDO::prepare)\b
REPORT AS area_of_interest
REASON Query execution appears to rely on direct input without parameterisation.
FAIL_REASON Query API matched, but parameterised query indicators were also found in the file.

示例2 - 具有文件感知检查的Android清单规则

XML规则：```xml Exported Components Without Permission activity|service|receiver|provider)\s[^>]*android:name="(?P[^"]+)"[^>]*android:exported="true"[^>]*(?:/>|>)]]> <rdl_ref>logic/mobile/android/core/exported_components.rdl</rdl_ref> <scan_config>...</scan_config>

外部 RDL:```text
VERSION 1
WHEN FILE_NAME_IS AndroidManifest.xml
WHEN CURRENT_FILE_MATCHES /android:exported\s*=\s*"true"/i
WHEN MISSING /android:permission\s*=\s*"/i
REPORT AS area_of_interest
REASON Exported component appears reachable without a permission guard.

示例3 - 文件路径感兴趣区域规则

XML规则：```xml Admin Section File Path <rdl_ref>logic/filepaths/core/admin_section.rdl</rdl_ref>

外部 RDL:```text
VERSION 1
WHEN CURRENT_FILE_MATCHES /(^|\/)(admin|administrator|root)(\/|$)/i
UNLESS CURRENT_FILE_MATCHES /(^|\/)(tests?|docs?|samples?|examples?)(\/|$)/i
REPORT AS area_of_interest
REASON File path suggests privileged application functionality.
FAIL_REASON Path matched an excluded documentation or sample location.

编写指导

保持regex足够宽泛以捕获候选对象，然后使用RDL过滤上下文。
优先使用rdl_ref处理所有规则逻辑，并将.rdl文件放在适当的平台/框架逻辑树旁。
不要添加新的内联<rdl>块。
对于简单的门控使用WHEN PRESENT / WHEN MISSING，仅当逻辑真正为布尔值时使用WHEN EXPR。
在REASON中放置面向审阅者的理由，在FAIL_REASON中放置抑制解释。
将PRESENT和MISSING视为全文件检查。文件中任何位置的缓解措施可以抑制该文件的所有匹配。
使用OBSERVE PROJECT_HAS_GLOB丰富发现结果的项目上下文，不作为通过/失败门控。
保持logic/...路径稳定且限定在平台范围内，使XML规则保持精简，逻辑层保持可重用。

报告输出结构

所有输出都写入reports/目录下：``` reports/ ├── scan/ │ ├── html/ │ │ ├── report.html # Single-file HTML scan report │ │ └── multi-file/ # Per-platform HTML report set │ ├── pdf/ │ │ ├── report.pdf # Single-file PDF scan report │ │ └── multi-file/ # Per-platform PDF report set │ ├── recon/ │ │ └── reconnaissance.html # Reconnaissance HTML report │ └── estimate/ │ └── estimation.html # Effort estimation HTML report ├── analysis/ │ └── / │ ├── analysis.html # Taint analysis report (default theme) │ ├── analysis_professional.html # Professional theme (if theme=both) │ ├── analysis_xref.html # Cross-reference report │ └── analysis.json # Structured analysis data └── data/ ├── areas_of_interest.json # AoI findings ├── filepaths_aoi.json # File path AoI findings ├── summary.json # Scan summary ├── recon.json # Recon summary └── analysis.json # Analyzer output

Runtime files (scan state, logs, inventory) are written under `runtime/`.

---

## Web UI

Daksh SCRA 包含一个基于浏览器的前端，用于启动扫描并实时查看进度。```bash
docker compose up --build

然后打开：http://localhost:8080

Web UI 功能：

支持扫描、侦察、估算、侦察+估算、列表以及从JSON生成PDF模式的响应式命令构建器
执行期间的实时控制台输出
每次作业的HTML/PDF/JSON输出工件快照
浏览器内快速导航，涵盖运行表单、实时输出、工件和最近作业
内置目录浏览器，用于选择目标路径（识别操作系统：Windows、macOS、Linux / Docker）

执行模型：

CLI 仍然是事实来源，并生成所有 HTML / PDF / JSON 输出
Web UI 一次只支持一个活动作业（CLI 写入共享的 runtime/ 和 reports/ 路径）
已完成的作业将输出快照到 runtime/webui/jobs/<job-id>/artifacts/，以便之前的报告仍然可访问

Docker

启动 Web UI：```bash docker compose up --build

然后打开：[http://localhost:8080](http://localhost:8080)

**在Docker中运行CLI：**```bash
docker compose run --rm cli -h
docker compose run --rm cli -r auto -t /scan-targets/path/to/source

停止栈：```bash docker compose down

**Docker 包含内容：**

- FastAPI + Web 前端
- 完整的 Daksh SCRA CLI 作为独立服务
- Playwright Chromium 用于 PDF 生成
- 持久化的 `reports/` 和 `runtime/` 卷
- 主机路径挂载，使扫描可以从容器内部访问源代码树

**关键挂载点：**

| 挂载 | 容器内路径 |
|---|---|
| 项目源代码 | `/app` |
| 默认扫描根目录 | `/scan-targets` |
| 主机驱动器别名 | `/host`, `/host/c`, `/host/d` |
| WSL 挂载 | `/mnt`, `/run/desktop/mnt/host` |

**环境变量（在 `.env` 中配置）：**

| 变量 | 描述 |
|---|---|
| `DAKSH_PORT` | Web UI 端口（默认：`8080`） |
| `DAKSH_SCAN_ROOT` | 容器内默认目标目录 |
| `DAKSH_HOST_SOURCE` | 挂载为 `/scan-targets` 的主机路径（默认：`/tmp`） |
| `DAKSH_HOST_MOUNT` | 额外的主机挂载根目录 |
| `DAKSH_HOST_C` | Windows C: 驱动器路径（WSL） |
| `DAKSH_HOST_D` | Windows D: 驱动器路径（WSL） |
| `DAKSH_DESKTOP_MOUNT` | WSL 桌面挂载路径 |
| `DAKSH_BROWSE_ROOTS` | 覆盖目录浏览器根目录（逗号分隔） |

运行 Docker 前，请将 `.env.example` 复制为 `.env` 并根据你的机器设置路径。

---

## 作者

| | |
|---|---|
| 网站 | [coffeeandsecurity.com](https://www.coffeeandsecurity.com) |
| 邮箱 | [email protected] |
| Twitter / X | [@coffeensecurity](https://x.com/coffeensecurity) |
| 源代码 | [github.com/coffeeandsecurity/DakshSCRA](https://github.com/coffeeandsecurity/DakshSCRA) |
| 许可证 | GNU General Public License v3.0 (GPL-3.0) |

如果 DakshSCRA 为你的团队节省了大量时间、精力或成本，减少了对昂贵商业工具的依赖，提高了审查覆盖率，或使代码审查更加结构化和高效，欢迎联系我们分享你的经验。我一直乐于接受深思熟虑的反馈和有趣的对话。

发现 Bug 或想贡献代码？请在 GitHub 上提交 Issue 或 Pull Request。

`WHEN PRESENT <regex>`	要求当前文件文本中存在某个模式	要求同时存在有风险的 API 或敏感字段
`WHEN MISSING <regex>`	要求当前文件文本中不存在某个模式	当缓解措施已存在时抑制
`WHEN EXPR <expr>`	使用 `PRESENT:`/`MISSING:`/`EXISTS:` 结合 `&&`、`
`WHEN CURRENT_FILE_MATCHES <regex>`	针对完整的当前文件文本进行匹配	重新检查复杂整文件条件
`WHEN FILE_NAME_IS <name>`	要求当前文件名完全匹配	限制 plist/manifest/config 规则
`WHEN FILE_PATH_MATCHES <glob>`	要求当前相对路径匹配一个 glob 模式	缩小框架/配置文件路径规则
`UNLESS CURRENT_FILE_MATCHES <regex>`	当整个文件匹配排除模式时失败	阻止已知安全的结构案例
`OBSERVE PROJECT_HAS_GLOB <glob> AS <label>`	在跟踪元数据中记录相关的项目文件	显示支持配置或伴随文件
`REPORT AS <outcome>`	设置规则结果，通常为 `area_of_interest`	未来兼容的明确结果
`REASON <text>`	规则通过时显示的原因	解释发现为何保持可见
`FAIL_REASON <text>`	规则抑制匹配时显示的原因	解释命中为何被过滤
`TRACE <text>`	添加调试/决策跟踪行	迁移/调试支持

DakshSCRA

最受欢迎