• Stars
    star
    103
  • Rank 332,955 (Top 7 %)
  • Language
    Ruby
  • License
    MIT License
  • Created about 7 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

๐Ÿ”ญ A modern, async Ruby gem for Shodan.

Shodanz

Gem Version Yard Docs CI

A modern, async Ruby gem for Shodan, the world's first search engine for Internet-connected devices.

Installation

$ gem install shodanz

Usage

require "shodanz"

client = Shodanz.client.new(key: "YOUR_API_KEY")

NOTE: You can also set the SHODAN_API_KEY environment variable instead of passing the API key as an argument when creating a client.

Optional Async Support

Shodanz utilizes async to provide asyncronous IO. This doesn't break any existing scripts using Shodanz, but now offers even more flexibility to write more awesome things, like this asyncronous honeypot detector:

require 'async'
require 'shodanz'

client = Shodanz.client.new

# Asynchronously stream banner info from shodan  and check any
# IP addresses against the experimental honeypot scoring service.
client.streaming_api.banners do |banner|
  if ip = banner['ip_str']
    Async do
      score = client.rest_api.honeypot_score(ip).wait
      puts "#{ip} has a #{score * 100}% chance of being a honeypot"
    rescue Shodanz::Errors::RateLimited
      sleep rand
      retry
    rescue # any other errors
      next
    end
  end
end

Note: To run any Shodanz method asyncronously, simply wrap it in a Async { ... } block. To wait for any other async operation to finnish in the block, call .wait on it.

REST API

The REST API provides methods to search Shodan, look up hosts, get summary information on queries and a variety of utility methods to make developing easier. Refer to the REST API documentation for more ideas on how to use it.

Shodan Search Methods

Search'n for stuff, are 'ya?

Host Information

Returns all services that have been found on the given host IP.

client.host("8.8.8.8")                # Default
client.host("8.8.8.8", history: true) # All historical banners should be returned.
client.host("8.8.8.8", minify: true)  # Only return the list of ports and the general host information, no banners.

Host Search

Search Shodan using the same query syntax as the website and use facets to get summary information for different properties.

client.host_search("mongodb")
client.host_search("nginx")
client.host_search("apache", after: "1/12/16")
client.host_search("ssh", port: 22, page: 1)
client.host_search("ssh", port: 22, page: 2)
client.host_search("ftp", port: 21, facets: { link: "Ethernet or modem" })

Search Shodan without Results

This method behaves identical to host_search with the only difference that this method does not return any host results, it only returns the total number of results that matched the query and any facet information that was requested. As a result this method does not consume query credits.

client.host_count("apache")
client.host_count("apache", country: "US")
client.host_count("apache", country: "US", state: "MI")
client.host_count("apache", country: "US", state: "MI", city: "Detroit")
client.host_count("nginx",  facets: { country: 5 })
client.host_count("apache", facets: { country: 5 })

Scan Targets

Use this method to request Shodan to crawl an IP or netblock.

client.scan("8.8.8.8")

Crawl Internet for Port

Use this method to request Shodan to crawl the Internet for a specific port.

This method is restricted to security researchers and companies with a Shodan Data license. To apply for access to this method as a researcher, please email [email protected] with information about your project. Access is restricted to prevent abuse.

client.crawl_for(port: 80, protocol: "http")

List Community Queries

Use this method to obtain a list of search queries that users have saved in Shodan.

client.community_queries
client.community_queries(page: 2)
client.community_queries(sort: "votes")
client.community_queries(sort: "votes", page: 2)
client.community_queries(order: "asc")
client.community_queries(order: "desc")

Search Community Queries

Use this method to search the directory of search queries that users have saved in Shodan.

client.search_for_community_query("the best")
client.search_for_community_query("the best", page: 2)

Popular Community Query Tags

Use this method to obtain a list of popular tags for the saved search queries in Shodan.

client.popular_query_tags
client.popular_query_tags(20)

Protocols

This method returns an object containing all the protocols that can be used when launching an Internet scan.

client.protocols

Ports

This method returns a list of port numbers that the Shodan crawlers are looking for.

client.ports

Account Profile

Returns information about the Shodan account linked to this API key.

client.profile

DNS Lookup

Look up the IP address for the provided list of hostnames.

client.resolve("google.com")
client.resolve("google.com", "bing.com")

Reverse DNS Lookup

Look up the hostnames that have been defined for the given list of IP addresses.

client.reverse_lookup("74.125.227.230")
client.reverse_lookup("74.125.227.230", "204.79.197.200")

HTTP Headers

