Skip to content

Update 'ACCESS DENIED' status description #286

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
RomuDeuxfois merged 4 commits into from
Apr 24, 2026
Merged

Update 'ACCESS DENIED' status description #286

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
16ceeb5
Update 'ACCESS DENIED' status description
DeniseMonreale Apr 23, 2026
694b80f
clarify execution vs expectation and update status hierarchy
DeniseMonreale Apr 24, 2026
a6e3339
2 EME Update inject status computation explanation
DeniseMonreale Apr 24, 2026
0bdfdbe
Updated grammar
DeniseMonreale Apr 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 47 additions & 37 deletions docs/usage/inject-status.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.

Expand All @@ -37,67 +42,72 @@ 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. This confirms the security control is working: 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). | |
| `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) | |

!!! 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:

| Priority | Condition | Resulting status |
|----------|-----------|---------------------------------------------------------------------|
| 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**:
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 | <span style="color: #4caf50">**SUCCESS**</span> |
| All active Agents succeeded | <span style="color: #4caf50">**EXECUTED**</span> |
| All active Agents errored | <span style="color: #f44336">**ERROR**</span> |
| Mix of success and error | <span style="color: #ff9800">**PARTIAL**</span> |
| No active Agents | <span style="color: #f44336">**ERROR**</span> |
| No active Agents | <span style="color: #f44336">**ERROR**</span> *(Execution cannot succeed without at least one active agent)* |

## In practice

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

Expand All @@ -131,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