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.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
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.ymlindex 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 pytestcd packages/aisoc-sandboxPYTHONPATH=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.ymlindex 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.mdnew file mode 100644index 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.tomlindex 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.jsonindex 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.jsonindex 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}}