### Shodan Utility Methods in Go

Source: https://context7.com/shadowscatcher/shodan/llms.txt

Demonstrates how to use the Shodan Go client to access utility endpoints. This includes fetching your public IP, checking honeypot scores, listing scanned ports and protocols, retrieving search filters and facets, getting HTTP headers, and accessing account profile information. Requires the SHODAN_API_KEY environment variable.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os"

    "github.com/shadowscatcher/shodan"
)

func main() {
    client, _ := shodan.GetClient(os.Getenv("SHODAN_API_KEY"), http.DefaultClient, true)
    ctx := context.Background()

    // Get your public IP
    myIP, _ := client.MyIP(ctx)
    fmt.Printf("My IP: %s\n", myIP)
    // Output: My IP: 203.0.113.50

    // Check if IP is a honeypot (0.0 = not honeypot, 1.0 = definitely honeypot)
    score, _ := client.Honeyscore(ctx, "1.2.3.4")
    fmt.Printf("Honeypot score: %.2f\n", score)
    // Output: Honeypot score: 0.15

    // List ports Shodan scans
    ports, _ := client.Ports(ctx)
    fmt.Printf("Shodan scans %d ports\n", len(ports))
    // Output: Shodan scans 400+ ports

    // List available protocols for scanning
    protocols, _ := client.Protocols(ctx)
    for name, desc := range protocols {
        fmt.Printf("%s: %s\n", name, desc)
    }
    // Output:
    // http: HTTP web server
    // ssh: SSH server
    // ftp: FTP server

    // List available search filters
    filters, _ := client.Filters(ctx)
    fmt.Printf("Available filters: %v\n", filters[:5])
    // Output: Available filters: [asn city country device geo]

    // List available facets
    facets, _ := client.Facets(ctx)
    fmt.Printf("Available facets: %v\n", facets[:5])
    // Output: Available facets: [asn city country device domain]

    // Get HTTP headers your client sends
    headers, _ := client.HttpHeaders(ctx)
    for name, value := range headers {
        fmt.Printf("%s: %s\n", name, value)
    }

    // Account profile
    profile, _ := client.AccountProfile(ctx)
    fmt.Printf("Account: %s, Member since: %s\n", profile.DisplayName, profile.Created)
}

```

--------------------------------

### Perform Shodan Search with Golang

Source: https://github.com/shadowscatcher/shodan/blob/master/README.md

Demonstrates how to perform a Shodan search using the 'shadowscatcher/shodan' library. It shows how to construct search parameters, including product, ASN, and SSL options, and how to process the search results. Requires a Shodan API key.

```go
package main

import (
	"context"
	"github.com/shadowscatcher/shodan"
	"github.com/shadowscatcher/shodan/search"
	"github.com/shadowscatcher/shodan/search/ssl_versions"
	"log"
	"net/http"
	"os"
)

func main() {
	nginxSearch := search.Params{
		Page:1,
		Query: search.Query{
			Product: "nginx",
			ASN:  "AS14618",
			SSLOpts: search.SSLOpts{
				Cert: search.CertOptions{
					Expired: true,
				},
				Version: ssl_versions.TLSv1_2,
			},
		},
	}

	client, _ := shodan.GetClient(os.Getenv("SHODAN_API_KEY"), http.DefaultClient, true)
	ctx := context.Background()
	result, err := client.Search(ctx, nginxSearch)
	if err != nil {
		log.Fatal(err)
	}

	for _, match := range result.Matches {
		// a lot of returned data can be used in another searches
		// it's easy because you will get response with almost all possible fields, just don't forget to check them
		if match.HTTP != nil && match.HTTP.Favicon != nil {
			//newQuery := search.Query{HTTP: search.HTTP{Favicon: search.Favicon{Hash: match.HTTP.Favicon.Hash}}}
		}
	}
	
	// later on you can change every part of search query or parameters:
	nginxSearch.Page++  // for example, increase page
	nginxSearch.Query.Port = 443 // or add new search term
	result, err = client.Search(ctx, nginxSearch)  // and reuse modified parameters object
	if err != nil {
		log.Fatal(err)
	}
}
```

--------------------------------

### Client Initialization

Source: https://context7.com/shadowscatcher/shodan/llms.txt

Initializes a Shodan API client with optional rate limiting to enforce the 1 request/second limit required by Shodan's terms of service. It also demonstrates verifying the API key and checking remaining credits.

```APIDOC
## Client Initialization

Creates a Shodan API client with optional rate limiting that enforces the 1 request/second limit required by Shodan's terms of service.

### Method
POST

### Endpoint
/api/v1/auth/ தோken

