{"id":13539733,"url":"https://github.com/zmap/zgrab2","last_synced_at":"2025-05-13T19:03:03.142Z","repository":{"id":37663288,"uuid":"66118002","full_name":"zmap/zgrab2","owner":"zmap","description":"Fast Application Layer Scanner","archived":false,"fork":false,"pushed_at":"2025-05-12T23:38:17.000Z","size":15636,"stargazers_count":1869,"open_issues_count":35,"forks_count":322,"subscribers_count":47,"default_branch":"master","last_synced_at":"2025-05-13T00:28:22.750Z","etag":null,"topics":["internet-scanning","network-scanner"],"latest_commit_sha":null,"homepage":"","language":"Go","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/zmap.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,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-08-19T23:22:02.000Z","updated_at":"2025-05-13T00:22:44.000Z","dependencies_parsed_at":"2023-01-25T16:01:19.252Z","dependency_job_id":"5a1e61ac-3ddc-4ba6-b454-c92d2d7b536f","html_url":"https://github.com/zmap/zgrab2","commit_stats":{"total_commits":542,"total_committers":70,"mean_commits":7.742857142857143,"dds":0.6180811808118081,"last_synced_commit":"82b0038c0494ccb46b2ea76a5dec94aff99be587"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zmap%2Fzgrab2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zmap%2Fzgrab2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zmap%2Fzgrab2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zmap%2Fzgrab2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zmap","download_url":"https://codeload.github.com/zmap/zgrab2/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254010792,"owners_count":21998993,"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":["internet-scanning","network-scanner"],"created_at":"2024-08-01T09:01:31.069Z","updated_at":"2025-05-13T19:03:03.116Z","avatar_url":"https://github.com/zmap.png","language":"Go","funding_links":[],"categories":["\u003ca id=\"8f92ead9997a4b68d06a9acf9b01ef63\"\u003e\u003c/a\u003e扫描器\u0026\u0026安全扫描\u0026\u0026App扫描\u0026\u0026漏洞扫描","Go","Go (531)","\u003ca id=\"132036452bfacf61471e3ea0b7bf7a55\"\u003e\u003c/a\u003e工具"],"sub_categories":["\u003ca id=\"de63a029bda6a7e429af272f291bb769\"\u003e\u003c/a\u003e未分类-Scanner"],"readme":"ZGrab 2.0\n=========\n\nZGrab is a fast, modular application-layer network scanner designed for completing large Internet-wide surveys. ZGrab is built to work with ZMap (ZMap identifies L4 responsive hosts, ZGrab performs in-depth, follow-up L7 handshakes). Unlike many other network scanners, ZGrab outputs detailed transcripts of network handshakes (e.g., all messages exchanged in a TLS handshake) for offline analysis.  \n\nZGrab 2.0 contains a new, modular ZGrab framework, which fully supersedes https://github.com/zmap/zgrab.\n\n## Installation\n\n### With Docker\n\nYou can run ZGrab 2.0 with our official Docker image. For example, to scan a single website using the HTTP module, you can use:\n\n```shell\necho 'example.com' | docker run --rm -i ghcr.io/zmap/zgrab2 http\n```\n\nFor more complex scanning scenarios, such as using multiple modules or custom configurations, you can create a configuration file and pass it to the container:\n\n```shell\ndocker run --rm -i -v /path/to/your/config.ini:/config.ini ghcr.io/zmap/zgrab2 multiple -c /config.ini\n```\n\nReplace `/path/to/your/config.ini` with the path to your configuration file on the host machine. See [Multiple Module Usage](#multiple-module-usage) for more details on configurations.\n\n### Building from Source\n\nZGrab2 requires Go 1.23 or later to build from source.\n\n```shell\ngit clone https://github.com/zmap/zgrab2.git\ncd zgrab2\nmake\n./zgrab2 http --help # to see the http module's help message\n```\n\nStarting in Go 1.21, Go added [support](https://go.dev/doc/toolchain) for auto-downloading the appropriate toolchain for building a given module.\n\nThis will let you build ZGrab2 using Go 1.21.X or 1.22.X without needing to manually install another version.\n\n```shell\ngo version\n$ go version go1.21.13 linux/arm64\n\nexport GOTOOLCHAIN=auto\ngit clone https://github.com/zmap/zgrab2.git\ncd zgrab2\nmake # Go will download the required 1.23 toolchain automatically\n./zgrab2 http --help # to see the http module's help message\n```\n\n## Single Module Usage \n\nZGrab2 supports modules. For example, to run the ssh module use\n\n```shell\n./zgrab2 ssh\n```\n\nTo retrieve detailed command-line usage and options for a specific module, append `-h` to the command:\n\n```bash\n./zgrab2 [module] -h\n```\n\nThis will display the module-specific options, as well as the application-wide options, including usage examples, available flags, and descriptions for each option. \n\nModule specific options must be included after the module. Application specific options can be specified at any time.\n\n## Input Format\n\nTargets are specified with input files or from `stdin`, in CSV format.  Each input line has up to four fields:\n\n```text\nIP, DOMAIN, TAG, PORT\n```\n\nEach line must specify `IP`, `DOMAIN`, or both.  If only `DOMAIN` is provided, scanners perform a DNS hostname lookup to determine the IP address.  If both `IP` and `DOMAIN` are provided, scanners connect to `IP` but use `DOMAIN` in protocol-specific contexts, such as the HTTP HOST header and TLS SNI extension.\n\nIf the `IP` field contains a CIDR block, the framework will expand it to one target for each IP address in the block.\n\nThe `TAG` field is optional and used with the `--trigger` scanner argument. The `PORT` field is also optional, and acts\nas a per-line override for the `-p`/`--port` option.\n\nUnused fields can be blank, and trailing unused fields can be omitted entirely.  For backwards compatibility, the parser allows lines with only one field to contain `DOMAIN`.\n\nThese are examples of valid input lines:\n\n```text\n10.0.0.1\ndomain.com\n10.0.0.1, domain.com\n10.0.0.1, domain.com, tag\n10.0.0.1, domain.com, tag, 1234\n10.0.0.1, , tag\n10.0.0.1, , , 5678\n, domain.com, tag\n192.168.0.0/24, , tag\n```\n\nAnd an example of calling zgrab2 with input:\n\n```shell\necho \"en.wikipedia.org\" | ./zgrab2 http --max-redirects=1 --endpoint=\"/wiki/New_York_City\"\n```\n\n## Multiple Module Usage\n\nTo run a scan with multiple modules, a `.ini` file must be used with the `multiple` module. Below is an example `.ini` file with the corresponding zgrab2 command. \n\n***multiple.ini***\n```ini\n[Application Options]\noutput-file=\"output.txt\"\ninput-file=\"input.txt\"\n[http]\nname=\"http80\"\nport=80\nendpoint=\"/\"\n[http]\nname=\"http8080\"\nport=8080\nendpoint=\"/\"\n[ssh]\nport=22\n```\n```shell\n./zgrab2 multiple -c multiple.ini\n```\n`Application Options` must be the initial section name. Other section names should correspond exactly to the relevant zgrab2 module name. The default name for each module is the command name. If the same module is to be used multiple times then `name` must be specified and unique. \n\nMultiple module support is particularly powerful when combined with input tags and the `--trigger` scanner argument. For example, this input contains targets with two different tags:\n\n```text\n141.212.113.199, , tagA\n216.239.38.21, censys.io, tagB\n```\n\nInvoking zgrab2 with the following `multiple` configuration will perform an SSH grab on the first target above and an HTTP grab on the second target:\n\n```ini\n[ssh]\ntrigger=\"tagA\"\nname=\"ssh22\"\nport=22\n\n[http]\ntrigger=\"tagB\"\nname=\"http80\"\nport=80\n```\n\n## Adding New Protocols \n\nAdd module to modules/ that satisfies the following interfaces: `Scanner`, `ScanModule`, `ScanFlags`.\n\nThe flags struct must embed zgrab2.BaseFlags. In the modules `init()` function the following must be included. \n\n```go\nfunc init() {\n    var newModule NewModule\n    _, err := zgrab2.AddCommand(\"module\", \"short description\", \"long description of module\", portNumber, \u0026newModule)\n    if err != nil {\n        log.Fatal(err)\n    }\n}\n```\n\n### Output schema\n\nTo add a schema for the new module, add a module under schemas, and update [`zgrab2_schemas/zgrab2/__init__.py`](zgrab2_schemas/zgrab2/__init__.py) to ensure that it is loaded.\n\nSee [zgrab2_schemas/README.md](zgrab2_schemas/README.md) for details.\n\n### Integration tests\nTo add integration tests for the new module, you'll need to add a test service to scan against to `integration_tests/docker-compose.yml` and a `test.sh` in a folder named after your module.\nFollow the examples in `integration_tests/.template` to create the necessary files.\nSee [integration_tests/mysql/*](integration_tests/mysql) for an example.\nThe only hard requirement is that the `test.sh` script drops its output in `$ZGRAB_OUTPUT/[your-module]/*.json`, so that it can be validated against the schema.\n\n#### How to Run Integration Tests\n\nTo run integration tests, you must have [Docker](https://www.docker.com/) and **Python 3** on host installed. Then, you can follow the following steps to run integration tests:\n\n```shell\n# Install Python dependencies\nsudo apt update\nsudo apt install -y python3 jp python3-pip\npython3 -m venv venv\nsource venv/bin/activate\n# Install Python dependencies\npip install zschema\npip install -r requirements.txt\nmake integration-test-clean; make integration-test\n```\n\nRunning the integration tests will generate quite a bit of debug output. To ensure that tests completed successfully, you can check for a successful exit code after the tests complete:\n\n```shell\necho $?\n0\n```\n\nTo just run a single/few module's integration tests, you can use the `TEST_MODULES` env. var.:\n\n```shell\nmake integration-test-clean; TEST_MODULES=\"http\" make integration-test\nmake integration-test-clean; TEST_MODULES=\"http ssh\" make integration-test\n```\n\nRefer to our [Github Actions workflow](.github/workflows/integration-test.yml) for an example of how to prepare environment for integration tests.\n\n## License\nZGrab2.0 is licensed under Apache 2.0 and ISC. For more information, see the LICENSE file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzmap%2Fzgrab2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzmap%2Fzgrab2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzmap%2Fzgrab2/lists"}