From 16ceeb59e792b7263c63da28de38c3a53016982f Mon Sep 17 00:00:00 2001 From: Denise Date: Thu, 23 Apr 2026 15:24:18 +0200 Subject: [PATCH 1/4] Update 'ACCESS DENIED' status description Clarified the description for 'ACCESS DENIED' status. --- docs/usage/inject-status.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/inject-status.md b/docs/usage/inject-status.md index d81ad85e..2d2159a8 100644 --- a/docs/usage/inject-status.md +++ b/docs/usage/inject-status.md @@ -46,7 +46,7 @@ Every execution step reports a **trace status**, grouped into three categories. | `SUCCESS` | Command executed successfully | | | `SUCCESS WITH CLEANUP FAIL` | Main command succeeded, but cleanup failed | The main command executed successfully, but the cleanup step failed. Check cleanup prerequisites and logs on the target. | | `WARNING` | Command completed with stderr output | The command completed but produced stderr output. Review stderr for potential issues. | -| `ACCESS DENIED` | Command blocked due to insufficient privileges | The command was denied due to insufficient privileges. This confirms the security control is working: the agent attempted execution but was blocked. | +| `ACCESS DENIED` | Command blocked due to insufficient privileges | The command was denied due to insufficient privileges. The agent attempted execution but was blocked | ### Error statuses From 694b80f66f340acfe0e2fa2ad7116b5c2d4640a9 Mon Sep 17 00:00:00 2001 From: Denise Date: Fri, 24 Apr 2026 15:25:55 +0200 Subject: [PATCH 2/4] clarify execution vs expectation and update status hierarchy This major rewrite fixes critical architectural and semantic inaccuracies in the Inject Status documentation --- docs/usage/inject-status.md | 66 +++++++++++++++++++++---------------- 1 file changed, 38 insertions(+), 28 deletions(-) diff --git a/docs/usage/inject-status.md b/docs/usage/inject-status.md index 2d2159a8..1b5eac2f 100644 --- a/docs/usage/inject-status.md +++ b/docs/usage/inject-status.md @@ -4,6 +4,11 @@ Every Inject execution produces a **status** that tells you the outcome at a gla completion. Statuses are computed automatically from the execution traces reported by [OpenAEV Agents](openaev-agent.md). +**⚠️ IMPORTANT: Execution Status vs. Expectation Results** +> The **Execution Status** strictly reflects the *operational state* of the action (e.g., did the command run, crash, or time out); It exists **only to give the user visibility into the technical execution** of the injector. +> +> Execution Status **DOES NOT** represent your security posture. To evaluate if an attack was actually detected or prevented by your security controls, you must refer to **Expectation Results**, which gather data directly from OpenAEV Collectors. + ## Why it matters - **Diagnose at a glance**: know immediately whether an Inject worked, failed, or was blocked. @@ -21,7 +26,7 @@ When an Inject targets [Endpoints](assets.md), each installed Agent reports its | **Attack command** | Executes the actual Payload | | **Cleanup** | Removes artifacts left by the attack | -!!! warning +!!! Note If a prerequisite check succeeds, the retrieval step is skipped. The UI always marks prerequisite checks as "SUCCESS". Inspect the stderr logs to verify actual execution results. @@ -37,47 +42,52 @@ Only tabs with at least one active target appear. Use pagination and filters to ## Trace statuses reference -Every execution step reports a **trace status**, grouped into three categories. +Every execution step reports a **trace status**. Below is the complete list of actionable execution statuses, divided into logical categories to help operators troubleshoot technical issues. -### Success statuses + +### ✅ Successful Executions | Status | Description | Details | |-----------------------------|-------------|---------| -| `SUCCESS` | Command executed successfully | | -| `SUCCESS WITH CLEANUP FAIL` | Main command succeeded, but cleanup failed | The main command executed successfully, but the cleanup step failed. Check cleanup prerequisites and logs on the target. | -| `WARNING` | Command completed with stderr output | The command completed but produced stderr output. Review stderr for potential issues. | -| `ACCESS DENIED` | Command blocked due to insufficient privileges | The command was denied due to insufficient privileges. The agent attempted execution but was blocked | +| `EXECUTED` | Command executed to completion without system errors | *Note: This only means the command ran, not that it bypassed defenses* | +| `EXECUTED WITH CLEANUP FAIL` | | Main command succeeded, but cleanup failed | Check if the action locked the file or if permissions changed during execution | +| `WARNING` | Command completed but produced stderr output | Review stderr logs for potential non-blocking issues | +| `ACCESS DENIED` | Command denied by the OS due to insufficient privileges | Check if the agent is running with the required rights (e.g., Admin/Root) | -### Error statuses +### ❌ Error statuses | Status | Description | Details | |------------------------------|-------------|---------| -| `ERROR` | General execution failure | | -| `COMMAND NOT FOUND` | Command not found on the target | The command was not found on the target. Ensure the tool is installed and available in the system `PATH`. | -| `COMMAND CANNOT BE EXECUTED` | Command exists but cannot run | The command exists but cannot be executed. Check file permissions and ensure the binary has execute rights. | -| `PREREQUISITE FAILED` | Prerequisite check failed | A prerequisite check failed before the main command could run. Review prerequisite dependencies and ensure they are met on the target. | -| `INVALID USAGE` | Incorrect arguments or syntax | The command was invoked with incorrect arguments or syntax. Verify the inject parameters and command. | -| `TIMEOUT` | Execution exceeded time threshold | The agent did not complete execution within the allowed time threshold. Consider investigating target performance. | -| `INTERRUPTED` | Inject interrupted before completion | The inject was interrupted before completion. This may be caused by a system signal, user intervention, or resource constraint. | +| `ERROR` | General, unclassified execution failure | Check the agent logs for detailed stack traces | +| `COMMAND NOT FOUND` | Executable or binary missing on the target system | Ensure dependencies (e.g., `curl`, `powershell`) are installed in the `PATH` | +| `COMMAND CANNOT BE EXECUTED` | Command exists but cannot run | Check file execute permissions (`chmod +x`) or architecture compatibility. | +| `PREREQUISITE FAILED` | A prerequisite check failed before the main command | Review prerequisite dependencies and ensure they are met on the target | +| `INVALID USAGE` | Incorrect arguments or syntax | The command was invoked with incorrect arguments or syntax Verify the inject parameters and command | +| `TIMEOUT` | Execution exceeded time threshold | The agent did not complete execution within the allowed time threshold. Consider investigating target performance | +| `INTERRUPTED` | Inject interrupted before completion | This may be caused by a system signal, user intervention, or resource constraint | -### Informational statuses (excluded from status computation) +### ℹ️ Informational statuses (excluded from status computation) | Status | Description | Details | |-------------------|-------------|---------| | `AGENT INACTIVE` | Agent was not active during Inject execution | This agent was not active during the inject execution. Check your asset connectivity. | -| `ASSET AGENTLESS` | Asset has no Agent installed. | | -| `INFO` | Informational trace (e.g., Agent spawn notification). | | +| `ASSET AGENTLESS` | Asset has no Agent installed | Install an OpenAEV agent on the target asset | +| `INFO` | Informational trace (e.g., Agent spawn notification) | | !!! note "Deprecated statuses" - `MAYBE PREVENTED`, `PARTIAL`, and `MAYBE PARTIAL PREVENTED` are deprecated. + `MAYBE PREVENTED` and `MAYBE PARTIAL PREVENTED` are deprecated. + +## Status computation hierarchy -## Status computation +In OpenAEV, the execution status is not a simple average of agents. The platform computes the final status by bubbling up the results through the architectural hierarchy: -The OAEV Server aggregates trace statuses in two levels: first per **Agent**, then across Agents to produce the -**Inject status**. +1. **Agent level:** The atomic execution result on a specific endpoint (e.g., `SUCCESS` or `BLOCKED_BY_EDR`). +2. **Asset level:** Aggregates the status of all agents running on that specific asset. +3. **Asset Group level:** Aggregates the status of all assets within the targeted group. +4. **Inject level:** The final global status displayed in the UI, aggregating all targeted asset groups and direct assets. -### Agent status +### Agent status computation The server evaluates all traces for a single Agent with the following priority rules: @@ -85,16 +95,16 @@ The server evaluates all traces for a single Agent with the following priority r |----------|-----------|---------------------------------------------------------------------| | 1 | Any non-cleanup, non-prerequisite trace is an error | That specific error status (or `ERROR` if multiple distinct errors) | | 2 | A prerequisite failed | `PREREQUISITE FAILED` | -| 3 | Execution succeeded but cleanup failed | `SUCCESS WITH CLEANUP FAIL` | -| 4 | All traces succeeded | `SUCCESS` | +| 3 | Execution succeeded but cleanup failed | `EXECUTED WITH CLEANUP FAIL` | +| 4 | All traces succeeded | `EXECUTED` | -### Inject status +### Inject status computation The server computes the Inject-level status from per-Agent COMPLETE traces, **excluding `AGENT INACTIVE` Agents**: | Condition | Inject status | |-----------|--------------| -| All active Agents succeeded | **SUCCESS** | +| All active Agents succeeded | **EXECUTED** | | All active Agents errored | **ERROR** | | Mix of success and error | **PARTIAL** | | No active Agents | **ERROR** | @@ -109,7 +119,7 @@ You run an Inject targeting three Endpoints, each with one OpenAEV Agent: | **Agent B** | Attack command blocked by EDR | `ACCESS DENIED` | | **Agent C** | Agent was offline | `AGENT INACTIVE` (excluded) | -One success + one error among active Agents → Inject status: **PARTIAL**. +One success + one error among active Agents → The status are mixed, so the final Inject status is **PARTIAL** ## Alert details From a6e3339ea11b287f6e9ab48548fd1fa6601e5010 Mon Sep 17 00:00:00 2001 From: Denise Date: Fri, 24 Apr 2026 15:39:57 +0200 Subject: [PATCH 3/4] 2 EME Update inject status computation explanation Clarify that execution fails if no agents are active --- docs/usage/inject-status.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/usage/inject-status.md b/docs/usage/inject-status.md index 1b5eac2f..67c26c8e 100644 --- a/docs/usage/inject-status.md +++ b/docs/usage/inject-status.md @@ -100,14 +100,14 @@ The server evaluates all traces for a single Agent with the following priority r ### Inject status computation -The server computes the Inject-level status from per-Agent COMPLETE traces, **excluding `AGENT INACTIVE` Agents**: +The server computes the Inject-level status from per-Agent COMPLETE traces, **excluding `AGENT INACTIVE` Agents**. However, if *no* agents were active, the execution fails: | Condition | Inject status | |-----------|--------------| | All active Agents succeeded | **EXECUTED** | | All active Agents errored | **ERROR** | | Mix of success and error | **PARTIAL** | -| No active Agents | **ERROR** | +| No active Agents | **ERROR** *(Execution cannot succeed without at least one active agent)* | ## In practice From 0bdfdbeba0527d5d9dead4ab139ac48ca7d65f63 Mon Sep 17 00:00:00 2001 From: Denise Date: Fri, 24 Apr 2026 16:14:36 +0200 Subject: [PATCH 4/4] Updated grammar Updated descriptions --- docs/usage/inject-status.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/usage/inject-status.md b/docs/usage/inject-status.md index 67c26c8e..82be1868 100644 --- a/docs/usage/inject-status.md +++ b/docs/usage/inject-status.md @@ -50,7 +50,7 @@ Every execution step reports a **trace status**. Below is the complete list of a | Status | Description | Details | |-----------------------------|-------------|---------| | `EXECUTED` | Command executed to completion without system errors | *Note: This only means the command ran, not that it bypassed defenses* | -| `EXECUTED WITH CLEANUP FAIL` | | Main command succeeded, but cleanup failed | Check if the action locked the file or if permissions changed during execution | +| `EXECUTED WITH CLEANUP FAIL` | Main command succeeded, but cleanup failed | Check if the action locked the file or if permissions changed during execution | | `WARNING` | Command completed but produced stderr output | Review stderr logs for potential non-blocking issues | | `ACCESS DENIED` | Command denied by the OS due to insufficient privileges | Check if the agent is running with the required rights (e.g., Admin/Root) | @@ -60,7 +60,7 @@ Every execution step reports a **trace status**. Below is the complete list of a |------------------------------|-------------|---------| | `ERROR` | General, unclassified execution failure | Check the agent logs for detailed stack traces | | `COMMAND NOT FOUND` | Executable or binary missing on the target system | Ensure dependencies (e.g., `curl`, `powershell`) are installed in the `PATH` | -| `COMMAND CANNOT BE EXECUTED` | Command exists but cannot run | Check file execute permissions (`chmod +x`) or architecture compatibility. | +| `COMMAND CANNOT BE EXECUTED` | Command exists but cannot run | Check file execute permissions (`chmod +x`) or architecture compatibility | | `PREREQUISITE FAILED` | A prerequisite check failed before the main command | Review prerequisite dependencies and ensure they are met on the target | | `INVALID USAGE` | Incorrect arguments or syntax | The command was invoked with incorrect arguments or syntax Verify the inject parameters and command | | `TIMEOUT` | Execution exceeded time threshold | The agent did not complete execution within the allowed time threshold. Consider investigating target performance | @@ -70,7 +70,7 @@ Every execution step reports a **trace status**. Below is the complete list of a | Status | Description | Details | |-------------------|-------------|---------| -| `AGENT INACTIVE` | Agent was not active during Inject execution | This agent was not active during the inject execution. Check your asset connectivity. | +| `AGENT INACTIVE` | Agent was not active during Inject execution | This agent was not active during the inject execution. Check your asset connectivity | | `ASSET AGENTLESS` | Asset has no Agent installed | Install an OpenAEV agent on the target asset | | `INFO` | Informational trace (e.g., Agent spawn notification) | | @@ -141,16 +141,16 @@ detection was identified on an external platform, click the alert name to open i When automated result retrieval is not possible (e.g., non-technical Injects), record results manually: -1. Open the Inject result page. -2. Click the **shield** icon labeled **Add a result**. -3. Fill in the result form and save. +1. Open the Inject result page +2. Click the **shield** icon labeled **Add a result** +3. Fill in the result form and save ![Adding a manual result](assets/inject-expectation-manual-result-1.png) ![Adding a manual result popup](assets/inject-expectation-manual-result-2.png) ## Go further -- Define [Expectations](expectations/overview.md) to set success criteria for your Injects. -- Explore [Findings](findings.md) to see what was detected during execution. -- Review [Inject results](inject-result.md) for a full breakdown of your security posture against a test. +- Define [Expectations](expectations/overview.md) to set success criteria for your Injects +- Explore [Findings](findings.md) to see what was detected during execution +- Review [Inject results](inject-result.md) for a full breakdown of your security posture against a test