### Parameters
#### Query Parameters
- **api_key** (string) - Required - Your Shodan API key.

#### Request Body
None

### Request Example
```go
package main

import (
    "context"
    "log"
    "net/http"
    "os"

    "github.com/shadowscatcher/shodan"
)

func main() {
    // Create client with rate limiting enabled (recommended)
    client, err := shodan.GetClient(os.Getenv("SHODAN_API_KEY"), http.DefaultClient, true)
    if err != nil {
        log.Fatal(err)
    }

    // Verify API key and check remaining credits
    ctx := context.Background()
    info, err := client.ApiInfo(ctx)
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("Plan: %s, Query Credits: %d, Scan Credits: %d",
        info.Plan, info.QueryCredits, info.ScanCredits)
}
```

### Response
#### Success Response (200)
- **Plan** (string) - The user's current Shodan plan.
- **QueryCredits** (integer) - The number of remaining query credits.
- **ScanCredits** (integer) - The number of remaining scan credits.

#### Response Example
```json
{
  "Plan": "dev",
  "QueryCredits": 100,
  "ScanCredits": 100
}
```
```

--------------------------------

### Manage Network Alerts with Shodan API

Source: https://context7.com/shadowscatcher/shodan/llms.txt

Demonstrates creating, managing, and deleting network alerts using the Shodan API. It includes setting up filters, triggers, and notification providers like Slack. Requires a Shodan API key and the 'github.com/shadowscatcher/shodan' library.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os"

    "github.com/shadowscatcher/shodan"
    "github.com/shadowscatcher/shodan/models"
)

func main() {
    client, _ := shodan.GetClient(os.Getenv("SHODAN_API_KEY"), http.DefaultClient, true)
    ctx := context.Background()

    // Create a new alert
    alert := models.Alert{
        Name:    "My Network Monitor",
        Filters: models.Filter{IP: []string{"192.168.1.0/24", "10.0.0.1"}},
        Expires: 0,  // 0 = never expires
    }

    created, err := client.CreateAlert(ctx, alert)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Alert created: %s (ID: %s)\n", created.Name, created.ID)
    // Output: Alert created: My Network Monitor (ID: ABCD1234)

    // List available triggers
    triggers, _ := client.ListTriggers(ctx)
    for _, t := range triggers {
        fmt.Printf("Trigger: %s - %s\n", t.Name, t.Description)
    }
    // Output:
    // Trigger: new_service - New service discovered
    // Trigger: open_database - Database exposed
    // Trigger: vulnerable - Vulnerability found

    // Enable a trigger on the alert
    _, err = client.CreateAlertTrigger(ctx, created.ID, "new_service")
    if err != nil {
        log.Fatal(err)
    }

    // Create a notification provider
    slackProvider, _ := models.CreateSlackProvider(
        "https://hooks.slack.com/services/XXX/YYY/ZZZ",
        "Security Alerts",
    )
    notifier, _ := client.CreateNotifier(ctx, slackProvider)

    // Link notifier to alert
    _, _ = client.AddAlertNotifier(ctx, created.ID, notifier.NotifierID)

    // List all alerts
    alerts, _ := client.ListAlerts(ctx)
    for _, a := range alerts {
        fmt.Printf("Alert: %s, IPs: %v\n", a.Name, a.Filters.IP)
    }

    // Clean up
    client.DeleteAlert(ctx, created.ID)
}
```

--------------------------------

### Initialize Shodan API Client in Go

Source: https://context7.com/shadowscatcher/shodan/llms.txt

Creates a Shodan API client with optional rate limiting to enforce the 1 request/second limit. It requires an API key and an HTTP client, and returns an initialized client or an error. The client can then be used to verify the API key and check remaining credits.

```go
package main

import (
    "context"
    "log"
    "net/http"
    "os"

    "github.com/shadowscatcher/shodan"
)

func main() {
    // Create client with rate limiting enabled (recommended)
    client, err := shodan.GetClient(os.Getenv("SHODAN_API_KEY"), http.DefaultClient, true)
    if err != nil {
        log.Fatal(err)
    }

    // Verify API key and check remaining credits
    ctx := context.Background()
    info, err := client.ApiInfo(ctx)
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("Plan: %s, Query Credits: %d, Scan Credits: %d",
        info.Plan, info.QueryCredits, info.ScanCredits)
    // Output: Plan: dev, Query Credits: 100, Scan Credits: 100
}
```

--------------------------------

### Lookup Host Information with Shodan API

Source: https://context7.com/shadowscatcher/shodan/llms.txt

