Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 2 additions & 2 deletions docs/deployment/ecosystem/executors.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:<br/>
`schtasks /delete /tn OpenAEVCaldera`<br/>
`Stop-Process -Name obas-agent-caldera`<br/>
`rm -force -Recurse "C:\Program Files (x86)\Filigran\OBAS Caldera"`
`Stop-Process -Name oaev-agent-caldera`<br/>
`rm -force -Recurse "C:\Program Files (x86)\Filigran\OAEV Caldera"`
12 changes: 6 additions & 6 deletions docs/development/collectors.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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.
2 changes: 1 addition & 1 deletion docs/development/injectors.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
6 changes: 3 additions & 3 deletions docs/usage/inject-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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**

Expand All @@ -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).
Expand Down
74 changes: 54 additions & 20 deletions docs/usage/scenario/security-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,18 +20,22 @@ 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)

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 **targets** (e.g., Asset Groups) using **Custom Tag Rule** labeled `OpenCTI`, extracting the associated **platforms and architectures** to match compatible payloads.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you please provide more specific details?

5. Generates injects for each extracted entity
6. Schedules the scenario for execution

## STIX Fields Used for Scenario Creation

Expand Down Expand Up @@ -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 targets 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 targets.
> - 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 targets
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 <br/> (External ID or Name) | Matching Payload in OpenAEV <br/> (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 **Targets** 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)

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