Forerunner

<p align="center">
    <img width="256" height="256" src="https://image.flaticon.com/icons/svg/776/776246.svg">
</p>

# الرائد
<p align="left">
    <!-- الإصدار -->
    <img src="https://img.shields.io/badge/version-1.0.0-brightgreen.svg">
    <!-- <img src="https://img.shields.io/appveyor/ci/gruntjs/grunt.svg"> -->
    <!-- الوثائق -->
    <img src="https://img.shields.io/badge/docs-not%20found-lightgrey.svg">
    <!-- الترخيص -->
    <img src="https://img.shields.io/badge/license-MIT-blue.svg">
</p>

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

### المتطلبات
- .NET Framework 4.6.1

# الميزات
| الطريقة           | الوصف          | الاستخدام                      |
| ----------------- | -------------------- | ---------------------- |
| Scan               | مسح IP واحد للحصول على معلومات     | ```Scan("192.168.1.1");```
| ScanRange          | مسح نطاق من عناوين IP للحصول على معلومات  | ```ScanRange("192.168.1.1", "192.168.1.255")```
| ScanList           | مسح قائمة عناوين IP للحصول على معلومات  | ```ScanList("192.168.1.1, 192.168.1.2, 192.168.1.3")```
| PortKnock          | إرسال طلب ping لكل منفذ في IP واحد | ```PortKnock("192.168.1.1");```
| PortKnockRange     | إرسال طلب ping لكل منفذ في نطاق من عناوين IP | ```PortKnockRange("192.168.1.1", "192.168.1.255");```
| PortKnockList      | إرسال طلب ping لكل منفذ باستخدام قائمة عناوين IP | ```PortKnockList("192.198.1.1, 192.168.1.2, 192.168.1.3");```
| IsHostAlive        | إرسال ping إلى مضيف N مرة لمدة X مللي ثانية | ```IsHostAlive("192.168.1.1", 5, 1000);```
| GetAveragePingResponse | الحصول على متوسط زمن الاستجابة للـ ping لمضيف | ```GetAveragePingResponse("192.168.1.1", 5, 1000);```
| IsPortOpen         | إرسال ping إلى منافذ فردية عبر TCP و UDP | ```IsPortOpen("192.168.1.1", 45000, new TimeSpan(1000), false);```

# أمثلة
### مسح IP

يعد مسح الشبكة مهمة شائعة في هذا العصر الرقمي، ولذا فقد أخذت على عاتقي جعل هذا الأمر بسيطاً قدر الإمكان لأي مبرمج مستقبلي قد يرغب في فعل شيء كهذا بطريقة سهلة. مكتبة الرائد موجهة بالكامل للكائنات، مما يجعلها مثالية لمواقف التوصيل والتشغيل؛ الكائن الخاص بمسح IP يسمى <i>IPScanObject</i> ويحتوي في الواقع على عدد غير قليل من الخصائص:

- Address (<i><b>String</b></i>)
- IP (<i><b>IPAddress</b></i>)
- Ping (<i><b>Long</b></i>)
- Hostname (<i><b>String</b></i>)
- MAC (<i><b>String</b></i>)
- isOnline (<i><b>Bool</b></i>)
- Errors (<i><b>Exception</b></i>)

مع وضع هذا الكائن في الاعتبار، دعنا نحاول إنشاء كائن جديد وإجراء مسح باستخدامه. هناك طرق متعددة للقيام بذلك، ولكن أسهل طريقة للبدء هي أولاً إنشاء كائن <i>Scanner</i> جديد حتى نتمكن من الوصول إلى طرق المسح الخاصة بنا. بعد ذلك، قم بإنشاء <i>IPScanObject</i> ثم قم بتعيينه إلى طريقة <i>Scan</i> مع عنوان IP الذي ترغب في تعداد معلوماته؛ على سبيل المثال:

##### متزامن