Retrieves comprehensive information about a specific IP address, including open ports, services, banners, and detected vulnerabilities. Requires a Shodan API key and the 'github.com/shadowscatcher/shodan' library.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os"

    "github.com/shadowscatcher/shodan"
    "github.com/shadowscatcher/shodan/search"
)

func main() {
    client, _ := shodan.GetClient(os.Getenv("SHODAN_API_KEY"), http.DefaultClient, true)
    ctx := context.Background()

    params := search.HostParams{
        IP:      "8.8.8.8",
        History: false,  // Set true for historical data
        Minify:  false,  // Set true to reduce response size
    }

    host, err := client.Host(ctx, params)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("IP: %s\n", host.IPstr)
    fmt.Printf("Organization: %s\n", *host.Org)
    fmt.Printf("Country: %s\n", host.Location.CountryName)
    fmt.Printf("Open Ports: %v\n", host.Ports)
    fmt.Printf("Vulnerabilities: %v\n", host.Vulns)
    // Output:
    // IP: 8.8.8.8
    // Organization: Google LLC
    // Country: United States
    // Open Ports: [53 443]
    // Vulnerabilities: []

    for _, service := range host.Services {
        fmt.Printf("Port %d/%s: %s %s\n",
            service.Port, service.Transport,
            service.ProductString(), service.VersionString())
    }
}
```

--------------------------------

### Host Information Lookup

Source: https://context7.com/shadowscatcher/shodan/llms.txt

Retrieves all services discovered on a specific IP address, including banners, vulnerabilities, and service-specific metadata.

```APIDOC
## GET /api/host

### Description
Retrieves all services discovered on a specific IP address, including banners, vulnerabilities, and service-specific metadata.

### Method
GET

### Endpoint
/api/host

### Parameters
#### Query Parameters
- **ip** (string) - Required - The IP address to look up.
- **history** (boolean) - Optional - Set to `true` to retrieve historical data.
- **minify** (boolean) - Optional - Set to `true` to reduce the response size.

### Request Example
```json
{
  "ip": "8.8.8.8",
  "history": false,
  "minify": false
}
```

### Response
#### Success Response (200)
- **ip_str** (string) - The IP address.
- **org** (string) - The organization associated with the IP address.
- **location** (object) - Information about the location.
  - **country_name** (string) - The name of the country.
- **ports** (array) - A list of open ports.
- **vulns** (array) - A list of detected vulnerabilities.
- **services** (array) - A list of discovered services.
  - **port** (integer) - The port number.
  - **transport** (string) - The transport protocol (e.g., "tcp").
  - **product** (string) - The name of the service product.
  - **version** (string) - The version of the service product.

#### Response Example
```json
{
  "ip_str": "8.8.8.8",
  "org": "Google LLC",
  "location": {
    "country_name": "United States"
  },
  "ports": [53, 443],
  "vulns": [],
  "services": [
    {
      "port": 53,
      "transport": "udp",
      "product": "dns",
      "version": ""
    },
    {
      "port": 443,
      "transport": "tcp",
      "product": "http",
      "version": ""
    }
  ]
}
```
```

--------------------------------

### Search Devices

Source: https://context7.com/shadowscatcher/shodan/llms.txt

Searches Shodan using structured query parameters with support for filters, facets, and pagination. Each page returns up to 100 results.

```APIDOC
## Search Devices

Searches Shodan using structured query parameters with support for filters, facets, and pagination. Each page returns up to 100 results.

### Method
GET

### Endpoint
/shodan/host

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query string.
- **page** (integer) - Optional - The page number of results to return (default: 1).
- **facets** (array of strings) - Optional - Facets to include in the search results (e.g., `country:10`, `org:10`).

#### Request Body
None

### Request Example
```go
package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os"

    "github.com/shadowscatcher/shodan"
    "github.com/shadowscatcher/shodan/search"
    "github.com/shadowscatcher/shodan/search/ssl_versions"
)

func main() {
    client, _ := shodan.GetClient(os.Getenv("SHODAN_API_KEY"), http.DefaultClient, true)
    ctx := context.Background()

    // Build structured search query
    params := search.Params{
        Page: 1,
        Query: search.Query{
            Product: "nginx",
            Country: "US",
            Port:    443,
            SSLOpts: search.SSLOpts{
                Version: ssl_versions.TLSv1_2,
                Cert: search.CertOptions{
                    Expired: false,
                },
            },
        },
        Facets: []string{"country:10", "org:10"},
    }

    result, err := client.Search(ctx, params)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Total results: %d\n", result.Total)

    for _, match := range result.Matches {
        fmt.Printf("IP: %s, Port: %d, Org: %s\n",
            match.IPString(), match.Port, *match.Org)

        // Access service-specific data
        if match.HTTP != nil {
            fmt.Printf("  Title: %s\n", match.HTTP.Title)
        }
        if match.SSL != nil && match.SSL.Cert.Expired {
            fmt.Println("  WARNING: SSL certificate expired")
        }
    }

    // Paginate through results
    params.Page++
    nextPage, _ := client.Search(ctx, params)
    fmt.Printf("Page 2 results: %d\n", len(nextPage.Matches))
}
```

