cmtrl-netscope 1.0.0__tar.gz

cmtrl_netscope-1.0.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.ruff_cache/
+netscope-*.json

cmtrl_netscope-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayoub Alshammari (cmtrl)
+
+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.

cmtrl_netscope-1.0.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include main.py requirements.txt .gitignore
+recursive-include tests *.py
+recursive-include docs *.md

cmtrl_netscope-1.0.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: cmtrl-netscope
+Version: 1.0.0
+Summary: A Python CLI for checking DNS records, TCP ports, and HTTP headers
+Author: Ayoub Alshammari
+License-Expression: MIT
+Project-URL: GitHub profile, https://github.com/cmtrl
+Project-URL: Repository, https://github.com/cmtrl/netscope
+Project-URL: Issues, https://github.com/cmtrl/netscope/issues
+Project-URL: Documentation, https://github.com/cmtrl/netscope/blob/main/docs/REFERENCE.md
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp<4.0,>=3.12.14
+Requires-Dist: dnspython<3.0,>=2.7.0
+Requires-Dist: rich<15.0,>=13.9.4
+Dynamic: license-file
+
+# NetScope
+
+A Python CLI for checking DNS records, common TCP ports, and HTTP headers.
+
+By **Ayoub Alshammari** · [@cmtrl](https://github.com/cmtrl)
+
+```text
+ _   _      _   ____
+| \ | | ___| |_/ ___|  ___ ___  _ __   ___
+|  \| |/ _ \ __\___ \ / __/ _ \| '_ \ / _ \
+| |\  |  __/ |_ ___) | (_| (_) | |_) |  __/
+|_| \_|\___|\__|____/ \___\___/| .__/ \___|
+                               |_|
+```
+
+I'm using this project to work on Python networking, async code, and CLI design.
+It's a starting point I plan to keep improving as I learn more about how these
+checks work.
+
+## What it does
+
+- Looks up A, AAAA, MX, TXT, and NS records concurrently.
+- Checks TCP ports `21`, `22`, `80`, `443`, `8080`, and `8443`.
+- Fetches HTTP and HTTPS response headers.
+- Checks for HSTS, CSP, and X-Frame-Options.
+- Shows technology hints from headers such as `Server` and `X-Powered-By`.
+- Displays results in the terminal and optionally saves them as JSON.
+
+The checks run with `asyncio`, `aiohttp`, and `dnspython`. The terminal output
+uses `rich`.
+
+The package is being prepared for PyPI as `cmtrl-netscope`. The command stays
+`netscope`. See the [publishing guide](https://github.com/cmtrl/netscope/blob/main/docs/PUBLISHING.md)
+for the release setup.
+
+## Setup
+
+Requires Python **3.10 or newer**. No root privileges needed.
+
+Download the source, open its folder, then run:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -r requirements.txt
+```
+
+On Windows PowerShell, activate with `.venv\Scripts\Activate.ps1` instead.
+Use `python3` in place of `python` if that's how Python is installed on your system.
+
+## Usage
+
+```bash
+python main.py -t example.com
+```
+
+Save a JSON report:
+
+```bash
+python main.py -t example.com -o json --output-file report.json
+```
+
+Set a shorter timeout or change the number of concurrent TCP checks:
+
+```bash
+python main.py -t example.com --timeout 3 --concurrency 12
+```
+
+IP addresses work too. Forward DNS enumeration is skipped for IP targets:
+
+```bash
+python main.py -t 127.0.0.1
+python main.py -t ::1
+```
+
+Use a bare hostname or IP address, without `https://`, a path, or a port number.
+
+```bash
+python main.py --help
+```
+
+You can also install the command in your virtual environment:
+
+```bash
+python -m pip install .
+netscope -t example.com
+# Or: python -m netscope -t example.com
+```
+
+## A few things to know
+
+Use this on systems you own or have permission to check.
+
+An open port means a TCP connection succeeded. It doesn't confirm which service
+is running. A missing security header isn't automatically a vulnerability, and
+technology headers can be wrong.
+
+HTTP checks use ports 80 and 443. Ports 8080 and 8443 get TCP checks only.
+Redirects are shown without being followed, and HTTPS certificate verification
+stays enabled. A failed check doesn't discard results from the other checks.
+
+More detail on result states, timeouts, proxies, JSON fields, and exit codes is
+in [docs/REFERENCE.md](https://github.com/cmtrl/netscope/blob/main/docs/REFERENCE.md).
+
+## Working on the code
+
+```text
+main.py              entry point
+netscope/cli.py      arguments and terminal output
+netscope/scanner.py  DNS, TCP, and HTTP checks
+netscope/utils.py    input validation and JSON export
+tests/              tests using local servers and simulated failures
+```
+
+Run the tests:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+Optional development tools:
+
+```bash
+python -m pip install ruff build
+ruff check .
+python -m build
+```
+
+Some things I'd like to work on next:
+
+- Letting the user choose which ports to check.
+- Making the output easier to skim when a host has several IP addresses.
+- Adding more tests as I change the scanner.
+
+If you find a bug or have a suggestion, an issue or pull request is welcome.
+
+## License
+
+[MIT](https://github.com/cmtrl/netscope/blob/main/LICENSE) · Copyright (c) 2026 Ayoub Alshammari (cmtrl).

cmtrl_netscope-1.0.0/README.md

@@ -0,0 +1,139 @@
+# NetScope
+
+A Python CLI for checking DNS records, common TCP ports, and HTTP headers.
+
+By **Ayoub Alshammari** · [@cmtrl](https://github.com/cmtrl)
+
+```text
+ _   _      _   ____
+| \ | | ___| |_/ ___|  ___ ___  _ __   ___
+|  \| |/ _ \ __\___ \ / __/ _ \| '_ \ / _ \
+| |\  |  __/ |_ ___) | (_| (_) | |_) |  __/
+|_| \_|\___|\__|____/ \___\___/| .__/ \___|
+                               |_|
+```
+
+I'm using this project to work on Python networking, async code, and CLI design.
+It's a starting point I plan to keep improving as I learn more about how these
+checks work.
+
+## What it does
+
+- Looks up A, AAAA, MX, TXT, and NS records concurrently.
+- Checks TCP ports `21`, `22`, `80`, `443`, `8080`, and `8443`.
+- Fetches HTTP and HTTPS response headers.
+- Checks for HSTS, CSP, and X-Frame-Options.
+- Shows technology hints from headers such as `Server` and `X-Powered-By`.
+- Displays results in the terminal and optionally saves them as JSON.
+
+The checks run with `asyncio`, `aiohttp`, and `dnspython`. The terminal output
+uses `rich`.
+
+The package is being prepared for PyPI as `cmtrl-netscope`. The command stays
+`netscope`. See the [publishing guide](https://github.com/cmtrl/netscope/blob/main/docs/PUBLISHING.md)
+for the release setup.
+
+## Setup
+
+Requires Python **3.10 or newer**. No root privileges needed.
+
+Download the source, open its folder, then run:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -r requirements.txt
+```
+
+On Windows PowerShell, activate with `.venv\Scripts\Activate.ps1` instead.
+Use `python3` in place of `python` if that's how Python is installed on your system.
+
+## Usage
+
+```bash
+python main.py -t example.com
+```
+
+Save a JSON report:
+
+```bash
+python main.py -t example.com -o json --output-file report.json
+```
+
+Set a shorter timeout or change the number of concurrent TCP checks:
+
+```bash
+python main.py -t example.com --timeout 3 --concurrency 12
+```
+
+IP addresses work too. Forward DNS enumeration is skipped for IP targets:
+
+```bash
+python main.py -t 127.0.0.1
+python main.py -t ::1
+```
+
+Use a bare hostname or IP address, without `https://`, a path, or a port number.
+
+```bash
+python main.py --help
+```
+
+You can also install the command in your virtual environment:
+
+```bash
+python -m pip install .
+netscope -t example.com
+# Or: python -m netscope -t example.com
+```
+
+## A few things to know
+
+Use this on systems you own or have permission to check.
+
+An open port means a TCP connection succeeded. It doesn't confirm which service
+is running. A missing security header isn't automatically a vulnerability, and
+technology headers can be wrong.
+
+HTTP checks use ports 80 and 443. Ports 8080 and 8443 get TCP checks only.
+Redirects are shown without being followed, and HTTPS certificate verification
+stays enabled. A failed check doesn't discard results from the other checks.
+
+More detail on result states, timeouts, proxies, JSON fields, and exit codes is
+in [docs/REFERENCE.md](https://github.com/cmtrl/netscope/blob/main/docs/REFERENCE.md).
+
+## Working on the code
+
+```text
+main.py              entry point
+netscope/cli.py      arguments and terminal output
+netscope/scanner.py  DNS, TCP, and HTTP checks
+netscope/utils.py    input validation and JSON export
+tests/              tests using local servers and simulated failures
+```
+
+Run the tests:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+Optional development tools:
+
+```bash
+python -m pip install ruff build
+ruff check .
+python -m build
+```
+
+Some things I'd like to work on next:
+
+- Letting the user choose which ports to check.
+- Making the output easier to skim when a host has several IP addresses.
+- Adding more tests as I change the scanner.
+
+If you find a bug or have a suggestion, an issue or pull request is welcome.
+
+## License
+
+[MIT](https://github.com/cmtrl/netscope/blob/main/LICENSE) · Copyright (c) 2026 Ayoub Alshammari (cmtrl).

cmtrl_netscope-1.0.0/cmtrl_netscope.egg-info/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: cmtrl-netscope
+Version: 1.0.0
+Summary: A Python CLI for checking DNS records, TCP ports, and HTTP headers
+Author: Ayoub Alshammari
+License-Expression: MIT
+Project-URL: GitHub profile, https://github.com/cmtrl
+Project-URL: Repository, https://github.com/cmtrl/netscope
+Project-URL: Issues, https://github.com/cmtrl/netscope/issues
+Project-URL: Documentation, https://github.com/cmtrl/netscope/blob/main/docs/REFERENCE.md
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp<4.0,>=3.12.14
+Requires-Dist: dnspython<3.0,>=2.7.0
+Requires-Dist: rich<15.0,>=13.9.4
+Dynamic: license-file
+
+# NetScope
+
+A Python CLI for checking DNS records, common TCP ports, and HTTP headers.
+
+By **Ayoub Alshammari** · [@cmtrl](https://github.com/cmtrl)
+
+```text
+ _   _      _   ____
+| \ | | ___| |_/ ___|  ___ ___  _ __   ___
+|  \| |/ _ \ __\___ \ / __/ _ \| '_ \ / _ \
+| |\  |  __/ |_ ___) | (_| (_) | |_) |  __/
+|_| \_|\___|\__|____/ \___\___/| .__/ \___|
+                               |_|
+```
+
+I'm using this project to work on Python networking, async code, and CLI design.
+It's a starting point I plan to keep improving as I learn more about how these
+checks work.
+
+## What it does
+
+- Looks up A, AAAA, MX, TXT, and NS records concurrently.
+- Checks TCP ports `21`, `22`, `80`, `443`, `8080`, and `8443`.
+- Fetches HTTP and HTTPS response headers.
+- Checks for HSTS, CSP, and X-Frame-Options.
+- Shows technology hints from headers such as `Server` and `X-Powered-By`.
+- Displays results in the terminal and optionally saves them as JSON.
+
+The checks run with `asyncio`, `aiohttp`, and `dnspython`. The terminal output
+uses `rich`.
+
+The package is being prepared for PyPI as `cmtrl-netscope`. The command stays
+`netscope`. See the [publishing guide](https://github.com/cmtrl/netscope/blob/main/docs/PUBLISHING.md)
+for the release setup.
+
+## Setup
+
+Requires Python **3.10 or newer**. No root privileges needed.
+
+Download the source, open its folder, then run:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -r requirements.txt
+```
+
+On Windows PowerShell, activate with `.venv\Scripts\Activate.ps1` instead.
+Use `python3` in place of `python` if that's how Python is installed on your system.
+
+## Usage
+
+```bash
+python main.py -t example.com
+```
+
+Save a JSON report:
+
+```bash
+python main.py -t example.com -o json --output-file report.json
+```
+
+Set a shorter timeout or change the number of concurrent TCP checks:
+
+```bash
+python main.py -t example.com --timeout 3 --concurrency 12
+```
+
+IP addresses work too. Forward DNS enumeration is skipped for IP targets:
+
+```bash
+python main.py -t 127.0.0.1
+python main.py -t ::1
+```
+
+Use a bare hostname or IP address, without `https://`, a path, or a port number.
+
+```bash
+python main.py --help
+```
+
+You can also install the command in your virtual environment:
+
+```bash
+python -m pip install .
+netscope -t example.com
+# Or: python -m netscope -t example.com
+```
+
+## A few things to know
+
+Use this on systems you own or have permission to check.
+
+An open port means a TCP connection succeeded. It doesn't confirm which service
+is running. A missing security header isn't automatically a vulnerability, and
+technology headers can be wrong.
+
+HTTP checks use ports 80 and 443. Ports 8080 and 8443 get TCP checks only.
+Redirects are shown without being followed, and HTTPS certificate verification
+stays enabled. A failed check doesn't discard results from the other checks.
+
+More detail on result states, timeouts, proxies, JSON fields, and exit codes is
+in [docs/REFERENCE.md](https://github.com/cmtrl/netscope/blob/main/docs/REFERENCE.md).
+
+## Working on the code
+
+```text
+main.py              entry point
+netscope/cli.py      arguments and terminal output
+netscope/scanner.py  DNS, TCP, and HTTP checks
+netscope/utils.py    input validation and JSON export
+tests/              tests using local servers and simulated failures
+```
+
+Run the tests:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+Optional development tools:
+
+```bash
+python -m pip install ruff build
+ruff check .
+python -m build
+```
+
+Some things I'd like to work on next:
+
+- Letting the user choose which ports to check.
+- Making the output easier to skim when a host has several IP addresses.
+- Adding more tests as I change the scanner.
+
+If you find a bug or have a suggestion, an issue or pull request is welcome.
+
+## License
+
+[MIT](https://github.com/cmtrl/netscope/blob/main/LICENSE) · Copyright (c) 2026 Ayoub Alshammari (cmtrl).

cmtrl_netscope-1.0.0/cmtrl_netscope.egg-info/SOURCES.txt

@@ -0,0 +1,24 @@
+.gitignore
+LICENSE
+MANIFEST.in
+README.md
+main.py
+pyproject.toml
+requirements.txt
+cmtrl_netscope.egg-info/PKG-INFO
+cmtrl_netscope.egg-info/SOURCES.txt
+cmtrl_netscope.egg-info/dependency_links.txt
+cmtrl_netscope.egg-info/entry_points.txt
+cmtrl_netscope.egg-info/requires.txt
+cmtrl_netscope.egg-info/top_level.txt
+docs/DEMO.md
+docs/PUBLISHING.md
+docs/REFERENCE.md
+netscope/__init__.py
+netscope/__main__.py
+netscope/cli.py
+netscope/scanner.py
+netscope/utils.py
+tests/test_cli.py
+tests/test_scanner.py
+tests/test_utils.py

cmtrl_netscope-1.0.0/cmtrl_netscope.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cmtrl_netscope-1.0.0/cmtrl_netscope.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+netscope = netscope.cli:main

cmtrl_netscope-1.0.0/cmtrl_netscope.egg-info/requires.txt

@@ -0,0 +1,3 @@
+aiohttp<4.0,>=3.12.14
+dnspython<3.0,>=2.7.0
+rich<15.0,>=13.9.4

cmtrl_netscope-1.0.0/cmtrl_netscope.egg-info/top_level.txt

@@ -0,0 +1 @@
+netscope

cmtrl_netscope-1.0.0/docs/DEMO.md

@@ -0,0 +1,59 @@
+# A short NetScope demo
+
+Aim for about 25 seconds. Use a large terminal font and a clean window.
+Keep notifications and unrelated windows out of the recording.
+
+## Commands
+
+Until the PyPI release is live, install from the GitHub source in a virtual
+environment:
+
+```bash
+git clone https://github.com/cmtrl/netscope.git
+cd netscope
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install .
+```
+
+For a repeatable demo, start a small server in a second terminal:
+
+```bash
+python -m http.server 8080 --bind 127.0.0.1
+```
+
+Record this in your main terminal:
+
+```bash
+netscope --version
+netscope -t 127.0.0.1 --timeout 2 -o json --output-file demo.json
+python -m json.tool demo.json
+```
+
+This shows port 8080 open and a JSON report. Forward DNS is skipped for an IP
+address, and HTTP analysis uses 80/443, so the server on 8080 does not produce
+HTTP header results. Say that if you explain this demo.
+
+For a fuller demo, use a domain you own or have permission to scan in place of
+`127.0.0.1`. A failed request remains visible in the output; keep it in the clip.
+
+## Shot list
+
+- **0–4 seconds:** show the command and target.
+- **4–14 seconds:** run it and pause on the results.
+- **14–20 seconds:** show the JSON export or one interesting result.
+- **20–25 seconds:** show `github.com/cmtrl/netscope`.
+
+OBS or your operating system's screen recorder can capture the terminal. Export
+an MP4. Check that the text is readable at phone size before posting.
+
+## Post text
+
+> First public project: NetScope, a Python CLI for DNS records, TCP port checks,
+> and HTTP headers. I'm using it to learn async Python and networking, and I'll
+> keep improving it as I go. Feedback welcome.
+>
+> https://github.com/cmtrl/netscope
+
+After PyPI publishing succeeds, you can add `pip install cmtrl-netscope` to the
+post. Avoid using it as an installation claim before the release exists.

cmtrl_netscope-1.0.0/docs/PUBLISHING.md

@@ -0,0 +1,59 @@
+# Publishing NetScope
+
+The PyPI distribution name is `cmtrl-netscope`. The CLI command and Python
+module are both still `netscope`.
+
+`netscope-cli` belongs to another project on PyPI. A package name that returns
+404 is not reserved or guaranteed to be available until PyPI accepts the upload.
+
+## One-time account setup
+
+Sign in to your own [PyPI account](https://pypi.org/account/publishing/).
+If you need to register, complete PyPI's account verification and 2FA setup first.
+
+Under **Add a new pending publisher**, select GitHub and enter:
+
+| Field | Value |
+| --- | --- |
+| PyPI project name | `cmtrl-netscope` |
+| Owner | `cmtrl` |
+| Repository name | `netscope` |
+| Workflow name | `publish.yml` |
+| Environment name | `pypi` |
+
+Save the pending publisher. It creates the PyPI project on the first successful
+upload. No API token needs to be copied into chat or GitHub secrets.
+
+This follows [PyPI's pending publisher setup](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/).
+
+## Publish
+
+In GitHub, open **Actions → Publish to PyPI → Run workflow** and select `main`.
+The workflow tests the code, builds and checks both distributions, then publishes
+using GitHub's identity. It does not run automatically on ordinary commits.
+
+After a successful upload, test installation in a fresh virtual environment:
+
+```bash
+python -m venv .venv-release
+source .venv-release/bin/activate
+python -m pip install cmtrl-netscope
+netscope --version
+netscope --help
+```
+
+Update the README to show the PyPI installation command after the release is live.
+
+## Later releases
+
+Bump the version in both `pyproject.toml` and `netscope/utils.py`, commit the
+changes, and run the workflow again. PyPI does not allow replacing an uploaded
+distribution file with another file of the same name.
+
+For a local packaging check:
+
+```bash
+python -m pip install build twine
+python -m build
+python -m twine check --strict dist/*
+```