Martian Proxy

Martian Proxy هو بروكسي HTTP قابل للبرمجة مصمم للاستخدام في الاختبار.

Martian أداة رائعة لاستخدامها إذا أردت أن:

• تتحقق من أن جميع الطلبات (أو مجموعة فرعية منها) آمنة
• تحاكي الخدمات الخارجية في طبقة الشبكة
• تحقن الترويسات، أو تعدّل ملفات تعريف الارتباط (cookies)، أو تجري تحويرات أخرى على طلبات HTTP واستجاباتها
• تتحقق من حدوث إشعارات الارتداد (pingbacks) عندما تعتقد أنه ينبغي أن تحدث
• تفك تشفير حركة المرور المشفرة (يتطلب تثبيت شهادة CA في المتصفح)

من خلال الاستفادة من قابلية Go للترجمة المتقاطعة، يمكن نشر Martian في أي مكان يمكن لـ Go أن تستهدفه.

أحدث إصدار

v3.0.0

المتطلبات

Go 1.11

دعم وحدات Go

أضاف Martian Proxy دعمًا لوحدات Go منذ الإصدار v3.0.0. إذا كنت تستخدم إصدار Go لا يدعم الوحدات، فسيؤدي ذلك إلى كسر الأمور لديك. أحدث إصدار بدون دعم وحدات Go تم وسمه v2.1.0.

البدء

التثبيت

يمكن تثبيت Martian Proxy باستخدام go install

go get github.com/google/martian/ && \
go install github.com/google/martian/cmd/proxy

تشغيل البروكسي

بافتراض أنك قمت بتثبيت Martian، فإن تشغيل البروكسي يكون ببساطة:

$GOPATH/bin/proxy

إذا أردت رؤية سجلات النظام أثناء تشغيل Martian، مرر علامة مستوى التفصيل:

$GOPATH/bin/proxy -v=2

افتراضيًا، سيعمل Martian على المنفذ 8080، وستعمل واجهة برمجة تطبيقات Martian على المنفذ 8181. ويمكن تحديد المنفذ عبر العلامات:

$GOPATH/bin/proxy -addr=:9999 -api-addr=:9898

التسجيل

لتسجيل الطلبات والاستجابات، يتوفر مُعدِّل تسجيل أو سجلات HAR إذا تم استخدام علامة -har.

تسجيل HAR

لتمكين تسجيل HAR في Martian، قم باستدعاء البرنامج بالعلامة -har:

$GOPATH/bin/proxy -har

إذا تم تمكين علامة -har، فستتوفر نقطتا نهاية مرتبطتان بـ HAR:

GET http://martian.proxy/logs

سيؤدي ذلك إلى استرداد سجل HAR لجميع الطلبات والاستجابات التي شاهدها البروكسي منذ آخر إعادة تعيين.

DELETE http://martian.proxy/logs/reset

سيؤدي ذلك إلى إعادة تعيين سجل HAR المحفوظ في الذاكرة. لاحظ أن السجل سينمو بدون حدود ما لم تتم إعادة تعيينه دوريًا.

الإعداد

بمجرد تشغيل Martian، تحتاج إلى تكوين سلوكه. بدون إعداد، يكون Martian مجرد بروكسي دون القيام بأي شيء بالطلبات أو الاستجابات. إذا تم تمكين التسجيل، فسيتم التسجيل دون إعداد إضافي.

يتم تكوين Martian عبر رسائل JSON تُرسل عبر HTTP وتأخذ الشكل العام التالي:

{
  "header.Modifier": {
    "scope": ["response"],
    "name": "Test-Header",
    "value": "true"
  }
}

يخبر الإعداد أعلاه Martian بحقن ترويسة باسم "Test-Header" وقيمة "true" في جميع الاستجابات.

دعنا نحلل أجزاء هذه الرسالة.

• [package.Type]: هو package.Type للمُعدِّل الذي تريد استخدامه. في هذه الحالة، هو "header.Modifier"، وهو اسم المُعدِّل الذي يعيّن الترويسات (لمعرفة المزيد عن header.Modifier، يرجى الرجوع إلى مرجع المُعدِّلات).

• [package.Type].scope: يشير إلى ما إذا كان سيتم تطبيق المُعدِّل على الطلبات أو الاستجابات أو كليهما. يمكن أن يكون مصفوفة تحتوي على "request" أو "response" أو كليهما.

• [package.Type].[key]: بيانات خاصة بالمُعدِّل. في حالة مُعدِّل الترويسات، نحتاج إلى name و value للترويسة.

هذا إعداد بسيط، أما بالنسبة للإعدادات الأكثر تعقيدًا، يتم دمج المُعدِّلات مع المجموعات والفلاتر لتكوين السلوك المطلوب.

لتكوين Martian، أرسل POST للـ JSON إلى http://martian.proxy/modifiers. ستحتاج إلى استخدام أي آلية توفرها لغة البرمجة التي تختارها لإجراء طلبات HTTP، ولكن لأغراض العرض التوضيحي، يعمل curl (بافتراض أن إعدادك موجود في ملف باسم modifier.json).

    curl -x localhost:8080 \
         -X POST \
         -H "Content-Type: application/json" \
         -d @modifier.json \
            "http://martian.proxy/configure"