### Response
#### Success Response (200)
- **Total** (integer) - The total number of matching devices.
- **Matches** (array of objects) - A list of matching devices, each containing details like IP address, port, organization, and service-specific data (e.g., HTTP, SSL).
- **Facets** (object) - Facet breakdown of the search results.

#### Response Example
```json
{
  "Total": 1523456,
  "Matches": [
    {
      "ip_str": "1.2.3.4",
      "port": 443,
      "org": "Example Corp",
      "http": {
        "title": "Example Website"
      },
      "ssl": {
        "cert": {
          "expired": false
        }
      }
    }
  ],
  "Facets": {
    "country": [
      {
        "value": "US",
        "count": 1000000
      }
    ],
    "org": [
      {
        "value": "Example Corp",
        "count": 500000
      }
    ]
  }
}
```
```

--------------------------------

### Search Shodan Devices with Structured Parameters in Go

Source: https://context7.com/shadowscatcher/shodan/llms.txt

Searches Shodan using structured query parameters, supporting filters, facets, and pagination. Each page returns up to 100 results. The function takes a context and search parameters, returning search results or an error. It allows access to host details and service-specific data, and supports pagination.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os"

    "github.com/shadowscatcher/shodan"
    "github.com/shadowscatcher/shodan/search"
    "github.com/shadowscatcher/shodan/search/ssl_versions"
)

func main() {
    client, _ := shodan.GetClient(os.Getenv("SHODAN_API_KEY"), http.DefaultClient, true)
    ctx := context.Background()

    // Build structured search query
    params := search.Params{
        Page: 1,
        Query: search.Query{
            Product: "nginx",
            Country: "US",
            Port:    443,
            SSLOpts: search.SSLOpts{
                Version: ssl_versions.TLSv1_2,
                Cert: search.CertOptions{
                    Expired: false,
                },
            },
        },
        Facets: []string{"country:10", "org:10"},
    }

    result, err := client.Search(ctx, params)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Total results: %d\n", result.Total)
    // Output: Total results: 1523456

    for _, match := range result.Matches {
        fmt.Printf("IP: %s, Port: %d, Org: %s\n",
            match.IPString(), match.Port, *match.Org)

        // Access service-specific data
        if match.HTTP != nil {
            fmt.Printf("  Title: %s\n", match.HTTP.Title)
        }
        if match.SSL != nil && match.SSL.Cert.Expired {
            fmt.Println("  WARNING: SSL certificate expired")
        }
    }

    // Paginate through results
    params.Page++
    nextPage, _ := client.Search(ctx, params)
    fmt.Printf("Page 2 results: %d\n", len(nextPage.Matches))
}
```

--------------------------------

### Shodan Service-Specific Data Models in Go

Source: https://context7.com/shadowscatcher/shodan/llms.txt

Illustrates how to use the Shodan Go client to search for and parse service-specific data from scan results. This includes detailed information for MongoDB, Elasticsearch, Docker, SSL certificates, and Redis. It requires the SHODAN_API_KEY environment variable and utilizes the `search` package for query parameters.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os"

    "github.com/shadowscatcher/shodan"
    "github.com/shadowscatcher/shodan/search"
)

