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

Author:

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

## 关于 Daksh SCRA

Daksh SCRA（Source Code Review Assist，源代码审查辅助工具）旨在提升源代码审查流程的效率，为代码审查人员提供结构良好、组织有序的方法。

Daksh SCRA 并非不加区分地将所有内容标记为潜在问题，而是倡导深思熟虑的分析，敦促对潜在问题进行调查和确认。这种方法减少了对每个潜在隐患都急于标记为漏洞的慌乱，减少了因误报而造成的混乱和浪费时间。

### 首次亮相

Daksh SCRA 最初在 Black Hat USA 2022（8 月 6 日至 9 日）的源代码审查培训课程中推出，当时仅向特定受众低调展示。其正式的公开亮相是在拉斯维加斯举行的 Black Hat USA 2023 上。

## 特性与功能

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

> 正在持续进行积极改进。多个新功能和改进计划在即将发布的版本中推出。

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

如果您发现任何错误，请报告至 [[email protected]](mailto:[email protected])。

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

---

## 快速开始

运行 Daksh SCRA 有两种方式——选择适合您工作流程的方式：

| | 最适合 | 跳转至 |
|---|---|---|
| 🌐 **Web UI (Docker)** | 最简单的入门方式——一条命令、浏览器仪表板、实时扫描进度，以及报告/产物浏览器。推荐大多数用户使用。 | [Web UI (Docker)](#web-ui-docker) |
| 💻 **CLI (Python)** | 脚本编写、CI 流水线，或在不使用 Docker 的情况下运行扫描。 | [CLI 设置](#cli-setup) |

两种方式运行完全相同的扫描引擎——Web UI 是同一 CLI 之上的浏览器前端，因此无论哪种方式结果都相同。

---

## Web UI (Docker)

运行 Daksh SCRA 最快的方式是通过其基于浏览器的 Web UI，使用主机感知的 Docker 启动辅助脚本启动。它为您提供扫描启动器、实时控制台输出，以及可浏览的历史报告。启动辅助脚本需要 Python 3（仅标准库）；应用程序及其依赖项在 Docker 中运行。

Docker 设置将 Web UI 和 CLI 作为基于同一镜像构建的独立服务运行，因此您可以从同一容器中使用其中任意一个（或两者）。

### 启动 Web UI

从 GitHub 下载 Daksh SCRA 后，**请先解压 ZIP 归档文件**。
在包含 `docker-compose.yml` 和 `dakshscra.py` 的解压项目文件夹内打开终端（Windows 上为 PowerShell 或命令提示符）。
**请从该文件夹运行以下所有启动和 Docker Compose 命令。**

如果您的终端在其他位置打开，请先切换到解压后的文件夹：```text
cd "path/to/extracted/DakshSCRA-folder"

将示例路径替换为你的实际下载位置和文件夹名称。 如果你改为克隆了仓库，请从其父文件夹运行 cd DakshSCRA。

启动辅助脚本会识别 Windows、WSL、Linux 和 macOS，然后在启动容器之前 以只读方式挂载主机根目录、可用的 Windows 驱动器以及常见文件夹。 请在运行 Docker 的计算机上运行它。

Linux、macOS 或 WSL（前台）：```bash python3 tools/start_webui.py

Windows PowerShell 或命令提示符（前台）：```powershell
py tools/start_webui.py

添加 --detach 以在后台运行，或使用 --dry-run 检查检测到的路径。 现有的 .env 路径覆盖会被保留。重新创建容器时，账户、扫描和运行时 卷都会被保留。

Docker Desktop 可能需要权限才能共享选定的主机路径。如果它 拒绝挂载，请在 Docker Desktop 中允许该位置并重新运行辅助脚本。 远程浏览器看到的是 Docker 主机 的文件夹，而不是它自己计算机的驱动器。 自动检测需要本地 Docker 引擎；使用远程 Docker 上下文时，请在引擎 主机上运行辅助脚本。

对于手动配置的挂载，docker compose up --build -d api web 仍然 可用。其基线将仓库挂载到 /scan-targets，并将 ${DAKSH_HOST_MOUNT:-/} 挂载到 /host/root。使用辅助脚本进行 Windows 驱动器发现 和常用文件夹快捷方式；普通 Compose 无法检测客户端操作系统。

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

要使用不同的端口：```bash DAKSH_PORT=9090 python3 tools/start_webui.py

使用以下命令停止堆栈：```bash
docker compose down

登录

Web UI 需要一个账户。首次启动时，会根据 DAKSH_ADMIN_USERNAME / DAKSH_ADMIN_PASSWORD（在 .env 中设置）创建一个初始管理员账户；如果 DAKSH_ADMIN_PASSWORD 未设置，则会生成一个随机密码，并在 API 的启动日志中打印一次——请保存好它，因为之后无法恢复。

首次登录时，你需要设置自己的密码（以及可选的用户名）。管理员账户可以通过 POST /api/v1/auth/users API 端点创建更多账户（目前还没有专门的 UI）。有关认证相关设置的完整列表（会话生命周期、cookie 安全性、CORS），请参阅 .env.example。

你将获得

• 响应式命令构建器，支持 scan、recon、estimate、recon+estimate、list 以及 PDF-from-JSON 模式
• 执行期间实时控制台输出和实时各阶段进度
• 每个作业的 HTML / PDF / JSON 输出产物快照
• 在运行表单、实时输出、产物和最近作业之间快速进行浏览器内导航
• 内置目录浏览器，用于选择目标路径（感知操作系统：Windows、macOS、Linux / Docker）

在底层，CLI 仍然是唯一事实来源——它执行所有扫描并生成每个 HTML / PDF / JSON 输出。Web UI 一次运行一个活动作业，并将每个已完成作业的输出快照保存到 runtime/webui/jobs/<job-id>/artifacts/，以便过去的报告仍然可以访问。

在 Docker 中运行 CLI

你也不需要本地 Python 环境来使用 CLI——它作为独立的 Compose 服务提供，基于同一个镜像构建：```bash docker compose run --rm cli -h docker compose run --rm cli -r auto -t /scan-targets/path/to/source

### 镜像内容

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

**关键挂载点：**

| 挂载 | 容器内路径 |
|---|---|
| 项目源码 | `/app` |
| 默认扫描根目录（仓库，或 `DAKSH_SCAN_ROOT`） | `/scan-targets` |
| 主机文件系统（Windows 上的系统盘） | `/host/root` |
| 其他 Windows/WSL 驱动器 | `/host/drives/<letter>` |
| 当前用户的主目录 | `/host/user` |
| 常见主机文件夹 | `/host/locations/<name>` |
| 可选的 `DAKSH_HOST_SOURCE` | `/host/source` |

将 `.env.example` 复制为 `.env`，以进行可选的路径和身份验证覆盖。
`DAKSH_BROWSE_ROOTS` 是**容器**路径的逗号分隔允许列表；
保持未设置状态以自动发现已挂载的位置。切换到该辅助工具时，应移除或更新过时的 `/host/c`、`/host/d`
或 `/mnt` 允许列表。
主机文件夹为只读；报告和运行时数据在其
现有应用程序位置中保持可写。挂载另一个驱动器后，使用该辅助工具重新启动。无需 Docker socket 或特权容器。

---

## CLI 设置

更喜欢直接用 Python 运行 Daksh SCRA？以下是在本地进行设置的方法。

### 先决条件

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

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

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

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

---

CLI 用法

在虚拟环境中使用 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