{"id":22479891,"url":"https://github.com/atshakil/portfinder","last_synced_at":"2025-09-05T02:46:05.598Z","repository":{"id":56888544,"uuid":"64749437","full_name":"atshakil/portfinder","owner":"atshakil","description":"Scan TCP ports using a pure Ruby scanner implementation","archived":false,"fork":false,"pushed_at":"2019-07-10T08:45:52.000Z","size":24,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-08-23T19:36:19.892Z","etag":null,"topics":["cli","port-scanner","ruby","ruby-cli","rubygems","utility"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/atshakil.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}},"created_at":"2016-08-02T10:56:53.000Z","updated_at":"2021-11-19T08:02:38.000Z","dependencies_parsed_at":"2022-08-20T16:00:15.187Z","dependency_job_id":null,"html_url":"https://github.com/atshakil/portfinder","commit_stats":null,"previous_names":["at-shakil/portfinder"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/atshakil/portfinder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atshakil%2Fportfinder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atshakil%2Fportfinder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atshakil%2Fportfinder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atshakil%2Fportfinder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/atshakil","download_url":"https://codeload.github.com/atshakil/portfinder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atshakil%2Fportfinder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273703616,"owners_count":25153000,"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","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cli","port-scanner","ruby","ruby-cli","rubygems","utility"],"created_at":"2024-12-06T15:17:49.070Z","updated_at":"2025-09-05T02:46:05.578Z","avatar_url":"https://github.com/atshakil.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Portfinder\n\n[![Build Status](https://travis-ci.org/atshakil/portfinder.svg?branch=master)](https://travis-ci.org/atshakil/portfinder)\n[![Gem Version](https://badge.fury.io/rb/portfinder.svg)](https://badge.fury.io/rb/portfinder)\n[![Test Coverage](https://codeclimate.com/github/atshakil/portfinder/badges/coverage.svg)](https://codeclimate.com/github/atshakil/portfinder/coverage)\n[![Inline docs](http://inch-ci.org/github/atshakil/portfinder.svg?branch=master)](http://inch-ci.org/github/atshakil/portfinder)\n[![Code Climate](https://codeclimate.com/github/atshakil/portfinder/badges/gpa.svg)](https://codeclimate.com/github/atshakil/portfinder)\n[![Issue Count](https://codeclimate.com/github/atshakil/portfinder/badges/issue_count.svg)](https://codeclimate.com/github/atshakil/portfinder)\n\n## Summary\n\nPortfinder is a ruby based port scanner with features like network/CIDR\nscanning, port randomization, hostname discovery and banner grabbing.\n\n## Installation\n\nPortfinder installation is as simple as a gem installation can get.\n\n```sh\ngem install portfinder\n```\n\n## Usage\n\n### As a CLI tool\n\n```sh\nportfinder \u003chost\u003e [--port=PORT] [--thread=THREAD] [--randomize]\n  [--out=OUT_FILE] [--verbose]\n```\n\n`portfinder` can also be invoked using it's aliased form `pf`.\n\nTo it's simplest form, single port of a host can be scanned.\n\n```sh\nportfinder 192.168.1.1 -p 80\n```\n\nIt is possible to scan multiple ports of a host. In this case, ports can be a\n*range*,\n\n```sh\nportfinder 192.168.1.1 -p 1-1024\n```\n\nOr, a list of *selections*:\n\n```sh\nportfinder 192.168.1.1 -p 22,80,8080,443\n```\n\nSimilarly, a scan can be performed on a selection of hosts,\n\n```sh\nportfinder 192.168.1.1,192.168.1.100,192.168.1.101 -p 1-65535\n```\n\nor, a range of hosts,\n\n```sh\nportfinder 192.168.1.1-10 -p 1-65535\n```\n\nor, on an entire network block, if you like.\n\n```sh\nportfinder 192.168.1.0/24 -p 1-65535\n```\n\nIf a large number of host needs to be scanned, you may choose to increase the\nnumber of concurrent scanners using the available `--thread` option.\n\n```sh\nportfinder 192.168.1.0/24 -p 1-65535 -t 20\n```\n\nBy default, ten scanner threads are spawned at max.\n\nWhen multiple ports are being scanned, they get scanned in the ascending order,\nor in the provided port selection order. If a randomized scan order is expected,\n`--randomize` flag can be utilized.\n\n```sh\nportfinder 192.168.1.0/24 -r\n```\n\n### As an API\n\nA minimal usage example,\n\n```ruby\nrequire \"portfinder\"\n\nscanner = Portfinder::Scanner.new(\"192.168.1.1\", [22, 80, 8080], threads = 5)\nscanner.scan\nputs \"\\nOpen ports detected: #{scanner.result[host]}\"\nputs \"Raw scan result: #{scanner.result}\"\nyml_stream = scanner.report_as \"yml\"\njson_stream = scanner.json_report\n```\n\nIt is possible to use the API in different modes,\n\n#### Mode 1: Blocking mode with monitoring\n\n```ruby\nscanner =\n  Portfinder::Scanner.new(\n    hosts, ports,\n    randomize: false, threaded: true, threads: 10, thread_for: :port\n  )\n\nscanner.log do |monitor|\n  puts \"Active threads:\\t#{monitor.threads}\\nScanning now:\\n\"\n  while true\n    print \"\\tHost:\\t#{monitor.host}\\tPort:\\t#{monitor.port}\\tStatus: #{\n      monitor.state}\\r\"\n    sleep 0.1\n  end\nend\n\nscanner.scan\nputs \"\\nScan complete!\\n\\nResult: #{scanner.generate_result}\"\n\nformat = \"json\"\nfile = open(\"export.#{format}\", \"wb\")\nfile.write scanner.report_as format.to_sym\nfile.close\n```\n\n#### Mode 2: Partial blocking (join during result invocation)\n\n```ruby\nscanner = Portfinder::Scanner.new(\"192.168.0.101\", 1..65535)\n#logger can be placed here...\n\nscanner.scan synchronus = false\n\n# logger can be placed here...\nputs \"\\nScan complete!\\n\\nResult: #{scanner.generate_result}\"\n```\n\n#### Mode 3 (GUI): Non-blocking (callback invocation upon completion)\n\n(NOTE: Parent thread must be alive to receive callback)\n\n```ruby\nscanner = Portfinder::Scanner.new(\"192.168.0.101\", 1..65535)\n\nscanner.scan(false) do\n  puts \"\\nScan complete!\\n\\nResult: #{scanner.generate_result}\"\nend\n\n# logger can be placed here...\n\nsleep 10\n```\n\nPlease note that the default scanner scans TCP ports using a full handshake\n(which is not, well..., stealthy. But, if you were expecting this feature, it's\ngonna be available on the TCP SYN scanner release).\n\nIt's also worth noting that, the current implementation doesn't check for host\nstatus (alive/dead). So, scan can be considerably slow for dead hosts.\n\n## Contributing\n\nIf you are interested in contributing, please [submit a pull request](https://help.github.com/articles/about-pull-requests/).\n\n## License\n\n[MIT](http://opensource.org/licenses/MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatshakil%2Fportfinder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatshakil%2Fportfinder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatshakil%2Fportfinder/lists"}