func main() {
    client, _ := shodan.GetClient(os.Getenv("SHODAN_API_KEY"), http.DefaultClient, true)
    ctx := context.Background()

    // Search for exposed MongoDB instances
    params := search.Params{
        Query: search.Query{Product: "MongoDB"},
    }

    result, _ := client.Search(ctx, params)
    for _, match := range result.Matches {
        if match.MongoDB != nil {
            if !match.MongoDB.Authentication {
                fmt.Printf("EXPOSED MongoDB: %s\n", match.IpAndPort())

                databases := match.MongoDB.ListDatabases.Databases
                fmt.Printf("  Databases: %d, Total Size: %d bytes\n",
                    len(databases), match.MongoDB.ListDatabases.TotalSize)

                for _, db := range databases {
                    fmt.Printf("    - %s (%d bytes)\n", db.Name, db.SizeOnDisk)
                }
            }
        }

        // Elasticsearch specific data
        if match.Elastic != nil {
            fmt.Printf("Elasticsearch: %s\n", match.IpAndPort())
            for indexName, index := range match.Elastic.Indices {
                fmt.Printf("  Index: %s, UUID: %s\n", indexName, index.UUID)
            }
        }

        // Docker specific data
        if match.Docker != nil {
            fmt.Printf("Docker: %s, Version: %s\n",
                match.IpAndPort(), match.Docker.Version)
            fmt.Printf("  Containers: %d\n", match.Docker.Containers)
        }

        // SSL certificate data
        if match.SSL != nil {
            fmt.Printf("SSL Certificate for %s\n", match.IpAndPort())
            fmt.Printf("  Issuer: %s\n", match.SSL.Cert.Issuer.CN)
            fmt.Printf("  Expires: %s\n", match.SSL.Cert.Expires)
            fmt.Printf("  Expired: %t\n", match.SSL.Cert.Expired)
        }

        // Redis specific data
        if match.Redis != nil {
            fmt.Printf("Redis: %s, Version: %s\n",
                match.IpAndPort(), match.Redis.RedisVersion)
        }
    }
}

```

--------------------------------

### Perform DNS Operations with Shodan API

Source: https://context7.com/shadowscatcher/shodan/llms.txt

Handles DNS resolution (hostname to IP) and reverse DNS lookups (IP to hostnames) using the Shodan API. It also demonstrates querying domain DNS records. Requires a Shodan API key and the 'github.com/shadowscatcher/shodan' library.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os"

    "github.com/shadowscatcher/shodan"
    "github.com/shadowscatcher/shodan/search"
)

func main() {
    client, _ := shodan.GetClient(os.Getenv("SHODAN_API_KEY"), http.DefaultClient, true)
    ctx := context.Background()

    // Resolve hostnames to IPs
    hostnames := []string{"google.com", "github.com", "shodan.io"}
    resolved, err := client.DnsResolve(ctx, hostnames)
    if err != nil {
        log.Fatal(err)
    }

    for hostname, ip := range resolved {
        fmt.Printf("%s -> %s\n", hostname, ip)
    }
    // Output:
    // google.com -> 142.250.185.46
    // github.com -> 140.82.121.4
    // shodan.io -> 66.240.192.138

    // Reverse DNS lookup
    ips := []string{"8.8.8.8", "1.1.1.1"}
    reverse, err := client.DnsReverse(ctx, ips)
    if err != nil {
        log.Fatal(err)
    }

    for ip, hostnames := range reverse {
        fmt.Printf("%s -> %v\n", ip, hostnames)
    }
    // Output:
    // 8.8.8.8 -> [dns.google]
    // 1.1.1.1 -> [one.one.one.one]

    // Domain DNS records
    domainQuery := search.DomainQuery{
        Domain:     "google.com",
        History:    false,
        RecordType: "A",
        Page:       1,
    }
    domain, _ := client.DnsDomain(ctx, domainQuery)
    fmt.Printf("Domain: %s, Records: %d\n", domain.Domain, len(domain.Data))
}
```

--------------------------------

### Search Shodan Exploit Database with API (Go)

Source: https://context7.com/shadowscatcher/shodan/llms.txt

Searches Shodan's exploit database for vulnerabilities and exploit code across multiple sources. It allows filtering by CVE, platform, and exploit type, and can return a count of matching exploits or detailed results.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os"

    "github.com/shadowscatcher/shodan"
    "github.com/shadowscatcher/shodan/search"
    "github.com/shadowscatcher/shodan/search/exploit_types"
)

