{"id":26140476,"url":"https://github.com/stavinski/showdown","last_synced_at":"2025-04-14T01:13:39.022Z","repository":{"id":69463864,"uuid":"469123424","full_name":"stavinski/showdown","owner":"stavinski","description":"Perform OSINT on external targets using Shodan","archived":false,"fork":false,"pushed_at":"2024-02-07T13:49:54.000Z","size":77,"stargazers_count":22,"open_issues_count":0,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-14T01:13:24.010Z","etag":null,"topics":["cybersecurity","osint","osint-python","osint-tool","security-tools"],"latest_commit_sha":null,"homepage":"","language":"Python","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/stavinski.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-03-12T15:33:53.000Z","updated_at":"2025-03-26T00:23:55.000Z","dependencies_parsed_at":"2023-02-22T23:31:25.568Z","dependency_job_id":null,"html_url":"https://github.com/stavinski/showdown","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stavinski%2Fshowdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stavinski%2Fshowdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stavinski%2Fshowdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stavinski%2Fshowdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stavinski","download_url":"https://codeload.github.com/stavinski/showdown/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248804825,"owners_count":21164135,"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":["cybersecurity","osint","osint-python","osint-tool","security-tools"],"created_at":"2025-03-11T02:53:47.855Z","updated_at":"2025-04-14T01:13:38.989Z","avatar_url":"https://github.com/stavinski.png","language":"Python","readme":"# SHOWDOWN\n\n  * [Summary](#summary)\n  * [Install](#install)\n  * [Screencast](#screencast)\n  * [Usage](#usage)\n  * [Docker](#docker)\n  * [Built-in Plugins](#built-in-plugins)\n  * [Developing a new Plugin](#developing-a-new-plugin)\n  * [FAQs](#faqs)\n  * [TODO](#todo)\n\n## Summary\n\nShowdown is a tool that utilises shodan in order to find targets of interest, it should be used at the start of an external test whilst other scans and enumeration are being performed, and allows for an efficient way of knowing which targets should be focused on initially.\n\nIt uses a plugin model and comes with built-in plugins to that should give good coverage on items such as vulnerabilities, SSL/TLS however if there are certain items not covered that you need then it's simple to write your own to cover these and better still send a PR to get it introduced to the built-in library!\n\n## Install\n\nI would ussually recommend setting up a venv environment to not clobber other libraries, this can be done by installing venv using your package manager (i.e. `sudo apt install python3-venv`).\n\nOnce this is done you can then clone the repo, setup venv and install the libraries from pip:\n\n~~~\ngit@github.com:stavinski/showdown.git\ncd showdown\npython3 -m venv .venv  # setup a venv environment in .venv dir\nsource .venv/bin/activate  # activate the venv, use deactivate to revert back\npip install -r requirements.txt\n~~~\n\nThis should allow you to now use the application, of course you could forgo using venv and just install the requirements globally.\n\n## Screencast\n\n[![Showdown in use](https://asciinema.org/a/482371.svg)](https://asciinema.org/a/482371)\n\n## Usage\n\n\n```\nusage: showdown.py [-h] [--key-file KEY_FILE] [--plugins PLUGIN [PLUGIN ...]] [--verbose] [--version] [--threads THREADS] [--list-plugins] [--formatter {console,csv}] [--output FILE]\n                   [--no-color] [--min-severity SEVERITY]\n                   {file,net} ...\n\n       \n███████╗██╗  ██╗ ██████╗ ██╗    ██╗██████╗  ██████╗ ██╗    ██╗███╗   ██╗\n██╔════╝██║  ██║██╔═══██╗██║    ██║██╔══██╗██╔═══██╗██║    ██║████╗  ██║\n███████╗███████║██║   ██║██║ █╗ ██║██║  ██║██║   ██║██║ █╗ ██║██╔██╗ ██║\n╚════██║██╔══██║██║   ██║██║███╗██║██║  ██║██║   ██║██║███╗██║██║╚██╗██║\n███████║██║  ██║╚██████╔╝╚███╔███╔╝██████╔╝╚██████╔╝╚███╔███╔╝██║ ╚████║\n╚══════╝╚═╝  ╚═╝ ╚═════╝  ╚══╝╚══╝ ╚═════╝  ╚═════╝  ╚══╝╚══╝ ╚═╝  ╚═══╝\n\n    1.0.0 Mike Nicholls\n    Pull back juicy info on external targets from shodan!\n\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --key-file KEY_FILE, -kf KEY_FILE\n                        Shodan API key file, if not provided then API key will be prompted for.\n  --plugins PLUGIN [PLUGIN ...], -p PLUGIN [PLUGIN ...]\n                        Plugins to run (defaults: info vulns ssl http shares).\n  --verbose, -v         Increase the logging verbosity.\n  --version, -V         show program's version number and exit\n  --threads THREADS, -t THREADS\n                        Number of threads to use for retrieving hosts (default: 10)\n  --list-plugins, -lp   Lists plugins available.\n  --formatter {console,csv}, -ft {console,csv}\n                        Formatter to use for output (default: console).\n  --output FILE, -o FILE\n                        Output file to use (default: stdout).\n  --no-color            Outputs to console with no color (default: False).\n  --min-severity SEVERITY\n                        Minimum severity to report on (default: INFO).\n\nInput mode:\n  {file,net}            Either from file or network address(es).\n```\n\nFind findings rated medium or above from hosts in file `hosts.txt`, use shodan key file `shodan.key`:\n\n~~~ sh\npython3 showdown.py --min-severity MEDIUM --key-file shodan.key file hosts.txt\n~~~\n\nFind SSL/TLS findings in network `103.71.205.0/24` and prompt for API key:\n\n~~~ sh\npython3 showdown.py --plugins ssl net 103.71.205.0/24\n~~~\n\n## Docker\n\nShowdown can be ran in a docker container either by pulling from the docker hub:\n\n~~~sh\ndocker pull stavinski/showdown\n~~~\n\nor cloning the repo and build the docker image:\n\n~~~sh\ngit@github.com:stavinski/showdown.git\ncd showdown\ndocker build -t showdown .\n~~~\n\nThe docker image can then be ran by providing the arguments as usual:\n\n~~~sh\ndocker run showdown --help\n~~~\n\nYou can also allow access to the host filesystem, for either providing the Shodan API key or for saving results by providing a volume:\n\n~~~sh\ndocker run --rm -v ~/scratch:/app showdown --output shodan.txt --key-file shodan.key net 114.32.236.74\n~~~\n\nThis will both pickup the `shodan.key` key file and save output to `~/scratch`.\n\n## Built-in Plugins\n\n* cloud\n* db\n* eol\n* files\n* http\n* info\n* ssh\n* ssl\n* vulns\n\n## Developing a new Plugin\n\n1. Create a new python file inside of the `plugins` directory (no spaces) this will act as the name so suggest a short name to convey what will be parsed such as `cloud.py`.\n2. Implement the required class structure, for example:\n\n```python\nfrom shared import AbstractPlugin, Severity, Finding\n\nclass Plugin(AbstractPlugin):\n\n    def process(self, host, output):\n        # populate using the output helper object, for example:\n        output.add_finding(Finding(\n                        'finding_key',\n                        val,\n                        'Summary',\n                        port,\n                        Severity.MEDIUM,\n                        proto\n                    ))\n        output.increase_score(50)\n\n    @property\n    def summary(self):\n        return 'Cloud details about the host'\n```\n3. That is all that is needed for the plugin to be registered with showdown.py. When you run the `--list-plugins` you should see the plugin has been added to the list.\n4. To use the plugin simply add it into the list of plugins, `python3 showdown.py --key-file shodan.key --plugins vulns cloud ...`\n\n## FAQs\n\n**Q. Why does it take a while to return results?**\n\n**A.** Shodan is rate limited to 1 request per second. Showdown does try to be as efficient as it can by utilising separate threads to make the request so that if a request is taking a while to respond it is not penalised by this delay. That being said it is still restricted to making calls once per second. Another option is batching IPs however this is only permitted on the Enterprise plan which I do not have so I cannot test against this approach.\n\n**Q. Can I run against a single host?**\n\n**A.** I mean you can using the `--network` argument and simply using a CIDR length of `/32` for example `--network 8.8.8.8/32` however this isn't really the intended purpose of the tool which was to cover a broad number of targets and help identify hosts to check first whilst waiting for other scans etc...\n\n\n## TODO\n\n- [X] List plugins\n- [X] Tidy up queueing and threading\n- [X] Add CSV output\n- [X] Common Data Structure for results\n- [X] Sorting hosts based off score\n- [X] Plugin: Cloud\n- [X] Plugin: SSL\n- [X] Minium severity argument\n- [X] Plugin: HTTP\n- [X] Wire up verbosity\n- [X] Docker support\n- [X] Plugin: Files\n- [X] Plugin: SSH\n- [X] Plugin: End of Life\n- [X] Plugin: DB\n- [ ] Plugin: Queues\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstavinski%2Fshowdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstavinski%2Fshowdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstavinski%2Fshowdown/lists"}