@peachstudio/synapse-sbom

Command: synapse-sbom · npm package: @peachstudio/synapse-sbom

Generate a CycloneDX 1.6 SBOM from your npm project locally and submit it to SYNAPSE Software Component Analysis (SCA). Vulnerable components are then continuously re-evaluated as new advisories land — scan once, monitored forever.

• Zero runtime dependencies. Node ≥ 18.
• The SBOM is built on your machine; only the SBOM JSON leaves it.
• Re-scans update the same product (stable project identity), so history and continuous monitoring survive renames and CI re-runs.

Quick start

# 1. Create an API key in the SYNAPSE webapp (see "Authentication" below):
#    Settings → Security → API Keys → name it → Create → copy the syn_… key

# 2. Store it once (written to ~/.config/synapse-sbom/config.json, mode 600):
npx @peachstudio/synapse-sbom login --key syn_xxxxxxxxxxxx

# 3. From your project root (needs package.json + package-lock.json):
npx @peachstudio/synapse-sbom scan

That's it. Output:

Project identity: git:github.com/acme/web (git remote)
Generated CycloneDX SBOM: acme-web@2.3.0 (412 components)
Submitting 412 component(s) to https://api.synapse-intel.com …
Done in 7s (HTTP 200)
Submitted to https://api.synapse-intel.com
  product   : acme-web (d51e5833-…)
  components : 412
  vulnerable : 5
  new CVEs   : 2

Install it instead of using npx if you prefer (the installed command is synapse-sbom):

npm i -g @peachstudio/synapse-sbom        # global CLI → `synapse-sbom`
npm i -D @peachstudio/synapse-sbom        # or as a dev dependency, run via npm scripts

Command reference

Copy-paste, no install needed (npx). If installed globally, drop the npx @peachstudio/synapse-sbom prefix and just use synapse-sbom.

# Authenticate once — key stored 0600 at ~/.config/synapse-sbom/config.json
npx @peachstudio/synapse-sbom login --key syn_xxx --url https://api.synapse-intel.com
npx @peachstudio/synapse-sbom login                 # interactive hidden prompt

# Scan
npx @peachstudio/synapse-sbom scan                  # current project, submit
npx @peachstudio/synapse-sbom scan ./path/to/app    # a specific project
npx @peachstudio/synapse-sbom scan --dry-run        # print SBOM only, no upload, no side effects
npx @peachstudio/synapse-sbom scan --product my-svc # override display name
npx @peachstudio/synapse-sbom scan --project my-key # explicit stable project key

# Per-run auth/endpoint overrides (skip stored config)
npx @peachstudio/synapse-sbom scan --url https://api.synapse-intel.com --key syn_xxx
SYNAPSE_API_KEY=syn_xxx SYNAPSE_API_URL=https://api.synapse-intel.com \
  npx @peachstudio/synapse-sbom scan

# Local SYNAPSE instead of prod
npx @peachstudio/synapse-sbom scan --url http://localhost:8085 --key syn_local

# Inspect resolved URL / masked key / config path
npx @peachstudio/synapse-sbom whoami

# Help
npx @peachstudio/synapse-sbom help

Resolution order (key & URL): flag > env > stored config > default. Security: the SBOM is built locally; only it (+ a Bearer key over HTTPS) leaves your machine. The key is never written to the project, the SBOM, or .synapse-sbom.json. The CLI warns if you point --url at a plaintext http:// non-local host (cleartext-key risk); http://localhost and https:// are silent. Exit code 0 on success, 1 on any error (CI-friendly).

Authentication (API key)

Get a key

1. Sign in to the SYNAPSE webapp.
2. Go to Settings → Security → API Keys. API access requires a Business (up to 5 keys) or Enterprise (up to 20 keys) tier — lower tiers see an upgrade notice and cannot create keys.
3. Enter a name (e.g. ci-sbom) and click Create.
4. The key (format syn_ + 32 hex chars) is shown once in a banner — copy it immediately with the copy button. It is not retrievable later; if lost, revoke it and create a new one. Keys can be revoked anytime from the same screen.

Give the key to the scanner

Three ways, highest precedence first (flag → env → stored config):

login also stores the API URL. Verify what's resolved at any time:

synapse-sbom whoami
# API URL : https://api.synapse-intel.com
# API key : syn_abc…(36 chars)
# Config  : /home/you/.config/synapse-sbom/config.json

The key is only ever stored in that 0600 config file (or your env/CI secret store) — it is never written into your project tree, the SBOM, or .synapse-sbom.json.

Commands

scan options

Other environment variables

Resolution order for API key / URL: flag → env → stored config → default.

Project identity (re-scans update the same product)

Every project gets a stable key so re-scanning always updates the same product — even after a package.json rename, and identically across every clone and CI runner. Resolution order:

1. --project <key> / SYNAPSE_PROJECT
2. committed .synapse-sbom.json — { "projectId": "…" }
3. the git remote URL, normalized (e.g. git:github.com/acme/web)
4. otherwise a UUID is generated and written to .synapse-sbom.json — commit that file so every clone / CI run scans as the same product.

Server-side identity is (your account, project key); the product name is just a mutable label. Two unrelated repos that happen to share a package name do not collide. --dry-run reports the resolved key without writing the file.

What it sends

1. Reads package.json (→ product name/version) and package-lock.json (lockfile v2/v3 packages graph; v1 dependencies fallback) and builds a CycloneDX 1.6 JSON document with pkg:npm/<name>@<version> purls (scoped names encoded per the purl spec).
2. POST {API_URL}/v1/sca/analyze with Authorization: Bearer <key> and body { "format": "cyclonedx", "sbom": { … }, "product": { "project_key": "…" } }.
3. The server resolves & enriches vulnerabilities (OSV.dev + NVD + KEV + exploit/PoC signals) and persists the product, SBOM snapshot, and report to your private instance. Prints product id + component / vulnerable / new-CVE counts.

Nothing but the generated SBOM JSON is transmitted. The API key is stored locally with 0600 permissions and is never written into your project tree.

Use in CI

# .github/workflows/sca.yml
name: SBOM SCA
on: [push]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npx @peachstudio/synapse-sbom scan
        env:
          SYNAPSE_API_KEY: ${{ secrets.SYNAPSE_API_KEY }}

Commit .synapse-sbom.json so every CI run reports as the same product. The exit code is 0 on success, 1 on any error (auth, network, malformed project, API error) — fail the build on it as you see fit.

Troubleshooting

Roadmap

synapse-sbom is the first of a family. PyPI (pip) and Go scanners will follow the same contract — generate a CycloneDX 1.6 SBOM locally, submit to /v1/sca/analyze. The SCA engine is already ecosystem-agnostic (npm / PyPI / Go via purl), so a CycloneDX file from any tool works today.