feat(python3-nethsec): move library and its tests into this repo

.github/workflows/jekyll-gh-pages.yml

@@ -5,7 +5,7 @@ on:
   # Runs on pushes targeting the default branch
   push:
     branches: ["main"]
-    paths: ["docs/**", "packages/**/README.md"]
+    paths: ["docs/**", "packages/**/README.md", "packages/python3-nethsec/src/**"]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -39,6 +39,27 @@ jobs:
         with:
           source: ./docs
           destination: ./_site
+      # Generate the python3-nethsec API reference into the built site, so it is
+      # published as a subpath of the existing documentation (/apidocs/python3-nethsec/).
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - name: Generate python3-nethsec API documentation
+        working-directory: packages/python3-nethsec
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          python -m pip install docutils pydoctor
+          pydoctor \
+              --project-name=python3-nethsec \
+              --project-url=https://github.com/$GITHUB_REPOSITORY \
+              --html-viewsource-base=https://github.com/$GITHUB_REPOSITORY/tree/$GITHUB_SHA \
+              --make-html \
+              --html-output="$GITHUB_WORKSPACE/_site/apidocs/python3-nethsec" \
+              --project-base-dir="$(pwd)" \
+              --docformat=restructuredtext \
+              --intersphinx=https://docs.python.org/3/objects.inv \
+              ./src/nethsec
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v5
 

.github/workflows/python3-nethsec-scans.yml

@@ -0,0 +1,49 @@
+name: "python3-nethsec scans"
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/python3-nethsec-scans.yml"
+      - "packages/python3-nethsec/**"
+  pull_request:
+    paths:
+      - ".github/workflows/python3-nethsec-scans.yml"
+      - "packages/python3-nethsec/**"
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  sbom:
+    name: SBOM
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+      - name: Generate SPDX SBOM
+        uses: aquasecurity/trivy-action@0.35.0
+        with:
+          scan-type: fs
+          scan-ref: packages/python3-nethsec
+          format: spdx-json
+          output: sbom.spdx.json
+      - name: Generate Sarif Report
+        uses: aquasecurity/trivy-action@0.35.0
+        with:
+          scan-type: fs
+          scan-ref: packages/python3-nethsec
+          format: sarif
+          output: trivy.sarif.json
+      - name: Upload report to GitHub
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: trivy.sarif.json
+          category: trivy-python3-nethsec
+      - name: Upload SBOM artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: python3-nethsec-sbom
+          path: sbom.spdx.json

.github/workflows/python3-nethsec-tests.yml

@@ -0,0 +1,26 @@
+name: "python3-nethsec tests"
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - ".github/workflows/python3-nethsec-tests.yml"
+      - "packages/python3-nethsec/**"
+  pull_request:
+    paths:
+      - ".github/workflows/python3-nethsec-tests.yml"
+      - "packages/python3-nethsec/**"
+
+jobs:
+  run_tests:
+    name: "Run tests"
+    runs-on: ubuntu-24.04
+    defaults:
+      run:
+        working-directory: packages/python3-nethsec
+    steps:
+      - uses: actions/checkout@v7
+      # test.sh always builds the test image locally from the Containerfile, so
+      # the tests do not depend on a published (and possibly private) image.
+      - id: test
+        run: ./test.sh

AGENTS.md

@@ -42,13 +42,11 @@ Output: `bin/` (image + packages) and `build-logs/`.
 
 **Build system is pure OpenWrt `make`** — no npm, pip, go build, or other language-specific tooling. All derivation runs inside the container.
 
-**Docs preview** (only when a local docs build is explicitly needed):
-```bash
-cd docs
-bundle config set --local path 'vendor/bundle'
-bundle install
-./prepare.sh && bundle exec jekyll serve
-```
+**Docs preview** (only when a local docs build is explicitly needed): see
+[`docs/README.md`](docs/README.md). The `github-pages` gems do not build on
+recent host Ruby (4.x), so the site is built in a `ruby:3.3` container and the
+`python3-nethsec` API docs are generated on top with pydoctor; the built
+`_site` is then served statically.
 
 ---
 
@@ -199,7 +197,6 @@ Existing Python files (listed in `ruff.toml` under `extend-exclude`) are grandfa
 
 | Repo | Purpose |
 |---|---|