Shows the HTTP headers that your client sends when connecting to a webserver.

client.http_headers

Your IP Address

Get your current IP address as seen from the Internet.

client.my_ip

Honeypot Score

Calculates a honeypot probability score ranging from 0 (not a honeypot) to 1.0 (is a honeypot).

client.honeypot_score('8.8.8.8')

API Plan Information

client.info

Streaming API

The Streaming API is an HTTP-based service that returns a real-time stream of data collected by Shodan. Refer to the Streaming API documentation for more ideas on how to use it.

Banners

This stream provides ALL of the data that Shodan collects. Use this stream if you need access to everything and/ or want to store your own Shodan database locally. If you only care about specific ports, please use the Ports stream.

client.banners do |data|
  # do something with banner data
  puts data
end

Banners Filtered by ASN

This stream provides a filtered, bandwidth-saving view of the Banners stream in case you are only interested in devices located in certain ASNs.

client.banners_within_asns(3303, 32475) do |data|
  # do something with banner data
  puts data
end

Banners Filtered by Country

This stream provides a filtered, bandwidth-saving view of the Banners stream in case you are only interested in devices located in certain countries.

client.banners_within_countries("DE", "US", "JP") do |data|
  # do something with banner data
  puts data
end

Banners Filtered by Ports

Only returns banner data for the list of specified ports. This stream provides a filtered, bandwidth-saving view of the Banners stream in case you are only interested in a specific list of ports.

client.banners_on_ports(21, 22, 80) do |data|
  # do something with banner data
  puts data
end

Banners by Network Alerts

Subscribe to banners discovered on all IP ranges described in the network alerts.

client.alerts do |data|
  # do something with banner data
  puts data
end

Banner Filtered by Alert ID

Subscribe to banners discovered on the IP range defined in a specific network alert.

client.alert("HKVGAIRWD79Z7W2T") do |data|
  # do something with banner data
  puts data
end

Exploits API

The Exploits API provides access to several exploit/ vulnerability data sources. Refer to the Exploits API documentation for more ideas on how to use it.

Search

Search across a variety of data sources for exploits and use facets to get summary information.

client.exploits_api.search("python")             # Search for python vulns.
client.exploits_api.search(port: 22)             # Port number for the affected service if the exploit is remote.
client.exploits_api.search(type: "shellcode")    # A category of exploit to search for.
client.exploits_api.search(osvdb: "100007")      # Open Source Vulnerability Database ID for the exploit.

Count

This method behaves identical to the Exploits API search method with the difference that it doesn't return any results.

client.exploits_api.count("python")             # Count python vulns.
client.exploits_api.count(port: 22)             # Port number for the affected service if the exploit is remote.
client.exploits_api.count(type: "shellcode")    # A category of exploit to search for.
client.exploits_api.count(osvdb: "100007")      # Open Source Vulnerability Database ID for the exploit.

License

The gem is available as open source under the terms of the MIT License.

More Repositories

1

doh

๐Ÿฉ DNS over HTTPS command-line client
Go
95
star
2

terraform-google-nomad

๐Ÿ“— Terraform Module for Nomad clusters with Consul on GCP
HCL
78
star
3

taint

๐Ÿšฐ Static taint analysis for Go programs.
Go
50
star
4

cube

๐Ÿˆฒ Chrome URL Blocking Extension
JavaScript
41
star
5

hunter

๐Ÿบ Command-line application and golang client library for hunter.io
Go
38
star
6

openai

๐Ÿค– Go package and CLI for OpenAI
Go
33
star
7

Violent-Ruby

๐ŸŽป Tools for Hackers, Forensic Analysts, Penetration Testers and Security Engineers.
Ruby
30
star
8

falconz

๐Ÿฆ… Falcon Malware Sandbox APIv2 Connector
Ruby
29
star
9

packetz

๐Ÿฆˆ Packet capturing library built with LibPcap
Crystal
24
star
10

whereisthis

๐ŸŒŽ A command-line application to help determine the location information from a given ip address or url.
Ruby
21
star
11

capra

๐Ÿ Intrusion Detection System
Ruby
17
star
12

iface

๐Ÿ•ถ Cross-platform network interface command-line utility.
Go
17
star
13

iptablez

๐Ÿฆ‘ A friendly Ruby API to iptables.
Ruby
16
star
14

nmap2json

๐Ÿ—บ Convert nmap XML output to beautiful JSON
Ruby
16
star
15

pcap-exporter

๐Ÿฆˆ Prometheus exporter for pcap metrics
Go
16
star
16

randomua

