Skip to content

Commit 7483fef

Browse files
DeniseMonrealeDeniseMonreale
authored
[docs] Enhance Inject Result Clarity & Actionability (#284)
1 parent 6c8a1c7 commit 7483fef

1 file changed

Lines changed: 47 additions & 37 deletions

File tree

‎docs/usage/inject-status.md‎

Lines changed: 47 additions & 37 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,67 +42,72 @@ 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. This confirms the security control is working: 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
|-------------------|-------------|---------|
67-
| `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). | |
73+
| `AGENT INACTIVE` | Agent was not active during Inject execution | This agent was not active during the inject execution. Check your asset connectivity |
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

93-
The server computes the Inject-level status from per-Agent COMPLETE traces, **excluding `AGENT INACTIVE` Agents**:
103+
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:
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> |
100-
| No active Agents | <span style="color: #f44336">**ERROR**</span> |
110+
| No active Agents | <span style="color: #f44336">**ERROR**</span> *(Execution cannot succeed without at least one active agent)* |
101111

102112
## In practice
103113

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

@@ -131,16 +141,16 @@ detection was identified on an external platform, click the alert name to open i
131141

132142
When automated result retrieval is not possible (e.g., non-technical Injects), record results manually:
133143

134-
1. Open the Inject result page.
135-
2. Click the **shield** icon labeled **Add a result**.
136-
3. Fill in the result form and save.
144+
1. Open the Inject result page
145+
2. Click the **shield** icon labeled **Add a result**
146+
3. Fill in the result form and save
137147

138148
![Adding a manual result](assets/inject-expectation-manual-result-1.png)
139149
![Adding a manual result popup](assets/inject-expectation-manual-result-2.png)
140150

141151
## Go further
142152

143-
- Define [Expectations](expectations/overview.md) to set success criteria for your Injects.
144-
- Explore [Findings](findings.md) to see what was detected during execution.
145-
- Review [Inject results](inject-result.md) for a full breakdown of your security posture against a test.
153+
- Define [Expectations](expectations/overview.md) to set success criteria for your Injects
154+
- Explore [Findings](findings.md) to see what was detected during execution
155+
- Review [Inject results](inject-result.md) for a full breakdown of your security posture against a test
146156

0 commit comments

Comments
 (0)