{"id":21937356,"url":"https://github.com/jasondrawdy/forerunner","last_synced_at":"2025-04-22T12:07:58.255Z","repository":{"id":183138454,"uuid":"141962431","full_name":"jasondrawdy/Forerunner","owner":"jasondrawdy","description":"Fast and extensible network scanning library featuring multithreading, ping probing, and scan fetchers.","archived":false,"fork":false,"pushed_at":"2020-05-01T21:11:51.000Z","size":28,"stargazers_count":40,"open_issues_count":0,"forks_count":14,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-22T12:07:25.951Z","etag":null,"topics":["library","network-scanner","network-scanning","networking","scanner","security","windows"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jasondrawdy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-07-23T04:47:56.000Z","updated_at":"2024-08-12T19:40:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"9f64a392-a3e5-4baf-9a17-4f20280ae249","html_url":"https://github.com/jasondrawdy/Forerunner","commit_stats":null,"previous_names":["jasondrawdy/forerunner"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasondrawdy%2FForerunner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasondrawdy%2FForerunner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasondrawdy%2FForerunner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasondrawdy%2FForerunner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jasondrawdy","download_url":"https://codeload.github.com/jasondrawdy/Forerunner/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250237832,"owners_count":21397401,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["library","network-scanner","network-scanning","networking","scanner","security","windows"],"created_at":"2024-11-29T01:19:14.379Z","updated_at":"2025-04-22T12:07:58.231Z","avatar_url":"https://github.com/jasondrawdy.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg width=\"256\" height=\"256\" src=\"https://image.flaticon.com/icons/svg/776/776246.svg\"\u003e\n\u003c/p\u003e\n\n# Forerunner\n\u003cp align=\"left\"\u003e\n    \u003c!-- Version --\u003e\n    \u003cimg src=\"https://img.shields.io/badge/version-1.0.0-brightgreen.svg\"\u003e\n    \u003c!-- \u003cimg src=\"https://img.shields.io/appveyor/ci/gruntjs/grunt.svg\"\u003e --\u003e\n    \u003c!-- Docs --\u003e\n    \u003cimg src=\"https://img.shields.io/badge/docs-not%20found-lightgrey.svg\"\u003e\n    \u003c!-- License --\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\"\u003e\n\u003c/p\u003e\n\nThe Forerunner library is a fast, lightweight, and extensible networking library created to aid in the development of robust network centric applications such as: IP Scanners, Port Knockers, Clients, Servers, etc. In it's current state, the Forerunner library is able to both synchronously and asynchronously scan and port knock IP addresses in order to obtain information about the device located at that endpoint such as: whether the IP is online, the physical MAC address, and etc. The library is a completely object oriented and event based library meaning that scan data is contained within specially crafted \"scan\" objects which are designed to handle all data from results to exceptions.\n\n### Requirements\n  - .NET Framework 4.6.1\n\n# Features\n| Method              | Description          | Usage                      |\n| ------------------ | -------------------- | ---------------------- |\n| Scan               | Scan a single IP for information     | ```Scan(\"192.168.1.1\");```\n| ScanRange          | Scan a range of IPs for information  | ```ScanRange(\"192.168.1.1\", \"192.168.1.255\")```\n| ScanList           | Scan a list of IPs for information  | ```ScanList(\"192.168.1.1, 192.168.1.2, 192.168.1.3\")```\n| PortKnock          | Ping every port of a single IP | ```PortKnock(\"192.168.1.1\");```\n| PortKnockRange     | Ping every port in a range of IPs | ```PortKnockRange(\"192.168.1.1\", \"192.168.1.255\");```\n| PortKnockList      | Ping every port using a list of IPs | ```PortKnockList(\"192.198.1.1, 192.168.1.2, 192.168.1.3\");```\n| IsHostAlive        | Ping a host N times for X milliseconds | ```IsHostAlive(\"192.168.1.1\", 5, 1000);```\n| GetAveragePingResponse | Get average ping response for a host | ```GetAveragePingResponse(\"192.168.1.1\", 5, 1000);```\n| IsPortOpen         | Ping individual ports via TCP \u0026 UDP | ```IsPortOpen(\"192.168.1.1\", 45000, new TimeSpan(1000), false);```\n\n# Examples\n### IP Scanning\n\nScanning a network is a commonplace task in this digital age and so I have taken the liberty to make this as simple as possible for any future programmer whom may wish to do such a thing in an easy way. The Forerunner library is completely object oriented, thus making it ideal for plug and play situations; the object for IP scanning is called an \u003ci\u003eIPScanObject\u003c/i\u003e and it actually contains quite a few properties:\n\n- Address (\u003ci\u003e\u003cb\u003eString\u003c/b\u003e\u003c/i\u003e)\n- IP (\u003ci\u003e\u003cb\u003eIPAddress\u003c/b\u003e\u003c/i\u003e)\n- Ping (\u003ci\u003e\u003cb\u003eLong\u003c/b\u003e\u003c/i\u003e)\n- Hostname (\u003ci\u003e\u003cb\u003eString\u003c/b\u003e\u003c/i\u003e)\n- MAC (\u003ci\u003e\u003cb\u003eString\u003c/b\u003e\u003c/i\u003e)\n- isOnline (\u003ci\u003e\u003cb\u003eBool\u003c/b\u003e\u003c/i\u003e)\n- Errors (\u003ci\u003e\u003cb\u003eException\u003c/b\u003e\u003c/i\u003e)\n\nWith the object in mind, let's try and create a new object and perform a scan using it. There are multiple ways to go about this, however, the simplest way to get started is to first create a new \u003ci\u003eScanner\u003c/i\u003e object so we can access our scanning methods. Next, create an \u003ci\u003eIPScanObject\u003c/i\u003e and then set it to the \u003ci\u003eScan\u003c/i\u003e method with the IP you would like to enumerate; for example:\n\n##### Synchronous\n\n```c#\nusing System;\nusing Forerunner; // Remember to import our library.\n\nnamespace Example\n{\n    class Program\n    {\n        static void Main(string[] args)\n        {\n            // Our IP we would like to scan.\n            string ip = \"192.168.1.1\";\n\n            // Create a new scanner object.\n            Scanner s = new Scanner();\n\n            // Create a new scan object and perform a scan.\n            IPScanObject result = s.Scan(ip);\n\n            // Output that we have finished the scan.\n            if (result.Errors != null)\n                Console.WriteLine(\"[x] An error occurred during the scan.\");\n            else\n                Console.WriteLine(\"[+] \" + ip + \" has been successfully scanned!\")\n\n            // Allow the user to exit at any time.\n            Console.Read();\n        }\n    }\n}\n```\n\nAnother way, which is my preferred method of operation, is to create a \u003ci\u003eScanner\u003c/i\u003e object and subscribe to the \u003ci\u003eEvent Handlers\u003c/i\u003e of things like \u003ci\u003eScanAsyncProgressChanged\u003c/i\u003e or \u003ci\u003eScanAsyncComplete\u003c/i\u003e, that way I have full control over my async methods; I can control how they're progress states affect my application and so on; for example:\n\n##### Asynchronous\n\n```c#\nusing System;\nusing System.Threading.Tasks;\nusing Forerunner; // Remember to import our library.\n\nnamespace Example\n{\n    class Program\n    {\n        static void Main(string[] args)\n        {\n            // Our IP we would like to scan.\n            string ip = \"192.168.1.1\";\n\n            // Setup our scanner object.\n            Scanner s = new Scanner();\n            s.ScanAsyncProgressChanged += new ScanAsyncProgressChangedHandler(ScanAsyncProgressChanged);\n            s.ScanAsyncComplete += new ScanAsyncCompleteHandler(ScanAsyncComplete);\n\n            // Start a new scan task with our ip.\n            TaskFactory task = new TaskFactory();\n            task.StartNew(() =\u003e s.ScanAsync(ip));\n\n            // Allow the user to exit at any time.\n            Console.Read();\n        }\n\n        static void ScanAsyncProgressChanged(object sender, ScanAsyncProgressChangedEventArgs e)\n        {\n            // Do something here with e.Progress, or you could leave this event\n            // unsubscribed so you wouldn't have to do anything.\n        }\n\n        static void ScanAsyncComplete(object sender, ScanAsyncCompleteEventArgs e)\n        {\n           // Do something with the IPScanObject aka e.Result.\n            if (e.Result.Errors != null)\n                Console.WriteLine(\"[x] An error occurred during the scan.\");\n            else\n                Console.WriteLine(\"[+] \" + e.Result.IP + \" has been successfully scanned!\")\n        }\n    }\n}\n```\n\n### Port Knocking\nI know what you're thinking. Port knocking? Yes, and no. The term doesn't mean port knocking in the traditional sense of connecting through a predefined set of ports, but rather just checking if any ports are actually open. It's literally \"knocking\" on a port in every sense of the word by trying to connect to each port and sending data. Just like with IP scanning, port knocking uses a custom object which is called a \"\u003ci\u003ePort Knock Scan Object\u003c/i\u003e\" or \u003ci\u003ePKScanObject\u003c/i\u003e for short. The \u003ci\u003ePKScanObject\u003c/i\u003e actually contains a list of \u003ci\u003ePKServiceObject\u003c/i\u003es which in turn hold our port data; the service object contains the following properties:\n\n- IP (\u003ci\u003e\u003cb\u003eString\u003c/b\u003e\u003c/i\u003e)\n- Port (\u003ci\u003e\u003cb\u003eInt\u003c/b\u003e\u003c/i\u003e)\n- Protocol (\u003ci\u003e\u003cb\u003ePortType\u003c/b\u003e\u003c/i\u003e)\n- Status (\u003ci\u003e\u003cb\u003eBool\u003c/b\u003e\u003c/i\u003e)\n\nPort knocking is in similar fashion with IP scanning. First, create a \u003ci\u003eScanner\u003c/i\u003e object. Next, create a new \u003ci\u003ePKScanObject\u003c/i\u003e and set it to the \u003ci\u003ePortKnock\u003c/i\u003e method with the IP of your choosing, then display your results; for example:\n\n##### Synchronous\n\n```c#\nusing System;\nusing Forerunner; // Remember to import our library.\n\nnamespace Example\n{\n    class Program\n    {\n        static void Main(string[] args)\n        {\n            // Our IP we would like to scan.\n            string ip = \"192.168.1.1\";\n\n            // Create a new scanner object.\n            Scanner s = new Scanner();\n\n            // Create a new scan object and perform a scan.\n            PKScanObject result = s.PortKnock(ip);\n\n            // Output that we have finished the scan.\n            if (result.Errors != null)\n                Console.WriteLine(\"[x] An error occurred during the scan.\");\n            else\n                Console.WriteLine(\"[+] \" + ip + \" has been successfully scanned!\")\n\n           // Display our results.\n           foreach (PKServiceObject port in result.Services)\n           {\n                Console.WriteLine(\"[+] IP: \" + port.IP + \" | \" +\n                                  \"Port: \" + port.Port.ToString() + \" | \" +\n                                  \"Protocol: \" + port.Protocol.ToString() + \" | \" +\n                                  \"Status: \" + port.Status.ToString());\n           }\n\n           // Allow the user to exit at any time.\n           Console.Read();\n        }\n    }\n}\n```\n\nLastly, I will show you a simple example of port knocking asynchronously. It is essentially the same as port knocking synchronously except for the fact that you can use events to your advantage. You can get progress updates without having to worry about UIs crashing or systems being in a locked state; for example:\n\n##### Asynchronous\n\n```c#\nusing System;\nusing System.Threading.Tasks;\nusing Forerunner; // Remember to import our library.\n\nnamespace Example\n{\n    class Program\n    {\n        static void Main(string[] args)\n        {\n            // Our IP we would like to scan.\n            string ip = \"192.168.1.1\";\n\n            // Setup our scanner object.\n            Scanner s = new Scanner();\n            s.PortKnockAsyncProgressChanged += new PortKnockAsyncProgressChangedHandler(PortKnockAsyncProgressChanged);\n            s.PortKnockAsyncComplete += new PortKnockAsyncCompleteHandler(PortKnockAsyncComplete);\n\n            // Start a new scan task with our ip.\n            TaskFactory task = new TaskFactory();\n            task.StartNew(() =\u003e s.PortKnockAsync(ip));\n\n            // Allow the user to exit at any time.\n            Console.Read();\n        }\n\n        static void PortKnockAsyncProgressChanged(object sender, PortKnockAsyncProgressChangedEventArgs e)\n        {\n            // Display our progress so we know the ETA.\n            if (e.Progress == 99)\n            {\n                Console.Write(e.Progress.ToString() + \"%...\");\n                Console.WriteLine(\"100%!\");\n            }\n            else\n                Console.Write(e.Progress.ToString() + \"%...\");\n        }\n\n        static void PortKnockAsyncComplete(object sender, PortKnockAsyncCompleteEventArgs e)\n        {\n            // Tell the user that the port knock was complete.\n            Console.WriteLine(\"[+] Port Knock Complete!\");\n\n            // Check if we resolved an error.\n            if (e.Result == null)\n                Console.WriteLine(\"[X] The port knock did not return any data!\");\n            else\n            {\n                // Check if we have any ports recorded.\n                if (e.Result.Services.Count == 0)\n                    Console.WriteLine(\"[!] No ports were open during the knock.\");\n                else\n                {\n                    // Display our ports and their details.\n                    foreach (PKServiceObject port in e.Result.Services)\n                    {\n                        Console.WriteLine(\"[+] IP: \" + port.IP + \" | \" +\n                                          \"Port: \" + port.Port.ToString() + \" | \" +\n                                          \"Protocol: \" + port.Protocol.ToString() + \" | \" +\n                                          \"Status: \" + port.Status.ToString());\n                    }\n                }\n            }\n        }\n    }\n}\n```\n\n# Credits\n**Icon:** `monkik` \u003cbr\u003e\nhttps://www.flaticon.com/authors/monkik\n\n# License\n\nCopyright © ∞ Jason Drawdy \n\nAll rights reserved.\n\nThe MIT License (MIT)\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n\nExcept as contained in this notice, the name of the above copyright holder\nshall not be used in advertising or otherwise to promote the sale, use or\nother dealings in this Software without prior written authorization.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasondrawdy%2Fforerunner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjasondrawdy%2Fforerunner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasondrawdy%2Fforerunner/lists"}