diff --git a/.github/workflows/plugin-release.yml b/.github/workflows/plugin-release.yml new file mode 100644 index 0000000..119b5c0 --- /dev/null +++ b/.github/workflows/plugin-release.yml @@ -0,0 +1,48 @@ +name: Build the QGIS plugin + +# Builds Castlegate Server's zip and attaches it to a GitHub release whose tag +# is the plugin's folder name and version, such as castlegate_server@0.1.0. +# The zip is uploaded to plugins.qgis.org by hand (RELEASING.md). + +on: + release: + types: + - published + +permissions: + contents: write + +jobs: + build: + name: Build castlegate_server + if: startsWith(github.event.release.tag_name, 'castlegate_server@') + runs-on: ubuntu-24.04 + timeout-minutes: 10 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 + with: + python-version: '3.12' + - name: Check the tag matches the plugin's version + env: + TAG: ${{ github.event.release.tag_name }} + run: | + version=$(python -c "import configparser; p = configparser.ConfigParser(); p.read('server/castlegate_server/metadata.txt', encoding='utf-8'); print(p['general']['version'])") + expected="castlegate_server@$version" + if [ "$TAG" != "$expected" ]; then + echo "::error::The release's tag is $TAG, but server/castlegate_server/metadata.txt gives $expected. Change the version in metadata.txt, or publish a release tagged $expected." + exit 1 + fi + - name: Tests + run: | + python -m unittest discover -s tests/core -t . + python -m unittest discover -s tests/plugin -t . + - name: Build the zip + id: zip + run: echo "path=$(python scripts/build.py "$RUNNER_TEMP/plugin" | tail -n 1)" >> "$GITHUB_OUTPUT" + - name: Attach the zip to the release + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ github.event.release.tag_name }} + ZIP: ${{ steps.zip.outputs.path }} + run: gh release upload "$TAG" "$ZIP" --repo "$GITHUB_REPOSITORY" diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..560614e --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,12 @@ +# Releasing Castlegate Server + +1. Set the new version in `server/castlegate_server/metadata.txt` and in `VERSION` in `server/castlegate_server/status.py`, and merge it to `main`. `tests/plugin/test_build.py` fails while the two differ. +2. Publish a GitHub release from `main` whose tag is the plugin's folder name and that version, such as `castlegate_server@0.1.0`. +3. The [Build the QGIS plugin](.github/workflows/plugin-release.yml) workflow checks the tag against the version, runs the core and plugin tests, builds the zip with `scripts/build.py` and attaches it to the release. +4. Upload that zip at [plugins.qgis.org](https://plugins.qgis.org/plugins/add/). + +The plugin is marked experimental in `metadata.txt`, so QGIS's Plugin Manager lists it only where **Show also experimental plugins** is ticked. + +## The QGIS plugin repository's checks + +The repository scans each upload with Bandit and detect-secrets, and blocks a version with any finding. `server/castlegate_server/.bandit`, which the zip carries beside `metadata.txt`, skips the one finding whose reason it gives; the repository then lists the version as "Validated (configured)". It also runs a Qt6 check, which does not block a version. diff --git a/install/README.md b/install/README.md index 1a4a902..5e9de8b 100644 --- a/install/README.md +++ b/install/README.md @@ -7,7 +7,7 @@ The plugin is the same on every web server. It reads its settings from environme 3. setting the plugin's environment variables and `QGIS_PLUGINPATH`; 4. running QGIS Server, restarting it, and keeping its log. -Each folder here does those four jobs for one web server, and each ends with the same status check. +Each folder here does those four jobs for one web server, and each ends with the same status check. Each starts from the release zip, `castlegate_server-.zip`, attached to each release on the repository's [Releases](https://github.com/vectoriahq/castlegate/releases) page. | Folder | State | | --- | --- | diff --git a/scripts/build.py b/scripts/build.py index 29eca2d..1f54ccb 100644 --- a/scripts/build.py +++ b/scripts/build.py @@ -3,8 +3,8 @@ python scripts/build.py [output folder] A QGIS plugin is installed as one self-contained folder, so the shared core is -copied into it here rather than installed beside it, and so is the status check -from install/common/, as tools/check.py. Writes +copied into it here rather than installed beside it, and so are the status check +from install/common/, as tools/check.py, and the repository's LICENSE. Writes /castlegate_server/ and /castlegate_server-.zip; the output folder defaults to build/. """ @@ -29,6 +29,8 @@ def build(out): # The status check every install profile ends with, so it ships with the plugin. (plugin / "tools").mkdir() shutil.copy2(ROOT / "install" / "common" / "check.py", plugin / "tools" / "check.py") + # The QGIS plugin repository refuses a zip without a LICENSE in the plugin's folder. + shutil.copy2(ROOT / "LICENSE", plugin / "LICENSE") metadata = configparser.ConfigParser() metadata.read(plugin / "metadata.txt", encoding="utf-8") version = metadata["general"]["version"] diff --git a/server/castlegate_server/.bandit b/server/castlegate_server/.bandit new file mode 100644 index 0000000..9622732 --- /dev/null +++ b/server/castlegate_server/.bandit @@ -0,0 +1,8 @@ +[bandit] +# B405 flags the import of xml.etree. transaction.py reads a WFS request's body, +# which comes from the request. Every parse goes through _parse, whose expat +# parser refuses any document type declaration and entity declaration; +# ElementTree only builds the tree from what expat accepts. No body over +# MAX_BODY_BYTES is parsed: read() refuses one, and is_transaction() counts one +# as a Transaction without parsing it, so read() refuses it. +skips = B405 diff --git a/server/castlegate_server/metadata.txt b/server/castlegate_server/metadata.txt index 3e5f566..a0b71f0 100644 --- a/server/castlegate_server/metadata.txt +++ b/server/castlegate_server/metadata.txt @@ -2,10 +2,27 @@ name=Castlegate Server qgisMinimumVersion=3.36 qgisMaximumVersion=4.99 -description=Per-person access to QGIS Server layers, features and fields, from a rules table and an OpenID Connect sign-in. -about=Castlegate checks each request's bearer token and answers QGIS Server's access-control questions from a rules table that is a layer of the project. It refuses services other than WMS and WFS, and saves that set a field the person may not change. +description=Lets QGIS Server give each signed-in person only the layers, features, fields and edits a rules table in the project allows, with OpenID Connect sign-in such as Microsoft Entra ID. +about=Castlegate gives each person who signs in to QGIS Server their own share of a project: the layers, features and fields they may read, and the edits they may make. People sign in with their organisation account through OpenID Connect, such as Microsoft Entra ID, and Castlegate checks the access token each request carries. + + The rules are a table in the QGIS project, edited in QGIS like any other table, with rows naming a user or a group and a layer: + - which layers they read; the rest are left out of the capabilities and of every response + - which features they read and which they may edit, each as a QGIS expression + - fields whose values are hidden from them, and fields they read but may not set + - inserting, updating attributes, updating geometry and deleting, each allowed on its own + + A request with no valid token gets nothing but a 401. A WFS-T transaction that sets a hidden or read-only field, or touches a feature the person may not edit, is refused. An error inside Castlegate refuses the request. Each edit is written to QGIS Server's log with the person who made it. + + Castlegate protects the WMS and WFS services and refuses every other service. It does not protect the database itself. + + Experimental: Castlegate has not yet been reviewed by anyone outside Vectoria. The repository holds the setup guides for IIS, Apache, nginx and Docker, the rules table's columns, the known limits and the brief for a security reviewer. version=0.1.0 author=Vectoria -email=simon.okeefe@vectoria.com.au +email=castlegate@vectoria.com.au server=True +experimental=True +homepage=https://github.com/vectoriahq/castlegate +tracker=https://github.com/vectoriahq/castlegate/issues +repository=https://github.com/vectoriahq/castlegate +tags=qgis server,security,access control,authentication,openid connect,wfs,wms icon=icon.png diff --git a/server/castlegate_server/request_filter.py b/server/castlegate_server/request_filter.py index aaa8fca..f002584 100644 --- a/server/castlegate_server/request_filter.py +++ b/server/castlegate_server/request_filter.py @@ -82,7 +82,7 @@ def onRequestReady(self): try: self._refuse("the request was refused") except Exception: # noqa: BLE001 - pass + log("refusing the request failed: " + traceback.format_exc(), Qgis.MessageLevel.Critical) return True # ---- once the project is open ------------------------------------------------------ diff --git a/server/castlegate_server/status.py b/server/castlegate_server/status.py index 1ac8459..d84747c 100644 --- a/server/castlegate_server/status.py +++ b/server/castlegate_server/status.py @@ -43,7 +43,7 @@ def executeRequest(self, request, response, project): try: response.setStatusCode(500) except Exception: # noqa: BLE001 - pass + log("setting the status answer's 500 failed: " + traceback.format_exc(), Qgis.MessageLevel.Critical) def _body(self, response): state = self.plugin.state diff --git a/server/castlegate_server/transaction.py b/server/castlegate_server/transaction.py index 096df5c..6ac175b 100644 --- a/server/castlegate_server/transaction.py +++ b/server/castlegate_server/transaction.py @@ -82,7 +82,14 @@ def tag(name): def is_transaction(body): - """Whether the body's root element is a WFS Transaction; False for a body that is not XML.""" + """ + Whether the body's root element is a WFS Transaction; False for a body that + is not XML. A body over MAX_BODY_BYTES is not parsed and counts as one, so + read() refuses it: answering False would pass a large Transaction to QGIS + Server unread. + """ + if len(body) > MAX_BODY_BYTES: + return True try: return _local(_parse(body).tag) == "Transaction" except TransactionError: diff --git a/spike/plugin/castlegate_spike/metadata.txt b/spike/plugin/castlegate_spike/metadata.txt index 82bc5b6..f9f85b3 100644 --- a/spike/plugin/castlegate_spike/metadata.txt +++ b/spike/plugin/castlegate_spike/metadata.txt @@ -4,5 +4,5 @@ qgisMinimumVersion=3.28 description=Package 1 prototype of per-person access control for QGIS Server. Not for production. version=0.0.1 author=Vectoria -email=simon.okeefe@vectoria.com.au +email=castlegate@vectoria.com.au server=True diff --git a/tests/plugin/test_build.py b/tests/plugin/test_build.py new file mode 100644 index 0000000..a519ce4 --- /dev/null +++ b/tests/plugin/test_build.py @@ -0,0 +1,67 @@ +"""scripts/build.py's zip holds what the QGIS plugin repository asks of an upload, in plain Python.""" + +import configparser +import importlib.util +import pathlib +import re +import tempfile +import unittest +import zipfile + +ROOT = pathlib.Path(__file__).resolve().parents[2] +_spec = importlib.util.spec_from_file_location("castlegate_build", ROOT / "scripts" / "build.py") +build = importlib.util.module_from_spec(_spec) +_spec.loader.exec_module(build) + +# The fields the QGIS plugin repository's validator refuses an upload without. +REQUIRED = ("name", "qgisMinimumVersion", "description", "about", "version", "author", "email", "repository") + + +def _metadata(): + # The repository reads metadata.txt with configparser's default interpolation, so a "%" in it fails the upload. + parser = configparser.ConfigParser() + parser.read(ROOT / "server" / "castlegate_server" / "metadata.txt", encoding="utf-8") + return parser["general"] + + +class BuildTest(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls._work = tempfile.TemporaryDirectory() + _, cls.archive = build.build(cls._work.name) + with zipfile.ZipFile(cls.archive) as z: + cls.names = z.namelist() + + @classmethod + def tearDownClass(cls): + cls._work.cleanup() + + def test_is_named_for_the_version(self): + self.assertEqual(self.archive.name, "castlegate_server-%s.zip" % _metadata()["version"]) + + def test_holds_one_folder(self): + self.assertEqual({name.split("/")[0] for name in self.names}, {"castlegate_server"}) + + def test_holds_the_licence_and_the_bandit_settings_beside_metadata(self): + # The repository refuses a zip without LICENSE, and reads .bandit only at the plugin's top level. + for name in ("metadata.txt", "__init__.py", "LICENSE", ".bandit", "core/__init__.py"): + self.assertIn("castlegate_server/" + name, self.names) + + def test_holds_no_compiled_python(self): + self.assertEqual([name for name in self.names if re.search(r"__pycache__|\.pyc$", name)], []) + + def test_metadata_has_every_required_field_and_its_icon(self): + metadata = _metadata() + self.assertEqual([field for field in REQUIRED if not metadata.get(field)], []) + self.assertIn("castlegate_server/" + metadata["icon"], self.names) + + def test_metadata_marks_the_plugin_experimental(self): + self.assertEqual(_metadata().getboolean("experimental"), True) + + def test_the_status_answer_reports_the_version_in_metadata(self): + status = (ROOT / "server" / "castlegate_server" / "status.py").read_text(encoding="utf-8") + self.assertEqual(re.search(r'^VERSION = "([^"]+)"', status, re.M).group(1), _metadata()["version"]) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/plugin/test_transaction.py b/tests/plugin/test_transaction.py index 2d52b83..97cb856 100644 --- a/tests/plugin/test_transaction.py +++ b/tests/plugin/test_transaction.py @@ -138,6 +138,15 @@ def test_is_transaction(self): self.assertFalse(is_transaction(tx("", root="wfs:GetFeature"))) self.assertFalse(is_transaction(b"not xml")) + def test_a_body_over_the_limit_is_not_parsed_and_counts_as_a_transaction(self): + # Review finding on #14: is_transaction() parsed a body of any size before read() checked it. + from castlegate_server import transaction + + body = b"" + b" " * transaction.MAX_BODY_BYTES + b"" + self.assertTrue(is_transaction(body)) + with self.assertRaisesRegex(TransactionError, "too large"): + read(body) + if __name__ == "__main__": unittest.main()