## الاستخدام

> [!WARNING]
> **إشعار إهمال**: سيتم إهمال استثناءات التهديدات (`Excludes`) في الإصدار القادم (**v2**). انظر [#73](https://github.com/teler-sh/teler-waf/discussions/73) & [#64](https://github.com/teler-sh/teler-waf/issues/64).

فيما يلي مثال على كيفية استخدام teler-waf في تطبيق Go:

1. استيراد حزمة teler-waf في كود Go الخاص بك:```go
import "github.com/teler-sh/teler-waf"

3. استخدم طريقة `Handler` من مثيل `Teler` لإنشاء معالج `net/http.Handler`. يمكن بعد ذلك استخدام هذا المعالج في توجيه HTTP لتطبيق إجراءات الأمان الخاصة بـ teler-waf على مسارات محددة.```go
handler := waf.Handler(http.HandlerFunc(yourHandlerFunc))

ذلك كل شيء! لقد قمت بتكوين teler-waf في تطبيق Go الخاص بك.

**الخيارات:**

للاطلاع على قائمة الخيارات المتاحة لتخصيص teler-waf، راجع بنية [`teler.Options`](https://pkg.go.dev/github.com/teler-sh/teler-waf#Options).

### أمثلة

فيما يلي مثال على كيفية تخصيص الخيارات والقواعد لـ teler-waf:```go
// main.go
package main

import (
	"net/http"

	"github.com/teler-sh/teler-waf"
	"github.com/teler-sh/teler-waf/request"
	"github.com/teler-sh/teler-waf/threat"
)

var myHandler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	// This is the handler function for the route that we want to protect
	// with teler-waf's security measures.
	w.Write([]byte("hello world"))
})

var rejectHandler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	// This is the handler function for the route that we want to be rejected
	// if the teler-waf's security measures are triggered.
	http.Error(w, "Sorry, your request has been denied for security reasons.", http.StatusForbidden)
})

func main() {
	// Create a new instance of the Teler type using the New function
	// and configure it using the Options struct.
	telerMiddleware := teler.New(teler.Options{
		// Exclude specific threats from being checked by the teler-waf.
		Excludes: []threat.Threat{
			threat.BadReferrer,
			threat.BadCrawler,
		},
		// Specify whitelisted URIs (path & query parameters), headers,
		// or IP addresses that will always be allowed by the teler-waf
		// with DSL expressions.
		Whitelists: []string{
			`request.Headers matches "(curl|Go-http-client|okhttp)/*" && threat == BadCrawler`,
			`request.URI startsWith "/wp-login.php"`,
			`request.IP in ["127.0.0.1", "::1", "0.0.0.0"]`,
			`request.Headers contains "authorization" && request.Method == "POST"`
		},
		// Specify file path or glob pattern of custom rule files.
		CustomsFromRule: "/path/to/custom/rules/**/*.yaml",
		// Specify custom rules for the teler-waf to follow.
		Customs: []teler.Rule{
			{
				// Give the rule a name for easy identification.
				Name:      "Log4j Attack",
				// Specify the logical operator to use when evaluating the rule's conditions.
				Condition: "or",
				// Specify the conditions that must be met for the rule to trigger.
				Rules: []teler.Condition{
					{
						// Specify the HTTP method that the rule applies to.
						Method: request.GET,
						// Specify the element of the request that the rule applies to
						// (e.g. URI, headers, body).
						Element: request.URI,
						// Specify the pattern to match against the element of the request.
						Pattern: `\$\{.*:\/\/.*\/?\w+?\}`,
					},
				},
			},
			{
				// Give the rule a name for easy identification.
				Name: `Headers Contains "curl" String`,
				// Specify the conditions that must be met for the rule to trigger.
				Rules: []teler.Condition{
					{
						// Specify the DSL expression that the rule applies to.
						DSL: `request.Headers contains "curl"`,
					},
				},
			},
		},
		// Specify the file path to use for logging.
		LogFile: "/tmp/teler.log",
	})

	// Set the rejectHandler as the handler for the telerMiddleware.
	telerMiddleware.SetHandler(rejectHandler)

	// Create a new handler using the handler method of the Teler instance
	// and pass in the myHandler function for the route we want to protect.
	app := telerMiddleware.Handler(myHandler)

	// Use the app handler as the handler for the route.
	http.ListenAndServe("127.0.0.1:3000", app)
}

> [!IMPORTANT]
> يُرجى ملاحظة أن `condition` و `method` و `element` هي معاملات اختيارية. القيم الافتراضية المخصصة لها هي كالتالي: `condition` مضبوط على **or**، و `method` مضبوط على **ALL**، و `element` مضبوط على **ANY**. لذلك، إذا رغبت، يمكنك ترك هذه المعاملات فارغة. المعامل `pattern` إلزامي، ما لم تحدد تعبير `dsl`. في مثل هذه الحالات، عند تقديم تعبير `dsl`، سيتجاهل teler-waf أي قيم مخصصة لـ `method` و `element`، حتى لو تم تعريفها. لرؤية بعض الأمثلة، يمكنك الرجوع إلى دليل [`tests/rules/`](https://github.com/teler-sh/teler-waf/tree/master/tests/rules/valid).

يمكنك تحديد خيار `CustomsFromFile` مع مسار الملف الفعلي أو نمط glob الذي يشير إلى موقع ملفات القواعد المخصصة لديك. على سبيل المثال:```go
// Create a new instance of the Teler middleware and
// specify custom rules with the CustomsFromFile option.
telerMiddleware := teler.New(teler.Options{
    CustomsFromFile: "/path/to/custom/rules/**/*.yaml",
})

تحقق مما إذا كانت طريقة الطلب الواردة هي "GET":```sql
request.Method == "GET"

تحقق مما إذا كان عنوان IP للطلب الوارد من المضيف المحلي:```sql
request.IP in ["127.0.0.1", "::1", "0.0.0.0"]

تحقق مما إذا كان نص الطلب الوارد يحتوي على "foo":```sql
request.Body contains "foo"

تقدم هذه الأمثلة لمحة عن القدرات التعبيرية لتعابير DSL، مما يسمح لك بتحديد شروط معقدة بناءً على سمات الطلب المختلفة. من خلال الاستفادة من هذه التعابير، يمكنك تحديد المعايير لتقييم الطلبات الواردة وتخصيص القواعد المخصصة أو القوائم البيضاء وفقًا لذلك، مما يتيح تحكمًا دقيقًا في سلوك تطبيقك.

#### المتغيرات المتاحة

عند العمل مع تعابير DSL، لديك إمكانية الوصول إلى متغيرات متنوعة توفر معلومات قيمة حول الطلبات الواردة وفئة التهديد التي يتم تحليلها. فيما يلي وصف تفصيلي للمتغيرات المتاحة:

- **فئة التهديد**

	يمكن استخدام جميع المعرفات الثابتة من نوع `threat.Threat` كمتغيرات صالحة. تمثل هذه المعرفات فئات تهديد مختلفة ذات صلة بتحليلك.

- **`request`**

	يمثل المتغير `request` الطلب الوارد ويوفر الوصول إلى حقوله والقيم المقابلة لها. تتوفر المتغيرات الفرعية التالية داخل المتغير `request`:

  - `request.URI`: يمثل URI للطلب الوارد، بما في ذلك المسار والاستعلامات والمعلمات والأجزاء.
  - `request.Headers`: يمثل رؤوس الطلب الوارد، معروضة في عدة أسطر.
  - `request.Body`: يمثل نص الطلب الوارد.
  - `request.Method`: يمثل طريقة الطلب الوارد.
  - `request.IP`: يمثل عنوان IP الخاص بالعميل المرتبط بالطلب الوارد.
  - `request.ALL`: يمثل جميع القيم النصية من حقول الطلب المذكورة أعلاه في شريحة.

- **`threat`**

	يمثل المتغير `threat` فئة التهديد التي يتم تحليلها. وهو من نوع `threat.Threat` ويسمح لك بتقييم واتخاذ القرارات بناءً على فئة التهديد المحددة المرتبطة بالطلب.

من خلال استخدام هذه المتغيرات داخل تعابير DSL الخاصة بك، يمكنك بشكل فعال الوصول إلى سمات الطلبات الواردة ومعالجتها وتقييم فئات التهديد ذات الصلة. وهذا يتيح لك إنشاء شروط قواعد مخصصة<!-- وقوائم بيضاء--> مصممة خصيصًا لحالة الاستخدام الخاصة بك.

#### الدوال المتاحة

أيضًا، لديك إمكانية الوصول إلى مجموعة متنوعة من الدوال. تشمل هذه الدوال كلاً من [الدوال المدمجة](https://expr.medv.io/docs/Language-Definition#built-in-functions) التي يوفرها حزمة expr وتلك المحددة تحديدًا داخل حزمة DSL. تستخدم الدوال الوظائف التي تقدمها حزمة `strings` المدمجة في Go. فيما يلي قائمة مفصلة بالدوال المتاحة:

- `cidr`: الحصول على جميع عناوين IP في النطاق مع CIDR معين.
- `clone`: إنشاء نسخة من سلسلة نصية.
- `containsAny`: التحقق مما إذا كانت السلسلة تحتوي على أي من السلاسل الفرعية المحددة.
- `equalFold`: مقارنة سلسلتين نصيتين بطريقة غير حساسة لحالة الأحرف.
- `hasPrefix`: التحقق مما إذا كانت السلسلة تحتوي على بادئة محددة.
- `hasSuffix`: التحقق مما إذا كانت السلسلة تحتوي على لاحقة محددة.
- `join`: ربط عدة سلاسل نصية باستخدام فاصل محدد.
- `repeat`: تكرار سلسلة نصية عددًا محددًا من المرات.
- `replace`: استبدال تكرارات سلسلة فرعية داخل سلسلة نصية.
- `replaceAll`: استبدال جميع تكرارات سلسلة فرعية داخل سلسلة نصية.
- `request`: الوصول إلى معلومات خاصة بالطلب داخل تعبير DSL.
- `threat`: الوصول إلى المعلومات المتعلقة بفئة التهديد التي يتم تحليلها.
- `title`: تحويل سلسلة نصية إلى حالة عنوان.
- `toLower`: تحويل سلسلة نصية إلى أحرف صغيرة.
- `toTitle`: تحويل سلسلة نصية إلى حالة عنوان.
- `toUpper`: تحويل سلسلة نصية إلى أحرف كبيرة.
- `toValidUTF8`: تحويل سلسلة نصية إلى سلسلة مشفرة بصيغة UTF-8 صالحة.
- `trim`: إزالة المسافات البيضاء البادئة والتالية من سلسلة نصية.
- `trimLeft`: إزالة المسافات البيضاء البادئة من سلسلة نصية.
- `trimPrefix`: إزالة بادئة محددة من سلسلة نصية.
- `trimRight`: إزالة المسافات البيضاء التالية من سلسلة نصية.
- `trimSpace`: إزالة المسافات البيضاء البادئة والتالية وضم المسافات البيضاء المتتالية داخل سلسلة نصية.
- `trimSuffix`: إزالة لاحقة محددة من سلسلة نصية.

لمزيد من التفاصيل الشاملة حول العوامل والدوال المدمجة، يرجى الرجوع إلى [توثيق Expr](https://expr.medv.io/docs/Getting-Started). حيث يوفر دليلاً شاملاً لاستخدام العوامل واستكشاف الدوال المدمجة المتاحة في تعابير DSL الخاصة بك.

### إدارة التهيئة المبسطة

للتهيئة الفعالة، من الضروري تحديد مجموعة من الإعدادات، بما في ذلك القوائم البيضاء، تعريفات القواعد المخصصة، تفضيلات التسجيل، والمعلمات الأخرى. تعمل حزمة [`option`](https://pkg.go.dev/github.com/teler-sh/teler-waf/option) على تبسيط سير عمل التهيئة هذا من خلال تمكينك من إلغاء تسلسل أو تحميل بيانات التهيئة من تنسيقات JSON و YAML بكفاءة إلى تنسيق يمكن لـ teler-waf فهمه وتطبيقه بسهولة.```go
// Load configuration from a YAML file.
opt, err := option.LoadFromYAMLFile("/path/to/teler-waf.conf.yaml")
if err != nil {
    panic(err)
}

// Create a new instance of the Teler type with
// the loaded options.
telerMiddleware := teler.New(opt)

### السجلات

فيما يلي مثال على ما قد تبدو عليه سطور السجل إذا اكتشف teler-waf تهديدًا في طلب:```json
{"level":"warn","ts":1672261174.5995026,"msg":"bad crawler","id":"654b85325e1b2911258a","category":"BadCrawler","caller":"teler-waf","listen_addr":"127.0.0.1:36267","request":{"method":"GET","path":"/","ip_addr":"127.0.0.1:37702","headers":{"Accept":["*/*"],"User-Agent":["curl/7.81.0"]},"body":""}}
{"level":"warn","ts":1672261175.9567692,"msg":"directory bruteforce","id":"b29546945276ed6b1fba","category":"DirectoryBruteforce","caller":"teler-waf","listen_addr":"127.0.0.1:36267","request":{"method":"GET","path":"/.git","ip_addr":"127.0.0.1:37716","headers":{"Accept":["*/*"],"User-Agent":["X"]},"body":""}}
{"level":"warn","ts":1672261177.1487508,"msg":"Detects common comment types","id":"75412f2cc0ec1cf79efd","category":"CommonWebAttack","caller":"teler-waf","listen_addr":"127.0.0.1:36267","request":{"method":"GET","path":"/?id=1%27%20or%201%3D1%23","ip_addr":"127.0.0.1:37728","headers":{"Accept":["*/*"],"User-Agent":["X"]},"body":""}}

بفضل هذا المستوى من التخصيص، يمكنك إنشاء ردود مخصصة وغنية بالمعلومات لعرضها عندما يقوم teler-waf بحظر أو رفض طلب. يتيح لك خيار `HTML` تحديد محتوى HTML المطلوب مباشرةً كسلسلة نصية، بينما يمكنك خيار `HTMLFile` من الإشارة إلى ملف خارجي يحتوي على رد HTML مخصص.

علاوة على ذلك، لتحسين تجربة المستخدم، يمكنك الاستفادة من العناصر النائبة في محتوى HTML الخاص بك لتوليد عناصر ديناميكية. أثناء وقت التشغيل، سيتم استبدال هذه العناصر النائبة بقيم فعلية، مما يؤدي إلى ردود أكثر صلة بالسياق. تشمل العناصر النائبة المتاحة والمدعومة ما يلي:

* `{{ID}}`: معرفات الطلب، مما يسمح بتعريف فريد لكل طلب مرفوض.
* `{{message}}`: رسائل الرفض التي توضح سبب حظر الطلب.
* `{{threat}}`: فئات التهديدات، مما يوفر رؤى حول التهديد الأمني المكتشف.

من خلال تضمين هذه العناصر النائبة، يمكنك إنشاء ردود مفصلة وشاملة تنقل بشكل فعال الأساس المنطقي وراء رفض الطلبات أو حظرها.

### Falco Sidekick

[Falco Sidekick](https://github.com/falcosecurity/falcosidekick) هي أداة تستقبل الأحداث من Falco، وهو مشروع أمني مفتوح المصدر للتشغيل في الوقت الفعلي للحاويات، وترسلها إلى قنوات إخراج مختلفة. يتيح لك إعادة توجيه التنبيهات الأمنية إلى أنظمة طرف ثالث متنوعة مثل Slack وElasticsearch وLoki وGrafana وDatadog و[المزيد](https://github.com/falcosecurity/falcosidekick#outputs). وهذا يمكّن فرق الأمن من مراقبة التهديدات والأحداث الأمنية والاستجابة لها بكفاءة في الوقت الفعلي.

من الممكن أيضًا دمج Falco Sidekick مع teler-waf. باستخدام خيار `FalcoSidekickURL`، يمكنك تكوين teler-waf لإرسال الأحداث إلى Falco Sidekick، والذي سيتلقاها ويعالجها نيابةً عنك. للقيام بذلك، ما عليك سوى إنشاء مثيل جديد من نوع `Teler` باستخدام الدالة `New` وتوفير خيار `FalcoSidekickURL` مع عنوان URL لمثيل Falco Sidekick الخاص بك. على سبيل المثال:```go
// Create a new instance of the Teler type using
// the New function & integrate Falco Sidekick.
telerMiddleware := teler.New(teler.Options{
	FalcoSidekickURL: "http://localhost:2801",
})

أخيرًا، قد تكون هناك حالات يلزم فيها تحميل مجموعة بيانات التهديدات في الذاكرة بدلاً من حفظها في دليل ذاكرة التخزين المؤقت على مستوى المستخدم. يمكن أن يكون هذا مفيدًا بشكل خاص إذا كنت تشغل التطبيق أو الخدمة على صورة خالية من التوزيع (distroless) أو بيئة تشغيل، حيث قد يكون الوصول إلى الملفات محدودًا أو بطيئًا. في هذا السيناريو، يمكنك تعيين خيار يسمى **InMemory** إلى `true`، مما يؤدي إلى تحميل مجموعة بيانات التهديدات في الذاكرة للوصول الأسرع.```go
// Create a new instance of the Teler type using the
// New function & enable in-memory threat datasets store.
telerMiddleware := teler.New(teler.Options{
	InMemory: true,
})

> [!NOTE]
> قد تختلف نتائج الاختبارات المعيارية وقد لا تكون متسقة. قد تكون مجموعة بيانات [teler-resources](https://github.com/teler-sh/teler-resources) قد زادت منذ ذلك الحين، مما قد يؤثر على النتائج.

- **تعقيد التكوين**: قد يكون تكوين teler-waf لتلبية الاحتياجات المحددة لتطبيقك معقدًا، وقد يتطلب مستوى معينًا من الخبرة في أمن الويب. يمكن أن يجعل ذلك من الصعب على أولئك غير المألوفين بجدران الحماية للتطبيقات وأنظمة كشف التسلل إعداد teler-waf واستخدامه بشكل صحيح.
- **حماية محدودة**: teler-waf ليس حلاً أمنيًا مثاليًا، وقد لا يكون قادرًا على الحماية من جميع أنواع الهجمات الممكنة. كما هو الحال مع أي نظام أمان، من المهم مراقبة وصيانة teler-waf بانتظام لضمان أنه يوفر المستوى المطلوب من الحماية.

#### المشكلات المعروفة
لعرض قائمة المشكلات المعروفة مع teler-waf، يرجى تصفية المشكلات باستخدام [وسم "known-issue"](https://github.com/teler-sh/teler-waf/issues?q=is%3Aopen+is%3Aissue+label%3Aknown-issue).

## المجتمع
نستخدم Google Groups كقائمتنا البريدية المخصصة. اشترك في [teler-announce](https://groups.google.com/g/teler-announce) عبر [[email protected]](mailto:[email protected]) للحصول على الإعلانات المهمة، مثل توفر الإصدارات الجديدة. سيبقيك هذا الاشتراك على اطلاع بالتطورات الهامة المتعلقة بـ [teler IDS](https://github.com/teler-sh/teler) و [teler WAF](https://github.com/teler-sh/teler-waf) و [teler Proxy](https://github.com/teler-sh/teler-proxy) و [teler Caddy](https://github.com/teler-sh/teler-caddy) و [teler Resources](https://github.com/teler-sh/teler-resources).

بخصوص أي [استفسارات](https://github.com/teler-sh/teler-waf/discussions/categories/q-a) أو [مناقشات](https://github.com/teler-sh/teler-waf/discussions) أو [مشكلات](https://github.com/teler-sh/teler-waf/issues)، يتم تتبعها هنا على GitHub. هذا هو المكان الذي ندير فيه ونتعامل مع هذه الجوانب من مشاركة مجتمعنا بنشاط.

## الترخيص
هذه الحزمة متاحة بموجب ترخيص مزدوج: [رخصة Apache 2.0](https://github.com/teler-sh/teler-waf/blob/HEAD/LICENSE-APACHE) و [رخصة Elastic 2.0 (ELv2)](https://github.com/teler-sh/teler-waf/blob/HEAD/LICENSE-ELASTIC) (للحزمة الرئيسية، **teler**).

يمكنك استخدامها بحرية داخل مؤسستك لحماية تطبيقاتك. ومع ذلك، لا يمكنك استخدام الحزمة الرئيسية لإنشاء خدمة سحابية أو مستضافة أو مدارة، أو لأي أغراض تجارية، لأنك ستحتاج إلى ترخيص تجاري لذلك – على الرغم من أن هذا الخيار غير متاح حاليًا. إذا كنت مهتمًا بالحصول على هذا الترخيص التجاري للاستخدامات غير المصرح بها بموجب [ELv2](https://github.com/teler-sh/teler-waf/blob/HEAD/LICENSE-ELASTIC)، فيرجى التواصل مع **@dwisiswant0**.

teler-waf وأي مساهمات هي حقوق نشر © بواسطة Dwi Siswanto 2022-2024.