{"id":29406357,"url":"https://github.com/adyavanapalli/mdnslistener","last_synced_at":"2026-05-16T11:02:46.098Z","repository":{"id":302776706,"uuid":"1013547537","full_name":"adyavanapalli/MdnsListener","owner":"adyavanapalli","description":"A high-performance, production-ready multicast DNS (mDNS) listener built with .NET, designed to discover and monitor services on the local network using the mDNS protocol (RFC 6762).","archived":false,"fork":false,"pushed_at":"2025-07-04T06:42:20.000Z","size":1969,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-04T07:29:09.309Z","etag":null,"topics":["cross-platform","csharp","dns","dotnet","home-automation","iot","mdns","monitoring","multicast-dns","network-discovery","network-tools","service-discovery","zeroconf"],"latest_commit_sha":null,"homepage":"","language":"C#","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/adyavanapalli.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":"2025-07-04T04:54:35.000Z","updated_at":"2025-07-04T06:42:23.000Z","dependencies_parsed_at":"2025-07-04T07:39:55.556Z","dependency_job_id":null,"html_url":"https://github.com/adyavanapalli/MdnsListener","commit_stats":null,"previous_names":["adyavanapalli/mdnslistener"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/adyavanapalli/MdnsListener","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adyavanapalli%2FMdnsListener","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adyavanapalli%2FMdnsListener/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adyavanapalli%2FMdnsListener/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adyavanapalli%2FMdnsListener/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adyavanapalli","download_url":"https://codeload.github.com/adyavanapalli/MdnsListener/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adyavanapalli%2FMdnsListener/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264686799,"owners_count":23649565,"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":["cross-platform","csharp","dns","dotnet","home-automation","iot","mdns","monitoring","multicast-dns","network-discovery","network-tools","service-discovery","zeroconf"],"created_at":"2025-07-10T23:20:04.922Z","updated_at":"2025-10-20T00:24:24.195Z","avatar_url":"https://github.com/adyavanapalli.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mDNS Listener\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.png\" alt=\"mDNS Listener Logo\" width=\"350\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\nA high-performance, production-ready multicast DNS (mDNS) listener built with .NET, designed to discover and monitor services on the local network using the mDNS protocol (RFC 6762).\n\u003c/p\u003e\n\n## Features\n\n- **Dual-Stack Support**: Simultaneous IPv4 and IPv6 multicast listening\n- **Real-Time Service Discovery**: Automatic detection of services advertised via mDNS\n- **TTL-Based Expiration**: Automatic removal of expired services based on DNS TTL values\n- **Configurable Filtering**: Filter services by name, type, or pattern matching\n- **Graceful Shutdown**: Proper resource cleanup and cancellation support\n- **Security Hardened**: Input validation and protection against malformed packets\n- **Event-Driven Architecture**: Subscribe to service advertisement and removal events\n- **High Performance**: Zero-allocation parsing with efficient memory usage\n- **Resilient**: Built-in retry logic and timeout handling for network operations\n\n## Requirements\n\n- .NET 10.0 or later\n- Network access to multicast addresses (224.0.0.251 for IPv4, FF02::FB for IPv6)\n- Administrator/root privileges may be required on some systems for binding to port 5353\n\n## Installation\n\n1. Clone the repository:\n```bash\ngit clone \u003crepository-url\u003e\ncd MdnsListener\n```\n\n2. Build the project:\n```bash\ndotnet build\n```\n\n## Usage\n\n### Basic Usage\n\nRun the listener with default settings:\n```bash\ndotnet run\n```\n\n### Command Line Options\n\nThe application supports various command line options for filtering and configuration:\n\n```bash\n# Filter by specific service names\ndotnet run -- --service-name \"MyPrinter._ipp._tcp.local\" \"MyTV._airplay._tcp.local\"\n\n# Filter by DNS record types\ndotnet run -- --service-type PTR SRV TXT\n\n# Filter by domain patterns (supports wildcards)\ndotnet run -- --domain-pattern \"*.local\" \"*._tcp.local\"\n\n# Combine multiple filters\ndotnet run -- --service-type PTR --domain-pattern \"*._http._tcp.local\"\n\n# Monitor all services (no filtering)\ndotnet run -- --all\n\n# Set custom log level\ndotnet run -- --log-level Debug\ndotnet run -- --log-level Trace  # Most verbose\n\n# Use custom configuration file\ndotnet run -- --config /path/to/custom-config.json\n\n# Display help\ndotnet run -- --help\n```\n\n#### Available Options\n\n- `--service-name \u003cNAME1\u003e \u003cNAME2\u003e ...` - Filter by specific service names (space-separated)\n- `--service-type \u003cTYPE1\u003e \u003cTYPE2\u003e ...` - Filter by DNS record types like PTR, SRV, TXT (space-separated)\n- `--domain-pattern \u003cPATTERN1\u003e \u003cPATTERN2\u003e ...` - Filter by domain patterns with wildcard support (space-separated)\n- `--all` - Monitor all services without filtering (overrides other filters)\n- `--log-level \u003cLEVEL\u003e` - Set logging level: Trace, Debug, Information, Warning, Error, Critical\n- `-c, --config \u003cPATH\u003e` - Use custom configuration file instead of appsettings.json\n- `-h, --help` - Display help information\n\n**Note**: Command line filters override any filters configured in appsettings.json.\n\n### Bash Completion\n\nThe application includes bash completion support. To enable it:\n\n```bash\n# For current session only\nsource completion/mdnslistener-completion.bash\n\n# Or install permanently for current user\ncp completion/mdnslistener-completion.bash ~/.local/share/bash-completion/completions/mdnslistener\n```\n\nSee [completion/README.md](completion/README.md) for detailed installation instructions.\n\n### Configuration\n\nThe application uses `appsettings.json` for configuration. Create or modify this file to customize behavior:\n\n```json\n{\n  \"Logging\": {\n    \"LogLevel\": {\n      \"Default\": \"Information\",\n      \"Microsoft\": \"Warning\"\n    }\n  },\n  \"MdnsListener\": {\n    \"MulticastAddressIPv4\": \"224.0.0.251\",\n    \"MulticastAddressIPv6\": \"FF02::FB\",\n    \"Port\": 5353,\n    \"PacketProcessingTimeout\": \"00:00:05\",\n    \"CacheExpirationCheckInterval\": \"00:00:30\",\n    \"ServiceFilter\": {\n      \"IncludeAll\": true,\n      \"ServiceNames\": [],\n      \"ServiceTypes\": [],\n      \"DomainPatterns\": []\n    }\n  }\n}\n```\n\n#### Configuration Options\n\n- **MulticastAddressIPv4**: IPv4 multicast address for mDNS (default: 224.0.0.251)\n- **MulticastAddressIPv6**: IPv6 multicast address for mDNS (default: FF02::FB)\n- **Port**: mDNS port (default: 5353)\n- **PacketProcessingTimeout**: Maximum time to process a single packet\n- **CacheExpirationCheckInterval**: How often to check for expired services\n- **ServiceFilter**: Configure which services to track\n  - **IncludeAll**: Process all services (true) or only filtered ones (false)\n  - **ServiceNames**: Specific service names to include (e.g., [\"MyPrinter._ipp._tcp.local\"])\n  - **ServiceTypes**: DNS record types to include (e.g., [\"PTR\", \"SRV\"])\n  - **DomainPatterns**: Wildcard patterns for domain matching (e.g., [\"*.local\", \"*._tcp.local\"])\n\n### Environment-Specific Configuration\n\nUse environment-specific configuration files:\n```bash\nDOTNET_ENVIRONMENT=Development dotnet run\n```\n\nThis will load `appsettings.Development.json` in addition to the base configuration.\n\n## Architecture\n\nThe application follows SOLID principles and uses modern .NET patterns:\n\n### Project Structure\n\n```\nMdnsListener/\n├── Configuration/     # Configuration classes (Options pattern)\n├── Interfaces/        # Interface contracts\n├── Models/            # Domain models and data structures\n├── Services/          # Service implementations\n├── Program.cs         # Application entry point\n└── appsettings.json   # Configuration file\n```\n\n### Key Components\n\n- **MdnsListener**: Manages UDP clients and packet reception\n- **PacketHandler**: Processes incoming mDNS packets\n- **SecureDnsPacketParser**: Parses DNS packets with security validations\n- **ServiceCacheWithExpiration**: Stores discovered services with TTL management\n- **ConfigurableServiceFilter**: Filters services based on configuration\n- **MdnsEventLogger**: Logs service discovery events\n\n### Design Patterns\n\n- **Dependency Injection**: All components use constructor injection\n- **Options Pattern**: Configuration management via IOptions\u003cT\u003e\n- **Observer Pattern**: Event-driven notifications for service changes\n- **Repository Pattern**: Service cache for data storage\n- **Hosted Service**: Background service lifecycle management\n\n## Service Discovery Examples\n\nThe listener will automatically discover and log services like:\n\n```\n[SERVICE UP] MyPrinter._ipp._tcp.local | TTL: 120s | Source: 192.168.1.100:5353\n[SERVICE UP] Living Room TV._airplay._tcp.local | TTL: 4500s | Source: 192.168.1.105:5353\n[SERVICE DOWN] Old Device._http._tcp.local | Reason: Goodbye packet | Source: 192.168.1.50:5353\n[SERVICE EXPIRED] Temp Service._workstation._tcp.local | Age: 125.3s | Last seen: 2024-01-10 15:30:45\n```\n\n## Security Considerations\n\n- **Input Validation**: All network input is validated with bounds checking\n- **Packet Size Limits**: Maximum packet sizes are enforced\n- **Compression Attack Prevention**: Protection against DNS compression pointer loops\n- **Resource Limits**: Maximum number of resource records per packet\n- **Timeout Protection**: All packet processing has configurable timeouts\n\n## Performance\n\n- **Zero-Allocation Parsing**: Uses ref structs for efficient memory usage\n- **Concurrent Processing**: Packets are processed asynchronously\n- **Pre-Compiled Patterns**: Regex patterns are compiled once at startup\n- **Efficient Caching**: Thread-safe concurrent dictionary for service storage\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Permission Denied**: On some systems, binding to port 5353 requires elevated privileges\n   - Solution: Run with `sudo` on Linux/macOS or as Administrator on Windows\n\n2. **No Services Discovered**: Firewall may be blocking multicast traffic\n   - Solution: Allow UDP port 5353 and multicast addresses in firewall rules\n\n3. **IPv6 Not Working**: IPv6 may be disabled on the system\n   - Solution: The application will continue with IPv4 only (check logs)\n\n### Debug Logging\n\nEnable debug logging for detailed information:\n```json\n{\n  \"Logging\": {\n    \"LogLevel\": {\n      \"Default\": \"Debug\",\n      \"MdnsListener\": \"Trace\"\n    }\n  }\n}\n```\n\n## Contributing\n\nContributions are welcome! Please ensure:\n\n1. Code follows C# coding conventions\n2. All public APIs have XML documentation\n3. New features include appropriate logging\n4. Changes maintain backward compatibility\n5. Security considerations are addressed\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## References\n\n- [RFC 6762 - Multicast DNS](https://datatracker.ietf.org/doc/html/rfc6762)\n- [RFC 1035 - Domain Names - Implementation and Specification](https://datatracker.ietf.org/doc/html/rfc1035)\n- [Zero Configuration Networking](http://www.zeroconf.org/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadyavanapalli%2Fmdnslistener","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadyavanapalli%2Fmdnslistener","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadyavanapalli%2Fmdnslistener/lists"}