zte-wrapper 1.0.0__tar.gz

zte_wrapper-1.0.0/.gitignore

@@ -0,0 +1,225 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+.test-venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+.password
+
+test.py

zte_wrapper-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 ctih1
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

zte_wrapper-1.0.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.5
+Name: zte-wrapper
+Version: 1.0.0
+Summary: A wrapper that lets you interact with the new ZTE WebUI
+Project-URL: Homepage, https://github.com/ctih1/zte-wrapper
+Project-URL: Issues, https://github.com/ctih1/zte-wrapper/issues
+Author-email: ctih1 <contact@ctih1.fi>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: aiohttp
+Description-Content-Type: text/markdown
+
+# ZTE-Wrapper
+
+An API wrapper for modern ZTE routers using a more advanced authentication method. This has only been tested on an MC888B. If you have any feedback, please share!
+
+## Features
+"Support" in this case means that it can be controlled via the library.
+
+
+| Feature                               | Support |
+| ------------------------------------- | ------- |
+| Create portforward rules              | ✅      |
+| Delete portforward rules              | ✅      |
+| List portforward rules                | ✅      |
+| Send SMS                              | ✅      |
+| Read SMS                              | ✅      |
+| List wireless devices                 | ✅      |
+| List wired devices                    | ✅      |
+| Get signal strength                   | ✅      |
+| Band information                      | ✅      |
+| Usage statistics                      | ✅      |
+| Firewall (e.g. domain/port filtering) | ❌      |
+| DHCP Settings                         | ✅      |
+| MAC-IP bindings                       | ✅      |
+| DDNS settings                         | ✅      |
+| VPN settings                          | ❌      |
+| Network tools (e.g. traceroute/ping)  | ✅      |
+| "Preferred position" tools            | ❌*     |
+
+*: Not planning on implementing
+
+
+<details>
+<summary>Features as overlayed on web panel</summary>
+
+(based on commit a7baa3b)
+
+
+![Network tab](screenshots/network.png)
+
+
+![WiFi tab](screenshots/wifi.png)
+
+
+![Devices tab](screenshots/devices.png)
+
+
+![Data usage tab](screenshots/datausage.png)
+
+
+![Router tab](screenshots/router.png)
+
+
+![SMS tab](screenshots/sms.png)
+
+
+![Security tab](screenshots/security.png)
+
+
+![System tab](screenshots/system.png)
+
+</details>
+
+## Roadmap
+1. ~~Implement DDNS-settings~~
+
+2. Publish onto PyPI
+
+3. More reliable error handling
+
+4. Implement rest of the features
+
+5. Implement better documentation
+
+6. Write tests
+
+## Notes
+- When referring to "megabytes" or "bytes", they are in base 2 format (e.g. 1Gib = 1024Mib)
+- Authenticating (aka. running any of the API calls) logs off other clients from the admin web panel.
+- Even thought the `apn` wrapper *should* be able to change DNS settings, I've found that it doesn't work. This might have been patched in an update? 
+
+## Why?
+I wanted to harvest statistics from the router to my Prometheus instance. I might actually rewrite the entire admin webpage since it's kind of horrible

zte_wrapper-1.0.0/README.md

@@ -0,0 +1,82 @@
+# ZTE-Wrapper
+
+An API wrapper for modern ZTE routers using a more advanced authentication method. This has only been tested on an MC888B. If you have any feedback, please share!
+
+## Features
+"Support" in this case means that it can be controlled via the library.
+
+
+| Feature                               | Support |
+| ------------------------------------- | ------- |
+| Create portforward rules              | ✅      |
+| Delete portforward rules              | ✅      |
+| List portforward rules                | ✅      |
+| Send SMS                              | ✅      |
+| Read SMS                              | ✅      |
+| List wireless devices                 | ✅      |
+| List wired devices                    | ✅      |
+| Get signal strength                   | ✅      |
+| Band information                      | ✅      |
+| Usage statistics                      | ✅      |
+| Firewall (e.g. domain/port filtering) | ❌      |
+| DHCP Settings                         | ✅      |
+| MAC-IP bindings                       | ✅      |
+| DDNS settings                         | ✅      |
+| VPN settings                          | ❌      |
+| Network tools (e.g. traceroute/ping)  | ✅      |
+| "Preferred position" tools            | ❌*     |
+
+*: Not planning on implementing
+
+
+<details>
+<summary>Features as overlayed on web panel</summary>
+
+(based on commit a7baa3b)
+
+
+![Network tab](screenshots/network.png)
+
+
+![WiFi tab](screenshots/wifi.png)
+
+
+![Devices tab](screenshots/devices.png)
+
+
+![Data usage tab](screenshots/datausage.png)
+
+
+![Router tab](screenshots/router.png)
+
+
+![SMS tab](screenshots/sms.png)
+
+
+![Security tab](screenshots/security.png)
+
+
+![System tab](screenshots/system.png)
+
+</details>
+
+## Roadmap
+1. ~~Implement DDNS-settings~~
+
+2. Publish onto PyPI
+
+3. More reliable error handling
+
+4. Implement rest of the features
+
+5. Implement better documentation
+
+6. Write tests
+
+## Notes
+- When referring to "megabytes" or "bytes", they are in base 2 format (e.g. 1Gib = 1024Mib)
+- Authenticating (aka. running any of the API calls) logs off other clients from the admin web panel.
+- Even thought the `apn` wrapper *should* be able to change DNS settings, I've found that it doesn't work. This might have been patched in an update? 
+
+## Why?
+I wanted to harvest statistics from the router to my Prometheus instance. I might actually rewrite the entire admin webpage since it's kind of horrible

