feat(codegen): CU-17tkuw5tebe publish release-bound osquery schemas

.github/workflows/release.yml

@@ -33,6 +33,16 @@ env:
 # =============================================================================
 
 jobs:
+  schema_test:
+    name: Test Release Schema Exporter
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -B -m unittest discover -s tools/codegen -p test_release_schema.py -v
+
   # cmake needs 3 semver components and no leading "v"
   version:
     name: "Resolve Version"
@@ -79,11 +89,13 @@ jobs:
             os: macos-15-intel
             os_arch: x86-64
             cmake_arch: x86_64
+            schema_arch: amd64
             artifact_name: osquery-macos-x64
           - name: "macOS ARM64"
             os: macos-15 # pinned: Xcode 26 on macos-latest fails to compile boost mpl
             os_arch: arm64
             cmake_arch: arm64
+            schema_arch: arm64
             artifact_name: osquery-macos-arm64
 
     steps:
@@ -164,6 +176,27 @@ jobs:
 
           echo "Build completed successfully"
 
+      - name: Export and verify release schema
+        env:
+          RELEASE_TAG: ${{ inputs.version || 'latest' }}
+          OSQUERY_VERSION: ${{ needs.version.outputs.version }}
+          SOURCE_COMMIT: ${{ github.sha }}
+        run: |
+          python3 tools/codegen/release_schema.py variant \
+            --native-specs build/specs/native_specs.txt \
+            --foreign-specs build/specs/foreign_specs.txt \
+            --platform darwin --architecture '${{ matrix.schema_arch }}' \
+            --release-tag "$RELEASE_TAG" --osquery-version "$OSQUERY_VERSION" \
+            --source-commit "$SOURCE_COMMIT" --binary build/osquery/osqueryd \
+            --output schema/osquery-schema.json
+
+      - name: Upload schema variant
+        uses: actions/upload-artifact@v4
+        with:
+          name: schema-darwin-${{ matrix.schema_arch }}
+          path: schema/osquery-schema.json
+          if-no-files-found: error
+
       - name: ccache statistics
         if: always()
         run: ccache --show-stats
@@ -266,6 +299,10 @@ jobs:
 
       - name: Setup MSBuild
         uses: microsoft/setup-msbuild@v2
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
 
       - name: Setup Visual Studio Build Tools
         uses: ilammy/msvc-dev-cmd@v1
@@ -283,6 +320,28 @@ jobs:
           cd build
           cmake --build . --config RelWithDebInfo -j10
 
+      - name: Export and verify release schema
+        shell: bash
+        env:
+          RELEASE_TAG: ${{ inputs.version || 'latest' }}
+          OSQUERY_VERSION: ${{ needs.version.outputs.version }}
+          SOURCE_COMMIT: ${{ github.sha }}
+        run: |
+          python tools/codegen/release_schema.py variant \
+            --native-specs build/specs/native_specs.txt \
+            --foreign-specs build/specs/foreign_specs.txt \
+            --platform windows --architecture amd64 \
+            --release-tag "$RELEASE_TAG" --osquery-version "$OSQUERY_VERSION" \
+            --source-commit "$SOURCE_COMMIT" --binary build/osquery/RelWithDebInfo/osqueryd.exe \
+            --output schema/osquery-schema.json
+
+      - name: Upload schema variant
+        uses: actions/upload-artifact@v4
+        with:
+          name: schema-windows-amd64
+          path: schema/osquery-schema.json
+          if-no-files-found: error
+
       - name: Sign Windows package
         uses: ./.github/steps/sign-windows-package
         with:
@@ -307,7 +366,7 @@ jobs:
 
   release:
     name: "Create Release"
-    needs: [build_macos, create_universal_macos, build_windows]
+    needs: [schema_test, build_macos, create_universal_macos, build_windows]
     runs-on: ubuntu-latest
     if: |
       github.event_name == 'push' ||