A command-line application to generate random user agent strings.
Ruby
15
star
17

remove-twitter-trends

A chrome extension to limit exposure to tailored trends on twitter.
CSS
15
star
18

isit

๐Ÿ’ซ The domain availability command-line uitlity.
Go
15
star
19

flareon

๐ŸฆŠA cloudflare DNS over HTTPs resolver client library.
Ruby
13
star
20

Picatz-Guides

An assortment of general guides I've currated for general teaching purposes focusing on red / blue team methodologies and tasks.
13
star
21

VIM-Locker

BASH + VIM = Cryptolocker
Shell
11
star
22

tfmr

๐Ÿ” Search CLI for the Terraform Module Registry
Go
10
star
23

homoglyphr

๐Ÿ“ฏ Confusing domain name character generator.
Go
10
star
24

ip2asn

๐Ÿค–IP address to autonomous system number (ASN)
Ruby
10
star
25

rsalint

๐Ÿ•ต๏ธโ€โ™€๏ธ@golang linter for the crypto/rsa package.
Go
10
star
26

is_available

Simply check if a domain has been registered ( or if it is resolvable ) to determine if it's available.
Ruby
10
star
27

mtls-proxy

๐Ÿ”’ mTLS Local Proxy
Go
9
star
28

chart_js

๐Ÿ“ˆ๐Ÿ“Š๐Ÿ“‰ A simple ruby DSL to build responsive charts for the web using Chart.js
Ruby
9
star
29

ocr

๐Ÿ‘ Ocular character recognition command-line utility.
Go
9
star
30

jose

๐Ÿ” JavaScript Object Signing and Encryption (JOSE)
Go
8
star
31

competition-practice-env

๐ŸŒฉ Cloud infrastructure-as-code for attack and defense CTFs on GCP
Go
8
star
32

Catnet

IPv4 TCP/UDP network connection monitor.
Ruby
8
star
33

nmapr

๐Ÿ—บ Your friendly neighborhood Ruby DSL to Nmap for network exploration.
Ruby
8
star
34

builderJS

๐Ÿ‘ท Simple, composable user interface builder.
JavaScript
8
star
35

roku

๐Ÿ‘พ Roku External Control API package for Golang
Go
8
star
36

terraform-google-vault

๐Ÿ”’ Terraform Module for Vault clusters on GCP
HCL
7
star
37

subzero

โ„๏ธ Research project for SubFinder core API V2
Go
7
star
38

snyk

๐Ÿ• Golang client library for Snyk
Go
7
star
39

CTF-Framework

A simple, configurable Capture the Flag web application framework.
Ruby
6
star
40

Evil-Clipboard

๐Ÿ“‹ An evil clipboard.
Ruby
6
star
41

tlds

๐ŸŒ Top-level domains made easy.
Go
6
star
42

suggest

๐Ÿƒ Simple google search suggestions.
Go
6
star
43

fauxy

๐ŸฆŠ
Go
6
star
44

pj

โœŒ๏ธConvert network packets to json from a file or a live interface.
Go
6
star
45

vifi

๐Ÿ“ถ A simple wifi signal strength monitoring application for macOS.
Ruby
5
star
46

picatz.github.io

My Website
Svelte
5
star
47

hook

๐Ÿงšโ€โ™€๏ธ Proxy WASM Filter SDK
Go
5
star
48

glint

โœจExtensible, declarative linter for golang!
Go
5
star
49

huntr

A simple reconnaissance command-line application.
Ruby
5
star
50

eth_watcher

๐Ÿ‘ A command-line application to monitor network packets for hardware addresses in ethernet headers.
Ruby
5
star
51

command_lion

๐Ÿฆ Command-line application framework.
Ruby
4
star
52

web

๐Ÿ•ธYour friendly neighborhood HTTP client and server for Go
Go
4
star
53

shodan.js

๐Ÿ”ฎ Asyncronous, vanillaJS library for Shodan
JavaScript
4
star
54

niji

๐ŸŒˆ Turn your network packets into a command-line rainbow.
Crystal
4
star
55

interfacez

๐Ÿ”ŒSimplified network interfaces API
Ruby
4
star
56

cloud-sdn-demo

๐ŸŒฉ Software Defined Networking on the Google Cloud Platform with Terraform
HCL
4
star
57

bilbo

A simple, hobbit-like network packet capturing gem.
Ruby
3
star
58

pcapz

โšก๏ธPure ruby network capture API
Ruby
3
star
59

GoEnumerator

A personal tool in GO for my usual first enumeration steps on a target
Go
3
star
60

