ggshield

# [ggshield](https://github.com/GitGuardian/ggshield): احمِ الكود الخاص بك باستخدام GitGuardian

[![PyPI](https://img.shields.io/pypi/v/ggshield?color=%231B2D55&style=for-the-badge)](https://pypi.org/project/ggshield/)
[![Docker Image Version (latest semver)](https://img.shields.io/docker/v/gitguardian/ggshield?color=1B2D55&sort=semver&style=for-the-badge&label=Docker)](https://hub.docker.com/r/gitguardian/ggshield)
[![License](https://img.shields.io/github/license/GitGuardian/ggshield?color=%231B2D55&style=for-the-badge)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/gitguardian/ggshield?color=%231B2D55&style=for-the-badge)](https://github.com/GitGuardian/ggshield/stargazers)
[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/GitGuardian/ggshield/main.yml?branch=main&style=for-the-badge)](https://github.com/GitGuardian/ggshield/actions)
[![Codecov](https://img.shields.io/codecov/c/github/GitGuardian/ggshield?style=for-the-badge)](https://codecov.io/gh/GitGuardian/ggshield/)

> [!IMPORTANT]
> **macOS: الترقية إلى 1.54.0 تؤدي إلى ظهور مطالبة Keychain لـ `ggshield-py`**، وهو ملف تنفيذي ثانٍ يقرأ الآن الرمز المميز المحفوظ لديك كجزء من تحسينات الأداء لدينا. انقر على **Always Allow**؛ لن يسأل مرة أخرى.

`ggshield` هو تطبيق CLI يعمل في بيئتك المحلية أو في بيئة CI لمساعدتك في اكتشاف أكثر من 500+ نوع من الأسرار.

يستخدم `ggshield` [واجهة برمجة التطبيقات العامة](https://api.gitguardian.com/docs) الخاصة بنا عبر [py-gitguardian](https://github.com/GitGuardian/py-gitguardian) لفحص واكتشاف الثغرات المحتملة في الملفات والمحتوى النصي الآخر.

يتم تخزين البيانات الوصفية فقط مثل وقت الاستدعاء وحجم الطلب ووضع الفحص من عمليات الفحص باستخدام `ggshield`، لذلك لن يتم عرض الأسرار على لوحة التحكم الخاصة بك و**لن يتم تخزين ملفاتك وأسرارك**.

# جدول المحتويات

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [التثبيت](#installation)
  - [نص التثبيت (موصى به)](#install-script-recommended)
  - [macOS](#macos)
    - [Homebrew](#homebrew)
    - [حزمة .pkg مستقلة](#standalone-pkg-package)
  - [Linux](#linux)
    - [حزم Deb و RPM](#deb-and-rpm-packages)
  - [Windows](#windows)
    - [Chocolatey](#chocolatey)
    - [مثبّت MSI](#msi-installer)
    - [أرشيف .zip مستقل](#standalone-zip-archive)
  - [جميع أنظمة التشغيل](#all-operating-systems)
    - [باستخدام pipx](#using-pipx)
    - [باستخدام pip](#using-pip)
- [الإعداد الأولي](#initial-setup)
  - [باستخدام `ggshield auth login`](#using-ggshield-auth-login)
  - [الإعداد اليدوي](#manual-setup)
- [بدء الاستخدام](#getting-started)
  - [الأسرار](#secrets)
  - [ترحيل ملف تكوين قديم](#migrating-a-legacy-configuration-file)
- [التكاملات](#integrations)
  - [مساعدو البرمجة بالذكاء الاصطناعي](#ai-coding-assistants)
- [معرفة المزيد](#learn-more)
- [المخرجات](#output)
- [مشاريع مفتوحة المصدر ذات صلة](#related-open-source-projects)
- [الترخيص](#license)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

# التثبيت

<!--
Any change made in this section must be replicated in the "Step 1: Install
ggshield" section of the "Getting started" page of ggshield public
documentation.
-->

## نص التثبيت (موصى به)

أسرع طريقة لتثبيت `ggshield`.

Linux / macOS:

```shell
curl -sSfL \
  https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.sh | bash
```

Windows (PowerShell):

```powershell
irm https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | iex
```

أو، إذا كنت تفضل `curl` (المضمّن مع Windows 10+):

```powershell
curl.exe -sSL https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | powershell -NoProfile -ExecutionPolicy Bypass -Command -
```

يقبل النص خيارات مثل `--instance` و `--plugin` (تثبيت
إضافة). بالنسبة لمساحة العمل الأوروبية أو نسخة مستضافة ذاتيًا، قم بتعيين
متغير البيئة `GITGUARDIAN_INSTANCE` (أو تمرير `--instance <URL>`)
قبل التشغيل.

راجع [`scripts/install/README.md`](https://github.com/gitguardian/ggshield/blob/main/scripts/install/README.md) للحصول على القائمة الكاملة
من الخيارات، وطرق التثبيت الأخرى، وكيفية إلغاء التثبيت.

تقوم الطرق أدناه بتثبيت CLI يدويًا بدلاً من ذلك.

## macOS

### Homebrew

يمكنك تثبيت `ggshield` باستخدام Homebrew:

```shell
brew install ggshield
```

تتم الترقية بواسطة Homebrew.

### حزمة .pkg مستقلة

بدلاً من ذلك، يمكنك تنزيل وتثبيت حزمة .pkg مستقلة من [صفحة إصدارات `ggshield`](https://github.com/GitGuardian/ggshield/releases).

هذه الحزمة _لا_ تتطلب تثبيت Python، ولكن عليك تنزيل الإصدارات الجديدة يدويًا.

## Linux

### حزم Deb و RPM

حزم Deb و RPM متاحة على [Cloudsmith](https://cloudsmith.io/~gitguardian/repos/ggshield/packages/).

تعليمات الإعداد:

- [حزم Deb](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-deb)
- [حزم RPM](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-rpm)

تتم الترقية بواسطة مدير الحزم.

## Windows

### Chocolatey

`ggshield` متاح عبر [مدير حزم Chocolatey](https://chocolatey.org/packages/ggshield):

```shell
choco install ggshield
```

### مثبّت MSI

قم بتنزيل مثبّت MSI من [صفحة إصدارات `ggshield`](https://github.com/GitGuardian/ggshield/releases) وقم بتثبيته:

```powershell
msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi
```

### أرشيف .zip مستقل

نوفر أرشيف .zip مستقل على [صفحة إصدارات `ggshield`](https://github.com/GitGuardian/ggshield/releases).

قم بفك ضغط الأرشيف على القرص الخاص بك، ثم أضف الدليل الذي يحتوي على ملف `ggshield.exe` إلى `%PATH%`.

هذا الأرشيف _لا_ يتطلب تثبيت Python، ولكن عليك تنزيل الإصدارات الجديدة يدويًا.

## جميع أنظمة التشغيل

يمكن تثبيت `ggshield` على جميع أنظمة التشغيل المدعومة عبر [حزمة PyPI](https://pypi.org/project/ggshield).

يتطلب **إصدارًا مدعومًا من Python (غير منتهي الصلاحية)** (باستثناء الحزم المستقلة) و git.

إذا كنت لا تستخدم إصداراتنا المعبأة من `ggshield`، فيرجى العلم أننا نتبع [دورة إصدار Python](https://devguide.python.org/versions/) ولا ندعم الإصدارات التي وصلت إلى نهاية العمر الافتراضي (EOL).

### باستخدام pipx

الطريقة الموصى بها لتثبيت `ggshield` من PyPI هي استخدام [pipx](https://pypa.github.io/pipx/)، والذي سيثبته في بيئة معزولة:

```shell
pipx install ggshield
```

لترقية التثبيت الخاص بك، قم بتشغيل:

```shell
pipx upgrade ggshield
```

### باستخدام pip

يمكنك أيضًا تثبيت `ggshield` من PyPI باستخدام pip، ولكن هذا غير موصى به لأن التثبيت غير معزول، لذلك قد تؤثر التطبيقات أو الحزم الأخرى المثبتة بهذه الطريقة على تثبيت `ggshield` الخاص بك. لن تعمل هذه الطريقة أيضًا إذا كان تثبيت Python الخاص بك معلنًا كـ externally managed (على سبيل المثال عند استخدام Python النظام على أنظمة تشغيل مثل Debian 12):

```shell
pip install --user ggshield
```

لترقية التثبيت الخاص بك، قم بتشغيل:

```shell
pip install --user --upgrade ggshield
```

# الإعداد الأولي

## باستخدام `ggshield auth login`

لاستخدام `ggshield` تحتاج إلى المصادقة مقابل خوادم GitGuardian. للقيام بذلك، استخدم الأمر `ggshield auth login`. يقوم هذا الأمر بأتمتة توفير رمز وصول شخصي وتكوينه على محطة العمل المحلية.

يمكنك معرفة المزيد عنه من [وثائق `ggshield auth login`](https://docs.gitguardian.com/internal-repositories-monitoring/ggshield/reference/auth/login).

بعد المصادقة، قم بتشغيل `ggshield machine setup` لتكوين خطافات AI و git،
وزرع honeytokens، وتسجيل الجهاز في صفحة Endpoints قبل أول
فحص. يتضمن التسجيل المستخدم الحالي، أو جميع مستخدمي honeytoken المستهدفين عند
التشغيل كـ root. إنه بذل أفضل جهد، ويستغرق خمس ثوانٍ على الأكثر، ولا يؤثر
على رمز الخروج للأمر.

ترسل عمليات الفحص `ggshield secret scan pre-commit` و `pre-push` و `ai-hook` أيضًا
اسم مضيف الجهاز، والذي منه يسجل GitGuardian مستخدمي هذه الخطافات.
لا ترسله أوامر الفحص الأخرى، ولا يرسله خطاف AI الأصلي الذي تشغله
عمليات تثبيت `pip` المستقلة والخاصة بالمنصة.

في CI، لا يسجل ggshield الجهاز ولا يرسل اسم المضيف. لإيقاف كليهما
في مكان آخر، قم بتعيين `endpoint_registration: false` في `.gitguardian.yaml`، أو قم بتعيين
`GGSHIELD_NO_ENDPOINT_REGISTRATION` إلى قيمة غير فارغة.

## الإعداد اليدوي

يمكنك أيضًا إنشاء رمز الوصول الشخصي الخاص بك يدويًا وتخزينه في متغير البيئة `GITGUARDIAN_API_KEY` لإكمال الإعداد.

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

## الأسرار

يمكنك الآن استخدام `ggshield` للبحث عن الأسرار:

- في الملفات: `ggshield secret scan path -r .`
- في المستودعات: `ggshield secret scan repo .`
- في صور Docker (يجب أن يكون أمر `docker` متاحًا): `ggshield secret scan docker ubuntu:22.04`
- في حزم Pypi (يجب أن يكون أمر `pip` متاحًا): `ggshield secret scan pypi flask`
- والمزيد، ألقِ نظرة على مخرجات `ggshield secret scan --help` للحصول على التفاصيل.

## ترحيل ملف تكوين قديم

إذا أبلغ `ggshield` أن ملف التكوين `.gitguardian.yaml` (أو `.gitguardian.yml`) الخاص بك يستخدم تنسيقًا مهملاً، فقم بترحيله إلى أحدث إصدار باستخدام:

```shell
ggshield config migrate
```

بشكل افتراضي، يبحث هذا عن ملف التكوين في الدليل الحالي، لذا قم بتشغيله من الدليل الذي يحتوي على الملف. لتشغيله من أي مكان، وجّه `ggshield` إلى الملف بشكل صريح:

```shell
ggshield --config-path path/to/.gitguardian.yaml config migrate
```

يتم الاحتفاظ بالإصدار السابق من الملف كنسخة احتياطية `.old` بجانبه.

# التكاملات

يمكنك دمج `ggshield` في [سير عمل CI/CD](https://docs.gitguardian.com/ggshield-docs/integrations/overview#cicd-integrations-secrets-detection-in-your-cicd-workflow) الخاص بك.

لاكتشاف الأخطاء مبكرًا، استخدم `ggshield` كـ [خطاف Git pre-commit أو pre-push أو pre-receive](https://docs.gitguardian.com/ggshield-docs/integrations/overview#git-hooks-prevent-secrets-from-reaching-your-vcs).

## مساعدو البرمجة بالذكاء الاصطناعي

يمكن لـ `ggshield` [فحص التفاعلات](https://docs.gitguardian.com/ggshield-docs/integrations/ai-coding-tools/secret-scanning-for-ai-coding-tools) بينك وبين مساعد البرمجة بالذكاء الاصطناعي في الوقت الفعلي، مما يحظر الإجراءات التي تحتوي على أسرار قبل تنفيذها.

يمكنك تثبيت الخطافات باستخدام الأمر `ggshield install`.

الأدوات المدعومة: **Cursor**، **Claude Code**، **Copilot Chat**، **Codex**، و
**Mistral Vibe 2.21+**.

# معرفة المزيد

لمزيد من المعلومات، ألقِ نظرة على [الوثائق](https://docs.gitguardian.com/ggshield-docs/getting-started)

# المخرجات

إذا لم يتم العثور على أسرار، سيكون رمز الخروج 0:

```bash
ggshield secret scan pre-commit
```

إذا تم العثور على سر في الكود المُجهّز أو في CI الخاص بك، ستحصل على تنبيه يعطيك اسم الملف حيث تم العثور على السر ورقعة تعطيك موضع السر في الملف:

```shell
ggshield secret scan pre-commit
```

```
2 incidents have been found in file production.rb

11 | config.paperclip_defaults = {
12 |     :s3_credentials => {
13 |     :bucket => "XXX",
14 |     :access_key_id => "XXXXXXXXXXXXXXXXXXXX",
                            |_____AWS Keys_____|

15 |     :secret_access_key => "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
                                |_______________AWS Keys_______________|

16 |     }
17 | }
```

يتم اقتطاع الأسطر الطويلة جدًا لتتناسب مع حجم الطرفية، ما لم يتم استخدام الوضع المطوّل (`-v` أو `--verbose`).

# مشاريع مفتوحة المصدر ذات صلة

- [truffleHog](https://github.com/dxa4481/truffleHog)
- [gitleaks](https://github.com/zricethezav/gitleaks)
- [gitrob](https://github.com/michenriksen/gitrob)
- [git-hound](https://github.com/tillson/git-hound)
- [AWS git-secrets](https://github.com/awslabs/git-secrets)
- [detect-secrets](https://github.com/Yelp/detect-secrets)

# الترخيص

`ggshield` مرخّص بموجب MIT.