soheilkhodayari/jawJAW: Графовая среда анализа безопасности для клиентского JavaScript
J A W
Веб-сайт | Документация | Установка | Краулер | Быстрый старт Docker (Пример)
Открытая реализация прототипа графов свойств для JavaScript на основе парсера esprima и спецификации EsTree SpiderMonkey Spec. JAW может использоваться для анализа клиентской части веб-приложений и программ на JavaScript.
Этот проект лицензирован в соответствии с GNU AFFERO GENERAL PUBLIC LICENSE V3.0. Дополнительную информацию см. здесь.
У JAW есть веб-сайт на Github Pages, доступный по адресу https://soheilkhodayari.github.io/JAW/.
Примечания к выпуску:
JAW-V2.JAW-V1.Архитектура JAW показана ниже.
JAW можно использовать двумя способами:
Анализ произвольного JavaScript: Используйте JAW для моделирования и анализа любой программы на JavaScript, указав путь к файлу программы.
Анализ веб-приложения: Анализируйте веб-приложение, указав один начальный URL.
Используйте собранные веб-ресурсы для создания Гибридного Программного Графа (HPG), который будет импортирован в базу данных Neo4j.
При необходимости передайте модулю построения HPG отображение семантических типов на пользовательские токены языка JavaScript, что облегчает категоризацию функций JavaScript по их назначению (например, функции HTTP-запросов).
Запрашивайте построенную базу данных графа Neo4j для различных анализов. JAW предоставляет утилитарные обходы для анализа потоков данных, управления потоками, анализа достижимости и сопоставления с шаблонами. Эти обходы можно использовать для разработки пользовательских анализов безопасности.
JAW также включает встроенные обходы для обнаружения уязвимостей client-side CSRF, DOM Clobbering и перехвата запросов.
Результаты будут сохранены в той же папке, что и входные данные.
Сценарий установки требует следующие предварительные условия:
npm package manager (node js)python 3.xpipПосле этого установите необходимые зависимости с помощью:
$ ./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]
This script runs the tool pipeline.
optional arguments:
-h, --help show this help message and exit
--conf FILE, -C FILE pipeline configuration file. (default: config.yaml)
--site SITE, -S SITE website to test; overrides config file (default: None)
--list LIST, -L LIST site list to test; overrides config file (default: None)
--from FROM, -F FROM the first entry to consider when a site list is provided; overrides config file (default: -1)
--to TO, -T TO the last entry to consider when a site list is provided; overrides config file (default: -1)
Входной конфигурационный файл: JAW ожидает на входе .yaml конфигурационный файл. Пример см. в config.yaml.
Подсказка. В конфигурационном файле указаны различные этапы (например, сканирование, статический анализ и т.д.), которые можно включать или отключать для каждого класса уязвимостей. Это позволяет запускать компоненты инструмента по отдельности или в другом порядке (например, сначала сканировать все веб-приложения, затем проводить анализ безопасности).
Для запуска быстрого примера, демонстрирующего создание графа свойств и выполнение 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, инструментированную версию Firefox, для выполнения динамического отслеживания помеченных данных при навигации по веб-страницам. Для запуска краулера выполните:
$ cd crawler
$ node crawler-taint.js --seedurl=https://google.com --maxurls=100 --headless=true --foxhoundpath=<необязательный-путь-к-исполняемому-файлу-foxhound>
По умолчанию foxhoundpath указывает на следующий каталог: crawler/foxhound/firefox, который содержит двоичный файл с именем firefox.
Примечание: для использования этой версии необходима сборка foxhound. Сборка для Ubuntu включена в релиз JAW-v3.
Для запуска краулера выполните:
$ cd crawler
$ node crawler.js --seedurl=https://google.com --maxurls=100 --browser=chrome --headless=true
Дополнительную информацию см. здесь.
Для запуска краулера выполните:
$ cd crawler/hpg_crawler
$ vim docker-compose.yaml # укажите здесь сайты для сканирования и сохраните
$ docker-compose build
$ docker-compose up -d
Пожалуйста, обратитесь к документации hpg_crawler здесь для получения дополнительной информации.
Для создания HPG для одного (или набора) JavaScript-файла(ов) выполните:
$ node engine/cli.js --lang=js --graphid=graph1 --input=/in/file1.js --input=/in/file2.js --output=$(pwd)/data/out/ --mode=csv
дополнительные аргументы:
--lang: язык входной программы
--graphid: идентификатор для создаваемого HPG
--input: путь к входной программе(ам)
--output: путь к выходному HPG, должен быть внутри
--mode: определяет формат вывода (csv или graphML)
Для импорта 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]
This script imports a CSV of a property graph into a neo4j docker database.
optional arguments:
-h, --help show this help message and exit
--rpath P relative path to the folder containing the graph CSV files inside the `data` directory
--id I an identifier for the graph or docker container
--nodes N the name of the nodes csv file (default: nodes.csv)
--edges E the name of the relations csv file (default: rels.csv)
Чтобы создать гибридный граф свойств для вывода hpg_crawler и импортировать его в локальный экземпляр neo4j, вы также можете выполнить:
$ python3 -m engine.api <путь> --js=<program.js> --import=<bool> --hybrid=<bool> --reqs=<requests.out> --evts=<events.out> --cookies=<cookies.pkl> --html=<html_snapshot.html>
Спецификация параметров:
<путь>: абсолютный путь к папке, содержащей файлы программы для анализа (должна находиться в папке engine/outputs).--js=<program.js>: имя JavaScript-программы для анализа (по умолчанию: js_program.js).--import=<bool>: следует ли импортировать построенный граф свойств в активную базу данных neo4j (по умолчанию: true).--hybrid=bool: включен ли гибридный режим (по умолчанию: false). Это означает, что тестировщик хочет обогатить граф свойств, вводя файлы HTML-снимка, сработавших событий, HTTP-запросов и cookie, собранных краулером JAW.--reqs=<requests.out>: только для гибридного режима, имя файла, содержащего последовательность наблюдаемых сетевых запросов; передайте строку false, чтобы исключить (по умолчанию: request_logs_short.out).--evts=<events.out>: только для гибридного режима, имя файла, содержащего последовательность сработавших событий; передайте строку , чтобы исключить (по умолчанию: ).Для получения дополнительной информации вы можете использовать справку CLI, предоставленную с API построения графа:
$ python3 -m engine.api -h
Построенный HPG затем можно запрашивать с помощью Cypher или NeoModel ORM.
Вы должны размещать и выполнять свои запросы в analyses/<ИМЯ_АНАЛИЗА>.
Вы можете использовать NeoModel ORM для запросов к HPG. Чтобы написать запрос:
example_query_orm.py в папке analyses/example.$ python3 -m analyses.example.example_query_orm
Для получения дополнительной информации см. здесь.
Вы можете использовать Cypher для написания пользовательских запросов. Для этого:
example_query_cypher.py в папке analyses/example.$ python3 -m analyses.example.example_query_cypher
Для получения дополнительной информации см. здесь.
В этом разделе описывается, как настроить и использовать JAW для обнаружения уязвимостей, а также как интерпретировать результаты. JAW содержит, среди прочего, автономные запросы для обнаружения client-side 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 в той же папке, что и входные данные. Например, для Client-side CSRF для каждого обнаруженного HTTP-запроса JAW выводит запись, указывающую набор семантических типов (также известных как семантические теги или метки), связанных с элементами, формирующими запрос (т.е. срезами программы). Например, HTTP-запрос, помеченный семантическим типом ['WIN.LOC'], может быть подделан через точку инъекции 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'].
Чтобы упростить процесс тестирования JAW и убедиться в правильности вашей настройки, мы предоставляем простое веб-приложение на node.js, с которым вы можете протестировать JAW.
Сначала установите зависимости через:
$ cd tests/test-webapp
$ npm install
Затем запустите приложение в новом экране:
$ screen -dmS jawwebapp bash -c 'PORT=6789 npm run devstart; exec sh'
Для получения дополнительной информации посетите нашу вики-страницу здесь. Ниже приведено оглавление для быстрого доступа.
Запросы на вытягивание (pull requests) всегда приветствуются. Этот проект задуман как безопасное и гостеприимное пространство, и участники должны соблюдать кодекс поведения участников.
Если вы используете 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 прошёл долгий путь, и мы хотим выразить благодарность нашим участникам!
falseevents.out--cookies=<cookies.pkl>: только для гибридного режима, имя файла, содержащего cookie; передайте строку false, чтобы исключить (по умолчанию: cookies.pkl).--html=<html_snapshot.html>: только для гибридного режима, имя файла, содержащего снимок DOM-дерева; передайте строку false, чтобы исключить (по умолчанию: html_rendered.html).