Shodan 1.0.0

Intro

This library is an asynchronous C# client for shodan.io REST API.

Features

The main feature of this library is a rich models - they contain a lot of properties, which other libraries just not aware of. For example, Service object has the following properties with valueable information (if such services were detected on host, of course - otherwise they will just have null value):

• Cassandra
• DB2
• DNS
• Docker
• Elastic
• Etcd
• EthernetIP
• FTP
• Hive
• HTTP
• ISAKMP
• Lantronix
• Monero
• MongoDB
• MQTT
• Netbios
• NTP
• Redis
• RIP
• Rsync
• SMB
• SNMP
• SSH
• Vertx

All models and their complex properties also has ExtraValues property for an unknown keys in response.

The second feature, which makes this library unique, is a set of methods - all API is covered, including exploits and stream. There are even methods, that are not listed in documentantion - like ListScans() and Services()

Third feature is a search query classes, which allows you to create query as CLR object, modify and even serialize it. The object is mutable, so you can, for example, increase a page in search parameters. Of course, such approach has its own limitations, that's why you can always use just a string for performing search.

Also, because of very big set of API methods, there are separate client classes for exploits, stream and alerts APIs. You can use them by themselves or acces via ShodanClient class properties.

Basic usage example

This example shows how to create a client, compose a search query and how to use models later.

    class Program
    {
        static async Task Main()
        {
            string key = Environment.GetEnvironmentVariable("SHODAN_API_KEY");

            ShodanClient client = new ClientFactory(key).GetFullClient();

            // All client methods are asynchronous;
            // The only exception is StreamClient, which has generator methods.
            ApiInfo apiInfo = await client.ApiInfo();
            Console.WriteLine("Unlocked credits left: {0}", apiInfo.UnlockedLeft);

            // Some other clients are properties of full client
            var alerts = await client.Alerts.ListAlerts();

            // You can create a query object for search or just pass a string to search method;
            // Fill "Text" property of query to specify a search term.
            ShodanSearchQuery query = new ShodanSearchQuery
            {
                // We want to find exposed ElasticSearch instances in China with a "readme" index
                // (typically it's an index with ransom note)
                Text = "readme",
                Country = "CN",
                Port = 9200
            };

            for (int i = 0; i < 10; i++)
            {
                Console.WriteLine(query.Parameters.Page);
                query.Parameters.Page++;

                SearchResult result = await client.Search(query);

                PrintElasticsInfo(result);
                query.Parameters.Page++; // ShodanSearchQuery object is mutable

                if (result.Services.Count < 100)
                    break;
            }

            Console.ReadLine();
        }

        // This method prints some of ElasicSearch properties to stdout
        private static void PrintElasticsInfo(SearchResult result)
        {
            foreach (Service service in result.Services.Where(s => s.Elastic != null))
            {
                var elastic = service.Elastic;

                // you should be careful about nulls - Shodan responses are not statically typed and can lack some keys
                if (elastic.Cluster?.Indices?.Count > 0 && elastic.Cluster?.Indices?.Docs?.Count > 0)
                {
                    Console.WriteLine($"Exposed ElasticSearch at {service.IPStr}:{service.Port}");
                    Console.WriteLine($"Total docs: {elastic.Cluster.Indices.Docs.Count}");
                    Console.WriteLine($"Total bytes: {elastic.Cluster.Indices.Store?.SizeInBytes}");
                    Console.WriteLine($"Cluster name: {elastic.Cluster.ClusterName}");

                    Console.WriteLine("Indices:");
                    foreach (string indexName in elastic.Indices.Keys)
                    {
                        Console.WriteLine($"\t{indexName}");
                    }
                }
                Console.WriteLine();
            }
        }
    }

Since version 1.0.0 library supports Microsoft dependency injection. For example, in ASP.NET project you can register all available clients in your Startup.cs in ConfigureServices method like this:

        using Shodan.Extensions;  // namespace with DI extensions

        ...

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            services.AddShodanClients(Environment.GetEnvironmentVariable("SHODAN_API_KEY"));
        }

Now you can create your services with any client type as dependency.