pwned

Pwned

طريقة روبي سهلة لاستخدام واجهة برمجة تطبيقات كلمات المرور Pwned.

مستندات API | مستودع جيثب

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

• جدول المحتويات
• عن
• تثبيت
• الاستخدام
  • روبي عادي
    • خيارات الطلب المخصصة
      • رؤوس HTTP
      • وكيل HTTP
  • مدقق ActiveRecord
    • I18n
    • عتبة
    • معالجة أخطاء الشبكة
    • خيارات الطلب المخصصة
      • رؤوس HTTP
      • وكيل HTTP
  • باستخدام بشكل غير متزامن
  • ابتكر
  • رودوث
  • سطر الأوامر
  • غير معروف
• كيف Pwned هو باي؟
• تطوير
• المساهمة
• رخصة
• مدونة لقواعد السلوك

عن

تتيح لك واجهة برمجة تطبيقات كلمات المرور Pwned الخاصة بـ Troy Hunt التحقق مما إذا تم العثور على كلمة مرور في أي من عمليات اختراق البيانات الضخمة.

Pwned هي مكتبة روبي تستخدم نموذج k-Anonymity الخاص بواجهة برمجة تطبيقات Pwned Passwords لاختبار كلمة مرور مقابل واجهة برمجة التطبيقات دون إرسال كلمة المرور بالكامل إلى الخدمة.

يتم توفير البيانات من واجهة برمجة التطبيقات هذه بواسطة Have I been pwned?. قبل استخدام واجهة برمجة التطبيقات (API)، يرجى التحقق من الاستخدامات المقبولة وترخيص واجهة برمجة التطبيقات (API).

فيما يلي تدوينة كتبتها حول كيفية استخدام هذه الجوهرة في تطبيقات Ruby الخاصة بك لتحسين كلمات مرور المستخدمين.

تثبيت

أضف هذا السطر إلى ملف Gemfile الخاص بالتطبيق الخاص بك:

 gem 'pwned'

ومن ثم تنفيذ:

 $ bundle

أو قم بتثبيته بنفسك على النحو التالي:

 $ gem install pwned

الاستخدام

هناك عدة طرق يمكنك من خلالها استخدام هذه الأحجار الكريمة:

1. روبي عادي
2. القضبان
3. القضبان والتصميم

روبي عادي

لاختبار كلمة مرور مقابل واجهة برمجة التطبيقات (API)، قم بإنشاء مثيل لكائن Pwned::Password ثم اسأل ما إذا كان pwned? .

 password = Pwned :: Password . new ( "password" )
password . pwned?
#=> true
password . pwned_count
#=> 3303003

يمكنك أيضًا التحقق من عدد مرات ظهور كلمة المرور في مجموعة البيانات.

 password = Pwned :: Password . new ( "password" )
password . pwned_count
#=> 3303003

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

 begin
  password = Pwned :: Password . new ( "password" )
  password . pwned?
rescue Pwned :: Error => e
  # Ummm... don't worry about it, I guess?
end

في معظم الأوقات، لا تهتم إلا إذا كانت كلمة المرور قد تم اختراقها من قبل أم لا. يمكنك استخدام أدوات الوصول المبسطة للتحقق مما إذا كانت كلمة المرور قد تم اختراقها، أو عدد مرات اختراقها:

 Pwned . pwned? ( "password" )
#=> true
Pwned . pwned_count ( "password" )
#=> 3303003 

خيارات الطلب المخصصة

يمكنك ضبط خيارات طلب HTTP لاستخدامها مع Net::HTTP.start عند تقديم الطلب إلى واجهة برمجة التطبيقات (API). تم توثيق هذه الخيارات في وثائق Net::HTTP.start .

يمكنك تمرير الخيارات إلى المنشئ:

 password = Pwned :: Password . new ( "password" , read_timeout : 10 )

يمكنك أيضًا تحديد الإعدادات الافتراضية العامة:

 Pwned . default_request_options = { read_timeout : 10 } 

رؤوس HTTP

يحدد الخيار :headers رؤوس HTTP. يجب أن تكون هذه الرؤوس عبارة عن مفاتيح سلسلة.

 password = Pwned :: Password . new ( "password" , headers : {
  'User-Agent' => 'Super fun new user agent'
} ) 

وكيل HTTP

يمكن تعيين وكيل HTTP باستخدام متغير البيئة http_proxy أو HTTP_PROXY . هذه هي نفس الطريقة التي يتعامل بها Net::HTTP مع وكلاء HTTP إذا لم يتم توفير خيارات الوكيل. راجع URI::Generic#find_proxy للحصول على التفاصيل الكاملة حول كيفية اكتشاف Ruby للوكيل من البيئة.

 # Set in the environment
ENV [ "http_proxy" ] = "https://username:[email protected]:12345"

# Will use the above proxy
password = Pwned :: Password . new ( "password" )

