J A W

JAW

一个基于 esprima 解析器和 EsTree SpiderMonkey Spec 的 JavaScript 属性图开源原型实现。JAW 可用于分析 Web 应用程序的客户端和基于 JavaScript 的程序。

本项目采用 GNU AFFERO GENERAL PUBLIC LICENSE V3.0 许可。更多信息请参见此处。

JAW 有一个 Github Pages 网站，网址为 https://soheilkhodayari.github.io/JAW/。

发布说明：

2025 年 9 月，JAW-v5：通过此分支支持 DOM gadget 检测。
2024 年 12 月，JAW-v4：JAW 更新，增添了开放重定向检测查询。
2023 年 10 月，JAW-v3（Sheriff）：JAW 更新，可检测客户端请求劫持漏洞。
2022 年 7 月，JAW-v2（TheThing）：JAW 更新至下一个主要版本，具备检测 DOM Clobbering 漏洞的能力。请参见 JAW-V2 分支。
2020 年 12 月，JAW-v1：首个原型版本。请参见 JAW-V1 分支。

JAW 概述

JAW 的架构如下图所示。

测试输入

JAW 可通过两种不同的方式使用：

任意 JavaScript 分析： 通过指定程序的文件系统 路径，利用 JAW 对任何 JavaScript 程序进行建模和分析。
Web 应用分析： 通过提供一个种子 URL 来分析 Web 应用程序。

数据收集

JAW 具备多个支持 JavaScript 的 Web 爬虫，可用于大规模收集 Web 资源。

HPG 构建

使用收集到的 Web 资源创建一个混合属性图（HPG），并将其导入 Neo4j 数据库。
可选：为 HPG 构建模块提供语义类型到自定义 JavaScript 语言标记的映射，以便根据函数用途（例如 HTTP 请求函数）对 JavaScript 函数进行分类。

分析与输出

查询构建好的 Neo4j 图数据库以进行各种分析。JAW 提供了用于数据流分析、控制流分析、可达性分析和模式匹配的实用遍历。这些遍历可用于开发自定义安全分析。
JAW 还包含用于检测客户端 CSRF、DOM Clobbering 和请求劫持漏洞的内置遍历。
输出将存储在与输入相同的文件夹中。

设置

安装脚本依赖以下先决条件：

最新版本的 npm 包管理器（Node.js）
任何稳定版本的 Python 3.x
Python pip 包管理器

然后，通过以下命令安装必要的依赖项：

$ ./install.sh

有关 详细 安装说明，请参见此处。

快速开始

运行管道

您可以通过以下命令在后台屏幕中运行管道的实例：

$ python3 -m run_pipeline --conf=config.yaml

CLI 提供以下选项：

$ python3 -m run_pipeline -h

usage: run_pipeline.py [-h] [--conf FILE] [--site SITE] [--list LIST] [--from FROM] [--to TO]

此脚本运行工具管道。

optional arguments:
  -h, --help            显示此帮助信息并退出
  --conf FILE, -C FILE  管道配置文件。（默认值：config.yaml）
  --site SITE, -S SITE  要测试的网站；覆盖配置文件（默认值：None）
  --list LIST, -L LIST  要测试的网站列表；覆盖配置文件（默认值：None）
  --from FROM, -F FROM  当提供网站列表时，要考虑的第一个条目；覆盖配置文件（默认值：-1）
  --to TO, -T TO        当提供网站列表时，要考虑的最后一个条目；覆盖配置文件（默认值：-1）

输入配置： JAW 需要一个 .yaml 配置文件作为输入。参见 config.yaml 示例。

提示： 配置文件指定了不同的步骤（例如，爬取、静态分析等），可以为每个漏洞类别启用或禁用这些步骤。这允许单独或以不同的顺序运行工具的构建块（例如，先爬取所有 Web 应用，然后进行安全分析）。

快速示例

要运行一个快速示例，演示如何构建属性图并对其运行 Cypher 查询，请执行以下操作：

$ python3 -m analyses.example.example_analysis --input=$(pwd)/data/test_program/test.js

爬取与数据收集

此模块收集测试所需的数据（即 JavaScript 代码和网页状态值）。如果您要测试文件系统上已有的特定 JavaScript 文件，可以跳过此步骤。

JAW 具有基于 Selenium（JAW-v1）、Puppeteer（JAW-v2、v3）和 Playwright（JAW-v3）的爬虫。为了获得最新的功能，建议使用基于 Puppeteer 或 Playwright 的版本。

带 Foxhound 的 Playwright CLI

此 Web 爬虫使用 foxhound（Firefox 的仪表化版本）在浏览网页时执行动态污点跟踪。要启动爬虫，请执行：

