diff --git a/docs/deployment/ecosystem/executors.md b/docs/deployment/ecosystem/executors.md index 4f9d52fb..bb414485 100644 --- a/docs/deployment/ecosystem/executors.md +++ b/docs/deployment/ecosystem/executors.md @@ -489,5 +489,5 @@ available in the OpenAEV endpoints list. Run the following commands with an administrator Powershell in order to uninstall your Caldera agent:
`schtasks /delete /tn OpenAEVCaldera`
-`Stop-Process -Name obas-agent-caldera`
-`rm -force -Recurse "C:\Program Files (x86)\Filigran\OBAS Caldera"` +`Stop-Process -Name oaev-agent-caldera`
+`rm -force -Recurse "C:\Program Files (x86)\Filigran\OAEV Caldera"` diff --git a/docs/development/collectors.md b/docs/development/collectors.md index dbb7deaa..2d1d9128 100644 --- a/docs/development/collectors.md +++ b/docs/development/collectors.md @@ -13,9 +13,9 @@ them against injected expectations in OpenAEV. Note that while this guide puts an emphasis on the Python language, a collector may be implemented in any language because it communicates with the OpenAEV server via its REST API. However, Filigran provides an official implementation - of a REST client for the OpenAEV API, in python: PyOBAS. + of a REST client for the OpenAEV API, in python: PyOAEV. -In this guide, we will use [PyOBAS](https://pypi.org/project/pyobas/), the official OpenAEV API client for Python. The guide requires a basic understanding +In this guide, we will use [PyOAEV](https://pypi.org/project/pyoaev/), the official OpenAEV API client for Python. The guide requires a basic understanding of the Python language, and a working Python install on the development machine. ### High level overview @@ -25,10 +25,10 @@ expectations from within the OpenAEV system. ![High level process overview](assets/high-level-collector-overview.png) -This would translate to this partially-pseudo code, using PyOBAS (some functions omitted for brevity): +This would translate to this partially-pseudo code, using PyOAEV (some functions omitted for brevity): ```python -from pyobas.daemons import CollectorDaemon -from pyobas.configuration import Configuration +from pyoaev.daemons import CollectorDaemon +from pyoaev.configuration import Configuration # this is where the whole of the collector logic needs # to be implemented. @@ -145,4 +145,4 @@ You may find reference implementations in the OpenAEV Collectors repository: * [Microsoft Sentinel](https://github.com/OpenAEV-Platform/collectors/tree/main/microsoft-sentinel) You might find them useful to find inspiration on how to implement a matching logic against your EDR or SIEM -of choice, using PyOBAS. +of choice, using PyOAEV. diff --git a/docs/development/injectors.md b/docs/development/injectors.md index 8a33ee45..08479793 100644 --- a/docs/development/injectors.md +++ b/docs/development/injectors.md @@ -26,7 +26,7 @@ internally to access the parameter values. !!! note "🐍 Python-based injectors" - For injectors created with the Python language, Filigran maintains the [`pyobas` library](https://pypi.org/project/pyobas/) + For injectors created with the Python language, Filigran maintains the [`pyoaev` library](https://pypi.org/project/pyoaev/) which provides a wealth of utility classes to compose a functional contract. Note however that injectors are typically independent processes communicating with OpenAEV via a network transport, diff --git a/docs/usage/inject-overview.md b/docs/usage/inject-overview.md index 170faa76..8c2f9f6a 100644 --- a/docs/usage/inject-overview.md +++ b/docs/usage/inject-overview.md @@ -185,7 +185,7 @@ 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 OBAS Server, which logs detailed execution traces. +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 @@ -215,7 +215,7 @@ Each execution step reports a status: - ❌COMMAND_NOT_FOUND – Executor couldn’t find the command - 🛑 ERROR – General failure -All execution logs are stored on the OBAS Server, which later processes them to determine agent and inject statuses. +All execution logs are stored on the OAEV Server, which later processes them to determine agent and inject statuses. **Agent Status Computation** @@ -242,7 +242,7 @@ Once an inject have been executed, it is possible to access the alerts' details 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.obas.lan` asset. We can see there are detections on +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). diff --git a/docs/usage/scenario/security-coverage.md b/docs/usage/scenario/security-coverage.md index 8c1886e6..d18a8e62 100644 --- a/docs/usage/scenario/security-coverage.md +++ b/docs/usage/scenario/security-coverage.md @@ -20,7 +20,7 @@ This integration works across multiple OpenCTI entity types: ## How It Works When you click on the **Add Security Coverage** button in -OpenCTI ([see OpenCTI documentation](https://docs.opencti.io/latest/usage/security-coverage/)), OpenAEV receives a **STIX 2.1 bundle** representing the Security Coverage. +OpenCTI ([see OpenCTI documentation](https://docs.opencti.io/latest/usage/security-coverage/)), OpenAEV receives a **STIX 2.1 bundle** representing the Security Coverage. ![Button Security Coverage](assets/octi-security-coverage-button.png) @@ -28,10 +28,14 @@ OpenAEV then: 1. Parses the STIX object 2. Builds a scenario in OpenAEV -> **Note:** At time of writing, the automated Security Coverage feature can assess coverage for the following entities: Attack Patterns + +> **Note:** At time of writing, the automated Security Coverage feature can assess coverage for the following entities: +> Attack Patterns + 3. Extracts relevant **Attack Patterns references** -4. Generates injects for each extracted entity -5. Schedules the scenario for execution +4. Resolves Asset Groups using **Custom Tag Rule** labeled `opencti`, extracting the associated **platforms and architectures** to match compatible payloads. +5. Generates injects for each extracted entity +6. Schedules the scenario for execution ## STIX Fields Used for Scenario Creation @@ -60,29 +64,56 @@ After parsing and validating the **Security Coverage STIX** object, OpenAEV foll - **Create or update an OpenAEV scenario** - ![Scenario](assets/scenario-openaev.png) +![Scenario](assets/scenario-openaev.png) - **Extract all references** related to Attack Patterns. - For each **Object Reference** identified: - - If the referenced **Object** already exists in OpenAEV as an **Attack Pattern** and a related [Payload](../payloads/payloads.md) is available → a **concrete inject** is created. - - - If the referenced **Object** does **not** exist in OpenAEV → a **Placeholder Inject** is created to highlight the missing element. - -> **Note:** To ensure meaningful inject generation, the **Attack Patterns** in OpenCTI should be aligned with those configured in OpenAEV. - -Inject creation depends on matching the **Object Reference** values between OpenCTI and OpenAEV, example: - - | OpenCTI Attack Pattern | Exists in OpenAEV? | Result | - |------------------------|--------------------|----------------------------| - | T1059.001 | Yes | Concrete inject created | - | T1059.001 | No | Placeholder inject created | + - If the referenced **Attack Pattern** exists in OpenAEV + (matched by **External ID** or **Name**) **and** a related [Payload](../payloads/payloads.md) exists that + matches the **platforms and architectures** derived from the Asset groups resolved via **Custom Tag Rule + labeled `opencti`**. + => **Concrete Inject** is created. + + - If the Attack Pattern does **not** exist in OpenAEV, or no compatible payload exists for the resolved + platforms/architectures. + => **Placeholder Inject** is created to highlight missing coverage. + +> **Note** +> To ensure meaningful inject generation: +> +> - Attack Patterns defined in **OpenCTI** (by External ID or Name) must be aligned with those configured in **OpenAEV + **. +> - Targets are resolved via **Custom Tag Rule labeled `opencti`**, and the corresponding **platforms and architectures + ** are extracted from these Asset groups. +> - Payloads are matched against the Attack Patterns **and** must be compatible with the extracted platforms and + architectures. +> +> In other words, inject creation only occurs when: +> 1. The Attack Pattern exists in OpenAEV, and +> 2. A payload exists that matches both the Attack Pattern **and** the platforms/architectures derived from the Asset groups + defined in the Custom Tag Rules. +> +> If either condition is not met, a **Placeholder Inject** is created to highlight missing coverage. + +Inject creation depends on matching the **Object Reference** values between OpenCTI and OpenAEV, example: + +| OpenCTI Attack Pattern
(External ID or Name) | Matching Payload in OpenAEV
(Attack Pattern + Platform + Architecture) | Result | +|----------------------------------------------------|------------------------------------------------------------------------------|-------------------------| +| T1059.001 | Yes | Concrete inject created | +| T1059.001 | No | Placeholder inject | ![Inject Scenario](assets/inject-scenario-openaev.png) ![Inject Placeholder Scenario](assets/inject-placeholder.png) +![Asset Rules](../assets/asset_rules.png) + +After injects are generated: -After the injects are generated, review and customize the Scenario to ensure it fits your organization’s specific needs. You will also need to assign appropriate **Targets** to each inject. Additionally, you can configure default **Asset Groups** for scenarios created from OpenCTI using the [Default Asset Groups](../default_asset_rules.md) page. +- Review and customize the **Scenario** to match your organization’s needs. +- Assign appropriate **Asset groups** to each inject. +- Optionally, configure default **Asset Groups** for scenarios created from OpenCTI using + the [Default Asset Groups](../default_asset_rules.md) page. ![Inject Asset Groups](assets/inject-asset-group.png) @@ -94,7 +125,9 @@ Once the scenario is finalized and scheduled: - OpenAEV executes the scenario according to the periodicity. - After simulation, the results are compiled into new SROs. -- OpenAEV sends these results back to OpenCTI as part of automated [Enriched Security Posture Assessment](../xtm-suite-connector.md) in the same **STIX 2.1 bundle** representing the Security Coverage. +- OpenAEV sends these results back to OpenCTI as part of + automated [Enriched Security Posture Assessment](../xtm-suite-connector.md) in the same **STIX 2.1 bundle** + representing the Security Coverage. - OpenCTI displays the updated coverage assessment. ![Octi results](assets/octi-security-coverage-results.png) @@ -103,6 +136,7 @@ This creates a complete feedback loop between threat intelligence and security v ## What’s next? -The next step is to expand the integration between OpenCTI and OpenAEV by incorporating additional threat intelligence data, such as Observables, Artifacts, Malware, and more. +The next step is to expand the integration between OpenCTI and OpenAEV by incorporating additional threat intelligence +data, such as Observables, Artifacts, Malware, and more.