Skip to content

Commit 0d349a8

Browse files
authored
[docs] add traces and inject status documentation (#62)
1 parent 0c5e777 commit 0d349a8

File tree

2 files changed

+52
-0
lines changed

2 files changed

+52
-0
lines changed
203 KB
Loading

docs/usage/injects.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -177,6 +177,58 @@ After confirming the replay of the test, the details are updated.
177177

178178
The user can also replay all the tests in the list. An icon similar to the one in the injects toolbar is available at the top of the list. After clicking on it, the user confirms the tests launch and the details are updated.
179179

180+
## Inject status
181+
182+
183+
### Inject status using OBAS agent
184+
185+
#### Viewing Execution Traces
186+
When you create a technical Inject, you assign it to endpoints, each of which may have one or multiple agents. As the inject executes, agents communicate their progress to the OBAS Server, which logs detailed execution traces.
187+
188+
In the "Execution Details" tab, traces are organized by agent, and agents are grouped by endpoint. This allows you to easily track execution progress at both the agent and endpoint levels.
189+
Each agent generates multiple traces corresponding to different execution steps, including:
190+
191+
- Prerequisite checks (validation before execution)
192+
- Prerequisite retrieval (only if the check fails)
193+
- Attack command
194+
- Cleanup commands
195+
196+
![Inject execution details](assets/inject-execution-details.png)
197+
198+
!!! warning
199+
200+
If a prerequisite check succeeds, the prerequisite retrieval step is skipped. However, the UI always marks prerequisite checks as "SUCCESS"—to verify execution results, you must inspect the stderr logs.
201+
202+
203+
**Trace Statuses**
204+
205+
Each execution step reports a status:
206+
207+
- ✅ SUCCESS – Command executed successfully
208+
- ⚠️ WARNING – Executed with minor issues
209+
- ❓MAYBE_PREVENTED – A generic error occurred, possibly due to firewall restrictions
210+
- 🚫 COMMAND_CANNOT_BE_EXECUTED – Found but couldn't execute (e.g., permission issues)
211+
- ❌COMMAND_NOT_FOUND – Executor couldn’t find the command
212+
- 🛑 ERROR – General failure
213+
214+
All execution logs are stored on the OBAS Server, which later processes them to determine agent and inject statuses.
215+
216+
217+
**Agent Status Computation**
218+
219+
When an agent completes execution, the server retrieves all traces and computes an agent status based on the following rules:
220+
221+
- All traces SUCCESS → Agent status = <span style="color: #4caf50">INJECT EXECUTED</span>
222+
- All traces ERROR → Agent status = <span style="color: #f44336">ERROR</span>
223+
- All traces MAYBE_PREVENTED → Agent status = <span style="color: #673ab7">MAYBE_PREVENTED</span>
224+
- At least one SUCCESS trace → Agent status = <span style="color: #ff9800">PARTIAL</span>
225+
- Otherwise → Agent status = MAYBE_PARTIAL_PREVENTED
226+
227+
**Inject Status Computation**
228+
229+
After all agents have completed their execution, the system calculates the Inject status using the same logic applied to compute the agent status.
230+
231+
180232
## Conditional execution of injects
181233

182234
You can add conditions to an inject, ensuring it is triggered at a specific time only if the specified conditions are met. These conditions typically relate to whether an expectation is fulfilled or not, but they can also pertain to the success or failure of an execution. There are several methods to achieve this.

0 commit comments

Comments
 (0)