$ cd crawler
$ node crawler-taint.js --seedurl=https://google.com --maxurls=100 --headless=true --foxhoundpath=<可选-foxhound-可执行文件路径>

foxhoundpath 默认设置为以下目录：crawler/foxhound/firefox，其中包含一个名为 firefox 的二进制文件。

注意： 您需要构建 foxhound 才能使用此版本。JAW-v3 的发布版中包含一个 Ubuntu 构建。

Puppeteer CLI

要启动爬虫，请执行：

$ cd crawler
$ node crawler.js --seedurl=https://google.com --maxurls=100 --browser=chrome --headless=true

更多信息请参见此处。

Selenium CLI

要启动爬虫，请执行：

$ cd crawler/hpg_crawler
$ vim docker-compose.yaml # 在此处设置要爬取的网站并保存
$ docker-compose build
$ docker-compose up -d

请参考 hpg_crawler 的文档此处以获取更多信息。

图构建

HPG 构建 CLI

要为给定的 JavaScript 文件（集）生成 HPG，请执行：

$ node engine/cli.js  --lang=js --graphid=graph1 --input=/in/file1.js --input=/in/file2.js --output=$(pwd)/data/out/ --mode=csv

optional arguments:
  --lang:     输入程序的语言
  --graphid:  生成的 HPG 的标识符
  --input:    输入程序的路径
  --output:   输出 HPG 的路径，必须是 ...
  --mode:     确定输出格式（csv 或 graphML）

HPG 导入 CLI

要将 HPG 导入 Neo4j 图数据库（Docker 实例），请执行：

$ python3 -m hpg_neo4j.hpg_import --rpath=<CSV 文件所在文件夹的路径> --id=<xyz> --nodes=<nodes.csv> --edges=<rels.csv>
$ python3 -m hpg_neo4j.hpg_import -h

usage: hpg_import.py [-h] [--rpath P] [--id I] [--nodes N] [--edges E]

此脚本将属性图的 CSV 文件导入 Neo4j Docker 数据库。

optional arguments:
  -h, --help  显示此帮助信息并退出
  --rpath P   相对于 `data` 目录中包含图表 CSV 文件的文件夹的路径
  --id I      图或 Docker 容器的标识符
  --nodes N   节点 CSV 文件的名称（默认值：nodes.csv）
  --edges E   关系 CSV 文件的名称（默认值：rels.csv）

HPG 构建与导入 CLI（v1）

要为 hpg_crawler 的输出创建混合属性图并将其导入本地 Neo4j 实例，您还可以执行：

$ python3 -m engine.api <path> --js=<program.js> --import=<bool> --hybrid=<bool> --reqs=<requests.out> --evts=<events.out> --cookies=<cookies.pkl> --html=<html_snapshot.html>

参数说明：

<path>：包含要分析的程序文件的文件夹的绝对路径（必须位于 engine/outputs 文件夹下）。
--js=<program.js>：要分析的 JavaScript 程序的名称（默认值：js_program.js）。
--import=<bool>：是否应将构建的属性图导入到活动的 Neo4j 数据库（默认值：true）。
--hybrid=bool：是否启用混合模式（默认值：false）。这表示测试人员希望通过输入由 JAW 爬虫收集的 HTML 快照、触发事件、HTTP 请求和 cookie 文件来丰富属性图。
--reqs=<requests.out>：仅混合模式，包含观察到的网络请求序列的文件名，传递字符串 false 排除（默认值：request_logs_short.out）。
--evts=<events.out>：仅混合模式，包含触发事件序列的文件名，传递字符串 false 排除（默认值：events.out）。
--cookies=<cookies.pkl>：仅混合模式，包含 cookie 的文件名，传递字符串排除（默认值：）。

更多信息，您可以使用图构建 API 提供的帮助 CLI：

$ python3 -m engine.api -h

安全分析

构建的 HPG 随后可以使用 Cypher 或 NeoModel ORM 进行查询。

运行自定义图遍历

您应将查询放置在 analyses/<ANALYSIS_NAME> 中并运行。

选项 1：使用 NeoModel ORM（已弃用）

您可以使用 NeoModel ORM 查询 HPG。要编写查询：

(1) 查看 HPG 数据模型和语法树。
(2) 查看 HPG 的 ORM 模型。
(3) 参见提供的示例查询文件：analyses/example 文件夹中的 example_query_orm.py。

$ python3 -m analyses.example.example_query_orm

更多信息请参见此处。

选项 2：使用 Cypher 查询

您可以使用 Cypher 编写自定义查询。为此：

(1) 查看 HPG 数据模型和语法树。
(2) 参见提供的示例查询文件：analyses/example 文件夹中的 example_query_cypher.py。

