{"id":50533181,"url":"https://github.com/daedalus/pyiodine","last_synced_at":"2026-06-03T15:30:28.252Z","repository":{"id":354492678,"uuid":"1223876898","full_name":"daedalus/pyiodine","owner":"daedalus","description":"pyiodine — Python implementation of iodine DNS tunneling tool.","archived":false,"fork":false,"pushed_at":"2026-04-28T18:58:34.000Z","size":37,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-28T20:35:16.469Z","etag":null,"topics":["dns"],"latest_commit_sha":null,"homepage":"","language":"Python","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/daedalus.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-28T18:36:21.000Z","updated_at":"2026-04-28T18:59:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/daedalus/pyiodine","commit_stats":null,"previous_names":["daedalus/pyiodine"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/daedalus/pyiodine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daedalus%2Fpyiodine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daedalus%2Fpyiodine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daedalus%2Fpyiodine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daedalus%2Fpyiodine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daedalus","download_url":"https://codeload.github.com/daedalus/pyiodine/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daedalus%2Fpyiodine/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33872297,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"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":["dns"],"created_at":"2026-06-03T15:30:25.609Z","updated_at":"2026-06-03T15:30:28.239Z","avatar_url":"https://github.com/daedalus.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"**pyiodine** — Python implementation of iodine DNS tunneling tool.\n\n[![Python](https://img.shields.io/pypi/pyversions/pyiodine.svg)](https://pypi.org/project/pyiodine/)\n\n## Description\n\nPyiondine is a Python translation of the [iodine](http://code.kryo.se/iodine) DNS tunneling tool. It allows tunneling IPv4 data through DNS servers, enabling network access in firewalled environments where only DNS queries are allowed.\n\nThis implementation maintains protocol compatibility with the original C version while providing a Pythonic API for integration into Python applications.\n\n## Features\n\n- DNS tunneling client and server implementations\n- Multiple encoding schemes (Base32, Base64, Base128)\n- TUN interface support (Linux)\n- CHAP-style authentication\n- Compatible with original iodine protocol\n- Pure Python (with optional pytun for TUN support)\n\n## Installation\n\n```bash\npip install pyiodine\n```\n\nFor TUN interface support on Linux:\n```bash\npip install pyiodine[full]  # Includes pytun\n```\n\n## Quick Start\n\n### Server Side\n\n```bash\n# Start server with tunnel IP and domain\npyiodined -f 10.0.0.1 t1.example.com\n```\n\nEnter a password when prompted.\n\n### Client Side\n\n```bash\n# Connect to server via DNS\npyiodine -f 8.8.8.8 t1.example.com\n```\n\nEnter the same password as on the server.\n\n## Usage Examples\n\n### As a Python Library\n\n```python\nfrom pyiodine import IodineClient, IodineServer\n\n# Create a client\nclient = IodineClient(\n    domain=\"t1.example.com\",\n    nameserver=\"8.8.8.8\",\n    password=\"secret\"\n)\n\n# Connect\nclient.connect()\n\n# Run tunnel\nclient.tunnel()\n```\n\n### Using Different Encodings\n\n```python\n# Client with Base64 encoding\npyiodine -f -T base64 8.8.8.8 t1.example.com\n\n# Server with Base128\npyiodined -f 10.0.0.1 t1.example.com  # Encoding negotiated during handshake\n```\n\n## Command Line Options\n\n### Client (pyiodine)\n\n```\npyiodine [options] \u003cnameserver\u003e \u003cdomain\u003e\n  -f, --foreground    Run in foreground\n  -P, --password PASS  Password (not recommended, use prompt)\n  -r, --relay         Use raw UDP relay mode\n  -T, --type TYPE     DNS record type (txt, null, srv, mx, cname, a)\n  -L, --lazy          Enable lazy mode\n  -M, --mtu SIZE      Set MTU for tunnel\n  -t, --timeout SEC   DNS query timeout\n  -v, --verbose       Increase verbosity\n```\n\n### Server (pyiodined)\n\n```\npyiodined [options] \u003cip\u003e \u003cdomain\u003e\n  -f, --foreground    Run in foreground\n  -P, --password PASS  Password (not recommended, use prompt)\n  -p, --port PORT     DNS port to listen on\n  -u, --user USER     Drop privileges to user\n  -t, --mtu MTU       MTU for tunnel interface\n  -d, --debug         Enable debug output\n  -c, --chroot DIR    Chroot after startup\n```\n\n## Architecture\n\n```\n+----------------+     DNS Queries      +-----------------+\n|  pyiodine      | \u003c------------------\u003e |  pyiodined     |\n|  (Client)      |                      |  (Server)      |\n|                |     DNS Responses    |                |\n|  [TUN] -------| ------------------\u003e | ------ [TUN]    |\n+----------------+                      +-----------------+\n    10.0.0.2                          10.0.0.1\n```\n\n## Protocol\n\nThe implementation uses the iodine protocol:\n- Authentication: CHAP-style challenge/response\n- Encodings: Base32 (default), Base64, Base128\n- DNS Record Types: TXT (default), NULL, SRV, MX, CNAME\n- Fragmentation: Automatic for large packets\n\n## Development\n\n```bash\ngit clone https://github.com/daedalus/pyiodine.git\ncd pyiodine\npip install -e \".[test]\"\n\n# Run tests\npytest\n\n# Format code\nruff format src/ tests/\n\n# Lint\nruff check src/ tests/\nprospector src/\nsemgrep --config=auto --severity=ERROR src/\n\n# Type check\nmypy src/\n```\n\n## Testing\n\n```bash\n# Run all tests with coverage\npytest --cov --cov-report=term-missing\n\n# Run specific tests\npytest tests/test_encoding.py -v\n```\n\n## Limitations\n\n- Windows TUN support requires external drivers\n- Android not supported (use original C version)\n- Systemd integration not included\n- SELinux policies not included\n\n## Requirements\n\n- Python 3.11+\n- dnspython (DNS handling)\n- pytun (TUN interface on Linux, optional)\n\n## License\n\nMIT License - See LICENSE file for details.\n\n## Acknowledgments\n\nThis is a Python translation of the original [iodine](http://code.kryo.se/iodine) project by Erik Ekman and Bjorn Andersson. All credit for the protocol design and original implementation goes to them.\n\n## Troubleshooting\n\n### \"TUN device not found\"\nInstall the required kernel modules and ensure `/dev/net/tun` exists.\n\n### \"Failed to connect\"\n- Verify the domain is properly delegated to your server\n- Check that the server is running and accessible\n- Ensure firewalls allow DNS traffic (UDP port 53)\n\n### \"Authentication failed\"\nEnsure you're using the same password on both client and server.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaedalus%2Fpyiodine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaedalus%2Fpyiodine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaedalus%2Fpyiodine/lists"}