elastic/detection-rulesطوّر، وتحقق من صحة، وانشر قواعد كشف SIEM لمنصة Elastic Security، مع أدوات Python CLI، وتحليل KQL، وتكامل مع Kibana، واستعلامات صيد تهديدات مُعبأة.
قواعد الكشف هي الموطن للقواعد المستخدمة في Elastic Security. يُستخدم هذا المستودع لتطوير وصيانة واختبار والتحقق وإصدار القواعد الخاصة بمحرك الكشف في Elastic Security.
تم الإعلان عن هذا المستودع لأول مرة في منشور مدونة Elastic، Elastic Security تفتح مستودع قواعد الكشف العام. لمحتوى إضافي، راجع الندوة عبر الويب المصاحبة، Elastic Security: تقديم المستودع العام لقواعد الكشف.
تحتوي قواعد الكشف على أكثر من مجرد ملفات قواعد ثابتة. يحتوي هذا المستودع أيضًا على كود لبناء خطوط أنابيب الكشوفات كرمز، واختبار الوحدات في Python، والتكامل مع محرك الكشف في Kibana.
على الرغم من إمكانية إضافة القواعد عن طريق إنشاء ملفات .toml يدويًا، إلا أننا لا نوصي بذلك. يتكون هذا المستودع أيضًا من وحدة Python تساعد في إنشاء القواعد واختبار الوحدات. بافتراض أن لديك Python 3.12+، قم بتشغيل الأمر أدناه لتثبيت التبعيات باستخدام 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...
...
أو قم بتثبيت التبعيات باستخدام الأمر التالي:
$ 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
...
ملاحظة: حزمتا kibana و kql غير متوفرتين على PyPI ويجب تثبيتهما من دليل lib. تحتوي حزمة hunting على تبعيات اختيارية يتم تثبيتها باستخدام 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
تذكر، تأكد من تفعيل البيئة الافتراضية إذا كنت تستخدم واحدة. إذا تم التثبيت عبر make، فسيتم إنشاء البيئة الافتراضية المرتبطة في env/detection-rules-build/. إذا كنت تواجه مشكلة في استخدام بيئة Python 3.12، فيرجى الاطلاع على القسم ذي الصلة في دليل استكشاف الأخطاء وإصلاحها.
لتأكيد أن كل شيء تم تثبيته بشكل صحيح، قم بتشغيل الأمر مع العلامة --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.
ملاحظة:
<venv_directory>\Scripts\pywin32_postinstall.py -install اعتمادًا على إصدار Python لديك.يشرح دليل المساهمة كيفية استخدام أمرَي create-rule و test لإنشاء واختبار قاعدة جديدة عند المساهمة في قواعد الكشف.
للاستخدام الأكثر تقدمًا لواجهة سطر الأوامر (CLI)، راجع دليل CLI.
نرحب بمساهماتكم في قواعد الكشف! قبل المساهمة، يرجى التعرف على هذا المستودع، وهيكل الدليل، وفلسفتنا حول إنشاء القواعد. عندما تكون مستعدًا للمساهمة، اقرأ دليل المساهمة لتعلم كيف نحول أفكار الكشف إلى قواعد إنتاج ونتحقق منها من خلال الاختبار.
يتضمن مستودع قواعد الكشف عددًا من الأوامر لمساعدة المرء على إدارة القواعد بفلسفة «كرمز». نوصي بالبدء بـ توثيق DaC المحدد للاستراتيجيات ومعلومات الإعداد الموصى بها. ومع ذلك، إذا كنت تفضل البدء مباشرة، فيرجى الاطلاع على توثيق الكشوفات كرمز المحلي وتوثيق القواعد المخصصة للحصول على معلومات حول كيفية تكوين هذا المستودع للاستخدام مع القواعد المخصصة، متبوعًا بـ توثيق CLI للحصول على معلومات حول أوامرنا لاستيراد القواعد وتصديرها.
يمكن العثور على أتمتة الفريق الأحمر (RTAs) المستخدمة لمحاكاة تقنيات المهاجم والتحقق من القواعد في مستودع مخصص - Cortado.
كل شيء في هذا المستودع — القواعد والكود وما إلى ذلك — مرخص بموجب رخصة Elastic v2. صُممت هذه القواعد لاستخدامها في سياق محرك الكشف داخل تطبيق Elastic Security. إذا كنت تستخدم خدمة Elastic Cloud المُدارة أو التوزيعة الافتراضية لبرنامج Elastic Stack التي تتضمن المجموعة الكاملة من الميزات المجانية، فستحصل على أحدث القواعد في المرة الأولى التي تنتقل فيها إلى محرك الكشف.
من حين لآخر، قد نرغب في استيراد قواعد من مستودع آخر لديها بالفعل ترخيص، مثل MIT أو Apache 2.0. هذا مرحب به، طالما أن الترخيص يسمح بالترخيص من الباطن بموجب رخصة Elastic v2. نحتفظ بإشعارات الترخيص هذه في NOTICE.txt ونرخّص من الباطن بموجب رخصة Elastic v2 مع جميع القواعد الأخرى. نطلب أيضًا من المساهمين التوقيع على اتفاقية ترخيص المساهم قبل المساهمة بأي كود في أي مستودعات Elastic.
| folder | description |
|---|
detection_rules/ | وحدة Python لتحليل القواعد والتحقق منها وتعبئتها |
etc/ | ملفات متنوعة، مثل مخططات ECS و Beats وملفات الإعداد |
hunting/ | الدليل الجذري حيث يتم تخزين حزمة واستعلامات صيد التهديدات |
kibana/ | مكتبة Python للتعامل مع استدعاءات API إلى Kibana ومحرك الكشف |
kql/ | مكتبة Python لتحليل والتحقق من لغة استعلام Kibana |
rules/ | الدليل الجذري حيث يتم تخزين القواعد |
rules_building_block/ | الدليل الجذري حيث يتم تخزين قواعد اللبنات الأساسية |
tests/ | كود Python لاختبار الوحدات للقواعد |