User Guide

SmartScope monitors the open-source packages your team depends on and emails you a structured digest every week — new releases, CVEs, and breaking changes, filtered to exactly the packages you care about.

Getting started

After signing up you'll be taken through a short onboarding flow:

1. Choose a delivery day — pick the weekday you want your digest to arrive (8 am UTC).
2. Name your first project — projects group related packages (e.g. "Frontend", "Backend API").
3. Add packages — search npm, PyPI, GitHub, or NuGet by name and add them to your project.

Once onboarding is complete you'll land on your dashboard, where you can manage all your projects and packages at any time.

Projects

Projects let you group packages by context — a frontend app, a backend service, a data pipeline — so your digest is organized around how your stack is actually structured.

Creating a project

Click + New project in the top-right of your dashboard. Give the project a name and, optionally, paste or upload a package.json or requirements.txt to import packages in bulk.

Renaming a project

Double-click the project name on the dashboard card. Edit the name inline and press Enter to save, or Escape to cancel.

Deleting a project

Open the project card's action menu and choose Delete project. You'll be asked to confirm. Deleting a project removes all of its packages and stops tracking them in future digests.

Adding packages

Packages are added per-project. Open a project card and click Add package, or use the bulk import option when creating a new project.

Supported ecosystems

SmartScope validates each package against its registry before saving it — you'll see an error immediately if the name isn't found.

Bulk import

When creating a new project (or via the Import button on an existing project card) you can paste or drag-and-drop a manifest file. Supported formats:

Packages that already exist in the project are silently skipped — re-importing is safe.

Removing a package

Click the × next to any package in the project card. The package is removed immediately and will not appear in future digests.

Weekly digest

Once a week, SmartScope emails you a digest for each project you've set up. Digests are delivered on the day you chose during onboarding at 8 am UTC.

What's in the digest

CVE severity levels follow the CVSS scale: critical, high, medium, and low. High and critical advisories are highlighted in the email.

Changing your delivery day

Go to Settings and choose a new day under Digest schedule. The change takes effect for the next scheduled run.

Settings

Digest schedule

Choose which day of the week you receive your digest. All digests go out at 8 am UTC regardless of the day selected.

API access

Your API key grants access to the Scan API — a separate REST endpoint for running ad-hoc vulnerability scans from scripts or CI pipelines. Keys are tied to your subscription; generating a new key immediately invalidates the previous one.

The key is shown in full only once at generation time. If you lose it, generate a new one from Settings.

Scan API

The SmartScope Scan API lets you check a manifest against known vulnerabilities and outdated versions from any script or CI/CD pipeline. Send a package.json or requirements.txt, get back a structured report. Gate your deploys on it.

Authentication

All requests to /scan require a Bearer token in the Authorization header. API keys are tied to your account and require an active subscription.

To generate a key: open Settings → API Access and click Generate key. The full key is shown exactly once — copy it into your secret manager before dismissing the dialog.

export SMARTSCOPE_KEY="ss_live_your_key_here"

Store it as an environment secret in your CI provider — never commit it to source control. Keys can be regenerated or revoked at any time from Settings.

The endpoint

POST https://rtw7o67sla.execute-api.us-east-1.amazonaws.com/v1/scan
Authorization: Bearer <api-key>
Content-Type: application/json

The endpoint always returns HTTP 200. Use the passed field in the response to decide whether to fail your pipeline — see Pipeline control below.

Input formats

The request body is auto-detected. Three formats are supported:

1 — Raw package.json

Post the file directly. Both dependencies and devDependencies are scanned.

curl -s -X POST https://rtw7o67sla.execute-api.us-east-1.amazonaws.com/v1/scan \
  -H "Authorization: Bearer $SMARTSCOPE_KEY" \
  -H "Content-Type: application/json" \
  -d @package.json

2 — Raw requirements.txt

Only pinned versions (==) are scanned. Range specifiers like >=2.0 are skipped.

curl -s -X POST https://rtw7o67sla.execute-api.us-east-1.amazonaws.com/v1/scan \
  -H "Authorization: Bearer $SMARTSCOPE_KEY" \
  -H "Content-Type: text/plain" \
  --data-binary @requirements.txt

3 — Structured JSON

For multi-ecosystem projects or programmatic use. Supports npm, pypi, and github sources. Maximum 100 packages per request.