$ python3 -m analyses.example.example_query_cypher

更多信息请参见此处。

漏洞检测

本节介绍如何配置和使用 JAW 进行漏洞检测，以及如何解释输出。JAW 包含自包含的查询，用于检测客户端 CSRF 和 DOM Clobbering 等。

步骤 1： 在输入 config.yaml 文件中启用该漏洞类别的分析组件：

request_hijacking:
  enabled: true 
  # [...]

open_redirect:
  enabled: false 
  # [...]
  
domclobbering:
  enabled: false
  # [...]

cs_csrf:
  enabled: false
  # [...]

步骤 2： 运行管道的实例：

$ python3 -m run_pipeline --conf=config.yaml

提示： 您可以在不同的 screen 下运行管道的多个实例：

$ screen -dmS s1 bash -c 'python3 -m run_pipeline --conf=conf1.yaml; exec sh'
$ screen -dmS s2 bash -c 'python3 -m run_pipeline --conf=conf2.yaml; exec sh'
$ # [...]

要自动生成并行配置文件，您可以使用 generate_config.py 脚本。

如何解释分析输出？

输出将存储在输入文件所在文件夹中的 sink.flows.out 文件中。例如，对于客户端 CSRF，JAW 为每个检测到的 HTTP 请求输出一个条目，标记与该请求构建元素相关联的语义类型集（即程序切片）。例如，标记有语义类型 ['WIN.LOC'] 的 HTTP 请求可通过 window.location 注入点伪造。而标记有 ['NON-REACH'] 的请求则无法伪造。

下面显示了一个示例输出条目：

[*] Tags: ['WIN.LOC']
[*] NodeId: {'TopExpression': '86', 'CallExpression': '87', 'Argument': '94'}
[*] Location: 29
[*] Function: ajax
[*] Template: ajaxloc + "/bearer1234/"
[*] Top Expression: $.ajax({ xhrFields: { withCredentials: "true" }, url: ajaxloc + "/bearer1234/" })

1:['WIN.LOC'] variable=ajaxloc
	0 (loc:6)- var ajaxloc = window.location.href

该条目显示，在第 29 行，有一个 $.ajax 调用表达式，该调用表达式触发了一个 ajax 请求，URL 模板值为 ajaxloc + "/bearer1234/"，其中参数 ajaxloc 是一个程序切片，其值在第 6 行从 window.location.href 读取，因此可通过 ['WIN.LOC'] 伪造。

测试 Web 应用

为了简化 JAW 的测试过程并确保您的设置正确，我们提供了一个简单的 node.js Web 应用程序，您可以用它来测试 JAW。

首先，通过以下命令安装依赖项：

$ cd tests/test-webapp
$ npm install

然后，在一个新屏幕中运行该应用程序：

$ screen -dmS jawwebapp bash -c 'PORT=6789 npm run devstart; exec sh'

详细文档

更多信息，请访问我们的维基页面此处。以下是快速访问的目录。

JAW 的 Web 爬虫

Web 爬虫

混合属性图（HPG）的数据模型

图构建

图遍历

在属性图上运行查询

贡献与行为准则

欢迎提交 Pull Request。本项目旨在成为一个安全、友好的空间，贡献者应遵守行为准则。

学术出版物

如果您将 JAW 用于学术研究，我们建议您引用以下论文：

@inproceedings{JAW,
  title = {JAW: Studying Client-side CSRF with Hybrid Property Graphs and Declarative Traversals},
  author= {Soheil Khodayari and Giancarlo Pellegrino},
  booktitle = {30th {USENIX} Security Symposium ({USENIX} Security 21)},
  year = {2021},
  address = {Vancouver, B.C.},
  publisher = {{USENIX} Association},
}

致谢

JAW 已经走了很长的路，我们想在此向我们的贡献者致以诚挚的感谢！

@tmbrbr，@c01gide，@jndre，以及 Sepehr Mirzaei。

JAW

最受欢迎

JAW

目录

JAW 概述

设置

快速开始

更多信息

JAW 概述

测试输入

数据收集

HPG 构建

分析与输出

设置

快速开始

运行管道

快速示例

爬取与数据收集

带 Foxhound 的 Playwright CLI

Puppeteer CLI

Selenium CLI

图构建

HPG 构建 CLI

HPG 导入 CLI

HPG 构建与导入 CLI（v1）

安全分析

运行自定义图遍历

选项 1：使用 NeoModel ORM（已弃用）

选项 2：使用 Cypher 查询

漏洞检测

如何解释分析输出？

测试 Web 应用

详细文档

JAW 的 Web 爬虫

混合属性图（HPG）的数据模型

图构建

图遍历

贡献与行为准则

学术出版物

致谢