zte_wrapper-1.0.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "zte-wrapper"
+version = "1.0.0"
+authors = [
+  { name="ctih1", email="contact@ctih1.fi" },
+]
+description = "A wrapper that lets you interact with the new ZTE WebUI"
+readme = "README.md"
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+  "aiohttp"
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+
+[project.urls]
+Homepage = "https://github.com/ctih1/zte-wrapper"
+Issues = "https://github.com/ctih1/zte-wrapper/issues"
+
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+  ".vscode",
+  "notes",
+  "screenshots"
+]

zte_wrapper-1.0.0/pytest.ini

@@ -0,0 +1,8 @@
+[pytest]
+pythonpath = src/
+
+log_cli = 1
+log_cli_level = INFO
+log_cli_format = %(asctime)s [%(levelname)8s] %(message)s (%(filename)s:%(lineno)s)
+log_cli_date_format=%Y-%m-%d %H:%M:%S
+addopts = --cov=. --cov-report=xml

zte_wrapper-1.0.0/src/tests/test_generic.py

@@ -0,0 +1,5 @@
+from zte_wrapper.helpers import utf_16_encode, utf_16_decode
+
+
+def test_utf_16_be_encoding():
+    assert utf_16_decode(utf_16_encode("hello")) == "hello"

zte_wrapper-1.0.0/src/zte_wrapper/authwrapper.py