{
  "packages": [
    { "source": "npm",   "name": "lodash",  "version": "4.14.0" },
    { "source": "pypi",  "name": "django",  "version": "4.1.0"  },
    { "source": "npm",   "name": "express", "version": "4.18.0" }
  ]
}

Response format

{
  "summary": {
    "scanned":    3,
    "vulnerable": 1,   // packages with one or more CVEs at your version
    "outdated":   2,   // packages where version !== latestVersion
    "upToDate":   1,
    "critical":   0,
    "high":       1,
    "medium":     0,
    "low":        0
  },
  "packages": [
    {
      "name":          "lodash",
      "source":        "npm",
      "version":       "4.14.0",   // your installed version
      "latestVersion": "4.17.21",  // current registry version
      "upToDate":      false,
      "cves": [
        {
          "id":          "CVE-2021-23337",
          "severity":    "high",
          "summary":     "Command injection via template",
          "fixedIn":     "4.17.21",
          "publishedAt": "2021-02-15T00:00:00Z"
        }
      ]
    }
  ],
  "passed":  false,  // false = at least one CVE at or above failOn threshold
  "failOn":  "critical"
}

Pipeline control

Use the ?failOn query parameter to control what severity causes passed: false. Default is critical.

# Fail the pipeline if any high or critical CVE is found
curl -s -X POST "https://rtw7o67sla.execute-api.us-east-1.amazonaws.com/v1/scan?failOn=high" \
  -H "Authorization: Bearer $SMARTSCOPE_KEY" \
  -d @package.json | jq -e '.passed'

jq -e exits with code 1 when the value is false, which fails the pipeline step naturally.

GitHub Actions

Add SMARTSCOPE_KEY as a repository secret under Settings → Secrets and variables → Actions, then add this step to your workflow.

- name: SmartScope security scan
  env:
    SMARTSCOPE_KEY: ${{ secrets.SMARTSCOPE_KEY }}
  run: |
    result=$(curl -sf -X POST \
      "https://rtw7o67sla.execute-api.us-east-1.amazonaws.com/v1/scan?failOn=high" \
      -H "Authorization: Bearer $SMARTSCOPE_KEY" \
      -H "Content-Type: application/json" \
      -d @package.json)

    echo "$result" | jq '.summary'

    if [ "$(echo "$result" | jq -r '.passed')" = "false" ]; then
      echo "::error::SmartScope: vulnerabilities found — see summary above"
      exit 1
    fi

To see per-package details in the Actions log, pipe through jq '.packages[] | select(.cves | length > 0)'.

GitLab CI

Add SMARTSCOPE_KEY as a CI/CD variable under Settings → CI/CD → Variables, masked and protected.

smartscope-scan:
  stage: test
  image: alpine:latest
  before_script:
    - apk add --no-cache curl jq
  script:
    - |
      result=$(curl -sf -X POST \
        "https://rtw7o67sla.execute-api.us-east-1.amazonaws.com/v1/scan?failOn=high" \
        -H "Authorization: Bearer $SMARTSCOPE_KEY" \
        -H "Content-Type: application/json" \
        -d @package.json)

      echo "$result" | jq '.summary'

      passed=$(echo "$result" | jq -r '.passed')
      if [ "$passed" = "false" ]; then
        echo "Vulnerabilities found:"
        echo "$result" | jq '.packages[] | select(.cves | length > 0)'
        exit 1
      fi
  only:
    - merge_requests
    - main

Shell / curl

Minimal one-liner for local checks or custom scripts:

# Quick scan — prints summary, exits 1 if critical CVEs found
curl -sf -X POST https://rtw7o67sla.execute-api.us-east-1.amazonaws.com/v1/scan \
  -H "Authorization: Bearer $SMARTSCOPE_KEY" \
  -d @package.json | jq '{summary: .summary, passed: .passed}'

Print only vulnerable packages:

curl -sf -X POST https://rtw7o67sla.execute-api.us-east-1.amazonaws.com/v1/scan \
  -H "Authorization: Bearer $SMARTSCOPE_KEY" \
  -d @package.json \
  | jq '.packages[] | select(.cves | length > 0) | {name, version, latestVersion, cves}'

Scan a Python project with pinned requirements:

curl -sf -X POST https://rtw7o67sla.execute-api.us-east-1.amazonaws.com/v1/scan \
  -H "Authorization: Bearer $SMARTSCOPE_KEY" \
  -H "Content-Type: text/plain" \
  --data-binary @requirements.txt | jq '.summary'

Questions? kaercha@gmail.com · Get an API key