Skip to content

Commit 6c8a1c7

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

8 files changed

Lines changed: 474 additions & 444 deletions

File tree

‎AGENTS.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# AI Agent Instructions — OpenAEV Documentation
2+
3+
You are working on the **OpenAEV Documentation** repository, a MkDocs Material site for the OpenAEV Adversary Exposure
4+
Validation Platform.
5+
6+
## Project stack
7+
8+
- **Static site generator:** MkDocs with Material for MkDocs (Insiders)
9+
- **Content format:** Markdown (`.md`) files in `docs/`
10+
- **Config:** `mkdocs.yml` at root
11+
- **Deployment:** Mike for versioning, GitHub Pages
12+
- **Language:** English only
13+
14+
## Repository structure
15+
16+
```
17+
docs/ → Markdown source files (the documentation)
18+
overrides/ → MkDocs Material template overrides
19+
site/ → Generated output (do NOT edit)
20+
mkdocs.yml → MkDocs configuration and nav tree
21+
requirements.txt → Python dependencies
22+
```
23+
24+
## Writing style rules
25+
26+
Follow these rules strictly when creating or editing documentation:
27+
28+
### Voice and tone
29+
30+
- Use **active voice** and **present tense**: "Run the command" ✅, not "The command should be run" ❌.
31+
- Be clear, concise, and pedagogical. Avoid unnecessary jargon.
32+
- Capitalize proper nouns and frameworks: **OpenAEV**, **MITRE ATT&CK**, **REST API**, **Payload**, **Asset**, **Inject
33+
**, **Scenario**, **Simulation**.
34+
- Explain acronyms on first use: e.g., **IOC (Indicator of Compromise)**.
35+
36+
### Page structure (usage-driven, NOT "click-click" docs)
37+
38+
Every section should follow this structure:
39+
40+
1. **What is this?** — Define the concept.
41+
2. **Why use it?** — Explain the value and context.
42+
3. **How do I do it?** — Provide clear, ordered steps.
43+
4. **Example** — Add a realistic case (command, screenshot, workflow).
44+
5. **What's next?** — Suggest related pages or next steps.
45+
46+
Always start with usage and benefits, then show the execution.
47+
48+
### Markdown conventions
49+
50+
- Start each page with a short introduction explaining what the page covers.
51+
- Use `##` for sections, `###` for subsections — keep headings consistent.
52+
- Use **numbered lists** for steps.
53+
- Use **tables** for parameters, config options, and field descriptions.
54+
- Use **code blocks** with syntax highlighting for commands and configs.
55+
- Use **admonitions** for emphasis:
56+
- `!!! warning` for warnings
57+
- `!!! note` for tips/info
58+
- `!!! tip` for best practices
59+
60+
### Filenames and URIs
61+
62+
- Use **hyphens** (`-`) in filenames: `scenarios-and-simulations.md` ✅
63+
- **Never** use underscores (`_`): `scenarios_and_simulations.md` ❌
64+
65+
### Images
66+
67+
- Store images in `docs/[SECTION]/assets/`.
68+
- Use descriptive filenames: `scenario-import-global.png`.
69+
- Optimize for web (compressed, < 1 MB).
70+
71+
## When adding a new page
72+
73+
1. Create the `.md` file in the appropriate `docs/` subdirectory.
74+
2. Add the page to the `nav` section in `mkdocs.yml`.
75+
3. Add cross-links from related pages.
76+
4. Follow the usage-driven page structure above.

‎docs/usage/assets/inject-execution-details.png‎

-182 KB
Binary file not shown.