func main() {
    client, _ := shodan.GetClient(os.Getenv("SHODAN_API_KEY"), http.DefaultClient, true)
    ctx := context.Background()

    params := search.ExploitParams{
        Query: search.ExploitsQuery{
            CVE:      "2021-44228",  // Log4Shell
            Platform: "linux",
            Type:     exploit_types.Remote,
        },
        Facets: []string{"type", "platform"},
        Page:   1,
    }

    result, err := client.ExploitSearch(ctx, params)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Total exploits found: %d\n", result.Total)
    // Output: Total exploits found: 45

    for _, exploit := range result.Matches {
        fmt.Printf("CVE: %s, Source: %s\n", exploit.CVE, exploit.Source)
        fmt.Printf("  Title: %s\n", exploit.Description)
        fmt.Printf("  Author: %s\n", exploit.Author)
    }

    // Count only (no results returned)
    count, _ := client.ExploitCount(ctx, params)
    fmt.Printf("Exploit count: %d\n", count.Total)
}
```

--------------------------------

### Process Diverse Shodan Search Results with Golang

Source: https://github.com/shadowscatcher/shodan/blob/master/README.md

Illustrates how to parse and utilize various data types returned by Shodan search queries, such as MongoDB, SSL certificate information, and Elasticsearch indices. This snippet highlights accessing specific fields within the search results.

```go
for _, match := range result.Matches {
	if match.MongoDB != nil && !match.MongoDB.Authentication {
		fmt.Println("exposed mongodb:", match.IpAndPort())
		databases := match.MongoDB.ListDatabases.Databases

		fmt.Println("databases:", len(databases), "size:", match.MongoDB.ListDatabases.TotalSize)
		for _, db := range databases {
			for _, collectionName := range db.Collections {
				fmt.Println(collectionName)
			}
		}
	}
		
	if match.SSL != nil && match.SSL.Cert.Expired {
		fmt.Println("expired certificate:", match.IpAndPort())
	}
	
	if match.Elastic != nil {
		fmt.Println("exposed elastic:", match.IpAndPort())
		for indexName, index := range match.Elastic.Indices {
			fmt.Println(indexName, index.UUID)
		}
	}
}
```

--------------------------------

### Network Alerts API

Source: https://context7.com/shadowscatcher/shodan/llms.txt

Creates and manages network alerts to monitor IP ranges for changes. Alerts can trigger notifications via various channels.

```APIDOC
## Network Alerts API

### Description
Creates and manages network alerts to monitor IP ranges for changes. Alerts can trigger notifications via email, Slack, webhooks, and other channels.

### Method
POST, GET, DELETE

### Endpoint
/alerts, /alerts/{id}/triggers, /notifiers, /alerts/{id}/notifiers

### Parameters
#### Create Alert
##### Request Body
- **name** (string) - Required - The name of the alert.
- **filters** (object) - Required - Filtering criteria for the alert.
  - **ip** (array of strings) - Required - A list of IP addresses or CIDR ranges to monitor.
- **expires** (integer) - Optional - Expiration time in seconds. 0 means never expires.

##### Response (201 Created)
- **id** (string) - The unique identifier of the created alert.
- **name** (string) - The name of the alert.

#### Create Alert Trigger
##### Path Parameters
- **id** (string) - Required - The ID of the alert to add a trigger to.
##### Request Body
- **trigger_name** (string) - Required - The name of the trigger to add (e.g., "new_service", "open_database", "vulnerable").

#### List Triggers
##### Response (200 OK)
- **(array of objects)** - A list of available triggers.
  - **name** (string) - The name of the trigger.
  - **description** (string) - A description of the trigger.

#### Create Notifier
##### Request Body
- **provider_config** (object) - Configuration for the notification provider (e.g., Slack, Email).
  - **type** (string) - The type of provider (e.g., "slack").
  - **url** (string) - The webhook URL for Slack.
  - **channel** (string) - The channel name for Slack.

##### Response (201 Created)
- **notifier_id** (string) - The unique identifier of the created notifier.

#### Add Notifier to Alert
##### Path Parameters
- **id** (string) - Required - The ID of the alert.
- **notifier_id** (string) - Required - The ID of the notifier to add.

#### List Alerts
##### Response (200 OK)
- **(array of objects)** - A list of all configured alerts.
  - **name** (string) - The name of the alert.
  - **filters** (object) - The filters applied to the alert.
    - **ip** (array of strings) - The IP addresses or CIDR ranges.

#### Delete Alert
##### Path Parameters
- **id** (string) - Required - The ID of the alert to delete.

### Request Example (Create Alert)
```json
{
  "name": "My Network Monitor",
  "filters": {
    "ip": ["192.168.1.0/24", "10.0.0.1"]
  },
  "expires": 0
}
```

### Response Example (Create Alert)
```json
{
  "id": "ABCD1234",
  "name": "My Network Monitor"
}
```

### Response Example (List Triggers)
```json
[
  {
    "name": "new_service",
    "description": "New service discovered"
  },
  {
    "name": "open_database",
    "description": "Database exposed"
  }
]
```

### Request Example (Create Slack Notifier)
```json
{
  "provider_config": {
    "type": "slack",
    "url": "https://hooks.slack.com/services/XXX/YYY/ZZZ",
    "channel": "#security-alerts"
  }
}
```

### Response Example (Create Notifier)
```json
{
  "notifier_id": "NOTIFIER5678"
}
```

