Skip to content

Commit 694b80f

Browse files
DeniseMonrealeDeniseMonreale
authored
clarify execution vs expectation and update status hierarchy
This major rewrite fixes critical architectural and semantic inaccuracies in the Inject Status documentation
1 parent 16ceeb5 commit 694b80f

1 file changed

Lines changed: 38 additions & 28 deletions

File tree

‎docs/usage/inject-status.md‎

Lines changed: 38 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,11 @@ Every Inject execution produces a **status** that tells you the outcome at a gla
44
completion. Statuses are computed automatically from the execution traces reported by
55
[OpenAEV Agents](openaev-agent.md).
66

7+
**⚠️ IMPORTANT: Execution Status vs. Expectation Results**
8+
> 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.
9+
>
10+
> 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.
11+
712
## Why it matters
813

914
- **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
2126
| **Attack command** | Executes the actual Payload |
2227
| **Cleanup** | Removes artifacts left by the attack |
2328

24-
!!! warning
29+
!!! Note
2530

2631
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.
2732

@@ -37,64 +42,69 @@ Only tabs with at least one active target appear. Use pagination and filters to
3742

3843
## Trace statuses reference
3944

40-
Every execution step reports a **trace status**, grouped into three categories.
45+
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.
4146

42-
### Success statuses
47+
48+
### ✅ Successful Executions
4349

4450
| Status | Description | Details |
4551
|-----------------------------|-------------|---------|
46-
| `SUCCESS` | Command executed successfully | |
47-
| `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. |
48-
| `WARNING` | Command completed with stderr output | The command completed but produced stderr output. Review stderr for potential issues. |
49-
| `ACCESS DENIED` | Command blocked due to insufficient privileges | The command was denied due to insufficient privileges. The agent attempted execution but was blocked |
52+
| `EXECUTED` | Command executed to completion without system errors | *Note: This only means the command ran, not that it bypassed defenses* |
53+
| `EXECUTED WITH CLEANUP FAIL` | | Main command succeeded, but cleanup failed | Check if the action locked the file or if permissions changed during execution |
54+
| `WARNING` | Command completed but produced stderr output | Review stderr logs for potential non-blocking issues |
55+
| `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) |
5056

51-
### Error statuses
57+
### ❌ Error statuses
5258

5359
| Status | Description | Details |
5460
|------------------------------|-------------|---------|
55-
| `ERROR` | General execution failure | |
56-
| `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`. |
57-
| `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. |
58-
| `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. |
59-
| `INVALID USAGE` | Incorrect arguments or syntax | The command was invoked with incorrect arguments or syntax. Verify the inject parameters and command. |
60-
| `TIMEOUT` | Execution exceeded time threshold | The agent did not complete execution within the allowed time threshold. Consider investigating target performance. |
61-
| `INTERRUPTED` | Inject interrupted before completion | The inject was interrupted before completion. This may be caused by a system signal, user intervention, or resource constraint. |
61+
| `ERROR` | General, unclassified execution failure | Check the agent logs for detailed stack traces |
62+
| `COMMAND NOT FOUND` | Executable or binary missing on the target system | Ensure dependencies (e.g., `curl`, `powershell`) are installed in the `PATH` |
63+
| `COMMAND CANNOT BE EXECUTED` | Command exists but cannot run | Check file execute permissions (`chmod +x`) or architecture compatibility. |
64+
| `PREREQUISITE FAILED` | A prerequisite check failed before the main command | Review prerequisite dependencies and ensure they are met on the target |
65+
| `INVALID USAGE` | Incorrect arguments or syntax | The command was invoked with incorrect arguments or syntax Verify the inject parameters and command |
66+
| `TIMEOUT` | Execution exceeded time threshold | The agent did not complete execution within the allowed time threshold. Consider investigating target performance |
67+
| `INTERRUPTED` | Inject interrupted before completion | This may be caused by a system signal, user intervention, or resource constraint |
6268

63-
### Informational statuses (excluded from status computation)
69+
### ℹ️ Informational statuses (excluded from status computation)
6470

6571
| Status | Description | Details |
6672
|-------------------|-------------|---------|
6773
| `AGENT INACTIVE` | Agent was not active during Inject execution | This agent was not active during the inject execution. Check your asset connectivity. |
68-
| `ASSET AGENTLESS` | Asset has no Agent installed. | |
69-
| `INFO` | Informational trace (e.g., Agent spawn notification). | |
74+
| `ASSET AGENTLESS` | Asset has no Agent installed | Install an OpenAEV agent on the target asset |
75+
| `INFO` | Informational trace (e.g., Agent spawn notification) | |
7076

7177
!!! note "Deprecated statuses"
7278

73-
`MAYBE PREVENTED`, `PARTIAL`, and `MAYBE PARTIAL PREVENTED` are deprecated.
79+
`MAYBE PREVENTED` and `MAYBE PARTIAL PREVENTED` are deprecated.
80+
81+
## Status computation hierarchy
7482

75-
## Status computation
83+
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:
7684

77-
The OAEV Server aggregates trace statuses in two levels: first per **Agent**, then across Agents to produce the
78-
**Inject status**.
85+
1. **Agent level:** The atomic execution result on a specific endpoint (e.g., `SUCCESS` or `BLOCKED_BY_EDR`).
86+
2. **Asset level:** Aggregates the status of all agents running on that specific asset.
87+
3. **Asset Group level:** Aggregates the status of all assets within the targeted group.
88+
4. **Inject level:** The final global status displayed in the UI, aggregating all targeted asset groups and direct assets.
7989

80-
### Agent status
90+
### Agent status computation
8191

8292
The server evaluates all traces for a single Agent with the following priority rules:
8393

8494
| Priority | Condition | Resulting status |
8595
|----------|-----------|---------------------------------------------------------------------|
8696
| 1 | Any non-cleanup, non-prerequisite trace is an error | That specific error status (or `ERROR` if multiple distinct errors) |
8797
| 2 | A prerequisite failed | `PREREQUISITE FAILED` |
88-
| 3 | Execution succeeded but cleanup failed | `SUCCESS WITH CLEANUP FAIL` |
89-
| 4 | All traces succeeded | `SUCCESS` |
98+
| 3 | Execution succeeded but cleanup failed | `EXECUTED WITH CLEANUP FAIL` |
99+
| 4 | All traces succeeded | `EXECUTED` |
90100

91-
### Inject status
101+
### Inject status computation
92102

93103
The server computes the Inject-level status from per-Agent COMPLETE traces, **excluding `AGENT INACTIVE` Agents**:
94104

95105
| Condition | Inject status |
96106
|-----------|--------------|
97-
| All active Agents succeeded | <span style="color: #4caf50">**SUCCESS**</span> |
107+
| All active Agents succeeded | <span style="color: #4caf50">**EXECUTED**</span> |
98108
| All active Agents errored | <span style="color: #f44336">**ERROR**</span> |
99109
| Mix of success and error | <span style="color: #ff9800">**PARTIAL**</span> |
100110
| No active Agents | <span style="color: #f44336">**ERROR**</span> |
@@ -109,7 +119,7 @@ You run an Inject targeting three Endpoints, each with one OpenAEV Agent:
109119
| **Agent B** | Attack command blocked by EDR | `ACCESS DENIED` |
110120
| **Agent C** | Agent was offline | `AGENT INACTIVE` (excluded) |
111121

112-
One success + one error among active Agents → Inject status: **PARTIAL**.
122+
One success + one error among active Agents → The status are mixed, so the final Inject status is **PARTIAL**
113123

114124
## Alert details
115125

0 commit comments

Comments
 (0)