Detection Rules

Detection Rules è il luogo in cui risiedono le regole utilizzate da Elastic Security. Questo repository viene utilizzato per lo sviluppo, la manutenzione, i test, la validazione e il rilascio delle regole per il Detection Engine di Elastic Security.

Questo repository è stato annunciato per la prima volta nel post del blog di Elastic, Elastic Security apre il repository pubblico delle regole di rilevamento. Per ulteriori contenuti, consulta il webinar correlato, Elastic Security: introduzione al repository pubblico per le regole di rilevamento.

Indice

Detection Rules

Panoramica di questo repository

Detection Rules contiene molto più che semplici file di regole statiche. Questo repository include anche codice per la creazione di pipeline Detections-as-code, test unitari in Python e l'integrazione con il Detection Engine in Kibana.

folder	description
`detection_rules/`	Modulo Python per l'analisi, la validazione e il confezionamento delle regole
`etc/`	File vari, come gli schemi ECS e Beats e i file di configurazione
`hunting/`	Directory principale in cui sono memorizzati i pacchetti e le query di threat hunting
`kibana/`	Libreria Python per gestire le chiamate API a Kibana e al Detection Engine
`kql/`	Libreria Python per l'analisi e la validazione del Kibana Query Language
`rules/`	Directory principale in cui sono memorizzate le regole
`rules_building_block/`	Directory principale in cui sono memorizzate le regole building block
`tests/`	Codice Python per i test unitari delle regole

Per iniziare

Anche se le regole possono essere aggiunte creando manualmente file .toml, non lo consigliamo. Questo repository include anche un modulo Python che facilita la creazione delle regole e i test unitari. Supponendo che tu abbia Python 3.12+, esegui il comando seguente per installare le dipendenze usando il makefile:

✗ make
python3.12 -m pip install --upgrade pip setuptools
Looking in indexes: https://pypi.org/simple
Requirement already satisfied: pip in /opt/homebrew/lib/python3.12/site-packages (24.0)
Requirement already satisfied: setuptools in /opt/homebrew/lib/python3.12/site-packages (69.1.1)
python3.12 -m venv ./env/detection-rules-build
./env/detection-rules-build/bin/pip install --upgrade pip setuptools
Looking in indexes: https://pypi.org/simple
Requirement already satisfied: pip in ./env/detection-rules-build/lib/python3.12/site-packages (24.0)
Collecting setuptools
  Using cached setuptools-69.1.1-py3-none-any.whl.metadata (6.2 kB)
Using cached setuptools-69.1.1-py3-none-any.whl (819 kB)
Installing collected packages: setuptools
Successfully installed setuptools-69.1.1
Installing kql and kibana packages...
...

Oppure installa le dipendenze usando il seguente comando:

$ pip3 install ".[dev]"
Collecting jsl==0.2.4
  Downloading jsl-0.2.4.tar.gz (21 kB)
Collecting jsonschema==3.2.0
  Downloading jsonschema-3.2.0-py2.py3-none-any.whl (56 kB)
     |████████████████████████████████| 56 kB 318 kB/s
Collecting requests==2.22.0
  Downloading requests-2.22.0-py2.py3-none-any.whl (57 kB)
     |████████████████████████████████| 57 kB 1.2 MB/s
Collecting Click==7.0
  Downloading Click-7.0-py2.py3-none-any.whl (81 kB)
     |████████████████████████████████| 81 kB 2.6 MB/s
...

Nota: i pacchetti kibana e kql non sono disponibili su PyPI e devono essere installati dalla directory lib. Il pacchetto hunting ha dipendenze opzionali da installare con pip3 install ".[hunting]".


# Install from the repository
pip3 install git+https://github.com/elastic/detection-rules.git#subdirectory=lib/kibana
pip3 install git+https://github.com/elastic/detection-rules.git#subdirectory=lib/kql

# Or locally for development
pip3 install lib/kibana lib/kql

Ricorda di attivare il tuo ambiente virtuale se ne utilizzi uno. Se hai installato tramite make, l'ambiente virtuale associato viene creato in env/detection-rules-build/. Se hai problemi con un ambiente Python 3.12, consulta la sezione pertinente nella nostra guida alla risoluzione dei problemi.

Per confermare che tutto sia stato installato correttamente, esegui con il flag --help

$  python -m detection_rules --help

Usage: detection_rules [OPTIONS] COMMAND [ARGS]...

  Commands for detection-rules repository.

Options:
  -D, --debug / -N, --no-debug  Print full exception stacktrace on errors
  -h, --help                    Show this message and exit.