-| [NethServer/nethsecurity-api](https://github.com/NethServer/nethsecurity-api) | Go API server (ns-api-server); handles JWT auth, 2FA, proxies to ubus/rpcd. **Vendored in-tree**: source lives at `packages/ns-api-server/files/src/` and is built directly from there (`Build/Prepare` copies it, no upstream fetch) — edit it in this repo, then mirror the change upstream to keep the two in sync |
 | [NethServer/python3-nethsec](https://github.com/NethServer/python3-nethsec) | Python utility library for APIs; used by all Python API scripts |
 | [NethServer/nethsecurity-ui](https://github.com/NethServer/nethsecurity-ui) | Vue 3 + Tailwind CSS management UI (standalone + controller modes); built as `ns-ui` package |
 | [NethServer/nethsecurity-monitoring](https://github.com/NethServer/nethsecurity-monitoring) | Go monitoring tools (ns-flows); reads netifyd flows, exposes REST API on localhost:8080 |

docs/README.md

@@ -1,24 +1,55 @@
 # Build the documentation
 
-The documentation is built using Github pages on each commit to the main branch.
+The documentation is built and published to GitHub Pages on each commit to the
+`main` branch by the `Build documentation` workflow.
+
+The site includes the auto-generated `python3-nethsec` API reference, produced
+with [pydoctor](https://pydoctor.readthedocs.io) and published under
+`/apidocs/python3-nethsec/` (linked from *Design → python3-nethsec API*).
 
 ## Build locally
 
-Tested on Fedora 36.
+The Jekyll dependencies (`github-pages`) pin old gems that do not build on
+recent Ruby (4.x). The reliable way to build locally is inside a container with
+an older Ruby, then generate the API docs on top of the built site.
 
-Install the dependciesm make sure to install ruby >= 3.0
-```
-dnf module install ruby
-dnf install ruby-devel
-```
+```bash
+cd docs
 
-Install jekyll and all dependencies:
+# 1. Build the Jekyll site in a container (avoids host Ruby version issues)
+podman run --rm -v "$PWD/..":/repo:Z -w /repo/docs ruby:3.3 bash -c '
+  gem install bundler -v 2.5.20 --no-document &&
+  bundle install &&
+  ./prepare.sh &&
+  bundle exec jekyll build'
+
+# 2. Generate the python3-nethsec API docs into the built site
+pip install docutils pydoctor
+pydoctor \
+  --project-name=python3-nethsec \
+  --make-html \
+  --html-output=./_site/apidocs/python3-nethsec \
+  --project-base-dir="$PWD/../packages/python3-nethsec" \
+  --docformat=restructuredtext \
+  --intersphinx=https://docs.python.org/3/objects.inv \
+  ../packages/python3-nethsec/src/nethsec
+
+# 3. Serve the built site
+python3 -m http.server 4000 --directory ./_site
+# open http://localhost:4000
 ```
+
+The site is served statically (step 3) rather than with `jekyll serve` so that
+a rebuild does not wipe the generated API docs.
+
+### Native build (only if the host Ruby can build the gems)
+
+On a host with Ruby 3.x you can build without a container:
+
+```bash
+cd docs
 bundle config set --local path 'vendor/bundle'
 bundle install
-```
-
-Build and serve the site locally:
-```
-./prepare.sh && bundle exec jekyll serve
+./prepare.sh && bundle exec jekyll build
+# then run steps 2 and 3 above
 ```

docs/design/python3-nethsec-apidocs.md

@@ -0,0 +1,14 @@
+---
+layout: default
+title: python3-nethsec API
+parent: Design
+---
+
+# python3-nethsec API reference
+
+The `nethsec` Python library is packaged in this repository under
+`packages/python3-nethsec`. Its API reference is generated automatically from
+the source with [pydoctor](https://pydoctor.readthedocs.io) each time the
+documentation is built.
+
+[Open the python3-nethsec API reference]({{ site.baseurl }}/apidocs/python3-nethsec/)

packages/python3-nethsec/.gitignore

@@ -0,0 +1,2 @@
+**/__pycache__/
+*.cpython*

packages/python3-nethsec/Containerfile

@@ -0,0 +1,33 @@
+FROM python:3.13.9
+RUN apt-get update \
+    && apt-get install -y \
+        cmake \
+        liblua5.1-0-dev \
+        lua5.1 \
+        libjson-c-dev
+
+RUN mkdir /tmp/requirements \
+    && git clone https://github.com/openwrt/libubox.git /tmp/requirements/libubox \
+    && cd /tmp/requirements/libubox \
+    && git checkout 815633847cd32ffe6da28943cbeb37edc88265c8 \
+    && cmake CMakeLists.txt \
+    && make install \
+    && git clone https://github.com/openwrt/ubus.git /tmp/requirements/ubus \
+    && cd /tmp/requirements/ubus \
+    && git checkout 3cc98db1a422dcf560f2d6347fd410f17565a89d \
+    && cmake CMakeLists.txt \
+    && make install \
+    && git clone https://github.com/openwrt/uci.git /tmp/requirements/uci \
+    && cd /tmp/requirements/uci \
+    && git checkout 66127cd76c5d0bd46d5a90302cc6110f53a4e2f8 \
+    && cmake CMakeLists.txt \
+    && make install \
+    && rm -rf /tmp/requirements \
+    && echo "/usr/local/lib" >> /etc/ld.so.conf.d/local.conf \
+    && ldconfig
+
+COPY requirements.txt /tmp/requirements.txt
+RUN pip install --no-cache-dir -r /tmp/requirements.txt \
+    && rm /tmp/requirements.txt
+WORKDIR /app
+CMD ["python3", "-m", "pytest"]