@@ -324,6 +383,18 @@ jobs:
         with:
           path: release-artifacts
 
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Aggregate matching build schemas
+        run: |
+          python tools/codegen/release_schema.py aggregate \
+            --variants release-artifacts/schema-darwin-amd64/osquery-schema.json \
+              release-artifacts/schema-darwin-arm64/osquery-schema.json \
+              release-artifacts/schema-windows-amd64/osquery-schema.json \
+            --output final-artifacts/osquery-schema.json
+
       - name: Prepare release artifacts
         run: |
           set -e
@@ -350,12 +421,20 @@ jobs:
 
           ls -lh final-artifacts/clients/
 
+      - name: Hash release artifacts
+        run: |
+          cd final-artifacts
+          sha256sum osquery-schema.json clients/* > SHA256SUMS
+
       - name: Generate release header
         run: |
           cat > RELEASE_HEADER.md <<EOF
           ## OSQuery Clients
           - **macOS** (Universal): \`osquery-macos-universal.tar.gz\`
           - **Windows** (amd64): \`osquery-windows-amd64.zip\`
+          - **Versioned table schema**: \`osquery-schema.json\`
+          - **Schema SHA-256**: \`osquery-schema.json.sha256\`
+          - **Checksums**: \`SHA256SUMS\`
           EOF
 
       - name: Delete existing latest release
@@ -373,5 +452,9 @@ jobs:
           prerelease: ${{ github.event_name == 'push' }}
           token: ${{ secrets.GITHUB_TOKEN }}
           body_path: RELEASE_HEADER.md
+          fail_on_unmatched_files: true
           files: |
             final-artifacts/clients/*
+            final-artifacts/osquery-schema.json
+            final-artifacts/osquery-schema.json.sha256
+            final-artifacts/SHA256SUMS

.github/workflows/test.yml

@@ -32,6 +32,16 @@ env:
 # =============================================================================
 
 jobs:
+  schema_test:
+    name: Test Release Schema Exporter
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -B -m unittest discover -s tools/codegen -p test_release_schema.py -v
+
   build_macos:
     name: "Build C Client for (${{ matrix.os }} ${{ matrix.os_arch }})"
     runs-on: ${{ matrix.os }}
@@ -47,11 +57,13 @@ jobs:
             os: macos-15-intel
             os_arch: x86-64
             cmake_arch: x86_64
+            schema_arch: amd64
             artifact_name: osquery-macos-x64
           - name: "macOS ARM64"
             os: macos-15 # pinned: Xcode 26 on macos-latest fails to compile boost mpl
             os_arch: arm64
             cmake_arch: arm64
+            schema_arch: arm64
             artifact_name: osquery-macos-arm64
     steps:
       - name: Checkout
@@ -131,6 +143,17 @@ jobs:
 
           echo "Build completed successfully"
 
+      - name: Verify built table schema
+        env:
+          SOURCE_COMMIT: ${{ github.sha }}
+        run: |
+          python3 tools/codegen/release_schema.py variant \
+            --native-specs build/specs/native_specs.txt \
+            --foreign-specs build/specs/foreign_specs.txt \
+            --platform darwin --architecture '${{ matrix.schema_arch }}' \
+            --release-tag pr-test --osquery-version 5.9.1 --source-commit "$SOURCE_COMMIT" \
+            --binary build/osquery/osqueryd --output schema/osquery-schema.json
+
       - name: ccache statistics
         if: always()
         run: ccache --show-stats
@@ -158,6 +181,10 @@ jobs:
 
       - name: Setup MSBuild
         uses: microsoft/setup-msbuild@v2
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
 
       - name: Setup Visual Studio Build Tools
         uses: ilammy/msvc-dev-cmd@v1
@@ -175,9 +202,21 @@ jobs:
           cd build
           cmake --build . --config RelWithDebInfo -j10
 
+      - name: Verify built table schema
+        shell: bash
+        env:
+          SOURCE_COMMIT: ${{ github.sha }}
+        run: |
+          python tools/codegen/release_schema.py variant \
+            --native-specs build/specs/native_specs.txt \
+            --foreign-specs build/specs/foreign_specs.txt \
+            --platform windows --architecture amd64 \
+            --release-tag pr-test --osquery-version 5.9.1 --source-commit "$SOURCE_COMMIT" \
+            --binary build/osquery/RelWithDebInfo/osqueryd.exe --output schema/osquery-schema.json
+
   all-checks:
     name: "All Checks"
-    needs: [build_macos, build_windows]
+    needs: [schema_test, build_macos, build_windows]
     runs-on: ubuntu-latest
     if: always()
     steps:

tools/codegen/CMakeLists.txt

@@ -118,6 +118,8 @@ function(generateTables category)
     list(APPEND table_spec_list "${CMAKE_SOURCE_DIR}/specs/${relative_table_spec}")
   endforeach()
 
+  file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/${category}_specs.txt" "${table_spec_list}")
+
   # Iterate through each table spec file
   set(output_folder "${CMAKE_CURRENT_BINARY_DIR}/${category}")
 

tools/codegen/RELEASE_SCHEMA.md

@@ -0,0 +1,56 @@
+# Released osquery schema
+
+The osquery release publishes `osquery-schema.json` and
+`osquery-schema.json.sha256` alongside the macOS universal and Windows binaries.
+The JSON is generated from the same checkout and CMake-selected specs as each
+binary. Publication requires all three build variants and matching provenance.
+
+## Contract (formatVersion 1)
+
+- `releaseTag`: exact GitHub release tag, including a leading `v` when supplied.
+- `osqueryVersion`: resolved CMake engine version (the fork release version).
+- `sourceCommit`: full 40-character checkout commit SHA.
+- `variants`: Darwin amd64, Darwin arm64, Windows amd64; each has `platform`,
+  `architecture` and `tables`.
+- Table: `name`, `aliases` (string array), `description`, `notes`, `url` (strings),
+  `examples` (string array), `availability`, `attributes` (spec attribute object),
+  `foreignKeys` (`{column, table}` array), `columns`.
+- Column: `name`, `aliases` (string array), SQL `type` (lowercase), `description`,
+  `notes`, `platforms` (string array), `options` (spec options object such as
+  `required`, `hidden`, `index`, `optimized`, `additional`, `collate`).
+
+`availability` is `native`, `foreign` or `disabled`. Foreign tables are registered
+empty-result placeholders. They do not establish native platform support.
+Platform-specific columns retain their platform list; an empty list means no
+column-level restriction within that variant. Hidden columns can be selected
+explicitly and are not automatically invalid SQL. Runtime event configuration,
+permissions and extensions remain separate from compiled schema availability.
+
+The checksum is SHA-256 of the exact complete JSON asset bytes, before decoding
+or reserialization. The sidecar uses `HASH  osquery-schema.json\n`, with a lowercase
+64-character hexadecimal hash. There is no embedded checksum or canonical JSON
+requirement. `SHA256SUMS` additionally covers the schema and binary archives.
+
+## Build and release checks
+
+CMake writes `build/specs/native_specs.txt` and `foreign_specs.txt` using its actual
+selected source lists. `release_schema.py variant` reads those manifests, applies
+the target platform to the upstream spec parser, and verifies version, table,
+column and alias registration using the just-built executable in shell mode.
+Metadata queries do not execute the table's data collection query.
+
+`release_schema.py aggregate` requires exactly the three supported variants with
+the same format, release tag, engine version and source commit. Release and PR CI
+run the exporter tests; each platform build verifies its own schema.
+
+The existing mutable `latest` prerelease retains its exact source and engine
+provenance. It does not prove a device has that build. Consumers must distinguish
+catalog provenance from verified installed platform, architecture and version.
+Older releases without an artifact remain unconfirmed rather than falling back
+to another version's schema.
+
+Run the local exporter tests with:
+
+```sh
+python3 -B -m unittest discover -s tools/codegen -p test_release_schema.py -v
+```