repokid

Repokid
=======
[![NetflixOSS Lifecycle](https://img.shields.io/osslifecycle/Netflix/osstracker.svg)]()
[![Build Status](https://travis-ci.com/Netflix/repokid.svg?branch=master)](https://travis-ci.com/Netflix/repokid)
[![PyPI version](https://badge.fury.io/py/repokid.svg)](https://badge.fury.io/py/repokid)
[![Coverage Status](https://coveralls.io/repos/github/Netflix/repokid/badge.svg?branch=master)](https://coveralls.io/github/Netflix/repokid?branch=master)
[![Discord chat](https://img.shields.io/discord/754080763070382130?logo=discord)](https://discord.gg/9kwMWa6)

<img align="center" alt="شعار Repokid" src="https://raw.githubusercontent.com/Netflix/repokid/master/docs/images/Repokid.png?raw=true" width="25%" display="block">

يستخدم Repokid Access Advisor المقدم من [Aardvark](https://github.com/Netflix-Skunkworks/aardvark)
لإزالة الصلاحيات التي تمنح الوصول إلى الخدمات غير المستخدمة من السياسات المضمنة لدور IAM في
حساب AWS.

## بدء الاستخدام

### التثبيت

```bash
mkvirtualenv repokid
git clone [email protected]:Netflix/repokid.git
cd repokid
pip install -e .
repokid config config.json
```

#### DynamoDB

ستحتاج إلى جدول [DynamoDB](https://aws.amazon.com/dynamodb/) يُسمى `repokid_roles` (حدد الحساب ونقطة النهاية في `dynamo_db` في ملف الإعدادات).

يجب أن يحتوي الجدول على الخصائص التالية:
 - `RoleId` (سلسلة) كمفتاح قسم أساسي، بدون مفتاح فرز أساسي
 - فهرس ثانوي عمومي يُسمى `Account` بمفتاح قسم أساسي `Account` وخصائص مسقطة `RoleId` و`Account`
 - فهرس ثانوي عمومي يُسمى `RoleName` بمفتاح قسم أساسي `RoleName` وخصائص مسقطة `RoleId` و`RoleName`

للتطوير، يمكنك تشغيل Dynamo [محلياً](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html).

للتشغيل محلياً:

```bash
docker-compose up
```

ستكون نقطة نهاية DynamoDB هي `http://localhost:8000`. يمكن العثور على لوحة إدارة DynamoDB على `http://localhost:8001`.

إذا قمت بتشغيل الإصدار التطويري، فسيتم إنشاء الجدول والفهرس تلقائياً نيابةً عنك.

#### أذونات IAM

يحتاج Repokid إلى دور IAM في كل حساب سيتم الاستعلام عنه. بالإضافة إلى ذلك، يحتاج Repokid إلى التشغيل بدور أو مستخدم يمكنه استدعاء `sts:AssumeRole` إلى أدوار الحسابات المختلفة.

RepokidInstanceProfile:
- أنشئ واحداً فقط.
- يحتاج إلى القدرة على استدعاء `sts:AssumeRole` إلى جميع أدوار RepokidRole.
- أذونات DynamoDB لجدول `repokid_roles` وجميع الفهارس (المحددة في القسم الفرعي `assume_role` من `dynamo_db` في الإعدادات) والقدرة على تشغيل `dynamodb:ListTables`

RepokidRole:
- يجب أن يكون موجوداً في كل حساب ستتم إدارته بواسطة Repokid.
- يجب أن يحتوي على سياسة ثقة تسمح بـ `RepokidInstanceProfile`.
- يجب تحديد الاسم في `connection_iam` في ملف الإعدادات.
- لديه هذه الأذونات:
 ```json
 {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "iam:DeleteInstanceProfile",
        "iam:DeleteRole",
        "iam:DeleteRolePolicy",
        "iam:GetAccountAuthorizationDetails",
        "iam:GetInstanceProfile",
        "iam:GetRole",
        "iam:GetRolePolicy",
        "iam:ListInstanceProfiles",
        "iam:ListInstanceProfilesForRole",
        "iam:ListRolePolicies",
        "iam:PutRolePolicy",
        "iam:UpdateRoleDescription"
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}
```

لذا إذا كنت تراقب `n` حساباً، فستحتاج دائماً إلى `n+1` دور. (`n` من RepokidRoles و `1` من RepokidInstanceProfile).

#### تحرير config.json

تشغيل `repokid config config.json` ينشئ ملفاً ستحتاج إلى تحريره. ابحث عن هذه الحقول وقم بتحديثها:
- `dynamodb`: إذا كنت تستخدم Dynamo محلياً، فاضبط نقطة النهاية على `http://localhost:8010`. إذا كنت تستخدم Dynamo المستضاف على AWS، فاضبط `region` و `assume_role` و `account_number`.
- `aardvark_api_location`: موقع واجهة Aardvark REST API الخاصة بك. شيء مثل `https://aardvark.yourcompany.net/api/1/advisors`
- `connection_iam`: عيّن `assume_role` إلى `RepokidRole`، أو أي اسم أطلقت عليه.

## إعدادات اختيارية
يستخدم Repokid عوامل تصفية لتحديد الأدوار المرشحة للإزالة. يمكن تكوين عوامل التصفية لتناسب بيئتك
كما هو موضح أدناه.

### عامل تصفية القائمة المحظورة (Blocklist Filter)
يمكن استبعاد الأدوار عن طريق إضافتها إلى عامل تصفية القائمة المحظورة. أحد الأسباب الشائعة لاستبعاد دور هو
أن عبء العمل المقابل يقوم بإجراءات عرضية قد لا تكون قد لوحظت ولكن من المعروف أنها مطلوبة.
هناك طريقتان لاستبعاد دور:

 - استبعاد اسم الدور لجميع الحسابات: أضفه إلى قائمة في الإعدادات `filter_config.BlocklistFilter.all`
 - استبعاد اسم الدور لحساب محدد: أضفه إلى قائمة في الإعدادات `filter_config.BlocklistFilter.<ACCOUNT_NUMBER>`

يمكن أيضاً صيانة القوائم المحظورة في ملف S3 blocklist. يجب أن تكون بالشكل التالي:
 ```json
 {
   "arns": ["arn1", "arn2"],
   "names": {"role_name_1": ["all", "account_number_1"], "role_name_2": ["account_number_2", "account_number_3"]}
 }
 ```

### عامل التصفية الحصري (Exclusive Filter)
إذا كنت تفضل إزالة أدوار معينة فقط، يمكنك استخدام عامل التصفية الحصري. ربما تريد النظر فقط في الأدوار المستخدمة في الإنتاج أو من قبل فرق معينة.
لتحديد الأدوار للإزالة، يمكنك إدراج أسمائها في ملفات الإعدادات. كما أن أنماط glob بنمط Shell مدعومة أيضاً.
يمكن تحديد اختيار الدور لكل حساب على حدة أو بشكل عام.
لتفعيل هذا الفلتر، ضع `"repokid.filters.exclusive:ExclusiveFilter"` في القسم `active_filters` من ملف الإعدادات.
لتكوينه، يمكنك البدء بملف الإعدادات الذي تم إنشاؤه تلقائياً، والذي يحتوي على إعدادات مثال في القسم `"filter_config"`:

```
"ExclusiveFilter": {
                   "all": [
                     "<GLOB_PATTERN>"
                     ],
                   "<ACCOUNT_NUMBER>": [
                     "<GLOB_PATTERN>"
                    ]
                   }
```

### عامل تصفية العمر (Age Filter)
بشكل افتراضي، يستبعد عامل تصفية العمر الأدوار التي يكون عمرها أقل من 90 يوماً. لتغيير هذا، قم بتحرير إعداد الإعدادات:
`filter_config.AgeFilter.minimum_age`.

### عوامل التصفية النشطة (Active Filters)

يمكن إنشاء عوامل تصفية جديدة لدعم المنطق الداخلي. في Netflix، لدينا العديد منها خاصة
باستخداماتنا. لجعلها نشطة، تأكد من أنها في مسار Python وأضفها في الإعدادات إلى القائمة في
القسم `active_filters`.

## توسيع Repokid

### الخطافات (Hooks)

يمكن توسيع Repokid عبر خطافات يتم استدعاؤها قبل وأثناء وبعد عمليات متنوعة كما هو مدرج أدناه.

| اسم الخطاف | السياق |
|-----------|---------|
| `AFTER_REPO` | role, errors |
| `AFTER_REPO_ROLES` | roles, errors |
| `BEFORE_REPO_ROLES` | account_number, roles |
| `AFTER_SCHEDULE_REPO` | roles |
| `DURING_REPOABLE_CALCULATION` | role_id, arn, account_number, role_name, potentially_repoable_permissions, minimum_age |
| `DURING_REPOABLE_CALCULATION_BATCH` | role_batch, potentially_repoable_permissions, minimum_age |

يجب أن تلتزم الخطافات بالواجهة التالية:

```python
from repokid.hooks import implements_hook
from repokid.types import RepokidHookInput, RepokidHookOutput

@implements_hook("TARGET_HOOK_NAME", 1)
def custom_hook(input_dict: RepokidHookInput) -> RepokidHookOutput:
    """يتم استدعاء دوال الخطاف مع قاموس يحتوي على المفاتيح المدرجة أعلاه بناءً على الخطاف الهدف.
    سيتم تمرير أي تغييرات تُجرى على الإدخال وتُعاد في الإخراج إلى دوال الخطاف اللاحقة.
    """
    ...
```

يمكن العثور على أمثلة لتنفيذات الخطافات في [`repokid.hooks.loggers`](https://github.com/netflix/repokid/blob/master/repokid/hooks/loggers/__init__.py).

### عوامل التصفية (Filters)

يمكن كتابة عوامل تصفية مخصصة لاستبعاد الأدوار من الإزالة. يجب أن تلتزم عوامل التصفية بالواجهة التالية:

```python
from repokid.filters import Filter
from repokid.types import RepokidFilterConfig
from repokid.role import RoleList


class CustomFilterName(Filter):
    def __init__(self, config: RepokidFilterConfig = None) -> None:
        """يتم تهيئة عوامل التصفية باستخدام قاموس يحتوي على محتوى `filter_config.FilterName`
        من ملف الإعدادات. سيتم تهيئة هذا المثال باستخدام `filter_config.CustomFilterName`.
        يمكن الوصول إلى الإعدادات عبر `self.config`

        إذا كنت لا تحتاج إلى أي منطق تهيئة مخصص، يمكنك حذف هذه الدالة من
        فئة التصفية الخاصة بك.
        """
        super().__init__(config=config)
        # ضع منطق التهيئة المخصص هنا
        ...

    def apply(self, input_list: RoleList) -> RoleList:
        """حدد الأدوار التي سيتم استبعادها وأعدها كـ RoleList"""
        ...
```

يمكن العثور على تنفيذ بسيط لعامل تصفية في [`repokid.filters.age`](https://github.com/netflix/repokid/blob/master/repokid/filters/age/__init__.py). ومثال أكثر تعقيداً في [`repokid.blocklist.age`](https://github.com/netflix/repokid/blob/master/repokid/filters/blocklist/__init__.py).

## كيفية الاستخدام

بمجرد تكوين Repokid، استخدمه على النحو التالي:

### التدفق القياسي
 - تحديث ذاكرة التخزين المؤقت للأدوار: `repokid update_role_cache <ACCOUNT_NUMBER>`
 - عرض ذاكرة التخزين المؤقت للأدوار: `repokid display_role_cache <ACCOUNT_NUMBER>`
 - عرض معلومات حول دور محدد: `repokid display_role <ACCOUNT_NUMBER> <ROLE_NAME>`
 - إزالة دور محدد: `repokid repo_role <ACCOUNT_NUMBER> <ROLE_NAME>`
 - إزالة جميع الأدوار في حساب: `repokid repo_all_roles <ACCOUNT_NUMBER> -c`

### الجدولة
بدلاً من تشغيل عملية إزالة فوراً، يمكنك جدولة واحدة (أمر `schedule_repo`). المدة بين الجدولة والأهلية قابلة للتكوين، ولكن بشكل افتراضي يمكن إزالة الأدوار بعد 7 أيام من الجدولة. يمكنك بعد ذلك تشغيل أمر `repo_scheduled_roles` لإزالة الأدوار التي تم جدولتها فقط.

### استهداف صلاحية معينة

لنفترض أنك تجد صلاحية معينة خطيرة بشكل خاص في بيئتك. سأستخدم هنا `s3:PutObjectACL` كمثال. يمكنك استخدام Repokid للعثور على جميع الأدوار التي لديها هذه الصلاحية (حتى تلك المخفية في حرف بدل)، ثم إزالة تلك الصلاحية الواحدة فقط.

البحث والإزالة:
 - تأكد من تحديث ذاكرة التخزين المؤقت للأدوار قبل البدء.
 - ابحث عن الأدوار التي تحتوي على صلاحية معينة: `repokid find_roles_with_permissions <permission>... [--output=ROLE_FILE]`
 - إزالة الصلاحية من الأدوار: `repokid remove_permissions_from_roles --role-file=ROLE_FILE <permission>... [-c]`

مثال:
```
$ repokid find_roles_with_permissions "s3:putobjectacl" "sts:assumerole" --output=myroles.json
...
$ repokid remove_permissions_from_roles --role-file=myroles.json "s3:putobjectacl" "sts:assumerole" -c
```

### التراجع
يقوم Repokid بتخزين نسخة من كل إصدار من السياسات المضمنة التي يعرفها. تتم إضافتها عند
العثور على إصدار مختلف من سياسة أثناء `update_role_cache` وفي أي وقت يحدث فيه إجراء إزالة.
لاستعادة إصدار سابق، قم بتشغيل:

عرض جميع إصدارات الأدوار: `repokid rollback_role <ACCOUNT_NUMBER> <ROLE_NAME>`
استعادة إصدار محدد: `repokid rollback_role <ACCOUNT_NUMBER> <ROLE_NAME> --selection=<NUMBER> -c`

### الإحصائيات
يحتفظ Repokid بإحصاءات إجمالية للأذونات لكل دور. تتم إضافة الإحصائيات في أي وقت يحدث فيه إجراء `update_role_cache` أو
`repo_role`. لإخراج جميع الإحصائيات إلى ملف CSV، قم بتشغيل: `repokid repo_stats <OUTPUT_FILENAME>`. يمكن تحديد رقم حساب اختياري لإخراج إحصائيات لحساب محدد فقط.

### المكتبة

> جديد في `v0.14.2`

يمكن استدعاء Repokid كمكتبة باستخدام الوحدة `repokid.lib`:

```python
from repokid.lib import display_role, repo_role, update_role_cache

account_number = "123456789012"

display_role(account_number, "superCoolRoleName")
update_role_cache(account_number)
repo_role(account_number, "superCoolRoleName", commit=True)
```

## المُوزع (Dispatcher)
تم تصميم موزع Repokid للاستماع إلى الرسائل في قائمة انتظار وتنفيذ الإجراءات. الإجراءات حتى الآن هي:
 - سرد الخدمات القابلة للإزالة من دور
 - تعيين أو إزالة خيار إلغاء الاشتراك (opt-out)
 - سجل و قم بإجراء عمليات التراجع لدور

سيستجيب Repokid على موضوع SNS قابل للتكوين بمعلومات حول أي نجاح أو فشل. يوجد مكون الموزع
للمساعدة في تشغيل دورة حياة الإزالة عبر مؤسستك. يمكنك اختيار
فضح قائمة الانتظار مباشرة للمطورين، ولكن من المحتمل أن يتم حماية هذا لأن التراجع يمكن أن يكون
إجراءً مدمراً إذا لم يتم بحذر.

## التطوير

### الإصدارات

تتم إدارة الإصدارات بواسطة [setupmeta](https://github.com/zsimic/setupmeta). لإنشاء إصدار جديد:

```bash
python setup.py version --bump patch --push

# فحص الإخراج وتأكد من أنه ما تتوقعه
# إذا كان كل شيء على ما يرام، قم بتنفيذ الالتزام ودفع العلامة الجديدة:
python setup.py version --bump patch --push --commit
```