关于

open-appsec（openappsec.io）基于机器学习，提供针对OWASP十大威胁及零日攻击的主动式Web应用和API威胁防护。它可以作为附加组件部署在Linux、Docker或Kubernetes环境中，与NGINX、Kong、APISIX或Envoy集成。

open-appsec引擎会学习用户通常如何与您的Web应用交互。随后，它利用这些信息自动检测偏离正常操作模式的请求，并进一步分析以判断该请求是否具有恶意性。

每当收到HTTP请求时，系统会对所有部分进行解码，提取JSON和XML内容，并应用IP级别的访问控制。

每个发送到应用的请求都会经历两个阶段：

1. 多个变量会被输入到机器学习引擎中。这些变量或直接从HTTP请求中提取，或从有效载荷的不同部分解码而来，包括攻击指标、IP地址、用户代理、指纹等众多因素。机器学习引擎的监督模型会利用这些变量，将请求与全球范围内常见的多种攻击模式进行比对。

2. 如果请求被认定为合法有效的请求，则允许其通过并转发至您的应用。然而，若请求被视为可疑或高风险，它将进一步由在您特定环境中训练过的无监督模型进行评估。该模型会结合URL及涉及的用户等信息，生成最终置信度评分，以决定是否允许或阻止该请求。

open-appsec使用两种机器学习模型：

1. 一种是基于数百万条恶意和良性请求离线训练而成的监督模型。

   • 本仓库提供一个基础模型，建议用于仅监控和测试环境。
   • 另外还有一个更精确的高级模型，推荐用于生产环境，可从open-appsec门户 -> 用户菜单 -> 下载高级ML模型获取。该模型会定期更新，更新时您将收到电子邮件通知。

2. 另一种是无监督模型，它会在受保护的环境中实时构建。此模型会根据特定环境中的流量模式进行学习。

管理

open-appsec可以通过多种方式管理：

• 声明式配置文件
• Kubernetes Helm图表和注解
• 使用SaaS Web管理界面

open-appsec Web界面：

部署沙盒（虚拟实验室）

您可以使用Playgrounds体验open-appsec。

资源

• 项目官网
• 官方文档
• 视频教程

安装

对于使用Helm的Kubernetes环境（NGINX / Kong / APISIX / Istio）：请参考文档。

对于使用安装程序的Linux环境（NGINX / Kong / APISIX）：支持的预编译NGINX模块列表可在此处找到：

$ wget https://downloads.openappsec.io/open-appsec-install && chmod +x open-appsec-install
$ ./open-appsec-install --auto

对于基于Lua的Kong插件，请参考文档。

对于自行构建软件包的Linux用户，可使用以下命令：

$ install-cp-nano-agent.sh --install --hybrid_mode
$ install-cp-nano-service-http-transaction-handler.sh --install
$ install-cp-nano-attachment-registration-manager.sh --install

您可以在第一条命令中添加--token <token>、--email <email address>以及registered_server选项。如需获取令牌，请参阅文档。

对于Docker环境：请参考文档。

如需更多信息，请阅读文档或观看视频教程。

仓库

open-appsec GitHub包含四个主要仓库：

• openappsec/openappsec：open-appsec的核心代码和逻辑，采用C++开发。
• openappsec/attachment：负责连接提供HTTP数据的进程（例如NGINX）与open-appsec Agent安全逻辑，采用C语言开发。
• openappsec/smartsync：负责关联来自多个Agent实例的学习数据，并为每个资产生成统一的学习模型，采用Golang开发。
• openappsec/smartsync-shared-files：smartsync服务用于存储学习数据的物理存储接口，同样采用Golang开发。

编译说明

安装外部依赖

在编译服务之前，您需要确保已安装以下库和工具的最新开发版本：

• Boost
• OpenSSL
• PCRE2
• libxml2
• GTest
• GMock
• cURL
• Redis
• Hiredis
• MaxmindDB
• yq