```csharp
using System;
using Forerunner; // Remember to import our library.

namespace Example
{
    class Program
    {
        static void Main(string[] args)
        {
            // Our IP we would like to scan.
            string ip = "192.168.1.1";

            // Create a new scanner object.
            Scanner s = new Scanner();

            // Create a new scan object and perform a scan.
            IPScanObject result = s.Scan(ip);

            // Output that we have finished the scan.
            if (result.Errors != null)
                Console.WriteLine("[x] An error occurred during the scan.");
            else
                Console.WriteLine("[+] " + ip + " has been successfully scanned!")

            // Allow the user to exit at any time.
            Console.Read();
        }
    }
}
```

طريقة أخرى، وهي طريقتي المفضلة في التشغيل، هي إنشاء كائن <i>Scanner</i> والاشتراك في <i>معالجات الأحداث</i> مثل <i>ScanAsyncProgressChanged</i> أو <i>ScanAsyncComplete</i>، وبهذه الطريقة يكون لدي التحكم الكامل في طرق non المتزامنة الخاصة بي؛ يمكنني التحكم في كيفية تأثير حالات التقدم في تطبيقاتي وهكذا؛ على سبيل المثال:

##### غير متزامن

```csharp
using System;
using System.Threading.Tasks;
using Forerunner; // Remember to import our library.

namespace Example
{
    class Program
    {
        static void Main(string[] args)
        {
            // Our IP we would like to scan.
            string ip = "192.168.1.1";

            // Setup our scanner object.
            Scanner s = new Scanner();
            s.ScanAsyncProgressChanged += new ScanAsyncProgressChangedHandler(ScanAsyncProgressChanged);
            s.ScanAsyncComplete += new ScanAsyncCompleteHandler(ScanAsyncComplete);

            // Start a new scan task with our ip.
            TaskFactory task = new TaskFactory();
            task.StartNew(() => s.ScanAsync(ip));

            // Allow the user to exit at any time.
            Console.Read();
        }

        static void ScanAsyncProgressChanged(object sender, ScanAsyncProgressChangedEventArgs e)
        {
            // Do something here with e.Progress, or you could leave this event
            // unsubscribed so you wouldn't have to do anything.
        }

        static void ScanAsyncComplete(object sender, ScanAsyncCompleteEventArgs e)
        {
           // Do something with the IPScanObject aka e.Result.
            if (e.Result.Errors != null)
                Console.WriteLine("[x] An error occurred during the scan.");
            else
                Console.WriteLine("[+] " + e.Result.IP + " has been successfully scanned!")
        }
    }
}
```

### طرق المنافذ (Port Knocking)
أعرف ما تفكر فيه. طرق المنافذ؟ نعم، ولا. لا يعني المصطلح طرق المنافذ بالمعنى التقليدي للاتصال من خلال مجموعة محددة مسبقاً من المنافذ، بل يعني فقط التحقق مما إذا كانت أي منافذ مفتوحة بالفعل. إنه حرفياً "طرق" على منفذ بكل معنى الكلمة عن طريق محاولة الاتصال بكل منفذ وإرسال البيانات. كما هو الحال مع مسح IP، يستخدم طرق المنافذ كائنًا مخصصًا يسمى "<i>Port Knock Scan Object</i>" أو <i>PKScanObject</i> باختصار. يحتوي <i>PKScanObject</i> في الواقع على قائمة من <i>PKServiceObject</i> والتي تحمل بدورها بيانات المنفذ الخاصة بنا؛ يحتوي كائن الخدمة على الخصائص التالية:

- IP (<i><b>String</b></i>)
- Port (<i><b>Int</b></i>)
- Protocol (<i><b>PortType</b></i>)
- Status (<i><b>Bool</b></i>)

طرق المنافذ مشابه لمسح IP. أولاً، قم بإنشاء كائن <i>Scanner</i>. بعد ذلك، قم بإنشاء <i>PKScanObject</i> جديد وقم بتعيينه إلى طريقة <i>PortKnock</i> مع عنوان IP الذي تختاره، ثم اعرض نتائجك؛ على سبيل المثال:

##### متزامن