‎docs/usage/inject-chaining.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Inject chaining and transfer
2+
3+
This page covers two features that help you organize Injects beyond simple one-shot execution: **conditional chaining**
4+
to model multi-stage attacks, and **export/import** to reuse Injects across Scenarios and instances.
5+
6+
## Conditional execution
7+
8+
Conditional execution (also called **logical chaining**) lets you link Injects together so that a child Inject only
9+
runs if specific conditions on its parent are met at execution time. Conditions can be based on Expectation results
10+
(prevention, detection) or execution success/failure.
11+
12+
### Why chain Injects?
13+
14+
- **Model real attack chains**: execute lateral movement only if initial access succeeded.
15+
- **Reduce noise**: skip follow-up Injects when a prerequisite was blocked.
16+
- **Test decision trees**: simulate branching attacker behavior depending on defensive outcomes.
17+
18+
### Option 1: from the Inject update form
19+
20+
1. Open an Inject and go to the **Logical Chains** tab.
21+
2. Assign a **Parent**. The current Inject will only execute if the Parent's conditions are met.
22+
3. Assign **Children**. They will execute only if the current Inject's conditions are satisfied.
23+
4. Select the conditions: choose the relevant Expectation and toggle **Success** or **Fail**.
24+
5. Toggle the **AND / OR** operator to control whether all conditions must be met or just one.
25+
26+
![Logical chains form](assets/inject-chaining.png)
27+
![Modifying chain conditions](assets/inject-chaining-value.png)
28+
29+
!!! note
30+
31+
The AND/OR setting applies globally to all conditions of the Inject. You cannot mix operators.
32+
33+
### Option 2: from the timeline
34+
35+
1. Switch to the **timeline view** of the Injects list.
36+
2. Hover over the connection point (small dot) on the left or right of an Inject.
37+
3. Drag and drop a link to another Inject.
38+
39+
![Creating chains in the timeline](assets/inject-chaining-timeline.gif)
40+
41+
Links created this way default to the condition **"Execution is Success"**. Edit them via the Inject update form to set
42+
more specific conditions. You can reposition or remove links by dragging them to an empty area.
43+
44+
### In practice
45+
46+
You are simulating a multi-stage attack:
47+
48+
1. **Inject 1**: phishing email with a malicious attachment.
49+
2. **Inject 2**: Payload execution on the endpoint (child of Inject 1, condition: *Prevention expectation = Fail*).
50+
3. **Inject 3**: lateral movement (child of Inject 2, condition: *Execution = Success*).
51+
52+
If the EDR blocks the attachment (Prevention = Success), Inject 2 and 3 are automatically skipped.
53+
54+
---
55+
56+
## Export and import
57+
58+
The export/import feature transfers Injects, along with their configuration (arguments, content, tags, Expectations),
59+
between Simulations, Scenarios, and Atomic tests, even across different OpenAEV instances.
60+
61+
### Why export/import?
62+
63+
- **Reuse proven Injects**: export a well-tuned phishing Inject and import it into a new Scenario.
64+
- **Share across teams**: distribute standardized Injects to other operators.
65+
- **Migrate between environments**: move Injects from a lab instance to production.
66+
67+
### Export
68+
69+
1. Navigate to the Injects list in your Simulation, Scenario, or Atomic test.
70+
2. Select the Injects to export (or use the contextual menu for a single Inject).
71+
3. Choose whether to include **Teams/Players** in the export.
72+
4. Download the export file.
73+
74+
| Rule | Detail |
75+
|------|--------|
76+
| Multiple Injects | Supported for Scenarios and Simulations |
77+
| Atomic testing | Only **one** Inject per export |
78+
| Teams/Players | Optional, opt in during export |
79+
| Assets | **Never** exported |
80+
| Permissions | Read access on the source Scenario/Simulation; Admin for Atomic tests |
81+
82+
![Export popover](assets/export-popover.png)
83+
![Export from Atomic testing](assets/export-inject-atomic.png)
84+
![Export from Simulation](assets/export-inject-simulation.png)
85+
![Export from Simulation menu](assets/export-inject-simulation-menu.png)
86+
![Export from Scenario](assets/export-inject-scenario.png)
87+
![Export from Scenario menu](assets/export-inject-scenario-menu.png)
88+
89+
### Import
90+
91+
1. Navigate to the Injects list in the destination Simulation, Scenario, or Atomic test.
92+
2. Click the **import** action.
93+
3. Select the export file. Injects are created with their original configuration.
94+
95+
| Rule | Detail |
96+
|------|--------|
97+
| Cross-type import | Import from any source type into any destination type |
98+
| Permissions | Write access on the destination Scenario/Simulation; Admin for Atomic tests |
99+
100+
![Import popover](assets/import-popover.png)
101+
![Import into Atomic testing](assets/import-inject-atomic.png)
102+
![Import into Simulation](assets/import-inject-simulation.png)
103+
![Import into Scenario](assets/import-inject-scenario.png)
104+
105+
### In practice
106+
107+
Your red team built a set of credential-dumping Injects in a lab Scenario:
108+
109+
1. **Export** the Injects from the lab Scenario (include Teams).
110+
2. **Import** them into the production Simulation targeting the finance department.
111+
3. Adjust target Assets and timing. The rest of the configuration carries over.
112+
113+
## Go further
114+
115+
- Build complete attack chains with [Scenarios](scenario.md).
116+
- Import Injects from threat intelligence using [Scenario generation from OpenCTI](scenario/security-coverage.md).
117+
- Understand [Inject statuses](inject-status.md) to interpret execution results.
118+

0 commit comments

Comments
 (0)