@@ -0,0 +1,167 @@
+import logging
+import aiohttp
+from hashlib import sha256
+import urllib.parse
+import time
+import json
+from typing import Literal, Dict, Any, Tuple
+from copy import deepcopy
+
+logger = logging.getLogger("zte")
+
+GOFORM_COMMANDS = Literal["goform_get_cmd_process", "goform_set_cmd_process"]
+HEADERS = {
+    "Accept": "application/json, text/javascript, */*; q=0.01",
+    "Accept-Encoding": "gzip, deflate",
+    "Accept-Language": "en-US,en;q=0.5",
+    "Connection": "keep-alive",
+    "Host": "192.168.32.1",
+    "Referer": "http://192.168.32.1/",
+    "Sec-Gpc": "1",
+    "User-Agent": "Mozilla",
+    "X-Requested-With": "XMLHttpRequest",
+}
+
+
+def zte_sha256_string(input: str) -> str:
+    return sha256(input.encode("UTF-8")).hexdigest().upper()
+
+
+class ZTEAuthWrapper:
+    def __init__(self, webui_address: str, password: str) -> None:
+        self.address: str = webui_address
+        self.__password = zte_sha256_string(password)
+        self.__auth_code: str | None = None
+
+        self.headers = HEADERS
+        self.headers["Referer"] = f"http://{self.address}/"
+        self.headers["Host"] = self.address
+
+        self.session: aiohttp.ClientSession | None = None
+
+    def construct_url(self, command: GOFORM_COMMANDS, args: Dict[str, Any]) -> str:
+        base_url = f"http://{self.address}/goform/{command}/?"
+
+        url = base_url + urllib.parse.urlencode(
+            {k: urllib.parse.quote(str(v)) for k, v in args.items()}
+        )
+
+        logger.debug(f"Constructed url {url}")
+        return url
+
+    def get_timestamp(self) -> int:
+        return round(time.time() * 1000)
+
+    async def __get_ld(self) -> str:
+        async with aiohttp.ClientSession() as session:
+            res = await session.get(
+                self.construct_url(
+                    "goform_get_cmd_process",
+                    {"isTest": "false", "cmd": "LD", "_": self.get_timestamp()},
+                ),
+                headers=self.headers,
+            )
+
+            logger.info("Got LD token")
+            return json.loads((await res.text())).get(
+                "LD"
+            )  # json.loads instead of res.json() because the stupid API returns the stuff as text/html
+
+    async def __get_rd0_rd1(self) -> Tuple[str, str]:
+        res = await self.request(
+            "GET",
+            self.construct_url(
+                "goform_get_cmd_process",
+                {
+                    "isTest": "false",
+                    "cmd": "cr_version,wa_inner_version",
+                    "multi_data": "1",
+                },
+            ),
+        )
+        res_text = await res.text()
+        logger.debug(f"Retrieved rd0 and rd1: {res_text}")
+
+        data = json.loads(res_text)
+        return (data["wa_inner_version"], data["cr_version"])
+
+    async def __get_rd_token(self) -> str:
+        res = await self.request(
+            "GET",
+            self.construct_url(
+                "goform_get_cmd_process",
+                {"isTest": "false", "cmd": "RD", "_": self.get_timestamp()},
+            ),
+        )
+        logger.debug("")
+        return json.loads(await res.text())["RD"]
+
+    # please check notes/tokens.md if it breaks, it might help you a little
+    async def construct_ad_token(self) -> str:
+        rd0, rd1 = await self.__get_rd0_rd1()
+        first_step = zte_sha256_string(rd0 + rd1)
+        rd_token = await self.__get_rd_token()
+        return zte_sha256_string(first_step + rd_token)
+
+    async def refresh_auth(self) -> str:
+        ld_token: str = await self.__get_ld()
+        hashed_password: str = zte_sha256_string(self.__password + ld_token)
+
+        async with aiohttp.ClientSession() as session:
+            logger.debug("Refreshing authentication")
+            res = await session.post(
+                self.construct_url("goform_set_cmd_process", {}),
+                data={
+                    "isTest": "false",
+                    "goformId": "LOGIN",
+                    "password": hashed_password,
+                },
+                headers=self.headers,
+            )
+            self.__auth_code = str(res.cookies.get("stok"))
+
+        return self.__auth_code
+
+    async def confirm_auth(self) -> bool:
+        res = await self.request(
+            "GET",
+            self.construct_url(
+                "goform_get_cmd_process",
+                {"isTest": "false", "cmd": "date_month", "_": self.get_timestamp()},
+            ),
+            skip_auth_check=True,
+        )
+
+        result = bool(json.loads(await res.text())["date_month"])
+        logger.debug(f"Logged in? {result}")
+
+        return result
+
+    async def request(
+        self, method: Literal["GET", "POST"], *args, **kwargs
+    ) -> aiohttp.ClientResponse:
+        if not self.session:
+            self.session = aiohttp.ClientSession()
+
+        headers = deepcopy(self.headers)
+        headers["Cookie"] = f'stok="{self.__auth_code}"'
+
+        if kwargs.get("skip_auth_check"):
+            logger.debug("Skipping authentication checks...")
+            del kwargs["skip_auth_check"]
+        else:
+            if not await self.confirm_auth():
+                await self.refresh_auth()
+                headers["Cookie"] = f'stok="{self.__auth_code}"'
+
+        if method == "GET":
+            res = await self.session.get(*args, **kwargs, headers=headers)
+        elif method == "POST":
+            res = await self.session.post(*args, **kwargs, headers=headers)
+
+        return res
+
+    async def close(self) -> None:
+        logger.info("Closign aiohttp client")
+        if self.session:
+            await self.session.close()

zte_wrapper-1.0.0/src/zte_wrapper/helpers.py

@@ -0,0 +1,17 @@
+from datetime import datetime
+
+
+def utf_16_decode(inp: str) -> str:
+    return bytes.fromhex(inp).decode("utf-16-be")
+
+
+def utf_16_encode(inp: str) -> str:
+    return inp.encode("utf-16-be").hex().upper()
+
+
+def get_zte_timestring(timezone_offset: int) -> str:
+    now = datetime.now()
+
+    output = f"{str(now.year)[2:]};{now.month};{now.day};{now.hour+1};{now.minute};{now.second};+{timezone_offset}"
+
+    return output