```csharp
using System;
using Forerunner; // Remember to import our library.

namespace Example
{
    class Program
    {
        static void Main(string[] args)
        {
            // Our IP we would like to scan.
            string ip = "192.168.1.1";

            // Create a new scanner object.
            Scanner s = new Scanner();

            // Create a new scan object and perform a scan.
            PKScanObject result = s.PortKnock(ip);

            // Output that we have finished the scan.
            if (result.Errors != null)
                Console.WriteLine("[x] An error occurred during the scan.");
            else
                Console.WriteLine("[+] " + ip + " has been successfully scanned!")

           // Display our results.
           foreach (PKServiceObject port in result.Services)
           {
                Console.WriteLine("[+] IP: " + port.IP + " | " +
                                  "Port: " + port.Port.ToString() + " | " +
                                  "Protocol: " + port.Protocol.ToString() + " | " +
                                  "Status: " + port.Status.ToString());
           }

           // Allow the user to exit at any time.
           Console.Read();
        }
    }
}
```

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

##### غير متزامن

```csharp
using System;
using System.Threading.Tasks;
using Forerunner; // Remember to import our library.

namespace Example
{
    class Program
    {
        static void Main(string[] args)
        {
            // Our IP we would like to scan.
            string ip = "192.168.1.1";

            // Setup our scanner object.
            Scanner s = new Scanner();
            s.PortKnockAsyncProgressChanged += new PortKnockAsyncProgressChangedHandler(PortKnockAsyncProgressChanged);
            s.PortKnockAsyncComplete += new PortKnockAsyncCompleteHandler(PortKnockAsyncComplete);

            // Start a new scan task with our ip.
            TaskFactory task = new TaskFactory();
            task.StartNew(() => s.PortKnockAsync(ip));

            // Allow the user to exit at any time.
            Console.Read();
        }

        static void PortKnockAsyncProgressChanged(object sender, PortKnockAsyncProgressChangedEventArgs e)
        {
            // Display our progress so we know the ETA.
            if (e.Progress == 99)
            {
                Console.Write(e.Progress.ToString() + "%...");
                Console.WriteLine("100%!");
            }
            else
                Console.Write(e.Progress.ToString() + "%...");
        }

        static void PortKnockAsyncComplete(object sender, PortKnockAsyncCompleteEventArgs e)
        {
            // Tell the user that the port knock was complete.
            Console.WriteLine("[+] Port Knock Complete!");

            // Check if we resolved an error.
            if (e.Result == null)
                Console.WriteLine("[X] The port knock did not return any data!");
            else
            {
                // Check if we have any ports recorded.
                if (e.Result.Services.Count == 0)
                    Console.WriteLine("[!] No ports were open during the knock.");
                else
                {
                    // Display our ports and their details.
                    foreach (PKServiceObject port in e.Result.Services)
                    {
                        Console.WriteLine("[+] IP: " + port.IP + " | " +
                                          "Port: " + port.Port.ToString() + " | " +
                                          "Protocol: " + port.Protocol.ToString() + " | " +
                                          "Status: " + port.Status.ToString());
                    }
                }
            }
        }
    }
}
```

# الإسناد
**الأيقونة:** `monkik` <br>
https://www.flaticon.com/authors/monkik

# الترخيص

حقوق النشر محفوظة © ∞ Jason Drawdy 

جميع الحقوق محفوظة.

رخصة MIT (MIT)

يُمنح الإذن مجاناً لأي شخص يحصل على نسخة من هذا البرنامج والملفات المرتبطة به ("البرنامج")، للتعامل مع البرنامج دون قيود، بما في ذلك على سبيل المثال لا الحصر حقوق استخدام ونسخ وتعديل ودمج ونشر وتوزيع و/أو بيع نسخ من البرنامج، والسماح للأشخاص الذين حصلوا على البرنامج بالقيام بذلك، وذلك وفقاً للشروط التالية:

يجب تضمين إشعار حقوق النشر أعلاه وإذن الترخيص هذا في جميع نسخ البرنامج أو الأجزاء الجوهرية منه.

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

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