Skip to content

Commit

Permalink
Update ecs README with new tool usage
Browse files Browse the repository at this point in the history
  • Loading branch information
GitHub Actions committed Dec 31, 2024
1 parent 10b9ca6 commit 1670f33
Showing 1 changed file with 9 additions and 56 deletions.
65 changes: 9 additions & 56 deletions ecs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,8 @@ This script generates the ECS mappings for the Wazuh indices.

### Requirements

- ECS repository clone. The script is meant to be launched from the root level of that repository.
- `Python` 3.6 or higher + `venv` module
- `jq`
- [Docker Desktop](https://docs.docker.com/desktop/setup/install/linux/)
> Other option is to install the [docker-compose plugin](https://docs.docker.com/compose/install/#scenario-two-install-the-docker-compose-plugin).
### Folder structure

Expand All @@ -15,67 +14,21 @@ files to generate the mappings. These are the inputs for the ECS generator.

### Usage

1. Get a copy of the ECS repository at the same level as the `wazuh-indexer` repo:

```console
git clone [email protected]:elastic/ecs.git
```

2. Install the dependencies:

```console
cd ecs
python3 -m venv env
source env/bin/activate
pip install -r scripts/requirements.txt
```

2. Copy the `generate.sh` script to the root level of the ECS repository.

```console
cp generate.sh ../../ecs
cd ../../ecs
bash generate.sh
```

Expected output:
```
Usage: generate.sh <ECS_VERSION> <INDEXER_SRC> <MODULE> [--upload <URL>]
* ECS_VERSION: ECS version to generate mappings for
* INDEXER_SRC: Path to the wazuh-indexer repository
* MODULE: Module to generate mappings for
* --upload <URL>: Upload generated index template to the OpenSearch cluster. Defaults to https://localhost:9200
Example: generate.sh v8.11.0 ~/wazuh-indexer states-vulnerabilities --upload https://indexer:9200
```

3. Use the `generate.sh` script to generate the mappings for a module. The script takes 3 arguments,
plus 2 optional arguments to upload the mappings to the `wazuh-indexer`. Both, composable and legacy mappings
are generated. For example, to generate the mappings for the `states-vulnerabilities` module using the
ECS version `v8.11.0` and assuming that path of this repository is `~/wazuh/wazuh-indexer`:

1. Execute the mapping-generator tool
```bash
./generate.sh v8.11.0 ~/wazuh/wazuh-indexer states-vulnerabilities
bash ecs/generator/mapping-generator.sh run <MODULE_NAME>
```

The tool will output the folder where they have been generated.

```console
Loading schemas from git ref v8.11.0
Running generator. ECS version 8.11.0
Mappings saved to ~/wazuh/wazuh-indexer/ecs/states-vulnerabilities/mappings/v8.11.0
```

4. When you are done. Exit the virtual environment.

```console
deactivate
2. (Optional) Run the tool's cleanup
> The tool stops the container automatically, but it is recommended to run the down command if the tool is not going to be used anymore.
```bash
bash ecs/generator/mapping-generator.sh down
```
### Output
A new `mappings` folder will be created inside the module folder, containing all the generated files.
The files are versioned using the ECS version, so different versions of the same module can be generated.
For our use case, the most important files are under `mappings/<ECS_VERSION>/generated/elasticsearch/legacy/`:
For our use case, the most important files are under `mappings/v8.11.0/generated/elasticsearch/legacy/`:
- `template.json`: Elasticsearch compatible index template for the module
- `opensearch-template.json`: OpenSearch compatible index template for the module
Expand Down

0 comments on commit 1670f33

Please sign in to comment.