Pi-Charts

A ruby gem to easily build beautiful charts using chartjs.
Ruby
3
star
61

logoris

Logoris a Ruby gem that provides a simple, unified interface to manage logging for command-line applications to the appropriate standard stream.
Ruby
3
star
62

goldengirl

โœจ All that shimmers is gold!
Go
3
star
63

b64

๐Ÿ‘พ base64 command-line utlity
Go
3
star
64

manuf

๐Ÿ“‡ Go package and CLI tool for listing OUIs.
Go
3
star
65

noface

An almost practical network interface tool.
Go
3
star
66

rshark

A ruby packet analysis tool.
HTML
3
star
67

backdoor

๐ŸšชPOC for backdooring golang's http.DefaultServeMux
Go
3
star
68

no-localhost

POC zoom localhost server vulnerability mitigation.
JavaScript
3
star
69

lion

CLI Application Framework for mitchellh/cli
Go
3
star
70

xbar-plugin-hashicorp-nomad

Shell
3
star
71

terraform-google-quakejs

Shell
3
star
72

cbor

๐ŸŒ€ Concise Binary Object Representation (CBOR)
Go
3
star
73

GrrCON-2018

๐Ÿค–Compliance as Code
Ruby
3
star
74

Honey-Cat

Honey Cat is a simple, easy-to-use honey pot that sets up what looks like is a service, but is really a honey pot on a user specified port. It is built with with BASH, Net Cat and a little bit of love. Lolcat support is also a thing because people need rainbows, obviously.
Shell
3
star
75

Flipr

A simple, configurable flip table / put table command-line application with optional rainbows.
Ruby
3
star
76

mtls

๐Ÿ”’mTLS server and client library
Go
3
star
77

fah

Folding@Home with Docker
Dockerfile
2
star
78

vulscan

Simple, customizable vulnerability scanner that speaks JSON.
Ruby
2
star
79

EMU_IASA_Web_App

A web application built for Eastern Michigan University's Information Assurance Student Association.
HTML
2
star
80

skynet

๐ŸŒฉ Cloud automation technology research group for cyber attack & defense competitions.
Shell
2
star
81

argz

๐Ÿ‰ Command-line application library for Crystal
Crystal
2
star
82

Vmstator

Vmstator is a Ruby API for vmstat to monitor system memory, processes, interrupts, paging and block I/O.
Ruby
2
star
83

fluentd-zeek-conf

๐Ÿฆ A fluentd config for zeek
2
star
84

Red-Honey-Cat

Red Honey Cat is a simple, easy to use honey pot written in Ruby.
Ruby
2
star
85

Honey-Pot

A simple, multithreaded honey pot written in ruby. With logging and rainbow options.
Ruby
2
star
86

hyper_thread

Hyper Thread is simple, flexible thread pool library for Ruby.
Ruby
2
star
87

One-Ring-Package-Manager

Yo', dog. I heard you like package managers. So I made a package manager for yo' package managers.
Ruby
2
star
88

go-fuzz-exporter

Go
2
star
89

pls

๐ŸŒผ Cross-platform process listing command-line application
Go
2
star
90

inspec-nomad

Chef InSpec profile for HashiCorp Nomad
Ruby
2
star
91

b32

โœˆ๏ธ base32 command-line utlity
Go
2
star
92

layup

๐Ÿงฑ Model anything as a graph.
Go
2
star
93

packet_genie

Magically streaming live packet captures with a simple REST API
Ruby
2
star
94

Trouble-In-Hoboken

Trouble in Hoboken is a vulnerable, open source Ruby web application built to assit in understanding how to exploit and create vulnerable web applications built ontop of the Sinatra DSL, Bootstrap, and MySQL.
HTML
2
star
95

Wordpress-AIOWPS-Firewall-Captcha-Cracker

Proof of concept to bypass the Wordpress plugin All In One WP Security & Firewall custom captcha system implemented on Wordpress login pages in hopes to prevent brute force attacks. Since html and base64 are easy to work with, we can just need to decode the answer.
Ruby
2
star
96

Rektcha

Rektcha is a simple captcha solving tool that analyzes a given image and solves the captcha.
Shell
1
star
97

pwnypot

A simple, multithreaded honeypot creation library for Ruby.
Ruby
1
star
98

promoted-twitter-remover

A chrome extension to limit exposure to promoted twitter content.
CSS
1
star
99

Ruby-Research-SQL-Security

SQL security class work for IA480 by building applications with Ruby.
HTML
1
star
100

flipz

Table flipping command-line utility.
Go
1
star