اتبع إخراج تثبيت مخطط Helm حول كيفية إعادة توجيه المنفذ للوحة تحكم Krane.

### التشغيل باستخدام Docker

من المفترض أن يكون لديك [docker](https://docs.docker.com/get-docker/) قيد التشغيل على جهازك المحلي. قم بتثبيت [docker-compose](https://docs.docker.com/compose/install/#install-compose) إذا لم تكن قد قمت بذلك بالفعل.

يعتمد Krane على RedisGraph. يحدد مكدس `docker-compose` كل ما هو مطلوب لبناء وتشغيل خدمة _Krane_ محليًا. كما سيهتم باعتماده على [RedisGraph](https://oss.redislabs.com/redisgraph/).```
docker-compose up -d

بمجرد دخولك إلى الحاوية، يمكنك البدء في استخدام أوامر `krane`. جرب `krane -help`.```sh
krane -h

لإيقاف _Krane_ وخدمات التبعية الخاصة به:```
docker-compose down

krane

Kubernetes RBAC static analysis & visualisation tool

dashboard Start K8s RBAC dashboard server
help      Display global or [command] help documentation
report    Run K8s RBAC report

-h, --help
    Display help documentation

-v, --version
    Display version information

-t, --trace
    Display backtrace when an error occurs

Marcin Ciszak <[email protected]> - Appvia Ltd <appvia.io>

### إنشاء تقرير RBAC

#### باستخدام سياق `kubectl` المحلي

لتشغيل تقرير على كتلة عاملة، يجب توفير سياق _kubectl_.```
krane report -k <context>

ملاحظة: تتوقع _Krane_ وجود الملفات التالية (بتنسيق YAML أو JSON) في مسار الدليل المحدد:
  - psp
  - roles
  - clusterroles
  - rolebindings
  - clusterrolebindings

إذا لم تكن سياسات أمان Pod (Pod Security Policies) قيد الاستخدام، فيمكنك تجاوز التوقع أعلاه عن طريق إنشاء ملف `psp` يدويًا بالمحتوى التالي:```json
{
  "items": []
}

ملاحظة: سيتطلب حساب الخدمة المستخدم بواسطة _Krane_ الوصول إلى موارد RBAC. راجع [المتطلبات الأساسية](https://github.com/appvia/krane/blob/HEAD/k8s/one-time/prerequisites.yaml) للحصول على التفاصيل.

#### في خط أنابيب CI/CD

للتحقق من تعريف RBAC كخطوة في خط أنابيب CI/CD```
krane report --ci -d </path/to/rbac-directory>

Cluster flag `-c <cluster-name>` قد يتم تمرير علم الكتلة `-c <cluster-name>` إذا كنت ترغب في تشغيل لوحة التحكم مقابل اسم كتلة محدد. ستبحث لوحة التحكم عن البيانات المتعلقة باسم الكتلة المحدد المخزنة مؤقتًا على نظام الملفات.

الأمر أعلاه سيبدأ خادم الويب المحلي على المنفذ الافتراضي `8000`، ويعرض رابط لوحة التحكم.

## الهندسة المعمارية

### فهرسة بيانات RBAC في قاعدة بيانات رسوم بيانية محلية

_Krane_ يقوم بفهرسة كيانات RBAC في RedisGraph. هذا يسمح لنا بالاستعلام عن شبكة التبعيات بكفاءة وببساطة باستخدام مجموعة فرعية من [CypherQL](https://oss.redislabs.com/redisgraph/cypher_support/) المدعومة من [RedisGraph](https://oss.redislabs.com/redisgraph/).

#### المخطط

![مخطط كيان Krane](https://raw.githubusercontent.com/appvia/krane/HEAD/doc/images/krane-graph-diagram.svg "مخطط كيان Krane")

#### العقد

يتم إنشاء العقد التالية في الرسم البياني لكائنات RBAC ذات الصلة:

* `Psp`       - عقدة PSP تحتوي على سمات حول سياسة أمان البود. قابلة للتطبيق فقط عند العمل مع K8s < 1.25.
* `Rule`      - عقدة القاعدة تمثل قاعدة التحكم في الوصول حول موارد Kubernetes.
* `Role`      - عقدة الدور تمثل دورًا معينًا أو ClusterRole. سمة `kind` تحدد نوع الدور.
* `Subject`   - الموضوع يمثل جميع الجهات الفاعلة الممكنة في الكتلة (`kind`: User, Group و ServiceAccount)
* `Namespace` - عقدة Namespace الخاصة بـ Kubernetes.

#### الحواف

* `:SECURITY`  - يحدد رابطًا بين عقدتي Rule و Psp. قابلة للتطبيق فقط عند العمل مع K8s < 1.25.
* `:GRANT`     - يحدد رابطًا بين الدور (Role) والقاعدة (Rule) المرتبطة بهذا الدور.
* `:ASSIGN`    - يحدد رابطًا بين جهة فاعلة (Subject) ودور معين/ClusterRole (عقدة Role).
* `:RELATION`  - يحدد رابطًا بين عقدتي جهة فاعلة مختلفتين (Subject).
* `:SCOPE`     - يحدد رابطًا بين عقدتي Role و Namespace.
* `:ACCESS`    - يحدد رابطًا بين عقدتي Subject و Namespace.
* `:AGGREGATE` - يحدد رابطًا بين ClusterRoles (حيث يقوم ClusterRole بتجميع آخر) `A-(aggregates)->B`
* `:COMPOSITE` - يحدد رابطًا بين ClusterRoles (حيث يمكن تجميع ClusterRole في آخر) `A<-(is a composite of)-B`

جميع الحواف ثنائية الاتجاه، مما يعني أنه يمكن الاستعلام عن الرسم البياني في أي اتجاه. الاستثناءات الوحيدة هي علاقات `:AGGREGATE` و `:COMPOSITE` وهي أحادية الاتجاه، على الرغم من أنها معنية بنفس عقد الحافة.

#### الاستعلام عن الرسم البياني

لاستعلام عن الرسم البياني مباشرة، يمكنك تنفيذ exec في حاوية `redisgraph` قيد التشغيل، وبدء `redis-cli` وتشغيل استعلاماتك التعسفية. اتبع [التعليمات](https://oss.redislabs.com/redisgraph/) الرسمية للحصول على أمثلة على [الأوامر](https://oss.redislabs.com/redisgraph/commands/).

يمكنك أيضًا الاستعلام عن الرسم البياني من وحدة تحكم _Krane_. أولاً، قم بتنفيذ exec في حاوية _Krane_ قيد التشغيل، ثم```ruby
# Start Krane console - this will open interactive ruby shell with Krane code preloaded

console

# Instantiate Graph client

graph = Krane::Clients::RedisGraph.client cluster: 'default'

# Run arbitrary CypherQL query against indexed RBAC Graph

res = graph.query(%Q(
  MATCH (r:Rule {resource: "configmaps", verb: "update"})<-[:GRANT]-(ro:Role)<-[:ASSIGN]-(s:Subject)
  RETURN s.kind as subject_kind, s.name as subject_name, ro.kind as role_kind, ro.name as role_name))

# Print the results

res.print_resultset

ملاحظة: المثال أعلاه سيختار جميع الأشخاص (Subjects) الذين لديهم أدوار/أدوار عنقودية (Roles/ClusterRoles) تمنح صلاحية الوصول إلى `تحديث الكونفيج ماب (configmaps)`.

## الإعدادات

### قواعد مخاطر RBAC

يتم تعريف قواعد مخاطر RBAC في ملف [القواعد](https://github.com/appvia/krane/blob/HEAD/config/rules.yaml). بنية كل قاعدة واضحة إلى حد كبير.
يمكن توسيع / تجاوز المجموعة المدمجة بإضافة قواعد مخصصة إضافية إلى ملف [القواعد المخصصة](https://github.com/appvia/krane/blob/HEAD/config/custom-rules.yaml).

#### وحدات الماكرو لقاعدة المخاطر

وحدات الماكرو هي "حاويات" لمجموعة من السمات الشائعة/المشتركة، ويتم الرجوع إليها بواسطة قاعدة مخاطر واحدة أو أكثر. إذا اخترت استخدام ماكرو في قاعدة مخاطر معينة، فستحتاج إلى الرجوع إليه بالاسم، مثل `macro: <اسم-الماكرو>`. لاحظ أن السمات المحددة في الماكرو المُشار إليه ستكون لها الأولوية على نفس السمات المحددة على مستوى القاعدة.

يمكن أن يحتوي الماكرو على أي من السمات التالية:

- `query`   - [استعلام RedisGraph](#الاستعلام-من-الرسم-البياني). له أولوية على `template`. يتطلب تعريف `writer`.
- `writer`  - تعبير Ruby يُستخدم لتنسيق مجموعة نتائج `query`. للكاتب أولوية على `template`.
- `template` - اسم قالب الاستعلام/الكاتب المدمج. إذا لم يتم تحديد `query` و `writer`، فسيتم استخدام مُولد الاستعلام المختار مع الكاتب المطابق.

#### سمات قاعدة المخاطر

يمكن أن تحتوي القاعدة على أي من السمات التالية:

- `id`           [مطلوب] معرف القاعدة هو معرف فريد للقاعدة.
- `group_title`  [مطلوب] عنوان ينطبق على جميع العناصر التي تقع ضمن هذا الفحص المخاطر.
- `severity`     [مطلوب] درجة الخطورة، كأحد: :danger, :warning, :info.
- `info`         [مطلوب] معلومات نصية حول الفحص واقتراحات حول كيفية تخفيف المخاطرة.
- `query`        [شَرطي] [استعلام RedisGraph](#الاستعلام-من-الرسم-البياني).
  - له أولوية على `template`. يتطلب تعريف `writer`.
- `writer`       [شَرطي] تعبير Ruby يُستخدم لتنسيق مجموعة نتائج الاستعلام.
  - للكاتب أولوية على `template`. يتطلب تعريف `query`.
- `template`     [شَرطي] اسم قالب الاستعلام/الكاتب المدمج. إذا لم يتم تحديد `query` و `writer`، فسيتم استخدام مُولد الاستعلام المختار مع الكاتب المطابق.
  - تتطلب بعض القوالب المدمجة تحديد سمة `match_rules` على مستوى القاعدة الفردية لبناء الاستعلام الصحيح. القوالب التي تتطلب ذلك حالياً:

    - **_risky-role_** - يبني استعلام رسم بياني متعدد التطابقات بناءً على قواعد الوصول المحددة بواسطة `match_rules`. يُرجع استعلام الرسم البياني المُنشأ الأعمدة التالية:
      - role_name
      - role_kind
      - namespace_name (يتم إرجاع _مصفوفة_ إذا تم إرجاع عناصر متعددة)

- `match_rules`  [شَرطي] مطلوب عندما يعتمد `template` على قواعد التطابق لبناء استعلام.
  - مثال:
    ```yaml
     match_rules:
     - resources: ['cronjobs']
       verbs: ['update']
    ```
     تتبع السمات والقيم [مواصفات دور Kubernetes RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-examples).

- `custom_params` [اختياري] قائمة من أزواج القيم المخصصة التي سيتم تقييمها واستبدالها في تمثيل `query` و `writer` للقاعدة.
  - مثال:
    ```yaml
    custom_params:
    - attrA: valueA
    - attrB: valueB
    ```
    سيتم استبدال العناصر النائبة في القالب للمفاتيح أعلاه `{{attrA}}` و `{{attrB}}` بـ `valueA` و `valueB` على التوالي.

- `threshold`  [اختياري] قيمة رقمية. عند تعريفها ستصبح متاحة كعنصر نائب للقالب `{{threshold}}` في تعبير `writer`.
- `macro`      [اختياري] مرجع إلى المعلمات الشائعة المحددة في ماكرو مُسمى.
- `disabled`   [اختياري] عند تعيينها على `true` ستعطل القاعدة المحددة وتستبعدها من التقييم.
                بشكل افتراضي جميع القواعد مفعلة.

#### أمثلة على قواعد المخاطر

##### استعلام صريح وتعبير كاتب```yaml
- id: verbose-rule-example
  group_title: Example rule
  severity:    :danger
  info:        Risk description and instructions on how to mitigate it goes here
  query: |
    MATCH
      (s:Subject)-[:ACCESS]->(ns:Namespace)
    WHERE
      NOT s.name IN {{whitelist_subject_names}}
    RETURN
      s.kind as subject_kind,
      s.name as subject_name,
      COLLECT(ns.name) as namespace_names
    ORDER BY
      subject_kind,
      subject_name,
      namespace_names DESC
  threshold: 2
  writer: |
    if result.namespace_names.count > {{threshold}}
      "#{result.subject_kind} #{result.subject_name} can access namespaces: #{result.namespace_names.join(', ')}"
    end
  disabled: true

المثال أعلاه يُظهر إحدى القواعد المدمجة. يشير إلى قالب `risky-role` الذي سيؤدي، عند معالجته، إلى توسيع القاعدة عن طريق حقن تعبيرات `query` و `writer` قبل تشغيل تقييم القاعدة. سيتم استخدام `match_rules` لبناء استعلام المطابقة المناسب.

### القائمة البيضاء لمخاطر RBAC

تحتوي القائمة البيضاء الاختيارية على مجموعة من أسماء السمات المخصصة والقيم (المسموح بها) الخاصة بها.

#### سمات القائمة البيضاء

أسماء السمات وقيمها عشوائية. يتم تعريفها في ملف [القائمة البيضاء](https://github.com/appvia/krane/blob/HEAD/config/whitelist.yaml) وتنقسم إلى ثلاثة أقسام منفصلة:
  - `global` - النطاق الأعلى. السمات المخصصة المعرفة هنا ستنطبق على جميع قواعد المخاطر بغض النظر عن اسم المجموعة.
  - `common` - السمات المخصصة ستكون مقصورة على معرف قاعدة المخاطرة المحدد بغض النظر عن اسم المجموعة.
  - `cluster` (مع قائمة متداخلة من أسماء المجموعات) - السمات المخصصة ستنطبق على معرف قاعدة المخاطرة المحدد لاسم مجموعة معينة.

كل [قاعدة مخاطرة](#rbac-risk-rules)، عند التقييم، ستحاول استيفاء جميع العناصر النائبة للمعلمات المستخدمة في `query`، مثل `{{your_whitelist_attribute_name}}`. إذا تطابق اسم المعلمة النائبة (أي اسم بين القوسين المتعرجين المزدوجين) مع أي من أسماء السمات المدرجة في القائمة البيضاء لمعرف قاعدة المخاطرة تلك، فسيتم استبداله بقيمته المحسوبة.
إذا لم يتم العثور على قيم لعنصر نائب معين، فسيتم استبداله بـ `['']`.

#### أمثلة على القائمة البيضاء

مثال القائمة البيضاء أدناه ينتج التعيين التالي `placeholder-key => value` لـ [قاعدة مخاطرة](#rbac-risk-rules) بقيمة سمة `id` تطابق _"some-risk-rule-id"_```
{{whitelist_role_names}}    => ['acp:prometheus:operator']
{{whitelist_subject_names}} => ['privileged-psp-user', 'another-user']

## نشر Kubernetes

يمكن نشر _Krane_ بسهولة في مجموعات Kubernetes المحلية أو عن بُعد.

### متطلبات K8s الأساسية

يجب أن تكون مساحة الاسم (namespace) وحساب الخدمة (service account) في Kubernetes مع الأدوار المناسبة (RBAC) موجودة في المجموعة. راجع [المتطلبات الأساسية](https://github.com/appvia/krane/blob/HEAD/k8s/one-time/prerequisites.yaml) كمرجع.

نقطة الدخول الافتراضية لـ _Krane_ تنفذ [bin/in-cluster-run](https://github.com/appvia/krane/blob/HEAD/bin/in-cluster-run) والتي تنتظر حتى تصبح مثيل RedisGraph متاحة قبل بدء حلقة _تقرير_ RBAC وخادم الويب _لوحة القيادة_.

يمكنك التحكم في جوانب معينة من التنفيذ داخل المجموعة باستخدام متغيرات البيئة التالية:

* `KRANE_REPORT_INTERVAL` - يحدد الفاصل الزمني بالثواني لتشغيل تقرير التحليل الثابت لـ RBAC. الافتراضي: `300` (بالثواني، أي 5 دقائق).
* `KRANE_REPORT_OUTPUT` - يحدد تنسيق إخراج تقرير مخاطر RBAC. القيم الممكنة `:json`, `:yaml`, `:none`. الافتراضي: `:json`.

### مجموعة K8s محلية أو عن بُعد

#### Helm Chart

قبل البدء، ستحتاج إلى الأدوات التالية:
* [Helm CLI](https://helm.sh/docs/intro/install/)

تثبيت مخطط Helm:```sh
$ helm repo add appvia https://appvia.github.io/krane
$ helm repo update
$ helm install krane appvia/krane --namespace krane --create-namespace

لاحظ أن خدمة لوحة تحكم _Krane_ غير معروضة افتراضيًا!```sh
kubectl port-forward svc/krane 8000 \
  --context=<docker-desktop> \
  --namespace=krane

# Open Krane dashboard at http://localhost:8000

ملاحظة: تأكد من تعيين سياق kube الحالي بشكل صحيح قبل تشغيل الأمر أعلاه!

يجب أن تكون حزمة التطبيق الآن منشورة في مجموعة Kubernetes وجميع الخدمات جاهزة ومكشوفة. لاحظ أن _Krane_ ستبدأ تلقائيًا حلقة التقرير وخادم لوحة المعلومات.```sh
docker stack services --orchestrator kubernetes --namespace krane krane

تحقق من وضع أمان RBAC في مجموعة Kubernetes الخاصة بك عن طريق زيارة http://localhost:8000.

لاحظ أنه بالنسبة لنشر مجموعة عن بُعد، من المحتمل أن تحتاج إلى port-forward خدمة _Krane_ أولاً.```sh
kubectl --context=my-remote-cluster --namespace=krane port-forward svc/krane 8000

## الإشعارات

سيقوم Krane بإعلامك عن الشذوذ المكتشفة ذات الخطورة المتوسطة والعالية عبر تكامل Slack الخاص به.

لتمكين الإشعارات، حدد `webhook_url` و `channel` في ملف [config/config.yaml](https://github.com/appvia/krane/blob/HEAD/config/config.yaml)، أو بدلاً من ذلك قم بتعيين متغيرات البيئة `SLACK_WEBHOOK_URL` و `SLACK_CHANNEL`. ستتغلب متغيرات البيئة على قيم ملف الإعدادات.

## التطوير المحلي

يصف هذا القسم الخطوات لتمكين التطوير المحلي.

### الإعداد

قم بتثبيت تبعيات كود _Krane_ باستخدام```sh
./bin/setup

لتفقد حالة خدمة RedisGraph:```sh
docker-compose ps

docker compose -f docker-compose.yml down
``````sh
docker-compose down

لتمكين وضع التطوير المحلي لواجهة لوحة التحكم```sh
$ cd dashboard
$ npm install
$ npm start

### اختبارات

تشغيل الاختبارات محليًا باستخدام```sh
bundle exec rspec