以下是在Alpine系统上安装这些软件包的示例：

 $ apk update
 $ apk add boost-dev openssl-dev pcre2-dev libxml2-dev gtest-dev curl-dev hiredis-dev redis libmaxminddb-dev yq

编译并打包Agent代码

1. 克隆本仓库
2. 运行CMake命令
3. 执行make install命令

 $ git clone https://github.com/openappsec/openappsec.git
 $ cd openappsec/
 $ cmake -DCMAKE_INSTALL_PREFIX=build_out .
 $ make install
 $ make package

将代理代码放入 Alpine Docker 镜像中

在编译并打包好代理代码后，可以创建一个运行该代码的 Alpine 镜像。这需要具有执行 docker 命令的权限。

 $ make docker

这将为您的 Docker 创建一个名为 agent-docker 的本地镜像。

将代理 Docker 镜像部署为容器

要以容器形式运行 Nano-Agent，需执行以下步骤：

1. 如果您正在使用容器管理系统，或计划通过 CI 部署容器，请将代理 Docker 镜像添加到可访问的注册表中。
2. 如果您计划使用 open-appsec UI 来管理代理，请确保从 Management Portal 和 Enforce 中获取代理令牌。
3. 使用以下命令运行代理（其中 -e https_proxy 参数为可选）：

docker run -d --name=agent-container --ipc=host -v=<代理配置持久化路径>:/etc/cp/conf -v=<代理数据文件持久化路径>:/etc/cp/data -v=<代理调试和日志持久化路径>:/var/log/nano_agent -e https_proxy=<user:password@代理地址:端口> -e registered_server=<服务器类型> -it <代理镜像> /cp-nano-agent [--token <令牌> | --standalone]

示例：

 $ docker run -d --name=agent-container --ipc=host -v=/home/admin/agent/conf:/etc/cp/conf -v=/home/admin/agent/data:/etc/cp/data -v=/home/admin/agent/logs:/var/log/nano_agent –e https_proxy=user:password@1.2.3.4:8080 -e registered_server='nginx' -it agent-docker /cp-nano-agent --standalone
 $ docker ps
CONTAINER ID        IMAGE               COMMAND                          CREATED             STATUS              PORTS               NAMES
1e67f2abbfd4        agent-docker        "/cp-nano-agent --hybrid-mode"   1 minute ago        Up 1 minute                             agent-container

请注意，如果您在本地管理安全策略，则无需使用来自 Management Portal 的令牌。但在这种情况下，必须使用 --standalone 标志。此外，命令中的卷挂载仅在您希望代理在重启、升级或崩溃后重新启动时保持数据持久性时才为必选项。

最后，--ipc=host 参数是必需的，以便代理能够与受保护的应用程序（例如 NGINX 服务器）共享内存。

支持的 registered_server 类型包括：

• NGINX
• Kong
• KongLua
• APISIX
• Envoy

4. 使用 Attachment Repository 创建或替换 NGINX 容器。

这将使用代理 Docker 镜像运行一个 Docker 容器。

贡献

我们欢迎所有希望分享知识和专长以改进和扩展该项目的人士。

请参阅贡献指南。

安全

安全审计

open-appsec 代码于 2022 年 9 月至 10 月由独立第三方进行了安全审计。 请参阅完整报告。

报告安全漏洞

如果您发现 open-appsec 中存在漏洞或潜在漏洞，请通过 security-alert@openappsec.io 告知我们。我们将在 24 小时内发送确认邮件以确认收到您的报告，并在确认或否定问题后再次发送邮件。

许可证

open-appsec 是开源项目，采用 Apache 2.0 许可证。

基础机器学习模型也是开源的，采用 Apache 2.0 许可证。

高级机器学习模型同样是开源的，采用机器学习模型许可证，可在 tar 文件中下载获得。

openappsec 快速上手指南