### Response Example (List Alerts)
```json
[
  {
    "id": "ABCD1234",
    "name": "My Network Monitor",
    "filters": {
      "ip": ["192.168.1.0/24", "10.0.0.1"]
    }
  }
]
```
```

--------------------------------

### DNS Operations

Source: https://context7.com/shadowscatcher/shodan/llms.txt

Performs DNS resolution (hostname to IP) and reverse DNS lookups (IP to hostnames), and retrieves domain DNS records.

```APIDOC
## DNS Operations

### Description
Performs DNS resolution (hostname to IP) and reverse DNS lookups (IP to hostnames), and retrieves domain DNS records.

### Method
POST

### Endpoint
/dns/resolve, /dns/reverse, /dns/domain

### Parameters
#### DNS Resolution (hostname to IP)
##### Request Body
- **hostnames** (array of strings) - Required - A list of hostnames to resolve.

##### Response (200)
- **(object)** - A map where keys are hostnames and values are their corresponding IP addresses.

#### Reverse DNS Lookup (IP to hostnames)
##### Request Body
- **ips** (array of strings) - Required - A list of IP addresses to perform reverse lookups on.

##### Response (200)
- **(object)** - A map where keys are IP addresses and values are arrays of associated hostnames.

#### Domain DNS Records
##### Query Parameters
- **domain** (string) - Required - The domain name to query.
- **history** (boolean) - Optional - Set to `true` to include historical data.
- **record_type** (string) - Optional - The type of DNS record to retrieve (e.g., "A", "MX", "TXT"). Defaults to "A".
- **page** (integer) - Optional - The page number for paginated results.

##### Response (200)
- **domain** (string) - The queried domain name.
- **data** (array) - An array of DNS records.

### Request Example (DNS Resolution)
```json
{
  "hostnames": ["google.com", "github.com", "shodan.io"]
}
```

### Response Example (DNS Resolution)
```json
{
  "google.com": "142.250.185.46",
  "github.com": "140.82.121.4",
  "shodan.io": "66.240.192.138"
}
```

### Request Example (Reverse DNS Lookup)
```json
{
  "ips": ["8.8.8.8", "1.1.1.1"]
}
```

### Response Example (Reverse DNS Lookup)
```json
{
  "8.8.8.8": ["dns.google"],
  "1.1.1.1": ["one.one.one.one"]
}
```

### Request Example (Domain DNS Records)
`GET /dns/domain?domain=google.com&record_type=A&page=1`

### Response Example (Domain DNS Records)
```json
{
  "domain": "google.com",
  "data": [
    {
      "address": "142.250.185.46",
      "timestamp": 1678886400
    }
  ]
}
```
```

--------------------------------

### Count Search Results

Source: https://context7.com/shadowscatcher/shodan/llms.txt

Returns the total count of matching devices without consuming query credits. This is useful for estimating the size of search results before running a full search.

```APIDOC
## Count Search Results

Returns the total count of matching devices without consuming query credits. Useful for estimating result size before running full searches.

### Method
GET

### Endpoint
/shodan/count

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query string.
- **facets** (array of strings) - Optional - Facets to include in the count results (e.g., `vuln:10`, `country:5`).

#### Request Body
None

### Request Example
```go
package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os"

    "github.com/shadowscatcher/shodan"
    "github.com/shadowscatcher/shodan/search"
)

func main() {
    client, _ := shodan.GetClient(os.Getenv("SHODAN_API_KEY"), http.DefaultClient, true)
    ctx := context.Background()

    params := search.Params{
        Query: search.Query{
            Product: "Apache",
            HasVuln: true,
        },
        Facets: []string{"vuln:10", "country:5"},
    }

    result, err := client.Count(ctx, params)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Total vulnerable Apache servers: %d\n", result.Total)

    // Access facet breakdown
    for _, facet := range result.Facets["vuln"] {
        fmt.Printf("  %s: %d\n", facet.Value, facet.Count)
    }
}
```

### Response
#### Success Response (200)
- **Total** (integer) - The total count of matching devices.
- **Facets** (object) - Facet breakdown of the count results.

