Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

feat(release): publish the npm and PyPI packages the README advertises (#653)

Beenu Aroraba62bdad401e
diff --git a/.github/workflows/readme-gates.yml b/.github/workflows/readme-gates.yml
index 6c8655d38..4728f0fee 100644
--- a/.github/workflows/readme-gates.yml
+++ b/.github/workflows/readme-gates.yml
@@ -36,6 +36,11 @@ on:
- 'scripts/readme_gates.py'
- '.github/workflows/readme-gates.yml'
workflow_dispatch:
+ # The published-onramp job below checks the public registries, so it has to
+ # run on a clock as well as on diff — a package can break (or be yanked)
+ # without anyone touching this repo.
+ schedule:
+ - cron: '0 6 * * *'
permissions:
contents: read
@@ -104,3 +109,77 @@ jobs:
python3 -m pip install pytest
cd packages/aisoc-sandbox
PYTHONPATH=src python3 -m pytest tests/ -q
+
+ # The `static` gate above proves the README does not *reference* a package
+ # that fails to resolve. It cannot prove the advertised command actually
+ # works, and the `sandbox-offline` gate installs from source rather than
+ # from PyPI. Between them, `npx aisoc triage --demo` could sit on the front
+ # page indefinitely while no such package existed — which is exactly what
+ # happened.
+ #
+ # This job closes that by running the on-ramps a visitor would run, against
+ # the public registries, on a clean machine. It is self-arming: while a
+ # package is unpublished it warns and passes, and the moment it exists the
+ # command becomes a hard requirement.
+ published-onramp:
+ name: Published on-ramp · registry install (${{ matrix.os }})
+ runs-on: ${{ matrix.os }}
+ timeout-minutes: 15
+ strategy:
+ fail-fast: false
+ matrix:
+ os: [ubuntu-latest, macos-latest]
+
+ steps:
+ - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v6
+ with:
+ node-version: '22'
+
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+ with:
+ python-version: '3.11'
+
+ # Deliberately no checkout: a visitor running the README's hero command
+ # does not have the repo, and neither should this job.
+ - name: npx aisoc triage --demo
+ run: |
+ set -uo pipefail
+ if ! npm view aisoc version >/dev/null 2>&1; then
+ echo "::warning title=on-ramp::'aisoc' is not on npm yet, so the README hero command cannot be verified. This gate arms itself on first publish."
+ exit 0
+ fi
+ echo "npm has aisoc@$(npm view aisoc version) — the hero command must work."
+ out=$(npx --yes aisoc@latest triage --demo --no-telemetry 2>&1) || {
+ echo "$out"
+ echo "::error title=on-ramp::'npx aisoc triage --demo' is published but failed. The README's hero command is broken for every visitor."
+ exit 1
+ }
+ echo "$out"
+ echo "$out" | grep -qi 'triaged' || {
+ echo "::error title=on-ramp::'npx aisoc triage --demo' ran but printed no triage summary."
+ exit 1
+ }
+
+ - name: pip install aisoc-sandbox && aisoc-sandbox demo
+ run: |
+ set -uo pipefail
+ if ! python3 -m pip download aisoc-sandbox --no-deps --dest "$RUNNER_TEMP/probe" >/dev/null 2>&1; then
+ echo "::warning title=on-ramp::'aisoc-sandbox' is not on PyPI yet, so the documented pip path cannot be verified. This gate arms itself on first publish."
+ exit 0
+ fi
+ echo "PyPI has aisoc-sandbox — the documented pip path must work."
+ python3 -m pip install --quiet aisoc-sandbox || {
+ echo "::error title=on-ramp::'pip install aisoc-sandbox' is published but failed to install."
+ exit 1
+ }
+ out=$(aisoc-sandbox demo --json 2>&1) || {
+ echo "$out"
+ echo "::error title=on-ramp::'aisoc-sandbox demo' is published but failed to run."
+ exit 1
+ }
+ python3 -c "
+ import json, sys
+ steps = json.loads(sys.argv[1])['ledger']
+ assert len(steps) == 4, f'expected 4 ledger steps, got {len(steps)}'
+ print(f' {len(steps)} steps · final-agent={steps[-1][\"agent\"]}')
+ " "$out"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index f65ff1a88..6c39e5405 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -223,3 +223,149 @@ jobs:
--type cyclonedx \
--predicate /tmp/sbom.cdx.json \
"${{ matrix.image }}@${DIGEST}"
+
+ # ── Publish the npm packages ───────────────────────────────────────────────
+ #
+ # Every package is built and packed on every release, whether or not the
+ # upload is enabled, so this job fails the moment a package stops being
+ # publishable — a broken `npx aisoc` must never reach the README again.
+ #
+ # Only the final upload is gated on `NPM_TOKEN`, so the release does not go
+ # red before the registry credential exists. One-time setup (including the
+ # move to token-free trusted publishing after the first release) is in
+ # docs/operations/publishing.md.
+ #
+ # `pnpm pack` rather than `npm pack`: it rewrites `workspace:*` dependency
+ # specifiers to real versions, which npm would otherwise reject. The tarball
+ # is then handed to `npm publish`, which is what supports `--provenance`.
+ npm-publish:
+ name: npm — publish ${{ matrix.pkg }}
+ runs-on: ubuntu-latest
+ needs: release
+ permissions:
+ contents: read
+ id-token: write # npm provenance attestation
+ # Job-level so the step-level `if` guards below can read it. A step cannot
+ # see its own `env` block from its `if` expression.
+ env:
+ NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - pkg: aisoc
+ dir: packages/aisoc-lite
+ - pkg: '@aisoc/mcp'
+ dir: services/mcp
+ - pkg: '@aisoc/sdk'
+ dir: packages/sdk-ts
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+ - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+ - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v6
+ with:
+ node-version: '22'
+ registry-url: https://registry.npmjs.org
+ cache: pnpm
+ cache-dependency-path: pnpm-lock.yaml
+
+ - name: Install workspace
+ run: pnpm install --frozen-lockfile --ignore-scripts
+
+ - name: Build ${{ matrix.pkg }}
+ run: pnpm --filter ${{ matrix.pkg }} build
+
+ - name: Pack tarball
+ id: pack
+ working-directory: ${{ matrix.dir }}
+ run: |
+ set -euo pipefail
+ pnpm pack --pack-destination "$RUNNER_TEMP"
+ TARBALL=$(ls -t "$RUNNER_TEMP"/*.tgz | head -1)
+ echo "tarball=$TARBALL" >> "$GITHUB_OUTPUT"
+ echo "version=$(node -p 'require("./package.json").version')" >> "$GITHUB_OUTPUT"
+ tar -tzf "$TARBALL" | head -20
+
+ # Republishing an unchanged version is a hard error on npm, and package
+ # versions move independently of the monorepo tag, so most releases will
+ # legitimately have nothing to push for some packages.
+ - name: Is this version already on npm?
+ id: exists
+ run: |
+ set -euo pipefail
+ if npm view "${{ matrix.pkg }}@${{ steps.pack.outputs.version }}" version >/dev/null 2>&1; then
+ echo "already=true" >> "$GITHUB_OUTPUT"
+ else
+ echo "already=false" >> "$GITHUB_OUTPUT"
+ fi
+
+ - name: Publish to npm
+ if: steps.exists.outputs.already == 'false' && env.NPM_TOKEN != ''
+ env:
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+ run: npm publish "${{ steps.pack.outputs.tarball }}" --access public --provenance
+
+ - name: Explain a skipped publish
+ if: steps.exists.outputs.already == 'true' || env.NPM_TOKEN == ''
+ run: |
+ if [ "${{ steps.exists.outputs.already }}" = "true" ]; then
+ echo "::notice title=npm::${{ matrix.pkg }}@${{ steps.pack.outputs.version }} is already published — nothing to do."
+ else
+ echo "::warning title=npm::NPM_TOKEN is not configured, so ${{ matrix.pkg }} was built and packed but not uploaded. See docs/operations/publishing.md."
+ fi
+
+ # ── Publish the PyPI packages ──────────────────────────────────────────────
+ #
+ # Uses PyPI Trusted Publishing (OIDC), so there is no API token to store or
+ # rotate. PyPI supports "pending" publishers, which means the trust
+ # relationship can be registered before the project exists — that is how the
+ # first upload of each of these works. Setup: docs/operations/publishing.md.
+ pypi-publish:
+ name: PyPI — publish ${{ matrix.pkg }}
+ runs-on: ubuntu-latest
+ needs: release
+ permissions:
+ contents: read
+ id-token: write # PyPI trusted publishing
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - pkg: aisoc-sandbox
+ dir: packages/aisoc-sandbox
+ - pkg: aisoc-cli
+ dir: packages/aisoc-cli
+ - pkg: aisoc-sdk
+ dir: packages/sdk-py
+ - pkg: aisoc-plugin-sdk
+ dir: packages/plugin-sdk-py
+ - pkg: aisoc-detections
+ dir: packages/aisoc-detections
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+ with:
+ python-version: '3.12'
+
+ - name: Build sdist + wheel
+ working-directory: ${{ matrix.dir }}
+ run: |
+ set -euo pipefail
+ python -m pip install --quiet --upgrade build twine
+ python -m build
+ python -m twine check dist/*
+ ls -la dist/
+
+ # `skip-existing` because package versions move independently of the
+ # monorepo tag, so a release often has nothing new for a given package.
+ - name: Publish to PyPI
+ if: vars.AISOC_PYPI_TRUSTED_PUBLISHING == 'true'
+ uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+ with:
+ packages-dir: ${{ matrix.dir }}/dist
+ skip-existing: true
+
+ - name: Explain a skipped publish
+ if: vars.AISOC_PYPI_TRUSTED_PUBLISHING != 'true'
+ run: |
+ echo "::warning title=PyPI::Trusted publishing is not enabled, so ${{ matrix.pkg }} was built and validated but not uploaded. Set the AISOC_PYPI_TRUSTED_PUBLISHING repository variable to 'true' once the pending publishers exist — see docs/operations/publishing.md."
diff --git a/docs/operations/publishing.md b/docs/operations/publishing.md
new file mode 100644
index 000000000..6f2a174c9
--- /dev/null
+++ b/docs/operations/publishing.md
@@ -0,0 +1,111 @@
+# Publishing AiSOC packages
+
+`.github/workflows/release.yml` builds, packs and validates every publishable
+package on each `v*.*.*` tag. Uploading is deliberately gated behind the
+one-time setup below, so a release never fails just because a registry
+credential has not been configured yet.
+
+Until that setup is done the release still runs: each package is built,
+packed and `twine check`ed, and the job emits a warning explaining that the
+upload was skipped. That way the pipeline cannot silently rot, which is the
+failure mode that let `npx aisoc` sit in the README while no such package
+existed.
+
+## What gets published
+
+npm:
+
+| Package | Source | Notes |
+| --- | --- | --- |
+| `aisoc` | `packages/aisoc-lite` | The wedge CLI behind `npx aisoc triage --demo` |
+| `@aisoc/mcp` | `services/mcp` | MCP server for Claude / Cursor / Cody |
+| `@aisoc/sdk` | `packages/sdk-ts` | Generated TypeScript client |
+
+PyPI:
+
+| Package | Source |
+| --- | --- |
+| `aisoc-sandbox` | `packages/aisoc-sandbox` |
+| `aisoc-cli` | `packages/aisoc-cli` |
+| `aisoc-sdk` | `packages/sdk-py` |
+| `aisoc-plugin-sdk` | `packages/plugin-sdk-py` |
+| `aisoc-detections` | `packages/aisoc-detections` |
+
+Package versions move independently of the monorepo `VERSION`. A release that
+does not change a package's version simply skips it — npm rejects a duplicate
+version outright, and the PyPI step passes `skip-existing`.
+
+## Name availability
+
+`aisoc` on **npm** is unclaimed and is reserved by the first successful
+publish. Claim it early.
+
+`aisoc` on **PyPI is already taken** by an unrelated project, which is why the
+Python distributions all carry the `aisoc-` prefix. Do not plan around
+acquiring it; a PEP 541 name transfer only applies to abandoned projects and
+that one is actively maintained.
+
+## One-time setup: npm
+
+1. Create (or sign in to) the npm account that will own the packages, and
+ create the `@aisoc` organisation so the scoped packages have a home.
+2. Generate a **granular access token** scoped to just these three packages,
+ with read/write permission and a sensible expiry.
+3. Add it as the `NPM_TOKEN` repository secret.
+4. Tag a release. The first publish claims `aisoc`.
+
+After the first release, switch to trusted publishing and delete the token:
+on npmjs.com, open each package's settings, add a trusted publisher pointing
+at `beenuar/AiSOC` and the `release.yml` workflow, then remove the `NPM_TOKEN`
+secret. The publish step already requests an OIDC token (`id-token: write`),
+so nothing in the workflow needs to change.
+
+Every upload is published with `--provenance`, which requires the
+`repository` field in each `package.json` to point at this repo. If you add a
+fourth npm package, set that field or the publish will fail.
+
+## One-time setup: PyPI
+
+PyPI supports **pending** trusted publishers, so the trust relationship can be
+registered before a project exists. That is how the first upload of each of
+these works without an API token.
+
+For each of the five distributions, go to
+<https://pypi.org/manage/account/publishing/> and add a pending publisher:
+
+- PyPI project name: the package name from the table above
+- Owner: `beenuar`
+- Repository name: `AiSOC`
+- Workflow name: `release.yml`
+- Environment name: leave blank
+
+Then set the repository **variable** (not secret)
+`AISOC_PYPI_TRUSTED_PUBLISHING` to `true`, which arms the upload step.
+
+There is no API token to store or rotate in this path.
+
+## Cutting a release
+
+The existing tag-driven flow is unchanged — see the release section of
+`CONTRIBUTING.md`. Bump the package versions you intend to publish in the same
+commit as the `CHANGELOG.md` promotion, then tag:
+
+```bash
+git tag vX.Y.Z && git push --tags
+```
+
+## Verifying a publish
+
+```bash
+npm view aisoc version
+npx aisoc@latest triage --demo
+
+pip download aisoc-sandbox --no-deps -d /tmp/verify
+```
+
+`.github/workflows/readme-gates.yml` runs the first two of those against the
+published registry on a schedule, so a broken on-ramp is caught even between
+releases rather than by a user.
+
+Signature and SBOM verification for the container images is covered separately
+in `docs/operations/verifying-releases.md`.
diff --git a/packages/aisoc-sandbox/pyproject.toml b/packages/aisoc-sandbox/pyproject.toml
index f485ddb6e..5b151a838 100644
--- a/packages/aisoc-sandbox/pyproject.toml
+++ b/packages/aisoc-sandbox/pyproject.toml
@@ -36,7 +36,7 @@ dev = [
[project.urls]
Homepage = "https://github.com/beenuar/AiSOC"
-Documentation = "https://docs.tryaisoc.com"
+Documentation = "https://beenuar.github.io/AiSOC/"
Source = "https://github.com/beenuar/AiSOC/tree/main/packages/aisoc-sandbox"
Issues = "https://github.com/beenuar/AiSOC/issues"
Changelog = "https://github.com/beenuar/AiSOC/blob/main/CHANGELOG.md"
diff --git a/packages/sdk-ts/package.json b/packages/sdk-ts/package.json
index 79b1afaf8..608d8d045 100644
--- a/packages/sdk-ts/package.json
+++ b/packages/sdk-ts/package.json
@@ -35,6 +35,16 @@
"typescript": ">=5.0.0"
},
"publishConfig": {
- "access": "public"
+ "access": "public",
+ "provenance": true
+ },
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/beenuar/AiSOC.git",
+ "directory": "packages/sdk-ts"
+ },
+ "homepage": "https://beenuar.github.io/AiSOC/",
+ "bugs": {
+ "url": "https://github.com/beenuar/AiSOC/issues"
}
}
diff --git a/services/mcp/package.json b/services/mcp/package.json
index adbff9615..ad7e888cd 100644
--- a/services/mcp/package.json
+++ b/services/mcp/package.json
@@ -63,6 +63,7 @@
"node": ">=18.17"
},
"publishConfig": {
- "access": "public"
+ "access": "public",
+ "provenance": true
}
}