اعتراض طلبات واستجابات HTTPS

يدعم Martian تعديل طلبات واستجابات HTTPS إذا تم إعداده للقيام بذلك.

لكي يتمكن Martian من اعتراض حركة مرور HTTPS، يجب تثبيت شهادة CA مخصصة في المتصفح بحيث لا تظهر تحذيرات الاتصال.

أسهل طريقة لتثبيت شهادة CA هي تشغيل البروكسي بالعلامات اللازمة لاستخدام شهادة CA ومفتاح خاص مخصصين عبر العلامتين -cert و -key، أو جعل البروكسي يقوم بإنشاء واحدة باستخدام علامة -generate-ca-cert.

بعد بدء تشغيل البروكسي، قم بزيارة http://martian.proxy/authority.cer في المتصفح الذي تم إعداده لاستخدام البروكسي وستظهر رسالة لتثبيت الشهادة.

تتوفر عدة علامات في examples/main.go للمساعدة في إعداد وظيفة MITM:

-key=""
  PEM encoded private key file of the CA certificate provided in -cert; used
  to sign certificates that are generated on-the-fly
-cert=""
  PEM encoded CA certificate file used to generate certificates
-generate-ca-cert=false
  generates a CA certificate and private key to use for man-in-the-middle;
  most users choosing this option will immediately visit
  http://martian.proxy/authority.cer in the browser whose traffic is to be
  intercepted to install the newly generated CA certificate
-organization="Martian Proxy"
  organization name set on the dynamically-generated certificates during
  man-in-the-middle
-validity="1h"
  window of time around the time of request that the dynamically-generated
  certificate is valid for; the duration is set such that the total valid
  timeframe is double the value of validity (1h before & 1h after)

فحص المُتحقِّقات

لنفترض أنك قمت بإعداد Martian للتحقق من وجود ترويسة محددة في الاستجابات لعنوان URL محدد.

إليك إعداد للتحقق من أن جميع الطلبات إلى example.com تعيد استجابات برمز 200 OK.

      {
        "url.Filter": {
          "scope": ["request", "response"],
          "host" : "example.com",
          "modifier" : {
            "status.Verifier": {
              "scope" : ["response"],
              "statusCode": 200
            }
          }
        }
      }

بمجرد أن يكون Martian قيد التشغيل ومُعدًّا وتمت الطلبات والاستجابات الناتجة التي ترغب في التحقق منها، يمكنك التحقق من توقعك بأنك حصلت فقط على استجابات 200 OK.

لإجراء الفحوصات، نفّذ:

GET http://martian.proxy/verify

يتم تتبع التوقعات الفاشلة كأخطاء، ويتم استرداد قائمة الأخطاء عن طريق إجراء طلب GET إلى host:port/martian/verify، والذي سيعيد قائمة بالأخطاء:

  {
      "errors" : [
          {
              "message": "response(http://example.com) status code verify failure: got 500, want 200"
          },
          {
              "message": "response(http://example.com/foo) status code verify failure: got 500, want 200"
          }
      ]
  }

تُحفظ أخطاء التحقق في الذاكرة حتى يتم مسحها صراحةً عبر:

POST http://martian.proxy/verify/reset

Martian كمكتبة

يمكن أيضًا تضمين Martian في أي برنامج Go واستخدامه كمكتبة.

المُعدِّلات حتى النهاية

نظام تعديل الطلبات والاستجابات في Martian مصمم ليكون عامًا وقابلًا للتوسع. الهدف التصميمي هو توفير سلوكيات مُعدِّل فردية يمكن ترتيبها لبناء أي تعديل مطلوب تقريبًا.

عند العمل مع Martian لتكوين السلوكيات، ستحتاج إلى الإلمام بهذه الأنواع المختلفة من التفاعلات:

• المُعدِّلات: تغيّر حالة الطلب أو الاستجابة
• الفلاتر: تسمح بشكل مشروط لمُعدِّل مضمّن بالتنفيذ
• المجموعات: تجمع عدة مُعدِّلات ليتم تنفيذها بالترتيب المحدد في المجموعة
• المُتحقِّقات: تتبع حركة مرور الشبكة مقابل التوقعات

المُعدِّلات والفلاتر والمجموعات جميعها تنفّذ RequestModifier أو ResponseModifier أو RequestResponseModifier (المعرّفة في martian.go).

ModifyRequest(req *http.Request) error

ModifyResponse(res *http.Response) error

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

نشير إلى أي شيء ينفّذ واجهة modifier كمُعدِّل (Modifier).

تسجيل المُحلِّل

يجب على كل مُعدِّل تسجيل المُحلِّل الخاص به مع Martian. يكون المُحلِّل مسؤولًا عن تحليل رسالة JSON إلى بنية Go (struct) تنفّذ واجهة مُعدِّل.