# Webhawk/Catch 3.0
无监督机器学习 Web 攻击检测。
Image source:https://unsplash.com/photos/i4Y9hr5dxKc (Mathew Schwartz)
## 摘要
Webhawk 是一个由 ML/AI 驱动的检测工具，旨在自动识别应用程序日志（例如：HTTP）中的攻击痕迹，而无需依赖预设规则。利用无监督机器学习，Webhawk 将日志条目分组为聚类，并检测可能指示潜在攻击痕迹的异常值。检测完成后，Webhawk 利用 Agentic AI 提供详细的分析和可操作的建议。
Webhawk 配备了用户友好的 Web 界面。Webhawk UI 允许 SOC 团队成员轻松管理和审查检测结果。得益于内置的 API，检测结果还可以输入到您现有的 SOC 生态系统（例如：SIEM）中。
## 技术细节
Webhawk 将原始日志转换为数值数据，并应用主成分分析（PCA）提取最相关的特征（例如：User-Agent、IP 地址和传输参数的数量）。然后，它使用 DBSCAN（基于密度的噪声应用空间聚类）算法对日志行进行聚类并识别异常点，这些点可能代表潜在的攻击痕迹。
高级用户可以通过一组配置选项微调 Webhawk，以优化聚类算法——例如，通过调整每个聚类的最小点数或同一聚类内点之间的最大距离。
检测完成后，结果将发送到您选择的 LLM 进行深入分析和可操作的建议。Webhawk 利用 Agentic AI 设计模式，确保向用户提供的见解和建议具有有意义的、现实世界的价值。
为了从您的端点获取数据，Webhawk 提供了一个代理，您可以轻松地将其部署在每个端点上。启动后，该代理从相关文件获取日志，并通过 API 将其传输到检测引擎。
该工具易于使用 Docker Compose 部署，这简化了三个主要组件的安装：检测引擎、Web 应用程序和 LLM 服务。
## 生产环境设置
### 配置 webhawk/settings.conf 文件
有关设置此配置文件的详细信息，可在下面的开发环境设置/Create a settings.conf file 部分找到。
### 构建和启动 Docker 服务
```
docker compose build
docker compose up
```
启动上述命令后，将运行三个服务：
#### Webhawk
这是用于检测的服务，它将日志文件作为输入并返回检测结果。
#### Ollama
此服务用于向 LLM 发送提示词并获取响应。
#### Webhawk web application
此服务用于运行 Web 应用程序，安全分析师将在其中处理检测结果。
##### 首次启动 Docker 服务
如果您在首次构建后启动 Docker 服务，则第一次代理请求需要预期会有一些延迟。实际上，此延迟与下载所选的 Ollama 模型有关，请注意，如果您已将此模型拉取添加到 ./ollama_starter.sh 中，则此延迟将消失。
### Webhawk Agent
要在您的端点内进行检测，您需要配置并执行 webhawk agent，它位于 ./webhawk_agent 中。
```
python webhawk_agent.py -l ./HTTP_LOGS/access.log.2025-02-08
```
执行完成后，新的事件将出现在 Webhawk Web 应用程序中。
## 开发环境设置
本节的目标是帮助使用 webhawk 检测，而不使用 Web 应用程序。
对于接下来的步骤，您需要位于 ./webhawk 文件夹中。
### 使用 Python 虚拟环境
```
python -m venv webhawk_venv
source webhawk_venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
```
### 创建 settings.conf 文件
将 settings.conf.template 文件复制到 settings.conf，并按如下所示填写所需参数。
```
[FEATURES]
features:length,params_number,return_code,size,upper_cases,lower_cases,special_chars,url_depth,user_agent,http_query,ip
[LOG]
apache_regex:([(\d\.)]+) - - \[(.*?)\] "(.*?)" (\d+) (.+) "(.*?)" "(.*?)"
apache_names:["ip","date","query","code","size","referrer","user_agent"]
nginx_regex:([(\d\.)]+) - - \[(.*?)\] "(.*?)" (\d+) (\d+) (.+) "(.*?)" "(.*?)"
nginx_names:["ip","date","query","code","size","referrer","user_agent"]
http_regex:^(\d*?\.\d*?)\t.*?\t(.*?)\t.*?\t.*?\t.*?\t.*?\t(.*?\t.*?\t.*?\t.*?)\t(.*?)\t.*?\t(.*?)\t(.*?)\t.*$
http_names:["date","ip","query","user_agent","size","code"]
apache_error:
nginx_error:
[PROCESS_DETAILS]
attributes:['status', 'num_ctx_switches', 'memory_full_info', 'connections', 'cmdline', 'create_time', 'num_fds', 'cpu_percent', 'terminal', 'ppid', 'cwd', 'nice', 'username', 'cpu_times', 'memory_info', 'threads', 'open_files', 'name', 'num_threads', 'exe', 'uids', 'gids', 'memory_percent', 'environ']
[CVE]
source:https://services.nvd.nist.gov/rest/json/cves/2.0?keywordSearch=
year_threshold:YYYY
[LLM]
url:http://ollama:11434 #if using docker compose
url:http://localhost:11434 #if not using docker compose
model:intigration/analyzer:latest #or select a model of your choice
prompt:Analyze this web log line for malicious activity. Provide a brief one pragraph (less than 60 words) as a response. Indidate if there is a known related attack or vulnerability. Do not start with 'This log line'
[WEBAPP]
webhawk_ui
url:http://webhawk_ui:8080/api/v1/incidents #if using docker compose
url:http://localhost:8080/api/v1/incidents #if not using docker compose
```
## 无监督检测用法
### Catch.py 脚本
```
python catch.py -h
usage: catch.py [-h] -l LOG_FILE -t LOG_TYPE [-e EPS] [-s MIN_SAMPLES] [-j LOG_LINES_LIMIT] [-y OPT_LAMDA] [-m MINORITY_THRESHOLD] [-p] [-o] [-r] [-z] [-b] [-c] [-v] [-a] [-q]
options:
-h, --help show this help message and exit
-l, --log_file LOG_FILE
The raw log file
-t, --log_type LOG_TYPE
apache, http, nginx or os_processes
-e, --eps EPS DBSCAN Epsilon value (Max distance between two points)
-s, --min_samples MIN_SAMPLES
Minimum number of points with the same cluster. The default value is 2
-j, --log_lines_limit LOG_LINES_LIMIT
The maximum number of log lines of consider
-y, --opt_lamda OPT_LAMDA
Optimization lambda step
-m, --minority_threshold MINORITY_THRESHOLD
Minority clusters threshold
-p, --show_plots Show informative plots
-o, --standardize_data
Standardize feature values
-r, --report Create a HTML report
-z, --opt_silouhette Optimize DBSCAN silouhette
-b, --debug Activate debug logging
-c, --label_encoding Use label encoding instead of frequeny encoding to encode categorical features
-v, --find_cves Find the CVE(s) that are related to the attack traces
-a, --get_ai_advice Get AI advice on the detection
-q, --quick_scan Only most critical detection (no minority clusters)
-f, --submit_to_app Submit the finding to Webhawk app
```
### Apache 日志示例
对于无监督模式，编码是自动的。您只需运行 catch.py 脚本。
从以下示例中获取灵感：
```
python catch.py -l ./SAMPLE_DATA/RAW_APACHE_LOGS/access.log.2022-12-22 --log_type apache --standardize_data --report --find_cves --get_ai_advice
```
此命令的输出为：
### OS 进程示例
在运行 catch.py 之前，您需要通过利用 top 命令生成一个包含 OS 进程统计信息的 .txt 文件：
```
top > PATH/os_processes.txt
```
然后您可以运行 catch.py 来检测潜在的异常 OS 进程：
```
python catch.py -l PATH/os_processes.txt --log_type os_processes --show_plots --standardize_data --report
```
## Webhawk API
可以使用以下命令启动 Webhawk API：
```
uvicorn app:app --reload
```
使用以下方式测试 API：
可以使用脚本 api_test.py 或通过运行以下 python 命令来测试 API：
```
import requests
with open("./SAMPLE_DATA/RAW_APACHE_LOGS/access.log.2017-05-24",'r') as f:
logs=str(f.read())
params = {"hostname":"nothing","logs_content":logs}
response=requests.post("http://127.0.0.1:8000/scan",json=params)
print(response.json())
```
## 使用的示例数据
您在 ./SAMPLE_DATA 文件夹中找到的数据来自
https://www.secrepo.com。
## 生成您自己的测试数据
您还可以使用脚本 ./TESTING_LOGS_GENERATOR/apache_http_log_generator.py 生成测试数据
## 有趣的数据样本
https://www.kaggle.com/datasets/eliasdabbas/web-server-access-logs
https://dataverse.harvard.edu/dataset.xhtml?persistentId=doi:10.7910/DVN/3QBYB5
## TODO
为高层设计图添加更多细节
将发现逐个添加到 Webhawk UI
增强 UI
使用 Kafka（或等效工具）解耦数据传输
## 参考
轮廓系数
https://bioinformatics-training.github.io/intro-machine-learning-2017/clustering.html
Epsilon 的最佳值
https://towardsdatascience.com/machine-learning-clustering-dbscan-determine-the-optimal-value-for-epsilon-eps-python-example-3100091cfbc
最大曲率点
https://towardsdatascience.com/detecting-knee-elbow-points-in-a-graph-d13fc517a63c
## 贡献
非常欢迎所有反馈、测试和贡献！如果您想做出贡献，请 Fork 该项目，添加您的更改，并提交 Pull Request。