diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..b454c43e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,76 @@ +# AI Agent Instructions — OpenAEV Documentation + +You are working on the **OpenAEV Documentation** repository, a MkDocs Material site for the OpenAEV Adversary Exposure +Validation Platform. + +## Project stack + +- **Static site generator:** MkDocs with Material for MkDocs (Insiders) +- **Content format:** Markdown (`.md`) files in `docs/` +- **Config:** `mkdocs.yml` at root +- **Deployment:** Mike for versioning, GitHub Pages +- **Language:** English only + +## Repository structure + +``` +docs/ → Markdown source files (the documentation) +overrides/ → MkDocs Material template overrides +site/ → Generated output (do NOT edit) +mkdocs.yml → MkDocs configuration and nav tree +requirements.txt → Python dependencies +``` + +## Writing style rules + +Follow these rules strictly when creating or editing documentation: + +### Voice and tone + +- Use **active voice** and **present tense**: "Run the command" ✅, not "The command should be run" ❌. +- Be clear, concise, and pedagogical. Avoid unnecessary jargon. +- Capitalize proper nouns and frameworks: **OpenAEV**, **MITRE ATT&CK**, **REST API**, **Payload**, **Asset**, **Inject + **, **Scenario**, **Simulation**. +- Explain acronyms on first use: e.g., **IOC (Indicator of Compromise)**. + +### Page structure (usage-driven, NOT "click-click" docs) + +Every section should follow this structure: + +1. **What is this?** — Define the concept. +2. **Why use it?** — Explain the value and context. +3. **How do I do it?** — Provide clear, ordered steps. +4. **Example** — Add a realistic case (command, screenshot, workflow). +5. **What's next?** — Suggest related pages or next steps. + +Always start with usage and benefits, then show the execution. + +### Markdown conventions + +- Start each page with a short introduction explaining what the page covers. +- Use `##` for sections, `###` for subsections — keep headings consistent. +- Use **numbered lists** for steps. +- Use **tables** for parameters, config options, and field descriptions. +- Use **code blocks** with syntax highlighting for commands and configs. +- Use **admonitions** for emphasis: + - `!!! warning` for warnings + - `!!! note` for tips/info + - `!!! tip` for best practices + +### Filenames and URIs + +- Use **hyphens** (`-`) in filenames: `scenarios-and-simulations.md` ✅ +- **Never** use underscores (`_`): `scenarios_and_simulations.md` ❌ + +### Images + +- Store images in `docs/[SECTION]/assets/`. +- Use descriptive filenames: `scenario-import-global.png`. +- Optimize for web (compressed, < 1 MB). + +## When adding a new page + +1. Create the `.md` file in the appropriate `docs/` subdirectory. +2. Add the page to the `nav` section in `mkdocs.yml`. +3. Add cross-links from related pages. +4. Follow the usage-driven page structure above. \ No newline at end of file diff --git a/docs/usage/assets/inject-execution-details.png b/docs/usage/assets/inject-execution-details.png deleted file mode 100644 index 4335b088..00000000 Binary files a/docs/usage/assets/inject-execution-details.png and /dev/null differ diff --git a/docs/usage/inject-chaining.md b/docs/usage/inject-chaining.md new file mode 100644 index 00000000..09bc420e --- /dev/null +++ b/docs/usage/inject-chaining.md @@ -0,0 +1,118 @@ +# Inject chaining and transfer + +This page covers two features that help you organize Injects beyond simple one-shot execution: **conditional chaining** +to model multi-stage attacks, and **export/import** to reuse Injects across Scenarios and instances. + +## Conditional execution + +Conditional execution (also called **logical chaining**) lets you link Injects together so that a child Inject only +runs if specific conditions on its parent are met at execution time. Conditions can be based on Expectation results +(prevention, detection) or execution success/failure. + +### Why chain Injects? + +- **Model real attack chains**: execute lateral movement only if initial access succeeded. +- **Reduce noise**: skip follow-up Injects when a prerequisite was blocked. +- **Test decision trees**: simulate branching attacker behavior depending on defensive outcomes. + +### Option 1: from the Inject update form + +1. Open an Inject and go to the **Logical Chains** tab. +2. Assign a **Parent**. The current Inject will only execute if the Parent's conditions are met. +3. Assign **Children**. They will execute only if the current Inject's conditions are satisfied. +4. Select the conditions: choose the relevant Expectation and toggle **Success** or **Fail**. +5. Toggle the **AND / OR** operator to control whether all conditions must be met or just one. + +![Logical chains form](assets/inject-chaining.png) +![Modifying chain conditions](assets/inject-chaining-value.png) + +!!! note + + The AND/OR setting applies globally to all conditions of the Inject. You cannot mix operators. + +### Option 2: from the timeline + +1. Switch to the **timeline view** of the Injects list. +2. Hover over the connection point (small dot) on the left or right of an Inject. +3. Drag and drop a link to another Inject. + +![Creating chains in the timeline](assets/inject-chaining-timeline.gif) + +Links created this way default to the condition **"Execution is Success"**. Edit them via the Inject update form to set +more specific conditions. You can reposition or remove links by dragging them to an empty area. + +### In practice + +You are simulating a multi-stage attack: + +1. **Inject 1**: phishing email with a malicious attachment. +2. **Inject 2**: Payload execution on the endpoint (child of Inject 1, condition: *Prevention expectation = Fail*). +3. **Inject 3**: lateral movement (child of Inject 2, condition: *Execution = Success*). + +If the EDR blocks the attachment (Prevention = Success), Inject 2 and 3 are automatically skipped. + +--- + +## Export and import + +The export/import feature transfers Injects, along with their configuration (arguments, content, tags, Expectations), +between Simulations, Scenarios, and Atomic tests, even across different OpenAEV instances. + +### Why export/import? + +- **Reuse proven Injects**: export a well-tuned phishing Inject and import it into a new Scenario. +- **Share across teams**: distribute standardized Injects to other operators. +- **Migrate between environments**: move Injects from a lab instance to production. + +### Export + +1. Navigate to the Injects list in your Simulation, Scenario, or Atomic test. +2. Select the Injects to export (or use the contextual menu for a single Inject). +3. Choose whether to include **Teams/Players** in the export. +4. Download the export file. + +| Rule | Detail | +|------|--------| +| Multiple Injects | Supported for Scenarios and Simulations | +| Atomic testing | Only **one** Inject per export | +| Teams/Players | Optional, opt in during export | +| Assets | **Never** exported | +| Permissions | Read access on the source Scenario/Simulation; Admin for Atomic tests | + +![Export popover](assets/export-popover.png) +![Export from Atomic testing](assets/export-inject-atomic.png) +![Export from Simulation](assets/export-inject-simulation.png) +![Export from Simulation menu](assets/export-inject-simulation-menu.png) +![Export from Scenario](assets/export-inject-scenario.png) +![Export from Scenario menu](assets/export-inject-scenario-menu.png) + +### Import + +1. Navigate to the Injects list in the destination Simulation, Scenario, or Atomic test. +2. Click the **import** action. +3. Select the export file. Injects are created with their original configuration. + +| Rule | Detail | +|------|--------| +| Cross-type import | Import from any source type into any destination type | +| Permissions | Write access on the destination Scenario/Simulation; Admin for Atomic tests | + +![Import popover](assets/import-popover.png) +![Import into Atomic testing](assets/import-inject-atomic.png) +![Import into Simulation](assets/import-inject-simulation.png) +![Import into Scenario](assets/import-inject-scenario.png) + +### In practice + +Your red team built a set of credential-dumping Injects in a lab Scenario: + +1. **Export** the Injects from the lab Scenario (include Teams). +2. **Import** them into the production Simulation targeting the finance department. +3. Adjust target Assets and timing. The rest of the configuration carries over. + +## Go further + +- Build complete attack chains with [Scenarios](scenario.md). +- Import Injects from threat intelligence using [Scenario generation from OpenCTI](scenario/security-coverage.md). +- Understand [Inject statuses](inject-status.md) to interpret execution results. + diff --git a/docs/usage/inject-overview.md b/docs/usage/inject-overview.md index c6b81506..bf6bed98 100644 --- a/docs/usage/inject-overview.md +++ b/docs/usage/inject-overview.md @@ -1,364 +1,91 @@ # Injects -Injects are fundamental elements of simulations within OpenAEV, each representing a discrete action to be executed -during a Scenario. Managed and facilitated by various [injectors](injectors.md), each inject type serves a distinct -purpose, contributing to the comprehensive evaluation of defenses. +Injects are the building blocks of security testing in OpenAEV. Each Inject represents a single action (phishing +email, command execution, DNS resolution…) that OpenAEV executes against your infrastructure during a +[Scenario](scenario.md) or as a standalone [Atomic test](atomic.md). -## Create an inject +## Create an Inject -Whether intended for [Atomic testing](atomic.md) or for a [Simulation](simulation.md), the process for creating injects -remains consistent within OpenAEV. +Creating an Inject means defining **what** to execute, **against whom**, and **what outcome to expect**. Every Inject is +powered by an [Injector](injectors.md), the connector that knows how to deliver the action (email, agent command, +API call, etc.). -![Capture of a filtered list of inject during selection process](assets/example_inject_filtering.png) +### Benefits -### For Atomic testing +- **Validate defenses**: test whether your security stack prevents or detects a specific technique. +- **Build realistic Scenarios**: combine multiple Injects into a full attack chain. +- **Measure response**: check if your teams react as expected when facing a threat. -To create an inject for atomic testing, navigate to the "Atomic testing" section located in the left-hand banner. Click -on the "+" icon in the bottom right corner to initiate the inject creation process. +### Steps -### For Scenarios and Simulations +The creation workflow is the same whether you work from Atomic testing or from a Scenario/Simulation. -For injects intended for use within simulations, access the desired Scenario or Simulation and navigate to the "Injects" -tab. Click on the "+" icon in the bottom right corner of the screen to open the inject creation panel. +#### 1. Open the creation panel -Note that an inject defined in a Scenario will be used in all the scenario's subsequent simulations. An Inject defined -at the simulation level will not be replicated into the Scenario itself, thus it will not be replicated in future -scenario's simulations. +| Context | Where to go | +|---------|-------------| +| Atomic testing | **Atomic testing** in the left menu, then click the **+** button (bottom-right) | +| Scenario / Simulation | Open the Scenario or Simulation → **Injects** tab → click the **+** button (bottom-right) | - - -### Inject creation process - -Once the inject creation panel is open, you can proceed to configure the inject according to your requirements. Key -steps in the creation process include: - -#### 1. Choose the type of inject - -You first need to select an inject in the list of available ones (on the left of the creation screen). Logos on the left -of each line indicates which Injector is associated with each [inject](inject-overview.md). Depending on your integrations, this -list can be long. - -To facilitate the selection into this possibly very long list, you can search injects by name and filter the list by -selecting a precise MITRE ATT&CK techniques for instance. - -#### 2. Set inject parameters - -When selecting an inject on the left, the form on the right populates itself with a by-default title and propose you to -define: - -- Descriptive information: Fill in details such as the title, description, and relevant tags to categorize the inject - effectively. -- Execution timing: If you are creating your inject in the context of a scenario or simulation, you have to set the - timing for when the inject should be executed within the simulation timeline, ensuring it aligns with the overall - scenario progression. - -By clicking on "Inject content", you can define now or later: - -- [Inject targets](targets.md): Specify the targets for the inject, which may include [players and teams](people.md) - or [assets and assets groups](assets.md) depending on the inject chosen. -- [Expectations](expectations.md): Define the expected outcomes or responses to the inject, outlining the desired - actions or behaviors by players. -- Attachments: Attach any relevant documents or resources to provide additional context or information related to the - inject. -- Additional fields: Depending on the type of Inject selected, you may have access to additional fields specific to that - inject type. These fields may include the subject and body of an email, channel pressure settings for public - communications, obfuscation options, and more. - -The "available variables" button helps you to use already defined variables into compatible fields. - -![screenshot of the inject creation panel](assets/email_inject_definition.png) - -By following these steps and providing the necessary information, you can create injects tailored to your specific -testing or simulation objectives. - -### Output Parsing -- The injector captures and parses the JSON output of Nuclei, and returns: - -- Confirmed findings (if any) with severity and CVE IDs - -- Other lines as unstructured output - - -### Target Selection - -The targets vary based on the provided input type: - -#### If target type is **Assets**: - -| Targeted Property | Source Property | -|---------------------|------------------------| -| Seen IP | Seen IP address | -| Local IP (first) | IP Addresses (first) | -| Hostname | Hostname | - -#### If target type is **Manual**: - -- Hostnames or IP addresses are provided directly as comma-separated values. - -### Results - -Scan results are categorized into: - -- **CVEs** (based on template classifications) -- **Other vulnerabilities** (general issues found) - -If no vulnerabilities are detected, the injector will clearly indicate this with a **"Nothing Found"** message. - -## Resources - -* [Nuclei Documentation](https://github.com/projectdiscovery/nuclei) -* [Official Nuclei Templates](https://github.com/projectdiscovery/nuclei-templates) - -## Inject tests - -You can test direct contact injects in simulations and scenarios. - -!!! warning - - For now, only email and sms inject are concerned by this feature. +![Filtered list of Injects during selection](assets/example_inject_filtering.png) !!! note - Only the latest test is displayed for each inject. - -### Unit test - -You can test injects one at a time. - -![Inject test in a Simulation](assets/inject_test_single.png) - -In the injects list of your simulation/scenario, open the contextual menu of an email or sms inject. Click on "Test". A -confirmation dialog appears, you can confirm the test or cancel it. - -![Inject test result in a Simulation](assets/inject_test_result.png) - -After launching the test, an alert appears at the top of the page. You can click on the "dedicated page" link. You are -redirected to the tests list, a drawer with the execution details of the test opens. - -![Inject test details in a Simulation](assets/inject_test_details.png) - -!!! warning - - The option is disabled if your inject doesn't have any teams. - -### Bulk test - -You can test injects in bulk. - -![Inject test in bulk in a Simulation](assets/inject_test_bulk.png) - -Select the injects you want to test then click on the bug icon. A confirmation dialog appears, you can cancel or confirm -the launch of the test. - -![Inject test in bulk in a Simulation](assets/inject_test_bulk_confirmation_dialog.png) - -As mentioned in the dialog, only sms and emails injects will be tested. The emails/sms are sent to the current user. - -After the launch of the test, you are redirected to the tests list page. - -### Replay tests - -Each test in the list has a menu allowing users to delete or replay the test. - -![Inject test replay](assets/inject_replay_test.png) - -After confirming the replay of the test, the details are updated. - -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. - -## Inject status - -### Inject status using the OpenAEV agent - -#### Navigating between active inject targets - -All targets that are selected for the inject are available on the Targets panel on the left side of the screen. There is -a -tab for each target type (Asset group, Endpoint, Agent, Team and Player), and only the tabs that have at least one -active -target are visible on the screen. - -Since there may be a large number of targets of the same type (depending on your selection), a pagination utility -with various filters is provided to help skim through the list. - -#### Viewing Execution Traces - -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 OAEV Server, which logs detailed execution traces. - -In the "Execution details" tab, you can see the traces related to the overall execution of the inject. On the " -Execution" tab -found in the inject’s overview page, you’ll find the traces for each individual target, including both -endpoints and agents. This helps you easily track the progress of the execution at both the agent and endpoint levels. -Each agent produces several traces, which represent different steps of the execution process such as: - -- Prerequisite checks (validation before execution) -- Prerequisite retrieval (only if the check fails) -- Attack command -- Cleanup commands - -![Inject execution details](assets/inject-execution-details.png) - -!!! warning - - 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. - -**Trace Statuses** - -Each execution step reports a status: - -- ✅ SUCCESS – Command executed successfully -- ⚠️ WARNING – Executed with minor issues -- ❓MAYBE_PREVENTED – A generic error occurred, possibly due to firewall restrictions -- 🚫 COMMAND_CANNOT_BE_EXECUTED – Found but couldn't execute (e.g., permission issues) -- ❌COMMAND_NOT_FOUND – Executor couldn’t find the command -- 🛑 ERROR – General failure - -All execution logs are stored on the OAEV Server, which later processes them to determine agent and inject statuses. - -**Agent Status Computation** - -When an agent completes execution, the server retrieves all traces and computes an agent status based on the following -rules: - -- All traces SUCCESS → Agent status = INJECT EXECUTED -- All traces ERROR → Agent status = ERROR -- All traces MAYBE_PREVENTED → Agent status = MAYBE_PREVENTED -- At least one SUCCESS trace → Agent status = PARTIAL -- Otherwise → Agent status = MAYBE_PARTIAL_PREVENTED - -**Inject Status Computation** - -After all agents have completed their execution, the system calculates the Inject status using the same logic applied to -compute the agent status. - -**Alert Details** - -Once an inject has been executed, it is possible to access the alerts' details on the different security platforms -(SIEM or EDR) linked to the EDRs present on the tested assets. - -![Inject execution traces details](assets/inject-expectation-traces-1.png) - -By selecting an agent on the `Targets` panel, you can access the traces details that were retrieved by OpenAEV. - -On the above example, we can see that there are 2 agents on the `vm3.oaev.lan` asset. We can see there are detections on -the -OpenAEV agent, while the Crowdstrike agent hasn't had any yet (it can take several minutes for the traces to -show up in OpenAEV). - -By clicking on the OpenAEV agent, we can see that the inject's payload was already detected by the CrowdStrike Falcon -EDR -while more detections might arrive at a later point. -We can also see that there was one alert identified on CrowdStrike Falcon EDR. - -To get the details of this alert, you can click on the CrowdStrike line to see this: - -![Inject execution traces alert details](assets/inject-expectation-traces-2.png) - -On this new panel, you can click on the alert name, and you will be redirected to the alert details on the corresponding -security platform. - -!!! warning - - It can take some time for the details to appear after the execution of an inject, sometime up to several minutes. - -#### Adding manual results - -In some cases, or for some kinds of injects, it may not be possible to automate results retrieval. In this case, you -can manually add results to an inject by clicking on the `shield` icon named `Add a result`. - -![Adding a manual result](assets/inject-expectation-manual-result-1.png) - -This will open the following popup: - -![Adding a manual result popup](assets/inject-expectation-manual-result-2.png) - -You can then fill the form with the result you want to add. - -## Conditional execution of injects - -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. - -### Using the update form - -You can set conditions when updating an inject. In the inject update form, there is a tab "Logical Chains" for that. - -![Logical chains form](assets/inject-chaining.png) - -As you can see, you can assign a Parent and multiple Children. A Parent indicates that the current inject will only -execute if the conditions set on the Parent are met at the time of execution. Similarly, a Child will execute at the -specified time only if the conditions set on the current inject are satisfied. - -The conditions you can set include the expectations for the inject and whether its execution was successful or not. You -can select the desired expectation and Success/Fail status by clicking on them. - -![Modifying chains value form](assets/inject-chaining-value.png) - -You can also toggle whether all conditions must be met or just one by clicking on the small OR/AND cards. Note that -these settings are interconnected, so you cannot assign different values to them - -### Using the timeline + An Inject defined in a Scenario applies to all subsequent Simulations of that Scenario. An Inject added directly to a Simulation is **not** replicated back into the Scenario. -You also have the possibility to quickly create conditions between injects. To do that, you can go to the timeline view -of injects and place your cursor on the small point on the left and right of each injects. You can then drag and drop a -link from a point to another. +#### 2. Choose the Inject type -![Creating chains in the timeline](assets/inject-chaining-timeline.gif) +The left panel lists all available Inject types. Each row shows the Injector logo so you can identify the source at a +glance. Use the search bar or filter by [MITRE ATT&CK](https://attack.mitre.org/) technique to narrow the list. -The links created in this way will default to an expectation of "Execution is Success" and must be updated using the -injects' update form. Additionally, you can reposition links between injects or remove them entirely by dragging them to -an empty space. +#### 3. Configure the Inject -## Export & Import Injects +Select an Inject type on the left. The right panel loads a form with a default title. Fill in: -The Export & Import functionality allows users to transfer injects between **simulations, scenarios, and atomic testings -**. Injects are exported along with their configuration details and can be imported across different instances. +| Section | What to define | +|---------|---------------| +| **General** | Title, description, tags, and execution timing (for Scenarios/Simulations) | +| **Targets** | [Endpoints and Asset groups](assets.md) or [Players and Teams](people.md) | +| **Expectations** | [Expected outcomes](expectations.md): prevention, detection, human response | +| **Attachments** | Supporting documents or resources | +| **Inject-specific fields** | Email subject/body, obfuscation options, channel pressure, etc. | -### Export Injects +Use the **available variables** button to insert predefined variables into compatible fields. -Users can export injects from **simulations, scenarios, or atomic tests**. The exported injects will retain their -configuration details, which include: +![Inject creation panel](assets/email_inject_definition.png) -- **Arguments** -- **Content** -- **Tags** -- **Expectations** +### In practice -### **Export Rules** +You want to test whether your EDR blocks a `Mimikatz` execution (MITRE ATT&CK T1003): -- **Multiple injects** can be exported at once for **scenarios and simulations**. -- **Atomic testing restriction**: Only **one atomic test** can be exported at a time. -- **Teams/Players** can be optionally included in the export. -- **Assets** are **never** exported. -- **Permissions Required**: Read privileges are required on the **Scenario** or **Simulation** to perform an export. - Atomic testings require Admin privileges. +1. Open **Atomic testing**, then click **+**. +2. Filter by technique **T1003: OS Credential Dumping**. +3. Select the matching command-line Inject. +4. Assign your target Windows Endpoint. +5. Add a **Prevention** expectation. +6. Save and launch. -![Export in atomic](assets/export-popover.png) -![Export in atomic](assets/export-inject-atomic.png) -![Export in simulation](assets/export-inject-simulation.png) -![Export in simulation menu](assets/export-inject-simulation-menu.png) -![Export in scenario](assets/export-inject-scenario.png) -![Export in scenario menu](assets/export-inject-scenario-menu.png) +--- -### **Import Injects** +## Output parsing and results -Users can import injects into **simulations, scenarios, or atomic tests**, regardless of the instance from which they -were originally exported. +Some Inject types produce structured output that OpenAEV parses automatically to extract actionable results (CVEs, +vulnerabilities, alerts…) without any manual work. The parsing logic depends on the Injector and is handled by each +integration individually. -### **Import Rules** +Many community and official integrations are available. Check the +[OpenAEV integrations repository](https://github.com/OpenAEV-Platform) for the full list of supported tools and +connectors. -- Injects from any source (atomic testing, scenarios, or simulations) can be imported into any other instance ( - scenarios, simulations, or atomic testing). -- **Permissions Required**: Write privileges are required on the **destination object** (Scenario or Simulation) to - perform an import. Atomic testings require Admin privileges. +--- -![Import in atomic](assets/import-popover.png) -![Import in atomic](assets/import-inject-atomic.png) -![Import in simulation](assets/import-inject-simulation.png) -![Import in scenario](assets/import-inject-scenario.png) +## Go further -This feature enables seamless sharing of injects across different environments, ensuring flexibility and efficiency in -exercises. +- [Inject types](inject-types.md): full list of available actions. +- [Inject tests](inject-tests.md): dry-run email and SMS Injects before launching a Simulation. +- [Inject status](inject-status.md): understand execution traces, trace statuses, and how statuses are computed. +- [Chaining and transfer](inject-chaining.md): conditional execution and export/import between Scenarios. +- [Targets](targets.md): control where the Inject runs. +- [Expectations](expectations/overview.md): define success criteria. +- [Findings](findings.md): see parsed results after execution. +- [Inject results](inject-result.md): full breakdown of your security posture against a test. diff --git a/docs/usage/inject-status.md b/docs/usage/inject-status.md new file mode 100644 index 00000000..d81ad85e --- /dev/null +++ b/docs/usage/inject-status.md @@ -0,0 +1,146 @@ +# Inject status + +Every Inject execution produces a **status** that tells you the outcome at a glance: success, failure, or partial +completion. Statuses are computed automatically from the execution traces reported by +[OpenAEV Agents](openaev-agent.md). + +## Why it matters + +- **Diagnose at a glance**: know immediately whether an Inject worked, failed, or was blocked. +- **Prioritize investigation**: focus on `ERROR` or `PARTIAL` results instead of reviewing every trace manually. + +## Execution traces + +When an Inject targets [Endpoints](assets.md), each installed Agent reports its progress to the OAEV Server as +**execution traces**, structured log entries for each step of the process: + +| Step | Description | +|------|-------------| +| **Prerequisite check** | Validates required conditions before execution | +| **Prerequisite retrieval** | Installs missing prerequisites (only if the check fails) | +| **Attack command** | Executes the actual Payload | +| **Cleanup** | Removes artifacts left by the attack | + +!!! warning + + 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. + +### Where to find traces + +| Location | Content | +|----------|---------| +| **Execution details** tab (Inject result page) | Traces for the overall Inject execution | +| **Execution** tab (Inject overview page) | Per-target traces, including Endpoints and individual Agents | + +The **Targets** panel (left side) lists every target organized by type (Asset group, Endpoint, Agent, Team, Player). +Only tabs with at least one active target appear. Use pagination and filters to navigate large lists. + +## Trace statuses reference + +Every execution step reports a **trace status**, grouped into three categories. + +### Success statuses + +| 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. | + +### 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. | + +### 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). | | + +!!! note "Deprecated statuses" + + `MAYBE PREVENTED`, `PARTIAL`, and `MAYBE PARTIAL PREVENTED` are deprecated. + +## Status computation + +The OAEV Server aggregates trace statuses in two levels: first per **Agent**, then across Agents to produce the +**Inject status**. + +### Agent status + +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` | + +### Inject status + +The server computes the Inject-level status from per-Agent COMPLETE traces, **excluding `AGENT INACTIVE` Agents**: + +| Condition | Inject status | +|-----------|--------------| +| All active Agents succeeded | **SUCCESS** | +| All active Agents errored | **ERROR** | +| Mix of success and error | **PARTIAL** | +| No active Agents | **ERROR** | + +## In practice + +You run an Inject targeting three Endpoints, each with one OpenAEV Agent: + +| Agent | What happened | Agent status | +|-------|--------------|-----------------------------| +| **Agent A** | Attack command succeeds, cleanup fails | `SUCCESS WITH CLEANUP FAIL` | +| **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**. + +## Alert details + +After execution, OpenAEV retrieves alert data from connected security platforms (SIEM, EDR) so you can correlate Inject +activity with real detections. + +![Inject execution traces details](assets/inject-expectation-traces-1.png) + +Select an Agent in the **Targets** panel to view its detection traces. Click the Agent name to expand traces. If a +detection was identified on an external platform, click the alert name to open it directly in that platform. + +![Inject execution traces alert details](assets/inject-expectation-traces-2.png) + +!!! warning + + Detection data can take several minutes to appear in OpenAEV after Inject execution. + +## Adding manual results + +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. + +![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. + diff --git a/docs/usage/inject-tests.md b/docs/usage/inject-tests.md new file mode 100644 index 00000000..aab5095d --- /dev/null +++ b/docs/usage/inject-tests.md @@ -0,0 +1,62 @@ +# Inject tests + +Inject tests let you **dry-run** direct-contact Injects (email, SMS) before launching a real Simulation. OpenAEV sends +the Inject to the current user so you can verify content, formatting, and delivery without impacting participants. + +## Why test first? + +- **Catch errors early**: spot typos, broken links, or wrong variables before the Simulation starts. +- **Validate delivery**: confirm that emails and SMS actually arrive. +- **Iterate quickly**: replay tests until the content is right. + +!!! warning + + Only **email** and **SMS** Injects support testing. The test option is disabled if the Inject has no assigned Teams. + +!!! note + + Only the latest test result is displayed for each Inject. + +## Single test + +1. In the Injects list of your Simulation or Scenario, open the contextual menu of an email or SMS Inject. +2. Click **Test** and confirm. +3. An alert appears at the top of the page. Click the **dedicated page** link to view execution details. + +![Single Inject test](assets/inject_test_single.png) +![Inject test result](assets/inject_test_result.png) +![Inject test details](assets/inject_test_details.png) + +## Bulk test + +1. Select the Injects you want to test. +2. Click the **bug** icon in the toolbar and confirm. +3. OpenAEV sends all eligible email/SMS Injects to the current user and redirects you to the tests list. + +![Bulk test selection](assets/inject_test_bulk.png) +![Bulk test confirmation](assets/inject_test_bulk_confirmation_dialog.png) + +## Replay + +Each test in the list has a contextual menu to **replay** or **delete** it. You can also replay all tests at once using +the replay icon at the top of the list. + +![Replay test](assets/inject_replay_test.png) + +## In practice + +You are preparing a phishing awareness Simulation with a custom email template: + +1. Create the email Inject with your template and variables. +2. Run a single test. You receive the email in your own inbox. +3. Notice a broken `{{redirectUrl}}` variable, fix it in the Inject. +4. Replay the test. The email now renders correctly. +5. Launch the Simulation with confidence. + +## Go further + +- Set up [Expectations](expectations/overview.md) to define what a successful test looks like. +- Explore [Notifications](notifications.md) to understand how OpenAEV alerts participants. +- Understand [Inject statuses](inject-status.md) to interpret execution results. + += \ No newline at end of file diff --git a/docs/usage/inject-types.md b/docs/usage/inject-types.md index c63cbd4d..11d7faab 100644 --- a/docs/usage/inject-types.md +++ b/docs/usage/inject-types.md @@ -74,118 +74,16 @@ HTTP requests GET, POST, and PUT, can be sent. The corresponding injects are nam -## Integrations with Agents and CyberRanges +## Technical Injects via the OpenAEV Agent -Injects executed on remote systems are facilitated by Injectors like [Caldera](inject-caldera.md) or Airbus CyberRange. -These actions simulate real-world attack techniques, allowing administrators to gauge the effectiveness of their -security posture in response to various technical actions attackers may take. +Technical Injects execute commands and Payloads directly on target Endpoints through the +[OpenAEV Agent](openaev-agent.md). They simulate real-world attack techniques, allowing you to gauge the effectiveness +of your security posture against the actions an attacker would take. -There are over 1,700 such injects covering all the TTPs in the MITRE ATT&CK matrix. +## Agentless Injectors -## Nmap +Some Injects do not require an Agent on the target. Injectors like Nmap or Nuclei run scans and attacks remotely, +targeting endpoints by IP or hostname without any installed agent. -### Behavior - -The injector enables new inject contracts, supporting the following Nmap scan types: - -#### Nmap - FIN Scan - -Command executed: - -```shell -nmap -Pn -sF -``` - -#### Nmap - SYN Scan - -Command executed: - -```shell -nmap -Pn -sS -``` - -#### Nmap - TCP Connect Scan - -Command executed: - -```shell -nmap -Pn -sT -``` - -#### Target Selection - -The targets vary based on the provided options: - -If type of targets is Assets: - -| Targeted property | Asset property | -|-------------------|----------------------| -| Seen IP | Seen IP address | -| Local IP (first) | IP Addresses (first) | -| Hostname | Hostname | - -If type of targets is Manual: - -- Hostnames or IP addresses are provided directly as comma-separated values. - -### Resources - -- Official Nmap Documentation: https://nmap.org/docs.html -- Options Explanation: - - -Pn: Host Discovery - - -sS: SYN Scan - - -sT: TCP Connect Scan - - -sF: FIN Scan - -## Nuclei - -### Behavior - -The Nuclei injector supports contract-based scans by dynamically constructing and executing Nuclei commands based on provided tags or templates. - -#### Supported Contracts - -The following scan types are supported via `-tags`: - -- Cloud -- Misconfiguration -- Exposure -- Panel -- XSS -- WordPress -- HTTP - -The CVE scan uses the `-tags cve` argument and enforces JSON output. - -The Template scan accepts a manual template via `-t