ladder

<p align="center">
    <img src="https://raw.githubusercontent.com/everywall/ladder/HEAD/assets/pigeon.svg" width="100px">
</p>

<h1 align="center">Ladder</h1>
<div><img alt="License" src="https://img.shields.io/github/license/everywall/ladder"> <img alt="go.mod Go version " src="https://img.shields.io/github/go-mod/go-version/everywall/ladder"> <img alt="GitHub tag (with filter)" src="https://img.shields.io/github/v/tag/everywall/ladder"> <img alt="GitHub (Pre-)Release Date" src="https://img.shields.io/github/release-date-pre/everywall/ladder"> <img alt="GitHub Downloads all releases" src="https://img.shields.io/github/downloads/everywall/ladder/total"> <img alt="GitHub Build Status (with event)" src="https://img.shields.io/github/actions/workflow/status/everywall/ladder/release-binaries.yaml"></div>


*Ladder هو وكيل ويب HTTP.* 

[简体中文](https://github.com/everywall/ladder/blob/main/README.zh-CN.md)

Ladder هو أداة للمطورين لاختبار وتحليل تطبيقات أنظمة الدفع (paywalls) وسلوك توصيل المحتوى على المواقع الحديثة.

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

صُمم Ladder لأغراض الاختبار والبحث وضمان الجودة المشروعة فقط. ويجب استخدامه فقط بما يتوافق مع القوانين المعمول بها وشروط خدمة الموقع المستهدف.

![screenshot](https://assets.kitploit.com/production/public/readmes/43336/3002b002c6fb6a92722c4bfc86471341080d8f30a0842c4688474dfcc78ef4e7.png)

### كيف يعمل

```mermaid
sequenceDiagram
    client->>+ladder: GET
    ladder-->>ladder: apply RequestModifications
    ladder->>+website: GET
    website->>-ladder: 200 OK
    ladder-->>ladder: apply ResultModifications
    ladder->>-client: 200 OK
```

### الميزات
- [x] إزالة/تعديل ترويسات CORS من الاستجابات والأصول والصور ...
- [x] إزالة/تعديل الترويسات الأخرى (مثل Content-Security-Policy)
- [x] إزالة/حقن كود مخصص (HTML, CSS, JavaScript) في الصفحة
- [x] تطبيق قواعد/كود مبنية على النطاق لتعديل الاستجابة / عنوان URL المطلوب
- [x] إبقاء الموقع قابلًا للتصفح
- [x] API
- [x] جلب HTML الخام (RAW)
- [x] وكيل مستخدم مخصص
- [x] عنوان IP مخصص لـ X-Forwarded-For
- [x] [حاوية Docker](https://github.com/everywall/ladder/pkgs/container/ladder) (amd64, arm64)
- [x] ملف ثنائي لينكس
- [x] ملف ثنائي لنظام Mac OS
- [x] ملف ثنائي لنظام Windows (غير مُختبَر)
- [x] المصادقة الأساسية (Basic Auth)
- [x] سجلات الوصول
- [x] قد يكسر التتبع والإعلانات ومحتوى الأطراف الثالثة
- [x] قصر الوكيل على قائمة نطاقات
- [x] إتاحة مجموعة القواعد (Ruleset) لنسخ Ladder الأخرى
- [ ] اختبار Robots.txt
- [ ] وكيل TOR اختياري
- [ ] مفتاح لمشاركة رابط تمت بروكسته

### القيود
تقدم بعض المواقع محتوى مختلفًا (إخفاء/Cloaking) اعتمادًا على نوع العميل الذي يصل إليها (على سبيل المثال، برامج زحف محركات البحث مقابل متصفحات الويب القياسية). يمكن تكوين Ladder لمحاكاة أنواع عملاء مختلفة من أجل استرجاع المحتوى المتاح للعامة لأغراض الاختبار أو الأتمتة أو البحث.

ومع ذلك، تنفذ العديد من المواقع آليات متقدمة لتقييد الوصول الآلي، مثل البصمة الرقمية (fingerprinting)، أو تحديد المعدل (rate limiting)، أو التحليل السلوكي. لا يتجاوز Ladder هذه الحمايات وقد لا يعمل بشكل صحيح على الخدمات التي تقيد الوصول أو تتحكم فيه بنشاط.

توجد أدوات تابعة لجهات خارجية مثل FlareSolverr ويمكن استخدامها بشكل مستقل لعرض صفحات الويب في بيئة متصفح بدون واجهة رسومية (headless). هذه الأدوات ليست جزءًا من Ladder، وقد يخضع استخدامها لقيود قانونية وتعاقدية. يتحمل المستخدمون وحدهم مسؤولية ضمان امتثال استخدامهم لجميع اللوائح المعمول بها.

## التثبيت

> **تحذير:** إذا كان مثيلك (instance) سيكون متاحًا للجمهور، فتأكد من تفعيل المصادقة الأساسية (Basic Auth). سيمنع ذلك المستخدمين غير المصرح لهم من استخدام وكيلك. إذا لم تفعّل المصادقة الأساسية، يمكن لأي شخص استخدام وكيلك لتصفح محتوى سيئ/غير قانوني. وستُحمَّل المسؤولية عن ذلك.

### الملف الثنائي
1) نزّل الملف الثنائي [من هنا](https://github.com/everywall/ladder/releases/latest)
2) فك الضغط وشغّل الملف الثنائي `./ladder -r https://raw.githubusercontent.com/everywall/ladder-rules/main/ruleset.yaml`
3) افتح المتصفح (الافتراضي: http://localhost:8080)

### Docker
```bash
docker run -p 8080:8080 -d --env RULESET=https://raw.githubusercontent.com/everywall/ladder-rules/main/ruleset.yaml --name ladder ghcr.io/everywall/ladder:latest
```

### Docker Compose
```bash
curl https://raw.githubusercontent.com/everywall/ladder/main/docker-compose.yaml --output docker-compose.yaml
docker-compose up -d
```

### Helm
انظر [README.md](https://github.com/everywall/ladder/blob/main/helm-chart/README.md) في المجلد الفرعي helm-chart لمزيد من المعلومات.

## الاستخدام

### المتصفح
1) افتح المتصفح (الافتراضي: http://localhost:8080)
2) أدخل عنوان URL
3) اضغط Enter

أو بشكل مباشر بإلحاق عنوان URL بنهاية عنوان الوكيل:
http://localhost:8080/https://www.example.com

أو أنشئ إشارة مرجعية (bookmark) بالعنوان التالي:
```javascript
javascript:window.location.href="http://localhost:8080/"+location.href
```

### API
```bash
curl -X GET "http://localhost:8080/api/https://www.example.com"
```

### RAW
http://localhost:8080/raw/https://www.example.com

### تشغيل مجموعة القواعد (Ruleset)
http://localhost:8080/ruleset

## الإعدادات

### متغيرات البيئة

| المتغير | الوصف | القيمة |
| --- | --- | --- |
| `PORT` | المنفذ الذي سيستمع عليه | `8080` |
| `PREFORK` | تشغيل عدة مثيلات للخادم | `false` |
| `USER_AGENT` | وكيل المستخدم الذي سيتم محاكاته | `Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)` |
| `X_FORWARDED_FOR` | عنوان إعادة توجيه IP | `66.249.66.1` |
| `USERPASS` | يفعّل المصادقة الأساسية، الصيغة `admin:123456` | `` |
| `LOG_URLS` | تسجيل عناوين URL التي تم جلبها | `true` |
| `DISABLE_FORM` | يعطّل نموذج URL في الواجهة الأمامية | `false` |
| `FORM_PATH` | المسار إلى نموذج HTML مخصص | `` |
| `RULESET` | مسار أو عنوان URL لملف مجموعة القواعد، يقبل المجلدات المحلية | `https://raw.githubusercontent.com/everywall/ladder-rules/main/ruleset.yaml` أو `/path/to/my/rules.yaml` أو `/path/to/my/rules/` |
| `EXPOSE_RULESET` | جعل مجموعة القواعد الخاصة بك متاحة لنسخ Ladder أخرى | `true` |
| `ALLOWED_DOMAINS` | قائمة مفصولة بفواصل بالنطاقات المسموح بها. فارغ = لا قيود | `` |
| `ALLOWED_DOMAINS_RULESET` | السماح بالنطاقات من مجموعة القواعد. false = لا قيود | `false` |
| `FLARESOLVERR_HOST` | عنوان URL لخدمة FlareSolverr لتجاوز Cloudflare (اختياري) | `http://localhost:8191` |

`ALLOWED_DOMAINS` و `ALLOWED_DOMAINS_RULESET` يتم دمجهما معًا. إذا كان كلاهما فارغًا، فلن تُطبَّق أي قيود.
| `BASE_PATH` | المسار الأساسي للوكيل، مفيد إذا كنت تريد تشغيل الوكيل على مسار فرعي (مثل: http://localhost:8080/proxy/) | `` |

### مجموعة القواعد (Ruleset)

من الممكن تطبيق قواعد مخصصة لتعديل الاستجابة أو عنوان URL المطلوب. يمكن استخدام ذلك لإزالة عناصر غير مرغوب فيها أو تعديل عناصر من الصفحة. مجموعة القواعد عبارة عن ملف YAML، أو مجلد يحتوي على ملفات YAML، أو عنوان URL لملف YAML يحتوي على قائمة قواعد لكل نطاق. يتم تحميل هذه القواعد عند بدء التشغيل.

توجد مجموعة قواعد أساسية متاحة في مستودع منفصل [ruleset.yaml](https://raw.githubusercontent.com/everywall/ladder-rules/main/ruleset.yaml). لا تتردد في إضافة قواعدك الخاصة وإنشاء طلب سحب (pull request).

```yaml
- domain: example.com          # Includes all subdomains
  domains:                     # Additional domains to apply the rule
    - www.example.de
    - www.beispiel.de
  headers:
    x-forwarded-for: none      # override X-Forwarded-For header or delete with none
    referer: none              # override Referer header or delete with none
    user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36
    content-security-policy: script-src 'self'; # override response header
    cookie: privacy=1
  regexRules:
    - match: <script\s+([^>]*\s+)?src="(/)([^"]*)"
      replace: <script $1 script="/https://www.example.com/$3"
  injections:
    - position: head # Position where to inject the code
      append: |      # possible keys: append, prepend, replace
        <script>
          window.localStorage.clear();
          console.log("test");
          alert("Hello!");
        </script>
- domain: www.anotherdomain.com # Domain where the rule applies
  useFlareSolverr: false        # Use FlareSolverr for Cloudflare bypass (optional, default: false)
  paths:                        # Paths where the rule applies
    - /article
  googleCache: false            # Use Google Cache to fetch the content
  regexRules:                   # Regex rules to apply
    - match: <script\s+([^>]*\s+)?src="(/)([^"]*)"
      replace: <script $1 script="/https://www.example.com/$3"
  injections:
    - position: .left-content article .post-title # Position where to inject the code into DOM
      replace: | 
        <h1>My Custom Title</h1>
    - position: .left-content article # Position where to inject the code into DOM
      prepend: | 
        <h2>Subtitle</h2>
- domain: demo.com
  headers:
    content-security-policy: script-src 'self';
    user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36
  urlMods:              # Modify the URL
    query:              
      - key: amp        # (this will append ?amp=1 to the URL)
        value: 1 
    domain:             
      - match: www      # regex to match part of domain
        replace: amp    # (this would modify the domain from www.demo.de to amp.demo.de)
    path:               
      - match: ^        # regex to match part of path
        replace: /amp/  # (modify the url from https://www.demo.com/article/ to https://www.demo.de/amp/article/)
```

## تكامل FlareSolverr

يدعم Ladder الآن التكامل مع [FlareSolverr](https://github.com/FlareSolverr/FlareSolverr) لتجاوز حماية Cloudflare والتحديات الأخرى لمكافحة الروبوتات. وهذا مفيد بشكل خاص للمواقع التي تستخدم آليات متطورة لكشف الروبوتات.

### إعداد FlareSolverr

1. **استخدام Docker Compose (موصى به):**
   ```yaml
   # docker-compose.yaml
   services:
     ladder:
       image: ghcr.io/everywall/ladder:latest
       ports:
         - "8080:8080"
       environment:
         - RULESET=https://raw.githubusercontent.com/everywall/ladder-rules/main/ruleset.yaml
         # - FLARESOLVERR_HOST=http://flaresolverr:8191
       depends_on:
         - flaresolverr
     
     flaresolverr:
       image: ghcr.io/flaresolverr/flaresolverr:latest
       ports:
         - "8191:8191"
       environment:
         - LOG_LEVEL=info
   ```

2. **تشغيل FlareSolverr بشكل منفصل:**
   ```bash
   docker run -d \
     --name flaresolverr \
     -p 8191:8191 \
     ghcr.io/flaresolverr/flaresolverr:latest
   ```

   ثم ابدأ تشغيل Ladder مع عنوان URL الخاص بـ FlareSolverr:
   ```bash
   FLARESOLVERR_HOST=http://localhost:8191 ./ladder
   ```

### تكوين القواعد لـ FlareSolverr

لاستخدام FlareSolverr لنطاقات محددة، أضف العلم `useFlareSolverr: true` في مجموعة القواعد الخاصة بك:

```yaml
# Example ruleset with FlareSolverr
- domain: cloudflare-protected-site.com
  useFlareSolverr: true  # Enable FlareSolverr for this domain
  headers:
    user-agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
    accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"

# Regular site without FlareSolverr
- domain: regular-site.com
  headers:
    user-agent: "Custom User Agent 1.0"
```

### حالات الاستخدام

يعتبر تكامل FlareSolverr مفيدًا بشكل خاص في:
- **المواقع المحمية بواسطة Cloudflare**: المواقع التي تستخدم تحديات Cloudflare لمكافحة الروبوتات
- **المواقع التي تستخدم تحديات JavaScript**: الصفحات التي تتطلب تنفيذ JavaScript للوصول إلى المحتوى
- **تحميل المحتوى الديناميكي**: المواقع التي تحمّل المحتوى ديناميكيًا عبر JavaScript
- **كشف الروبوتات المتقدم**: المواقع التي تستخدم تقنيات متطورة للبصمة الرقمية وكشف الروبوتات

### ملاحظات مهمة

- يضيف FlareSolverr زمن استجابة إضافيًا للطلبات لأنه يحتاج إلى حل التحديات
- قم بتمكين `useFlareSolverr` فقط للنطاقات التي تحتاجه فعليًا للحفاظ على الأداء
- يتطلب FlareSolverr موارد أكثر لأنه يشغّل متصفحًا بدون واجهة رسومية
- تأكد من أن FlareSolverr قيد التشغيل ويمكن الوصول إليه قبل تمكينه في مجموعة القواعد الخاصة بك

## التطوير

لتشغيل خادم تطوير على http://localhost:8080:

```bash
echo "dev" > handlers/VERSION
RULESET="./ruleset.yaml" go run cmd/main.go
```

### اختياري: خادم تطوير بإعادة التحميل المباشر مع [cosmtrek/air](https://github.com/cosmtrek/air)

ثبّت air وفقًا [لتعليمات التثبيت](https://github.com/cosmtrek/air#installation).

شغّل خادم تطوير على http://localhost:8080:

```bash
air # or the path to air if you haven't added a path alias to your .bashrc or .zshrc
```

يستخدم هذا المشروع [pnpm](https://pnpm.io/) لبناء ورقة أنماط مع فئات [Tailwind CSS](https://tailwindcss.com/). للتطوير المحلي، إذا عدّلت الأنماط في `form.html`، قم بتشغيل `pnpm build` لإنشاء ورقة أنماط جديدة.