openappsec 是一款基于机器学习的开源 Web 应用及 API 安全防护工具，能够防御 OWASP Top 10 及零日攻击。它支持以插件形式部署在 Linux、Docker 或 Kubernetes 环境中，兼容 NGINX、Kong、APISIX 和 Envoy 等网关。

环境准备

系统要求

• 操作系统: Linux (推荐 Alpine, Ubuntu, CentOS)
• 容器环境: Docker 或 Kubernetes (可选)
• 支持的网关: NGINX, Kong, APISIX, Envoy, Istio

前置依赖

若需从源码编译，请确保安装以下开发库的最新版本：

• Boost, OpenSSL, PCRE2, libxml2
• GTest, GMock, cURL, Redis, Hiredis
• MaxmindDB, yq

Alpine 系统安装示例：

$ apk update
$ apk add boost-dev openssl-dev pcre2-dev libxml2-dev gtest-dev curl-dev hiredis-dev redis libmaxminddb-dev yq

安装步骤

根据部署环境选择以下一种方式：

方式一：Linux 自动安装（推荐）

适用于已预编译支持的 NGINX/Kong/APISIX 环境。

$ wget https://downloads.openappsec.io/open-appsec-install && chmod +x open-appsec-install
$ ./open-appsec-install --auto

注：如需连接 SaaS 管理平台，可在命令后添加 --token <token> 和 --email <email address> 参数。

方式二：Kubernetes 部署

使用 Helm Chart 进行部署（支持 NGINX Ingress, Kong, APISIX, Istio）。 请参考官方文档执行 Helm 安装命令： https://docs.openappsec.io/getting-started/start-with-kubernetes

方式三：Docker 容器部署

若已自行编译打包，可构建并运行 Docker 容器。

1. 构建镜像

$ make docker

这将生成名为 agent-docker 的本地镜像。

2. 运行容器

$ docker run -d --name=agent-container --ipc=host -v=<path to persistent location for agent config>:/etc/cp/conf -v=<path to persistent location for agent data files>:/etc/cp/data -v=<path to persistent location for agent debugs and logs>:/var/log/nano_agent -e https_proxy=<user:password@Proxy address:port> -e registered_server=<server-type> -it <agent-image> /cp-nano-agent [--token <token> | --standalone]

运行示例（ standalone 模式）：

$ docker run -d --name=agent-container --ipc=host -v=/home/admin/agent/conf:/etc/cp/conf -v=/home/admin/agent/data:/etc/cp/data -v=/home/admin/agent/logs:/var/log/nano_agent –e https_proxy=user:password@1.2.3.4:8080 -e registered_server='nginx' -it agent-docker /cp-nano-agent --standalone

注意：--ipc=host 参数是必须的，以便代理访问共享内存；registered_server 支持 NGINX, Kong, KongLua, APISIX, Envoy。

基本使用

安装完成后，openappsec 将自动开始学习流量模式。其工作流程如下：

1. 自动学习：引擎分析传入的 HTTP 请求（包括解码 JSON/XML），提取变量（如攻击指标、IP、User-Agent 等）。
2. 双重检测：
   • 监督模型：对比全球已知攻击模式进行初步筛选。
   • 无监督模型：针对当前环境特有的流量模式进行二次评估，生成置信度评分。
3. 决策执行：合法请求被放行，高风险请求将被拦截。

管理配置

您可以通过以下方式管理策略：

• 声明式配置文件：直接编辑本地配置。
• SaaS Web UI：登录 open-appsec Portal 查看实时威胁仪表盘、下载高级机器学习模型或管理分布式节点。
• Kubernetes Annotations：通过 K8s 注解动态调整策略。

获取高级模型（生产环境推荐）

基础模型适用于测试环境。生产环境建议登录门户下载更精准的高级模型：

1. 访问 open-appsec Portal
2. 进入 User Menu -> Download advanced ML model
3. 将下载的模型部署至相应目录，系统将自动更新。

更多详细配置与视频教程请访问 官方文档。