diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md deleted file mode 100644 index 26942972..00000000 --- a/.github/CONTRIBUTING.md +++ /dev/null @@ -1,14 +0,0 @@ - -## Pull Requests - -Please fork our repository and then raise a Pull Request (PR) against our `dev` branch. Please add a fulsome description in the Pull Request comment. We will attend to it and work with you as soon as possible. - -Once the PR is approved, we will sign any changed files, package for distribution and squash / merge the combined change set into the `dev` branch. Once merged into `dev`, changes will instantly be available to `stackql` applications configured to integrate the `dev` registry. After an additional period of monitoring from the team, it will be promoted to our main / production branch. This equates to publication for default configured instances of `stackql`. - -## Provider Document Requirements - -Provider documents are signed and published by CI after merge, so the pipeline enforces the layout below and rejects anything else: - -- documents live at `providers/src//v00.00.00000/provider.yaml` and `providers/src//v00.00.00000/services/.yaml`, nothing else is permitted under the version directory -- provider directory names and service file names must start with a letter, digit or `_` and contain only letters, digits, `.`, `_` and `-` -- every entry must be a regular file or directory; symbolic links are not permitted anywhere under `providers/src` diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index c9fad733..8a78265a 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -173,6 +173,11 @@ jobs: AWS_REGION: auto R2_BUCKET: stackql-provider-registry-dev run: | + # verify R2's TLS chain against the certifi bundle pinned in requirements.txt: the AWS CLI's + # embedded bundle still trusts the Sectigo AAA root that cross-signs the eMudhra + # intermediates compromised in Oct 2026, and the CLI ships no fix for that path + export AWS_CA_BUNDLE="$(python -c 'import certifi; print(certifi.where())')" + test -s "${AWS_CA_BUNDLE}" || { echo "certifi CA bundle not found"; exit 1; } # version-pinned .tgz are immutable -> --size-only keeps R2 ops low and skips re-uploads aws s3 sync "${REG_WEBSITE_DIR}/${REG_PROVIDER_PATH}" "s3://${R2_BUCKET}/${REG_PROVIDER_PATH}" \ --endpoint-url "https://${{ secrets.CLOUDFLARE_ACCOUNT_ID }}.r2.cloudflarestorage.com" \ @@ -192,6 +197,11 @@ jobs: AWS_REGION: auto R2_BUCKET: stackql-provider-registry run: | + # verify R2's TLS chain against the certifi bundle pinned in requirements.txt: the AWS CLI's + # embedded bundle still trusts the Sectigo AAA root that cross-signs the eMudhra + # intermediates compromised in Oct 2026, and the CLI ships no fix for that path + export AWS_CA_BUNDLE="$(python -c 'import certifi; print(certifi.where())')" + test -s "${AWS_CA_BUNDLE}" || { echo "certifi CA bundle not found"; exit 1; } aws s3 sync "${REG_WEBSITE_DIR}/${REG_PROVIDER_PATH}" "s3://${R2_BUCKET}/${REG_PROVIDER_PATH}" \ --endpoint-url "https://${{ secrets.CLOUDFLARE_ACCOUNT_ID }}.r2.cloudflarestorage.com" \ --size-only --delete --no-progress diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..2da55b80 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,59 @@ +**Note**: + +- All contributions to the StackQL Provider Registry, through any means, are subject to the [license](/LICENSE). +- Provider documents merged into this repository are signed with StackQL keys and published to the public registry used by every default configured `stackql` installation. The review and CI requirements below are enforced for that reason. +- For how the registry is built, tested and published, see [docs/build-and-deployment.md](/docs/build-and-deployment.md). For the signing scheme, see [docs/signing-and-verification.md](/docs/signing-and-verification.md). For running the test suites locally, see [docs/test-developer-guide.md](/docs/test-developer-guide.md). + +# Contribution flow + +For a new provider, or a substantive change to an existing one (for example, regenerating a provider from a new upstream specification, or changing its authentication configuration), please raise an issue first and receive consensus that the work should proceed. Targeted fixes to existing provider documents, such as a wrong path, a missing field or a response schema correction, can go straight to a pull request. + +## Pull Requests + +Please fork our repository and then raise a Pull Request (PR) against our `dev` branch. Please add a fulsome description in the Pull Request comment: the provider(s) and service(s) changed, the source of the upstream specification where applicable, and evidence that the affected resources work (for example, `stackql` query output). A usefully named feature branch for the PR source is appreciated. We will attend to it and work with you as soon as possible. + +Once the PR is approved, we will sign any changed files, package for distribution and squash / merge the combined change set into the `dev` branch. Once merged into `dev`, changes will instantly be available to `stackql` applications configured to integrate the `dev` registry. After an additional period of monitoring from the team, it will be promoted to our main / production branch. This equates to publication for default configured instances of `stackql`. + +## Provider Document Requirements + +Provider documents are signed and published by CI after merge, so the pipeline enforces the layout below and rejects anything else: + +- documents live at `providers/src//v00.00.00000/provider.yaml` and `providers/src//v00.00.00000/services/.yaml`, nothing else is permitted under the version directory +- provider directory names and service file names must start with a letter, digit or `_` and contain only letters, digits, `.`, `_` and `-` +- every entry must be a regular file or directory; symbolic links are not permitted anywhere under `providers/src` + +The `v00.00.00000` directory name is a placeholder. CI allocates the published version (`v..`) when the PR is built and stamps it into `provider.yaml`, so leave the directory name as is. + +## CI Checks + +Every PR to `dev` or `main` that touches `providers/src` runs the [Build and Deploy workflow](/.github/workflows/main.yml), which signs and packages the changed providers and runs end-to-end tests against them using [stackql-provider-tests](https://github.com/stackql/stackql-provider-tests). The tests check that each document is a valid OpenAPI specification, that every service and resource is enumerable, and that `SELECT` and `INSERT` methods have valid response and request schemas. See [provider tests](/docs/build-and-deployment.md#provider-tests-if-providers-were-updated) for details. A PR will not be merged with failing tests. + +A separate [provider delete guard](/docs/build-and-deployment.md#provider-delete-guard) fails any push or PR that removes a provider from `providers/src`. If a removal is intentional, add the override token described there to the commit message. Do not use `[skip ci]` on commits that touch `providers/src`, as it also skips the guard. + +## Developing and Testing a Provider + +Providers are generated from OpenAPI or Swagger specifications using [openapisaurus](https://github.com/stackql/openapisaurus); see [Developing a Provider](/README.md#developing-a-provider) in the README. + +To exercise a provider document before raising a PR, point `stackql` at your local checkout as an unsigned registry (this is the same configuration the repository's own robot tests use): + +```bash +export LOCAL_REG="{ \"url\": \"file:///path/to/stackql-provider-registry/providers\", \"verifyConfig\": { \"nopVerify\": true } }" +./stackql --registry="${LOCAL_REG}" shell +``` + +Once merged into `dev`, the change can be verified against the `dev` registry: + +```bash +export DEV_REG="{ \"url\": \"https://registry-dev.stackql.app/providers\" }" +./stackql --registry="${DEV_REG}" shell +``` + +## Changes to the Pipeline and Tooling + +Changes outside `providers/src` (the GitHub Actions workflows, `scripts/`, the signing tool under `signing/` and the Cloudflare Worker under `origin/`) affect how every provider is published and served. Please raise an issue to discuss these before opening a PR. Security issues should not be raised as issues or PRs; see [SECURITY.md](/SECURITY.md). + +Finally, in respect of all your efforts; we thank you and ask that you please give us a star while you are at it. + +Many Thanks, + +The StackQL team. diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..81436d18 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2022 StackQL Studios + +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. \ No newline at end of file diff --git a/README.md b/README.md index ac724feb..6d4816f1 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ The public StackQL Provider Registry is served from Cloudflare, using the follow ## Contributing -Please see [.github/CONTRIBUTING.md](/.github/CONTRIBUTING.md). +Please see [CONTRIBUTING.md](/CONTRIBUTING.md). ## Developing a Provider diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..a388578f --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,52 @@ +# Security Policy + +The StackQL team takes the security of the StackQL Provider Registry seriously. Provider documents published from this repository are pulled and executed by every `stackql` installation, so a defect here can affect many users. We appreciate everyone who reports vulnerabilities responsibly, and we will do our best to acknowledge and address valid reports promptly. + +## Reporting a Vulnerability + +Please do not open a public GitHub issue or pull request for security reports. A public issue discloses the problem before a fix is available and puts users at risk. + +Instead, report privately using GitHub private vulnerability reporting: + +1. Open the [new advisory form](https://github.com/stackql/stackql-provider-registry/security/advisories/new) (Security tab -> Advisories -> "Report a vulnerability"). +2. Provide as much detail as you can: the affected provider(s) and version(s) (as shown by `REGISTRY LIST`), reproduction steps, impact, and any suggested remediation. +3. Submit. This opens a private advisory thread visible only to you and the maintainers. + +If you cannot use GitHub private vulnerability reporting, email us at [info@stackql.io](mailto:info@stackql.io). Please put "SECURITY" in the subject line and treat the contents as confidential. + +## Supported Versions + +The registry is a continuously published service rather than a versioned release. Each provider is published as an immutable, signed version (`v..`) when a change is merged, and the registry serves the latest published version of each provider by default. + +Security fixes are published as a new version of the affected provider, first to the `dev` registry (`registry-dev.stackql.app`) and then to the production registry (`registry.stackql.app`). Previously published versions are not patched. To pick up a fix, pull the latest version of the affected provider: + +```sql +REGISTRY PULL ; +``` + +## Response Expectations + +These are targets, not contractual guarantees: + +- We aim to acknowledge a report within a few business days. +- We will keep you updated as we investigate and work on a fix. +- We will coordinate disclosure timing with you once a fix or mitigation is ready. + +## Disclosure Policy + +We follow coordinated (responsible) disclosure. Please give us a reasonable opportunity to release a fix before any public disclosure. We are happy to credit reporters in the advisory and release notes, unless you prefer to remain anonymous. + +## Scope + +This policy covers the contents of this repository and the services published from it: + +- provider interface documents under `providers/src`, for example a document that directs `stackql` to send requests or credentials to an unintended host, misconfigures authentication, or maps a mutating API operation to a `SELECT` method +- the signing and verification tooling under `signing/`, including the embedded certificate bundles, and the build, packaging and publishing pipeline under `.github/workflows` and `scripts/` +- the registry origin: the Cloudflare Worker under `origin/` and the `registry.stackql.app` and `registry-dev.stackql.app` endpoints +- credentials or other secrets inadvertently committed to this repository + +The following are out of scope for this repository and should be reported elsewhere: + +- the `stackql` engine itself, including how it verifies and consumes registry documents: report via the [stackql](https://github.com/stackql/stackql/security/advisories/new) advisory form +- the request-execution library: report to [any-sdk](https://github.com/stackql/any-sdk) +- vulnerabilities in the third-party services that providers describe (for example, a cloud vendor's API): report those to the vendor. The registry only describes how to call these APIs. diff --git a/requirements.txt b/requirements.txt index 25e7f9eb..c5cce5fc 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,6 @@ boto3>=1.37.24 +# certifi 2026.10.19 and later drop emSign ECC Root CA - G3, the root behind the eMudhra intermediates compromised in Oct 2026; boto3/botocore verify TLS with this bundle +certifi>=2026.10.19 PyYaml>=6.0.1 requests==2.33.0 robotframework==6.1.1 \ No newline at end of file