#### Response Example
```json
{
  "Total": 234567,
  "Facets": {
    "vuln": [
      {
        "value": "CVE-2021-41773",
        "count": 45000
      },
      {
        "value": "CVE-2021-42013",
        "count": 32000
      }
    ],
    "country": [
      {
        "value": "US",
        "count": 100000
      }
    ]
  }
}
```
```

--------------------------------

### Stream Real-Time Shodan Banners with API (Go)

Source: https://context7.com/shadowscatcher/shodan/llms.txt

Subscribes to Shodan's real-time data streams to receive banners as they are collected. This requires a streaming API subscription. The client can filter streams by ports, countries, ASNs, tags, vulnerabilities, or alerts.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os"

    "github.com/shadowscatcher/shodan"
)

func main() {
    // Create stream client (separate from regular client)
    streamClient, err := shodan.GetStreamClient(os.Getenv("SHODAN_API_KEY"), http.DefaultClient)
    if err != nil {
        log.Fatal(err)
    }

    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    // Stream banners for specific ports
    ports := []int{22, 80, 443, 8080}
    bannerChan, err := streamClient.Ports(ctx, ports)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println("Streaming banners...")
    count := 0
    for banner := range bannerChan {
        fmt.Printf("[%s] %s:%d - %s\n",
            banner.Timestamp,
            banner.IPString(),
            banner.Port,
            banner.ProductString())

        // Process service-specific data
        if banner.SSH != nil {
            fmt.Printf("  SSH: %s\n", banner.SSH.Type)
        }
        if banner.HTTP != nil {
            fmt.Printf("  HTTP Title: %s\n", banner.HTTP.Title)
        }

        count++
        if count >= 100 {
            cancel()  // Stop after 100 banners
            break
        }
    }
    // Output:
    // Streaming banners...
    // [2024-01-15T10:30:45.123456] 192.0.2.1:443 - nginx 1.18.0
    //   HTTP Title: Welcome Page
    // [2024-01-15T10:30:45.234567] 198.51.100.5:22 - OpenSSH 8.2
    //   SSH: ssh-rsa

    // Other stream types available:
    // streamClient.Banners(ctx)           // All banners
    // streamClient.Countries(ctx, []string{"US", "DE"})  // Filter by country
    // streamClient.ASN(ctx, []string{"AS15169"})         // Filter by ASN
    // streamClient.Tags(ctx, []string{"ics", "scada"})   // Filter by tags
    // streamClient.Vulns(ctx, []string{"CVE-2021-44228"}) // Filter by vulnerability
    // streamClient.Alerts(ctx)            // Your alert matches
}
```

--------------------------------

### Submit IPs for On-Demand Scanning with Shodan API (Go)

Source: https://context7.com/shadowscatcher/shodan/llms.txt

Submits IP addresses or netblocks for on-demand scanning using the Shodan API. This requires a paid API plan with scan credits. The function returns a scan ID and the remaining credits, and can poll for scan status.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os"
    "time"

    "github.com/shadowscatcher/shodan"
)

func main() {
    client, _ := shodan.GetClient(os.Getenv("SHODAN_API_KEY"), http.DefaultClient, true)
    ctx := context.Background()

    // Submit IPs for scanning (1 credit per IP)
    ips := []string{"203.0.113.1", "203.0.113.2"}
    scan, err := client.SubmitScan(ctx, ips, false)  // force=false to skip recently scanned IPs
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Scan ID: %s, Credits: %d\n", scan.ID, scan.CreditsLeft)
    // Output: Scan ID: ABC123, Credits: 98

    // Poll scan status
    for {
        status, _ := client.GetScan(ctx, scan.ID)
        fmt.Printf("Status: %s\n", status.Status)

        if status.Status == "DONE" {
            break
        }
        time.Sleep(10 * time.Second)
    }

    // List all scans
    scans, _ := client.ListScans(ctx, 1)
    for _, s := range scans.Matches {
        fmt.Printf("Scan: %s, Status: %s, Created: %s\n",
            s.ID, s.Status, s.Created)
    }
}
```

--------------------------------

### Count Shodan Search Results in Go

Source: https://context7.com/shadowscatcher/shodan/llms.txt

Returns the total count of matching devices without consuming query credits, useful for estimating result size. It takes a context and search parameters, returning a count result or an error. The function also allows access to facet breakdowns for further analysis.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os"

    "github.com/shadowscatcher/shodan"
    "github.com/shadowscatcher/shodan/search"
)

func main() {
    client, _ := shodan.GetClient(os.Getenv("SHODAN_API_KEY"), http.DefaultClient, true)
    ctx := context.Background()

    params := search.Params{
        Query: search.Query{
            Product: "Apache",
            HasVuln: true,
        },
        Facets: []string{"vuln:10", "country:5"},
    }

    result, err := client.Count(ctx, params)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Total vulnerable Apache servers: %d\n", result.Total)
    // Output: Total vulnerable Apache servers: 234567

    // Access facet breakdown
    for _, facet := range result.Facets["vuln"] {
        fmt.Printf("  %s: %d\n", facet.Value, facet.Count)
    }
    // Output:
    //   CVE-2021-41773: 45000
    //   CVE-2021-42013: 32000
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.