Commands:
  build-limited-rules     Import rules from json, toml, or Kibana exported rule file(s), filter out unsupported ones, and write to output NDJSON file.
  build-threat-map-entry  Build a threat map entry.
  create-rule             Create a detection rule.
  custom-rules            Commands for supporting custom rules.
  dev                     Commands related to the Elastic Stack rules release lifecycle.
  es                      Commands for integrating with Elasticsearch.
  export-rules-from-repo  Export rule(s) and exception(s) into an importable ndjson file.
  generate-rules-index    Generate enriched indexes of rules, based on a KQL search, for indexing/importing into elasticsearch/kibana.
  import-rules-to-repo    Import rules from json, toml, or yaml files containing Kibana exported rule(s).
  kibana                  Commands for integrating with Kibana.
  mass-update             Update multiple rules based on eql results.
  normalize-data          Normalize Elasticsearch data timestamps and sort.
  rule-search             Use KQL or EQL to find matching rules.
  test                    Run unit tests over all of the rules.
  toml-lint               Cleanup files with some simple toml formatting.
  typosquat               Commands for generating typosquat detections.
  validate-all            Check if all rules validates against a schema.
  validate-rule           Check if a rule staged in rules dir validates against a schema.
  view-rule               View an internal rule or specified rule file.

Nota:

Se stai usando un ambiente virtuale, assicurati di attivarlo prima di eseguire il comando precedente.
Se usi Windows, potresti dover eseguire anche <venv_directory>\Scripts\pywin32_postinstall.py -install a seconda della versione di Python.

La guida ai contributi descrive come usare i comandi create-rule e test per creare e testare una nuova regola quando contribuisci a Detection Rules.

Per un utilizzo più avanzato dell'interfaccia a riga di comando (CLI), fai riferimento alla guida CLI.

Come contribuire

Accogliamo con piacere i tuoi contributi a Detection Rules! Prima di contribuire, familiarizza con questo repository, la sua struttura delle directory e la nostra filosofia sulla creazione di regole. Quando sei pronto a contribuire, leggi la guida ai contributi per scoprire come trasformiamo le idee di rilevamento in regole di produzione e le validiamo con i test.

Detections as Code (DaC)

Il repository Detection Rules include una serie di comandi per aiutare a gestire le regole con una filosofia "as code". Ti consigliamo di iniziare con la nostra documentazione specifica per DaC per le strategie e le informazioni sulla configurazione consigliata. Se preferisci iniziare subito, consulta la nostra documentazione locale su Detections as Code e la documentazione sulle regole personalizzate per informazioni su come configurare questo repository per l'uso con regole personalizzate, seguita dalla nostra documentazione CLI per informazioni sui comandi di importazione ed esportazione delle regole.

RTAs

Le automazioni Red Team (RTA) utilizzate per emulare le tecniche degli attaccanti e verificare le regole si trovano in un repository dedicato: Cortado.

Licenza

Tutto ciò che si trova in questo repository — regole, codice, ecc. — è concesso in licenza ai sensi della Elastic License v2. Queste regole sono progettate per essere utilizzate nel contesto del Detection Engine all'interno dell'applicazione Elastic Security. Se stai utilizzando il nostro servizio gestito Elastic Cloud o la distribuzione predefinita del software Elastic Stack che include il set completo di funzionalità gratuite, riceverai le ultime regole la prima volta che accedi al detection engine.

Occasionalmente, potremmo voler importare regole da un altro repository che hanno già una licenza, come MIT o Apache 2.0. Questo è benvenuto, purché la licenza consenta la sublicenza ai sensi della Elastic License v2. Conserviamo tali avvisi di licenza in NOTICE.txt e concediamo in sublicenza secondo la Elastic License v2 insieme a tutte le altre regole. Richiediamo inoltre ai contributori di firmare un Contributor License Agreement prima di contribuire con codice a qualsiasi repository Elastic.

Domande? Problemi? Suggerimenti?

Vuoi saperne di più sul Detection Engine? Consulta la panoramica in Kibana.
Questo repository include regole nuove e aggiornate che non sono state ancora rilasciate. Per vedere l'ultimo set di regole rilasciate con lo stack, consulta il riferimento alle regole predefinite.
Se desideri segnalare un falso positivo o un altro tipo di bug, crea una issue su GitHub e controlla prima se ne esiste già una.
Hai bisogno di aiuto con Detection Rules? Pubblica una issue o chiedi nel nostro Security Discuss Forum o nel canale #security-detection-rules all'interno dell'area di lavoro Slack.
Per casi specifici di DaC, consulta la nostra documentazione su supporto e ambito di applicazione per maggiori informazioni.

detection-rules dev-v2.1.0

Categorie