chore: project maintenance and quality improvements

.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install Poetry
+      uses: snok/install-poetry@v1
+      with:
+        version: 1.7.1
+        virtualenvs-create: true
+        virtualenvs-in-project: true
+
+    - name: Install dependencies
+      run: |
+        poetry install
+
+    - name: Run linting
+      run: |
+        make lint
+
+    - name: Run tests
+      run: |
+        make test

.github/workflows/release.yml

@@ -32,7 +32,7 @@ jobs:
 
       - name: Build package
         run: python -m build
-        
+
       - name: Create Release
         id: create_release
         uses: actions/create-release@v1
@@ -43,7 +43,7 @@ jobs:
           release_name: Release v${{ env.VERSION }}
           draft: false
           prerelease: false
-          
+
       - name: Upload Wheel
         uses: actions/upload-release-asset@v1
         env:
@@ -53,7 +53,7 @@ jobs:
           asset_path: ./dist/zmapsdk-${{ env.VERSION }}-py3-none-any.whl
           asset_name: zmapsdk-${{ env.VERSION }}-py3-none-any.whl
           asset_content_type: application/octet-stream
-          
+
       - name: Upload Source
         uses: actions/upload-release-asset@v1
         env:
@@ -63,7 +63,7 @@ jobs:
           asset_path: ./dist/zmapsdk-${{ env.VERSION }}.tar.gz
           asset_name: zmapsdk-${{ env.VERSION }}.tar.gz
           asset_content_type: application/gzip
-          
+
       - name: Publish to PyPI
         env:
           TWINE_USERNAME: __token__

.gitignore

@@ -42,3 +42,6 @@ Thumbs.db
 *.conf
 test_results/
 scan_results/
+
+# docs build
+docs/_build/

.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-yaml
+    -   id: check-added-large-files
+    -   id: check-toml
+-   repo: https://github.com/psf/black
+    rev: 24.2.0
+    hooks:
+    -   id: black
+        language_version: python3
+-   repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+    -   id: isort
+-   repo: https://github.com/asottile/pyupgrade
+    rev: v3.15.1
+    hooks:
+    -   id: pyupgrade
+        args: [--py311-plus]

CODE_OF_CONDUCT.md

@@ -0,0 +1,66 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at {{ email }}. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.

Makefile

@@ -0,0 +1,21 @@
+.PHONY: install format lint test clean
+
+install:
+	poetry install
+	pre-commit install
+
+format:
+	poetry run isort zmapsdk
+	poetry run black zmapsdk
+
+lint:
+	poetry run isort --check-only --diff .
+	poetry run black --check .
+	poetry run pyupgrade --py311-plus $$(find . -name '*.py' -not -path './.venv/*')
+
+clean:
+	rm -rf build/
+	rm -rf dist/
+	rm -rf *.egg-info
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete

__init__.py

@@ -1,8 +1,21 @@
-"""
-ZMap SDK - Python SDK for the ZMap network scanner
-"""
-
-from .zmapsdk import ZMap, ZMapError, ZMapCommandError
-
-__version__ = "0.1.0"
-__all__ = ["ZMap", "ZMapError", "ZMapCommandError"] 
+"""
+ZMap SDK - Python SDK for the ZMap network scanner
+"""
+
+from pathlib import Path
+
+import tomli
+
+from .zmapsdk import ZMap, ZMapCommandError, ZMapError
+
+# read version from pyproject.toml
+try:
+    _PYPROJECT_PATH = Path(__file__).parent.parent / "pyproject.toml"
+    with open(_PYPROJECT_PATH, "rb") as f:
+        _PYPROJECT = tomli.load(f)
+        __version__ = _PYPROJECT["project"]["version"]
+except (FileNotFoundError, KeyError, tomli.TOMLDecodeError):
+    # fallback for something went wrong
+    __version__ = "0.0.0"
+
+__all__ = ["ZMap", "ZMapError", "ZMapCommandError"]

build-package.sh

@@ -14,4 +14,4 @@ python -m build
 echo "Installing package..."
 python -m pip install -e .
 
-echo "Build and installation complete!" 
+echo "Build and installation complete!"

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,52 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import tomlkit
+
+
+def _get_project_details():
+    """Get project meta details."""
+    with open("../pyproject.toml") as pyproject:
+        content = pyproject.read()
+
+    return tomlkit.parse(content)["tool"]["poetry"]
+
+
+pkg_meta = _get_project_details()
+project = str(pkg_meta["name"])
+version = str(pkg_meta["version"])
+copyright = "2025, Happy Hacking Space"
+author = "Happy Hacking Space"
+release = version
+
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+autoclass_content = "class"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.doctest",
+    "autoapi.extension",
+]
+
+master_doc = "index"
+
+# autoapi
+autoapi_dirs = ["../../zmapsdk/"]
+autoapi_type = "python"
+templates_path = ["_templates"]
+exclude_patterns = [".DS_Store", "_build", "Thumbs.db"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]

docs/index.rst

@@ -0,0 +1,16 @@
+.. ZMap-SDK documentation master file, created by
+   sphinx-quickstart on Fri Apr 25 17:32:20 2025.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+ZMap-SDK documentation
+======================
+
+Add your content using ``reStructuredText`` syntax. See the
+`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+documentation for details.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

examples/advanced-scan.py

@@ -4,9 +4,9 @@
 config = ZMapScanConfig(
     target_port=80,
     bandwidth="10M",  # Set bandwidth limit to 10 Mbps
-    rate=1000,        # Limit to 1000 packets per second
+    rate=1000,  # Limit to 1000 packets per second
     cooldown_time=5,  # Wait 5 seconds between scan attempts
-    retries=2         # Retry failed connections twice
+    retries=2,  # Retry failed connections twice
 )
 
 zmap = ZMap()
@@ -19,7 +19,7 @@
         "192.168.2.0/24",
     ],
     output_file="scan_results.csv",
-    output_fields=["saddr", "daddr", "sport", "dport", "seqnum", "timestamp"]
+    output_fields=["saddr", "daddr", "sport", "dport", "seqnum", "timestamp"],
 )
 
 # Print detailed results