{"id":39608338,"url":"https://github.com/aminekun90/mdns_listener_advanced","last_synced_at":"2026-04-08T14:05:19.399Z","repository":{"id":44687127,"uuid":"146887853","full_name":"aminekun90/mdns_listener_advanced","owner":"aminekun90","description":"Simple mDNS Listener to publish and listen .local hostnames in your network compatible with zeroconf, bonjour, avahi you can also scan any mdns device present in the network","archived":false,"fork":false,"pushed_at":"2026-02-23T14:25:04.000Z","size":2165,"stargazers_count":5,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-23T22:24:59.402Z","etag":null,"topics":["avahi","mdns","multicast-dns","zeroconf"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/aminekun90.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":"Contributing.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":"audit-security.md","citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["aminekun90"],"custom":"https://www.paypal.com/paypalme/aminebouzahar"}},"created_at":"2018-08-31T12:16:51.000Z","updated_at":"2026-01-22T14:07:57.000Z","dependencies_parsed_at":"2025-12-17T19:00:10.444Z","dependency_job_id":null,"html_url":"https://github.com/aminekun90/mdns_listener_advanced","commit_stats":{"total_commits":76,"total_committers":5,"mean_commits":15.2,"dds":0.618421052631579,"last_synced_commit":"403064ca53ca6a6fc13fe298ca9f7c58172065fe"},"previous_names":[],"tags_count":78,"template":false,"template_full_name":null,"purl":"pkg:github/aminekun90/mdns_listener_advanced","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aminekun90%2Fmdns_listener_advanced","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aminekun90%2Fmdns_listener_advanced/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aminekun90%2Fmdns_listener_advanced/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aminekun90%2Fmdns_listener_advanced/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aminekun90","download_url":"https://codeload.github.com/aminekun90/mdns_listener_advanced/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aminekun90%2Fmdns_listener_advanced/sbom","scorecard":{"id":189465,"data":{"date":"2025-08-11","repo":{"name":"github.com/aminekun90/mdns_listener_advanced","commit":"c1233b93e5cda97dc01e75591a38bde08a4b2134"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.8,"checks":[{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Code-Review","score":0,"reason":"Found 0/6 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: SECURITY.md:1","Info: Found linked content: SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: SECURITY.md:1","Info: Found text in security policy: SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/publish.yml:1","Warn: no topLevel permission defined: .github/workflows/test.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/aminekun90/mdns_listener_advanced/publish.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/publish.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/aminekun90/mdns_listener_advanced/publish.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:28: update your workflow using https://app.stepsecurity.io/secureworkflow/aminekun90/mdns_listener_advanced/publish.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:30: update your workflow using https://app.stepsecurity.io/secureworkflow/aminekun90/mdns_listener_advanced/publish.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:44: update your workflow using https://app.stepsecurity.io/secureworkflow/aminekun90/mdns_listener_advanced/publish.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:34: update your workflow using https://app.stepsecurity.io/secureworkflow/aminekun90/mdns_listener_advanced/test.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:36: update your workflow using https://app.stepsecurity.io/secureworkflow/aminekun90/mdns_listener_advanced/test.yml/master?enable=pin","Warn: npmCommand not pinned by hash: .github/workflows/publish.yml:37","Info:   0 out of   6 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   1 third-party GitHubAction dependencies pinned","Info:   0 out of   1 npmCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Packaging","score":10,"reason":"packaging workflow detected","details":["Info: Project packages its releases by way of GitHub Actions.: .github/workflows/publish.yml:25"],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":7,"reason":"SAST tool is not run on all commits -- score normalized to 7","details":["Warn: 22 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":5,"reason":"5 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8","Warn: Project is vulnerable to: GHSA-7q7g-4xm8-89cq","Warn: Project is vulnerable to: GHSA-xffm-g5w8-qvg7","Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw","Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-16T20:21:37.832Z","repository_id":44687127,"created_at":"2025-08-16T20:21:37.832Z","updated_at":"2025-08-16T20:21:37.832Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30377843,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T06:09:32.197Z","status":"ssl_error","status_checked_at":"2026-03-11T06:09:17.086Z","response_time":84,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["avahi","mdns","multicast-dns","zeroconf"],"created_at":"2026-01-18T08:01:58.848Z","updated_at":"2026-04-08T14:05:19.394Z","avatar_url":"https://github.com/aminekun90.png","language":"TypeScript","funding_links":["https://github.com/sponsors/aminekun90","https://www.paypal.com/paypalme/aminebouzahar"],"categories":[],"sub_categories":[],"readme":"# mDNS Listener Advanced\n\n[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/aminekun90/mdns_listener_advanced/graphs/commit-activity) [![version number](https://img.shields.io/npm/v/mdns-listener-advanced?color=green\u0026label=version)](https://github.com/aminekun90/mdns_listener_advanced/releases) [![Actions Status](https://github.com/aminekun90/mdns_listener_advanced/workflows/Test/badge.svg)](https://github.com/aminekun90/mdns_listener_advanced/actions) [![License](https://img.shields.io/github/license/aminekun90/mdns_listener_advanced)](https://github.com/aminekun90/mdns_listener_advanced/blob/master/LICENSE) ![node-current](https://img.shields.io/node/v/mdns-listener-advanced)[![Socket Badge](https://socket.dev/api/badge/npm/package/mdns-listener-advanced)](https://socket.dev/npm/package/mdns-listener-advanced) [![NPM](https://img.shields.io/badge/NPM-%23CB3837.svg?style=for-the-badge\u0026logo=npm\u0026logoColor=white)](https://www.npmjs.com/package/mdns-listener-advanced)\n\n\u003e **🚀 Major Update v3.4.0+**: This package has been re-architected to be **Zero-Dependency**. It now uses native Node.js modules (`dgram`, `crypto`) for maximum performance, security, and compatibility. No more heavy dependencies like `bonjour-service` or `multicast-dns`.\n\n**mDNS Listener Advanced** is a robust, cross-platform Node.js library for Multicast DNS (mDNS) operations. It allows you to:\n\n1. **Listen** for specific `.local` hostnames.\n2. **Publish** your own device/service to the network.\n3. **Scan/Discover** all devices and services on the network (Service Discovery).\n\nCompatible with mdns, Avahi, Bonjour, and Zeroconf.\n\n## Requirements\n\n- **Node.js:** v22 or later (Recommended).\n- **OS:** Fully tested on Windows 11, Ubuntu 20.04+, and macOS (Sonoma/Sequoia/Tahoe).\n- Not tested on Docker containers.\n- This library need to access the local network to work properly.\n\n## Installation\n\n```bash\nnpm install mdns-listener-advanced\n# or preferred way\nyarn add mdns-listener-advanced\n```\n\n## Features\n\n- 📦 Zero Dependencies: Lightweight and secure.\n- 🔍 Targeted Listening: Detect specific devices by name (e.g., MyDevice.local).\n- 📡 Service Discovery: Scan the network for all services (e.g., Google Cast, Printers).\n- 📢 Native Publisher: Announce your presence without external tools.\n- 🛡️ TypeScript: Written in TypeScript with full type definitions included.\n\n## Usage Examples\n\n### 1. Basic Listener (JavaScript)\n\nListen for specific devices defined in your constructor or hosts file.\n\n```javascript\nimport Core, { EmittedEvent } from \"mdns-listener-advanced\";\n\n// Look for a device named \"MyDevice2\"\nconst mdns = new Core([\"MyDevice2\"], null, {\n  debug: false\n});\n\nconst event = mdns.listen();\n\n// 1. Handle targeted response\nevent.on(EmittedEvent.RESPONSE, (found_hostnames) =\u003e {\n  console.log(\"✅ Found Target:\", found_hostnames);\n  // mdns.stop(); // Stop listening if needed\n});\n\n// 2. Handle errors\nevent.on(EmittedEvent.ERROR, (error) =\u003e {\n  console.error(\"❌ Error:\", error);\n});\n```\n\n### 2. Service Discovery / Scanning (TypeScript)\n\nNew in v3.4.0: actively query the network to find devices (Printers, Chromecast, HomeKit, etc.).\n\n```typescript\nimport { Core, EmittedEvent, Device } from 'mdns-listener-advanced';\n// or import Core,{ EmittedEvent, Device } from 'mdns-listener-advanced';\n\nconst mdns = new Core();\nconst event = mdns.listen();\n\nevent.on(EmittedEvent.DISCOVERY, (device: Device) =\u003e {\n  console.log(`🔎 Discovered [${device.type}]:`, device.name, device.data);\n});\n\n// Scan for Google Cast devices\nmdns.scan(\"_googlecast._tcp.local\");\n\n// OR Scan for EVERYTHING\n// mdns.scan(\"_services._dns-sd._udp.local\");\n```\n\n### 3. Publishing a Host\n\nAnnounce your service to the network.\n\n```javascript\nimport { Core } from \"mdns-listener-advanced\";\n// or import Core,{ EmittedEvent, Device } from 'mdns-listener-advanced';\n\nconst mdns = new Core();\n\n// Publish \"MyCoolService.local\"\nconst customData = { hello: \"world\" };\nmdns.publish(\"MyCoolService\",customData, 30000); // 30000 ms = 30 seconds by default\n\n// Your device is now visible to other mDNS scanners!\n\n// // 2. Start Listener\nconst event = mdns.listen();\n\n// // --- HANDLERS ---\n\nevent.on(EmittedEvent.RESPONSE, (found_hostnames: Device[]) =\u003e {\n  mdns.info(\"✅ Found TARGETED Host:\", found_hostnames);\n});\n// stop\n```\n\noutput:\n\n```shell\n[MDNS ADVANCED] INFO: ✅ Found TARGETED Host: [\n  {\n    name: 'MyDevice2',\n    type: 'TXT',\n    data: {\n      uuid: '\"eec91263-de12-4525-ba08-81adad17-ceb3\"',\n      ipv4: '\"192.168.1.102\"',\n      hello: 'world'\n    }\n  }\n]\n```\n\n### 4. Run the provided example\n\nClone the repository and run the following command:\n\n```bash\n# optional install (no dependencies required to run the example)\n# yarn install\nyarn start\n```\n\n## API Documentation\n\nClass: `Core`\n\n### Constructor\n\n```typescript\n// All args are optional\nnew Core(hostsList, mdnsHostsPath, options, logger)\n```\n\n| Parameter     | Type     | Description                                                                               |\n|---------------|----------|-------------------------------------------------------------------------------------------|\n| hostsList     | string[] | Optional array of hostnames to listen for (e.g. ['device1']).                             |\n| mdnsHostsPath | string   | Optional absolute path to a custom hosts file.                                            |\n| options       | Options  | \"Config object: { debug: boolean, disableListener: boolean, disablePublisher: boolean }.\" |\n| logger        | any      | \"Custom logger instance (must have .info, .debug, .warn, .error).\"                        |\n\n### Methods\n\n| Method                       | Description                                                                                                                                                |\n|------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| listen(ref)                  | Starts the UDP socket and joins the Multicast group. Returns the EventEmitter, you can provide a string to listen for a specific host check example.ts.    |\n| publish(name,data, interval) | \"Broadcasts an mDNS response, announcing name.local with your IP address. add data to the TXT record, personalize the interval by default set to 30000ms.\" |\n| scan(serviceType)            | (New) Sends a query to the network. Default serviceType is _services._dns-sd._udp.local.                                                                   |\n| stop()                       | Closes the socket and removes all event listeners.                                                                                                         |\n\n### Events (EmittedEvent)\n\n| Event Name         | Enum                      | Payload Type | Description                                                    |\n|--------------------|---------------------------|--------------|----------------------------------------------------------------|\n| \"\"\"response\"\"\"     | EmittedEvent.RESPONSE     | Device[]     | Fired when a Targeted Host (from your list) is found.          |\n| \"\"\"discovery\"\"\"    | EmittedEvent.DISCOVERY    | Device       | \"Fired when scan() finds ANY device (PTR, SRV, or A records).\" |\n| \"\"\"raw_response\"\"\" | EmittedEvent.RAW_RESPONSE | object       | The full raw packet structure (advanced debugging).            |\n| \"\"\"error\"\"\"        | EmittedEvent.ERROR        | Error        | Fired on socket errors or configuration issues.                |\n\n---\n\n### Configuration Files\n\nYou can optionally use a file to manage the list of devices you want to detect (Targeted Listening).\n\nLocation:\n\n- Windows: `C:\\Users\\\u003cusername\u003e\\.mdns-hosts`\n- Linux/macOS: `~/.mdns-hosts`\n\n```plaintext\nLivingRoomTV\nOfficePrinter\nRaspberryPi\n```\n\nIf you do not provide a constructor list or this file, the listener will warn you but still function (useful if you only want to use scan() or publish())\n\n---\n\n### Troubleshooting\n\n- Firewall: mDNS uses UDP port 5353. Ensure your firewall allows traffic on this port.\n- Docker: If running in Docker, you must use network_mode: \"host\" so the container can receive Multicast packets from the physical network.\n- Windows: You might need to allow Node.js through the Windows Defender Firewall on the first run.\n- macOS + Docker limitations : running docker in host mode might not work on macOS, since the container is not able to access the host network.\n\n## Support \u0026 Contribution\n\nIssues: [Open an issue here](https://github.com/aminekun90/mdns_listener_advanced/issues)\nContact: [Connect on LinkedIn](https://www.linkedin.com/in/amine-bouzahar/)\n\n### If you appreciate mdns-listener-advanced, consider supporting the project. :coffee:\n\nI dedicate time and effort on writing and maintaining this library since 2017 and I'm grateful for your support.\n\nIf this library saved you time, consider Donating!\n\n[![PayPal](https://img.shields.io/badge/PayPal-00457C?style=for-the-badge\u0026logo=paypal\u0026logoColor=white)](https://www.paypal.com/paypalme/aminebouzahar)\n\n---\n\nOriginal Credit: Based on concepts from @Richie765, now fully rewritten for modern Node.js and TypeScript.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faminekun90%2Fmdns_listener_advanced","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faminekun90%2Fmdns_listener_advanced","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faminekun90%2Fmdns_listener_advanced/lists"}