{"id":21204380,"url":"https://github.com/acidvegas/ptrstream","last_synced_at":"2025-07-10T08:31:18.656Z","repository":{"id":208789331,"uuid":"722465380","full_name":"acidvegas/ptrstream","owner":"acidvegas","description":"endless stream of rdns","archived":false,"fork":false,"pushed_at":"2023-12-02T00:41:59.000Z","size":3134,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-05-21T00:59:07.764Z","etag":null,"topics":["dns","dns-record","mass-dns","ptr","rdns"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/acidvegas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-11-23T07:58:06.000Z","updated_at":"2024-03-10T12:41:26.000Z","dependencies_parsed_at":"2023-12-02T01:27:00.921Z","dependency_job_id":"fb3be1f1-ac85-4ee5-86e4-cf75f340048f","html_url":"https://github.com/acidvegas/ptrstream","commit_stats":null,"previous_names":["acidvegas/ptrstream"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acidvegas%2Fptrstream","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acidvegas%2Fptrstream/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acidvegas%2Fptrstream/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acidvegas%2Fptrstream/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acidvegas","download_url":"https://codeload.github.com/acidvegas/ptrstream/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225627481,"owners_count":17498994,"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":["dns","dns-record","mass-dns","ptr","rdns"],"created_at":"2024-11-20T20:32:09.978Z","updated_at":"2025-07-10T08:31:18.651Z","avatar_url":"https://github.com/acidvegas.png","language":"Python","funding_links":[],"categories":["\u003ca name=\"monitor\"\u003e\u003c/a\u003eSystem monitoring"],"sub_categories":[],"readme":"# PTRStream\n\u003e High-performance distributed PTR record scanner with real-time streaming output\n\n![](./.screens/preview.gif)\n\nPTRStream is a fast and efficient PTR record scanner designed for distributed scanning operations. It uses a Linear Congruential Generator *(LCG)* for deterministic IP generation, allowing for easy distribution of work across multiple machines while maintaining pseudo-random ordering.\n\n## Features\n\n- Memory-efficient IP range processing using [GoLCG](https://github.com/acidvegas/golcg)\n- Distributed scanning support via sharding\n- Real-time NDJSON output for streaming to data pipelines\n- Support for both PTR and CNAME records\n- Automatic DNS server rotation from public resolvers\n- Progress tracking with detailed statistics\n- Colorized terminal output\n- CAIDA-style error formatting (with -debug flag)\n\n## Installation\n\n```bash\ngo install github.com/acidvegas/ptrstream@latest\n```\n\n## Options\n| Flag     | Type     | Default | Description                                |\n|----------|----------|---------|--------------------------------------------|\n| `-c`     | `int`    | `100`   | Concurrency level                          |\n| `-debug` | `bool`   | `false` | Show unsuccessful lookups                  |\n| `-dns`   | `string` |         | File containing DNS servers                |\n| `-j`     | `bool`   | `false` | Output NDJSON to stdout (no TUI)          |\n| `-l`     | `bool`   | `false` | Loop continuously after completion         |\n| `-o`     | `string` |         | Path to NDJSON output file                 |\n| `-r`     | `int`    | `2`     | Number of retries for failed lookups       |\n| `-s`     | `int`    | `0`     | Seed for IP generation *(0 for random)*    |\n| `-shard` | `string` |         | Shard specification *(index/total format)* |\n| `-t`     | `int`    | `2`     | Timeout for DNS queries                    |\n\n## Usage\n\n```bash\n# Basic usage\nptrstream -o output.json\n\n# Use specific DNS servers\nptrstream -dns resolvers.txt -o output.json\n\n# Increase concurrency\nptrstream -c 200 -o output.json\n\n# Distributed scanning (4 machines)\n# Machine 1:\nptrstream -shard 1/4 -s 12345 -o shard1.json\n# Machine 2:\nptrstream -shard 2/4 -s 12345 -o shard2.json\n# Machine 3:\nptrstream -shard 3/4 -s 12345 -o shard3.json\n# Machine 4:\nptrstream -shard 4/4 -s 12345 -o shard4.json\n```\n\n## Distributed Scanning\n\nPTRStream supports distributed scanning through its sharding system. By using the same seed value across multiple instances with different shard specifications, you can distribute the workload across multiple machines while ensuring:\n\n- No IP address is scanned twice\n- Even distribution of work\n- Deterministic results\n- Pseudo-random scanning patterns\n\nFor example, to split the work across 4 machines:\n```bash\n# Each machine uses the same seed but different shard\nptrstream -shard 1/4 -s 12345  # Machine 1\nptrstream -shard 2/4 -s 12345  # Machine 2\nptrstream -shard 3/4 -s 12345  # Machine 3\nptrstream -shard 4/4 -s 12345  # Machine 4\n```\n\n## Real-time Data Pipeline Integration\n\nPTRStream outputs NDJSON *(Newline Delimited JSON)* format, making it perfect for real-time data pipeline integration. Each line contains a complete JSON record with:\n\n- Timestamp\n- IP Address\n- DNS Server used\n- Record Type *(PTR/CNAME)*\n- PTR Record\n- CNAME Target *(if applicable)*\n- TTL Value\n\nExample using named pipe to Elasticsearch:\n```bash\n# Create a named pipe\nmkfifo /tmp/ptrstream\n\n# Start Elasticsearch ingestion in background\ncat /tmp/ptrstream | elasticsearch-bulk-import \u0026\n\n# Run PTRStream with pipe output\nptrstream -o /tmp/ptrstream\n```\n\n## CNAME Support\n\nPTRStream properly handles CNAME records in PTR responses, providing:\n- Detection of CNAME chains\n- Original hostname and target tracking\n- TTL values for both record types\n- Distinct coloring in terminal output\n- CNAME statistics tracking\n\nExample NDJSON output:\n```json\n{\"timestamp\":\"2024-01-05T12:34:56Z\",\"ip_addr\":\"1.2.3.4\",\"dns_server\":\"8.8.8.8\",\"ptr_record\":\"example.com\",\"record_type\":\"PTR\",\"ttl\":3600}\n{\"timestamp\":\"2024-01-05T12:34:57Z\",\"ip_addr\":\"5.6.7.8\",\"dns_server\":\"1.1.1.1\",\"ptr_record\":\"original.com\",\"record_type\":\"CNAME\",\"target\":\"target.com\",\"ttl\":600}\n```\n\n## Debug Mode\n\nWhen running with `-debug`, failed lookups are displayed and logged using CAIDA-style error formatting. Each error is represented as a special `.in-addr.arpa` address:\n\n```\n2024-01-05 12:34:56 │ 1.2.3.4     │ 8.8.8.8        │  ERR  │        │ FAIL.TIMEOUT.in-addr.arpa\n2024-01-05 12:34:57 │ 5.6.7.8     │ 1.1.1.1        │  ERR  │        │ FAIL.SERVER-FAILURE.in-addr.arpa\n2024-01-05 12:34:58 │ 9.10.11.12  │ 8.8.4.4        │  ERR  │        │ FAIL.NON-AUTHORITATIVE.in-addr.arpa\n```\n\nError types include:\n- `FAIL.TIMEOUT.in-addr.arpa` - DNS query timed out\n- `FAIL.SERVER-FAILURE.in-addr.arpa` - DNS server returned an error\n- `FAIL.NON-AUTHORITATIVE.in-addr.arpa` - No authoritative answer\n- `FAIL.REFUSED.in-addr.arpa` - Query was refused\n- `FAIL.NO-PTR-RECORD.in-addr.arpa` - No PTR record exists\n- And more...\n\nThese errors are also included in the NDJSON output when using `-debug` with either `-o` or `-j`:\n```json\n{\"seen\":\"2024-01-05T12:34:56Z\",\"ip\":\"1.2.3.4\",\"nameserver\":\"8.8.8.8\",\"record\":\"FAIL.TIMEOUT.in-addr.arpa\",\"record_type\":\"ERR\",\"ttl\":0}\n```\n\n___\n\n###### Mirrors: [acid.vegas](https://git.acid.vegas/ptrstream) • [SuperNETs](https://git.supernets.org/acidvegas/ptrstream) • [GitHub](https://github.com/acidvegas/ptrstream) • [GitLab](https://gitlab.com/acidvegas/ptrstream) • [Codeberg](https://codeberg.org/acidvegas/ptrstream)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facidvegas%2Fptrstream","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facidvegas%2Fptrstream","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facidvegas%2Fptrstream/lists"}