يمكنك تحديد وكيل HTTP مخصص باستخدام خيار :proxy :

 password = Pwned :: Password . new (
  "password" ,
  proxy : "https://username:[email protected]:12345"
)

إذا كنت لا تريد تعيين وكيل ولا تريد استنتاج الوكيل من البيئة، فاضبط المفتاح :ignore_env_proxy :

 password = Pwned :: Password . new ( "password" , ignore_env_proxy : true )

مدقق ActiveRecord

يتوفر مدقق مخصص لنماذج ActiveRecord الخاصة بك:

 class User < ApplicationRecord
  validates :password , not_pwned : true
  # or
  validates :password , not_pwned : { message : "has been pwned %{count} times" }
end 

I18n

يمكنك تغيير رسالة الخطأ باستخدام I18n (استخدم %{count} لاستكمال عدد المرات التي تمت فيها رؤية كلمة المرور في خروقات البيانات):

 en :
  errors :
    messages :
      not_pwned : has been pwned %{count} times
      pwned_error : might be pwned 

عتبة

إذا كنت موافقًا على ظهور كلمة المرور لعدد معين من المرات قبل أن تقرر أنها غير صالحة، فيمكنك تعيين حد معين. سوف يتحقق المدقق مما إذا كان pwned_count أكبر من العتبة.

 class User < ApplicationRecord
  # The record is marked as valid if the password has been used once in the breached data
  validates :password , not_pwned : { threshold : 1 }
end 

معالجة أخطاء الشبكة

افتراضيًا، سيتم التعامل مع السجل على أنه صالح عندما لا نتمكن من الوصول إلى خوادم hasibeenpwned.com. يمكن تغيير ذلك باستخدام معلمة التحقق من الصحة :on_error :

 class User < ApplicationRecord
  # The record is marked as valid on network errors.
  validates :password , not_pwned : true
  validates :password , not_pwned : { on_error : :valid }

  # The record is marked as invalid on network errors
  # (error message "could not be verified against the past data breaches".)
  validates :password , not_pwned : { on_error : :invalid }

  # The record is marked as invalid on network errors with custom error.
  validates :password , not_pwned : { on_error : :invalid , error_message : "might be pwned" }

  # We will raise an error on network errors.
  # This means that `record.valid?` will raise `Pwned::Error`.
  # Not recommended to use in production.
  validates :password , not_pwned : { on_error : :raise_error }

  # Call custom proc on error. For example, capture errors in Sentry,
  # but do not mark the record as invalid.
  validates :password , not_pwned : {
    on_error : -> ( record , error ) { Raven . capture_exception ( error ) }
  }
end 

خيارات الطلب المخصصة

يمكنك تكوين طلبات الشبكة التي يتم إجراؤها من أداة التحقق باستخدام :request_options (راجع Net::HTTP.start للحصول على قائمة الخيارات المتاحة).

  validates :password , not_pwned : {
    request_options : {
      read_timeout : 5 ,
      open_timeout : 1
    }
  }

تتجاوز هذه الخيارات الخيارات الافتراضية المحددة عالميًا (انظر أعلاه).

بالإضافة إلى هذه الخيارات، يمكنك أيضًا ضبط ما يلي:

رؤوس HTTP

يمكن تحديد رؤوس HTTP باستخدام مفتاح :headers (على سبيل المثال "User-Agent" )

  validates :password , not_pwned : {
    request_options : {
      headers : { "User-Agent" => "Super fun user agent" }
    }
  } 

وكيل HTTP

يمكن تعيين وكيل HTTP باستخدام متغير البيئة http_proxy أو HTTP_PROXY . هذه هي نفس الطريقة التي يتعامل بها Net::HTTP مع وكلاء HTTP إذا لم يتم توفير خيارات الوكيل. راجع URI::Generic#find_proxy للحصول على التفاصيل الكاملة حول كيفية اكتشاف Ruby للوكيل من البيئة.

  # Set in the environment
  ENV [ "http_proxy" ] = "https://username:[email protected]:12345"

  validates :password , not_pwned : true

يمكنك تحديد وكيل HTTP مخصص باستخدام مفتاح :proxy :

  validates :password , not_pwned : {
    request_options : {
      proxy : "https://username:[email protected]:12345"
    }
  }

إذا كنت لا تريد تعيين وكيل ولا تريد استنتاج الوكيل من البيئة، فاضبط المفتاح :ignore_env_proxy :

  validates :password , not_pwned : {
    request_options : {
      ignore_env_proxy : true
    }
  }

باستخدام بشكل غير متزامن

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

 hashed_password = Pwned . hash_password ( password )
# some time later
Pwned :: HashedPassword . new ( hashed_password , request_options ) . pwned?

يأخذ منشئ Pwned::HashedPassword جميع الخيارات نفسها التي يتخذها منشئ Pwned::Password العادي.

