Introduces support for .NET 8. Code refactoring and general library maintenance.

Author: akacdev

.github/workflows/build-and-release.yml

@@ -0,0 +1,60 @@
+name: Build and Release
+
+env:
+  DOTNET_VERSION: '8.x'
+  NUGET_SOURCE_URL: 'https://api.nuget.org/v3/index.json'
+  BUILD_DIRECTORY: '${{ github.workspace }}/build'
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  build-and-release:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - name: Checkout Repository
+      uses: actions/checkout@v2
+
+    - name: Get Version
+      id: get_version
+      run: |
+          echo "tag=${GITHUB_REF_NAME}" >> $GITHUB_OUTPUT
+          echo "version=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
+    
+    - name: Get Project Metadata
+      id: get_project_meta
+      run: |
+          name=$(echo '${{ github.repository }}' | cut -d '/' -f 2)
+          
+          echo "name=${name}" >> $GITHUB_OUTPUT
+          echo "path=${name}/${name}.csproj" >> $GITHUB_OUTPUT
+
+    - name: Setup .NET
+      uses: actions/setup-dotnet@v3.2.0
+      with:
+        dotnet-version: ${{ env.DOTNET_VERSION }}
+
+    - name: Restore Packages
+      run: dotnet restore ${{ steps.get_project_meta.outputs.path }}
+      
+    - name: Build Project
+      run: dotnet build ${{ steps.get_project_meta.outputs.path }} /p:ContinuousIntegrationBuild=true --no-restore --configuration Release
+
+    - name: Pack Project
+      run: dotnet pack ${{ steps.get_project_meta.outputs.path }} --no-restore --no-build --configuration Release --include-symbols -p:PackageVersion=${{ steps.get_version.outputs.version }} --output ${{ env.BUILD_DIRECTORY }}
+
+    - name: Push Package
+      env:
+        NUGET_AUTH_TOKEN: ${{ secrets.NUGET_AUTH_TOKEN }}
+      run: dotnet nuget push ${{ env.BUILD_DIRECTORY }}/*.nupkg -k $NUGET_AUTH_TOKEN -s ${{ env.NUGET_SOURCE_URL }}
+
+    - name: Create Release
+      uses: softprops/action-gh-release@v1
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        name: ${{ steps.get_version.outputs.tag }}
+        body: ${{ github.event.head_commit.message }}
+        files: '${{ env.BUILD_DIRECTORY }}/*'

Example/Example.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFrameworks>net6.0;net7.0</TargetFrameworks>
+    <TargetFrameworks>net8.0</TargetFrameworks>
   </PropertyGroup>
 
   <ItemGroup>

Example/Program.cs

@@ -9,18 +9,22 @@ namespace Example
 {
     public static class Program
     {
+        private static UrlscanClient Client;
+        private static LiveClient Live;
+
         public static async Task Main()
         {
-            Console.WriteLine("Enter your Urlscan API Key:");
+            Console.WriteLine("> Enter your Urlscan API Key:");
             string key = Console.ReadLine();
 
-            Console.WriteLine("Enter your Urlscan SID, or press enter to skip:");
+            Console.WriteLine("\n> Enter your Urlscan SID, or press enter to skip:");
             string sid = Console.ReadLine();
             if (string.IsNullOrEmpty(sid)) sid = null;
 
-            UrlscanClient client = new(key, sid);
+            Console.WriteLine();
+            Client = new(key, sid);
 
-            User user = await client.GetCurrentUser();
+            User user = await Client.GetCurrentUser();
 
             Console.WriteLine($"Current user info:");
             Console.WriteLine($"Registered: {(int)(DateTime.Now - user.CreatedAt).TotalDays} days ago");
@@ -41,12 +45,12 @@ public static async Task Main()
             Console.WriteLine($"You've made {user.Stats.Total} sumissions, of which {user.Stats.Private + user.Stats.Unlisted} were private");
             Console.WriteLine();
 
-            Stats stats = await client.GetStats();
+            Stats stats = await Client.GetStats();
             Console.WriteLine($"Currently running scan tasks: {stats.Running}");
             Console.WriteLine($"24h stats: public: {stats.Public}, unlisted: {stats.Unlisted}, private: {stats.Private}");
             Console.WriteLine($"Total: {stats.Total}\n");
 
-            Console.Write($"Enter a URL to scan: ");
+            Console.Write($"\n> Enter a URL to scan: ");
 
             string url = Console.ReadLine();
 
@@ -55,41 +59,36 @@ public static async Task Main()
             Submission subm;
             try
             {
-                subm = await client.Scan(new ScanParameters()
+                subm = await Client.Scan(new ScanParameters()
                 {
-                    //URL is the only necessary argument, the rest is all optional.
+                    //URL is the only mandatory argument, the rest is all optional.
                     Url = url,
-                    Tags = new string[] { "test" },
+                    Tags = ["test"],
                     Country = ScanCountry.FI,
                     UserAgent = "My-Custom-Scanner/1.0.0",
                     OverrideSafety = false,
                     Referer = "https://google.com",
                     Visibility = Visibility.Public
                 });
             }
-            catch (NxDomainException ex)
+            catch (UrlscanException ex)
             {
-                Console.WriteLine($"The domain doesn't have any DNS records.\nUrlscan Message: {ex.Message}");
-                Console.ReadKey();
-                return;
-            }
-            catch (SillyException ex)
-            {
-                Console.WriteLine($"You've entered a malformed hostname/URL.\nUrlscan Message: {ex.Message}");
+                Console.WriteLine($"Received an Urlscan exception: {ex.Message}");
+                if (ex.Error is not null) Console.WriteLine($"{ex.Error.Description} => {ex.Error.Message}");
                 Console.ReadKey();
                 return;
             }
             catch (Exception ex)
             {
-                Console.WriteLine($"Received an unknown exception while scanning of type {ex.GetType().Name}\nMessage: {ex.Message}");
+                Console.WriteLine($"Received an unknown exception while scanning: {ex.GetType().Name} => {ex.Message}");
                 Console.ReadKey();
                 return;
             }
 
             Console.WriteLine($"Submission created: {subm.UUID}\n");
 
             Console.WriteLine($"Waiting for the scan to finish, this will take about 10 seconds.\n");
-            Result res = await client.Poll(subm);
+            Result res = await Client.Poll(subm);
 
             Console.WriteLine($"Page was successfully scanned by a submitter from {res.Submitter.Country}.\n");
 
@@ -129,63 +128,63 @@ public static async Task Main()
                 Console.WriteLine($"Malicious: {cver.Malicious}\n");
             }
 
-            SimilarScan[] similar = await client.GetSimilarScans("bc1ef5f2-eddc-40ae-86c9-fb5894b5d1f2");
+            SimilarScan[] similar = await Client.GetSimilarScans("bc1ef5f2-eddc-40ae-86c9-fb5894b5d1f2");
             Console.WriteLine($"Found {similar.Length} similar scans");
 
             Console.WriteLine($"Done analysing URL\n");
 
-            Console.WriteLine($"Downloading screenshot (screenshot.png) and DOM (dom.html) to the current directory.");
-            File.WriteAllBytes("screenshot.png", await client.DownloadScreenshot(res));
-            File.WriteAllText("dom.html", await client.DownloadDOM(res));
-            Console.WriteLine();
-            Console.WriteLine();
+            Console.WriteLine($"\n> Downloading screenshot (screenshot.png) and DOM (dom.html) to the current directory.");
+            File.WriteAllBytes("screenshot.png", await Client.DownloadScreenshot(res));
+            File.WriteAllText("dom.html", await Client.DownloadDOM(res));
 
-            if (client.UsesAccountSID)
+            if (Client.UsesAccountSID)
             {
-                Console.WriteLine("Press any key to submit a verdict to a known Discord phishing site.");
+                Console.WriteLine("\n> Press any key to submit a verdict to a known Discord phishing site.");
                 Console.ReadKey();
 
-                await client.AddVerdict(new VerdictParameters()
+                await Client.AddVerdict(new VerdictParameters()
                 {
                     UUID = "8964cc71-ea31-476c-ba8f-863bf4bf6b2f",
                     Comment = "Running a Discord phishing scam with Discord HypeSquad as their target.",
                     Scope = VerdictScope.PageDomain,
                     ScopeValue = "contact-hype-testers.com",
-                    ThreatTypes = new ThreatType[]
-                    {
+                    ThreatTypes =
+                    [
                         ThreatType.Phishing,
                         ThreatType.BrandImpersonation
-                    },
-                    Brands = new string[]
-                    {
+                    ],
+                    Brands =
+                    [
                         "Discord"
-                    },
+                    ],
                     Verdict = VerdictType.Malicious
                 });
 
-                Console.WriteLine("Successfully verdicted, see it at: https://urlscan.io/result/8964cc71-ea31-476c-ba8f-863bf4bf6b2f/#verdicts\n");
+                Console.WriteLine("Successfully verdicted, see it at: https://urlscan.io/result/8964cc71-ea31-476c-ba8f-863bf4bf6b2f/#verdicts");
 
-                Console.WriteLine("Press any key to search for scans that contain hypesquad in them.");
+                Console.WriteLine("\n> Press any key to search for scans that contain hypesquad in them.");
                 Console.ReadKey();
 
-                SearchItem[] scans = await client.Search("page.status:200 AND domain.keyword:*hypesquad*", 10);
+                SearchItem[] scans = await Client.Search("page.status:200 AND domain.keyword:*hypesquad*", 10);
                 foreach (SearchItem scan in scans)
                 {
                     Console.WriteLine(scan.Page.Url[..Math.Min(scan.Page.Url.Length, 50)]);
                 }
             }
 
-            Console.WriteLine("Press any key to start watching for newly scanned URLs.");
+            Console.WriteLine("\n> Press any key to start watching for newly scanned URLs.");
             Console.ReadKey();
 
-            LiveClient live = new(1000 * 3, 10);
-            live.UrlScanned += (sender, scan) =>
+            Live = new(1000 * 3, 10);
+
+            Live.UrlScanned += (sender, scan) =>
             {
                 Console.WriteLine(scan.Task.Url[..Math.Min(scan.Task.Url.Length, 50)]);
             };
 
-            Console.WriteLine("Demo finished, press any key to exit.");
+            Console.WriteLine("\n> Demo finished, press any key to exit.");
             Console.ReadKey();
+            Live.Stop();
         }
     }
 }

README.md

@@ -9,11 +9,10 @@
 </div>
 
 ## Usage
-Provides an easy interface for interacting with the Urlscan API.
-
+This library provides an easy interface for interacting with the Urlscan API.
 You can use this library to automate your Urlscan submissions, search for existing scans, track newly submitted scans and analyse network activity of malicious websites.
 
-To get started, add the library into your solution with either the `NuGet Package Manager` or the `dotnet` CLI.
+To get started, import the library into your solution with either the `NuGet Package Manager` or the `dotnet` CLI.
 ```rust
 dotnet add package Urlscan
 ```
@@ -26,20 +25,23 @@ using Urlscan;
 Need more examples? Under the `Example` directory you can find a working demo project that implements this library.
 
 ### Obtaining API keys
-> API keys can be created in the user section `Settings & API`
+API keys can be created under the user section `Settings & API`.
 
-> Secure identifier SID cookies can be obtained from your browser's cookie storage. Make sure to only copy the value, without the name! 
+Secure identifier SID cookies can be obtained from your browser's cookie storage. Make sure to only copy the value, without the name! 
 
-## Features
-- Built for **.NET 6** and **.NET 7**
+## Properties
+- Built for **.NET 8**, **.NET 7** and **.NET 6**
 - Fully **async**
 - Extensive **XML documentation**
-- Coverage of the free API endpoints, including some user-only and beta routes  
-- **No external dependencies** (uses integrated HTTP and JSON)
-- **Custom exceptions** (`UrlscanException`) for advanced catching
-- Automatic **ratelimit** handling and request **retries**
+- Coverage of the free API endpoints, including some user-only and beta routes
+- **No external dependencies** (makes use of built-in `HttpClient` and `JsonSerializer`)
+- **Custom exceptions** (`UrlscanException`) for easy debugging
+- Parsing of custom Urlscan errors
 - Example project to demonstrate all capabilities of the library
+
+## Features
 - Scan suspicious URLs and submit verdicts on them
+- Search for public scans using ElasticSearch queries
 - Download screenshots and page DOMs
 - Empower your threat intelligence with live scans through `LiveClient`
 
@@ -109,30 +111,8 @@ await client.AddVerdict(new VerdictParameters()
 });
 ```
 
-## Available Methods
-- Task **AddVerdict**(Result result, VerdictScope scope, VerdictType type, string comment, string[] brands, ThreatType[] threats)
-- Task **AddVerdict**(string uuid, VerdictScope scope, string scopeValue, VerdictType type, string comment, string[] brands, ThreatType[] threats)
-- Task **AddVerdict**(VerdictParameters parameters)
-- Task\<byte[]> **DownloadScreenshot**(Result result)
-- Task\<byte[]> **DownloadScreenshot**(string uuid)
-- Task\<byte[]> **Liveshot**(string url, int width = 1280, int height = 1024)
-- Task\<Result> **GetResult**(string uuid)
-- Task\<Result> **Poll**(string uuid, int delay = 5000, int interval = 2000)
-- Task\<Result> **Poll**(Submission submission, int delay = 5000, int interval = 2000)
-- Task\<SearchItem[]> **Search**(string query, int amount = 100, string targetScan = null)
-- Task\<SimilarScan[]> **GetSimilarScans**(string uuid)
-- Task\<Stats> **GetStats**()
-- Task\<Stream> **DownloadScreenshotStream**(string uuid)
-- Task\<Stream> **LiveshotStream**(string url, int width = 1280, int height = 1024)
-- Task\<string> **DownloadDOM**(Result result)
-- Task\<string> **DownloadDOM**(string uuid)
-- Task\<Submission> **Scan**(string url, string[] tags = null, string userAgent = null, string referer = null, bool overrideSafety = false, Visibility visibility = Visibility.Public, ScanCountry country = ScanCountry.Auto)
-- Task\<Submission> **Scan**(ScanParameters parameters)
-- Task\<User> **GetCurrentUser**()
-
-## Available Events
-- EventHandler\<LiveScan> `UrlScanned`
-
 ## References
-- https://urlscan.io
-- https://twitter.com/urlscanio
+- Official website: https://urlscan.io
+- Urlscan Twitter: https://twitter.com/urlscanio
+
+*This is a community-ran library. Not affiliated with Urlscan GmbH.*