ابتكر

إذا كنت تستخدم Devise فإنني أوصيك باستخدام ملحق devise-pwned_password الذي يتم تشغيله الآن بواسطة هذه الجوهرة.

رودوث

إذا كنت تستخدم Rodauth، فيمكنك استخدام ميزة Rodauth-pwned التي تدعمها هذه الجوهرة.

سطر الأوامر

توفر الجوهرة أداة مساعدة لسطر الأوامر للتحقق من كلمات المرور. يمكنك الاتصال به من تطبيقك الطرفي مثل هذا:

$ pwned password
Pwned !
The password has been found in public breaches 3645804 times.

إذا كنت لا تريد أن تكون كلمة المرور التي تتحقق منها مرئية، فاتصل بـ:

$ pwned --secret

ستتم مطالبتك بكلمة المرور، ولكن لن يتم عرضها.

غير معروف

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

كيف Pwned هو باي؟

شارك @daz مثالًا رائعًا لاستخدام هذه الجوهرة لإظهار عدد المرات التي تم فيها استخدام أرقام Pi ككلمات مرور وتسريبها.

 require 'pwned'

PI = '3.14159265358979323846264338327950288419716939937510582097494459230781640628620899862803482534211706798214808651328230664709384460955058223172535940812848111'

for n in 1 .. 40
  password = Pwned :: Password . new PI [ 0 .. ( n + 1 ) ]
  str = [ n . to_s . rjust ( 2 ) ]
  str << ( password . pwned? ? '?' : '?' )
  str << password . pwned_count . to_s . rjust ( 4 )
  str << password . password

  puts str . join ' '
end

قد تفاجئك النتائج وقد لا تفاجئك.

 1 ?   16 3.1
 2 ?  238 3.14
 3 ?   34 3.141
 4 ? 1345 3.1415
 5 ? 2552 3.14159
 6 ?  791 3.141592
 7 ? 9582 3.1415926
 8 ? 1591 3.14159265
 9 ?  637 3.141592653
10 ?  873 3.1415926535
11 ?  137 3.14159265358
12 ?  103 3.141592653589
13 ?   65 3.1415926535897
14 ?  201 3.14159265358979
15 ?   41 3.141592653589793
16 ?   57 3.1415926535897932
17 ?   28 3.14159265358979323
18 ?   29 3.141592653589793238
19 ?    1 3.1415926535897932384
20 ?    7 3.14159265358979323846
21 ?    5 3.141592653589793238462
22 ?    2 3.1415926535897932384626
23 ?    2 3.14159265358979323846264
24 ?    0 3.141592653589793238462643
25 ?    3 3.1415926535897932384626433
26 ?    0 3.14159265358979323846264338
27 ?    0 3.141592653589793238462643383
28 ?    0 3.1415926535897932384626433832
29 ?    0 3.14159265358979323846264338327
30 ?    0 3.141592653589793238462643383279
31 ?    0 3.1415926535897932384626433832795
32 ?    0 3.14159265358979323846264338327950
33 ?    0 3.141592653589793238462643383279502
34 ?    0 3.1415926535897932384626433832795028
35 ?    0 3.14159265358979323846264338327950288
36 ?    0 3.141592653589793238462643383279502884
37 ?    0 3.1415926535897932384626433832795028841
38 ?    0 3.14159265358979323846264338327950288419
39 ?    0 3.141592653589793238462643383279502884197
40 ?    0 3.1415926535897932384626433832795028841971

تطوير

بعد التحقق من المستودع، قم بتشغيل bin/setup لتثبيت التبعيات. ثم قم بتشغيل rake spec لإجراء الاختبارات. يمكنك أيضًا تشغيل bin/console للحصول على مطالبة تفاعلية تسمح لك بالتجربة.

لتثبيت هذه الجوهرة على جهازك المحلي، قم بتشغيل bundle exec rake install . لإصدار إصدار جديد، قم بتحديث رقم الإصدار في version.rb ، ثم قم بتشغيل bundle exec rake release ، والذي سينشئ علامة git للإصدار، ويدفع التزامات git وعلاماته، ويدفع ملف .gem إلى Rubygems.org.

المساهمة

نرحب بتقارير الأخطاء وطلبات السحب على GitHub على https://github.com/philnash/pwned. يهدف هذا المشروع إلى أن يكون مساحة آمنة ومرحبة للتعاون، ومن المتوقع أن يلتزم المساهمون بمدونة قواعد سلوك ميثاق المساهمين.

رخصة

الجوهرة متاحة كمصدر مفتوح بموجب شروط ترخيص MIT.

مدونة لقواعد السلوك

من المتوقع أن يتبع كل من يتفاعل في قواعد التعليمات البرمجية لمشروع Pwned ومتتبعي المشكلات وغرف الدردشة والقوائم البريدية قواعد السلوك.