api

API Endpoints

Complete reference for all sus API endpoints

Overview

The sus API provides programmatic access to package security scanning. Use it to integrate sus into your CI/CD pipelines, build tools, or custom workflows.

Base URL: https://api.sus-pm.com

Authentication: No authentication required. All endpoints are public.

Content-Type: All requests and responses use application/json

Get Package

Get the latest scan result for a package.

Bash

GET /v1/packages/{name}

Path Parameters:

Name	Type	Description
`name`	string	Package name (URL-encoded for scoped packages)

Example:

Bash

curl https://api.sus-pm.com/v1/packages/express

For scoped packages, URL-encode the name:

Bash

curl https://api.sus-pm.com/v1/packages/@types%2Fnode

Response:

JSON

{
  "name": "express",
  "version": "4.21.0",
  "registry": "npm",
  "risk_level": "clean",
  "risk_reasons": [],
  "publisher": {
    "name": "expressjs",
    "verified": true
  },
  "weekly_downloads": 32000000,
  "install_scripts": {
    "preinstall": false,
    "install": false,
    "postinstall": false,
    "prepare": false
  },
  "cves": [],
  "agentic_threats": [],
  "scanned_at": "2024-01-15T10:30:00Z"
}

Get Package Version

Get the scan result for a specific package version.

Bash

GET /v1/packages/{name}/{version}

Path Parameters:

Name	Type	Description
`name`	string	Package name
`version`	string	Package version

Example:

Bash

curl https://api.sus-pm.com/v1/packages/lodash/4.17.20

List Packages

Get a paginated list of all scanned packages, sorted by weekly downloads.

Bash

GET /v1/packages

Query Parameters:

Name	Type	Default	Description
`limit`	number	50	Number of packages to return (max 100)
`offset`	number	0	Number of packages to skip

Example:

Bash

curl "https://api.sus-pm.com/v1/packages?limit=20&offset=0"

Response:

JSON

{
  "packages": [
    {
      "name": "semver",
      "version": "7.7.3",
      "registry": "npm",
      "risk_level": "clean",
      "trust_score": 95,
      "weekly_downloads": 492100000,
      "publisher_verified": true,
      "cve_count": 0,
      "threat_count": 0,
      "capabilities": {
        "network": { "makes_requests": false },
        "filesystem": { "reads": false, "writes": false },
        "process": { "spawns_children": false },
        "environment": { "accessed_vars": [] },
        "native": { "has_native": false }
      },
      "scanned_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1006,
  "limit": 20,
  "offset": 0
}

Search Packages

Search for packages by name. Returns paginated results matching the query.

Bash

GET /v1/packages?q={query}

Query Parameters:

Name	Type	Default	Description
`q`	string	-	Search query (matches package name)
`limit`	number	50	Number of packages to return (max 100)
`offset`	number	0	Number of packages to skip

Example:

Bash

curl "https://api.sus-pm.com/v1/packages?q=express&limit=10"

Response:

JSON

{
  "packages": [
    {
      "name": "express",
      "version": "4.21.0",
      "registry": "npm",
      "risk_level": "clean",
      "trust_score": 92,
      "weekly_downloads": 32000000,
      "publisher_verified": true,
      "cve_count": 0,
      "threat_count": 0,
      "capabilities": {
        "network": { "makes_requests": true },
        "filesystem": { "reads": true, "writes": false },
        "process": { "spawns_children": false },
        "environment": { "accessed_vars": ["NODE_ENV"] },
        "native": { "has_native": false }
      },
      "scanned_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 15,
  "limit": 10,
  "offset": 0
}

Request Scan

Request a new scan for a package. The scan is queued and processed asynchronously.

Bash

POST /v1/scan

Request Body:

Name	Type	Required	Description
`name`	string	Yes	Package name
`version`	string	No	Package version (latest if not specified)
`registry`	string	No	Package registry (defaults to "npm")

Example:

Bash

curl -X POST https://api.sus-pm.com/v1/scan \
  -H "Content-Type: application/json" \
  -d '{"name": "express", "version": "4.21.0", "registry": "npm"}'

Response:

JSON

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "estimated_seconds": 30
}

Scan Tarball

Upload and scan a local package tarball. Useful for scanning private packages or packages before publishing.

Bash

POST /v1/scan/tarball

Content-Type: multipart/form-data

Form Fields:

Name	Type	Description
`tarball`	file	Gzipped tarball file (.tgz or .tar.gz)

Example:

Bash

curl -X POST https://api.sus-pm.com/v1/scan/tarball \
  -F "tarball=@my-package-1.0.0.tgz"

Response:

JSON

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "estimated_seconds": 60
}

Bulk Lookup

Look up multiple packages in a single request.

Bash

POST /v1/bulk

Request Body:

Name	Type	Description
`packages`	array	Array of package objects with `name`, optional `version`, and optional `registry`

Example:

Bash

curl -X POST https://api.sus-pm.com/v1/bulk \
  -H "Content-Type: application/json" \
  -d '{
    "packages": [
      {"name": "express", "version": "4.21.0", "registry": "npm"},
      {"name": "lodash", "version": "4.17.20"},
      {"name": "axios"}
    ]
  }'

Response:

Returns an array of package responses. Each response includes the registry field.

Health Check

Check if the API is running.

Bash

GET /health

Response:

JSON

{
  "status": "ok"
}

Response Schema

PackageResponse

Field	Type	Description
`name`	string	Package name
`version`	string	Package version
`registry`	string	Package registry (e.g., "npm")
`risk_level`	string	"clean", "warning", or "critical"
`risk_reasons`	string[]	List of reasons for the risk level
`publisher`	object	Publisher info with name and verified
`weekly_downloads`	number	Weekly download count
`install_scripts`	object	Which install scripts are present
`cves`	array	List of CVEs affecting this package
`agentic_threats`	array	Detected agentic threats
`capabilities`	object	Package capability analysis
`docs_md`	string	Generated package documentation markdown
`scanned_at`	string	ISO 8601 timestamp of scan

PackageListItem

Lightweight package object returned by list and search endpoints.

Field	Type	Description
`name`	string	Package name
`version`	string	Package version
`registry`	string	Package registry (e.g., "npm")
`risk_level`	string	"clean", "warning", or "critical"
`trust_score`	number	Trust score (0-100)
`weekly_downloads`	number	Weekly download count
`publisher_verified`	boolean	Whether publisher is verified
`cve_count`	number	Number of CVEs affecting this version
`threat_count`	number	Number of threats detected
`capabilities`	object	Package capability analysis
`scanned_at`	string	ISO 8601 timestamp of scan

CVE Object

Field	Type	Description
`cve_id`	string	CVE identifier (e.g., CVE-2021-23337)
`severity`	string	"low", "medium", "high", or "critical"
`description`	string	CVE description
`fixed_in`	string	Version where the CVE is fixed

Agentic Threat Object

Field	Type	Description
`threat_type`	string	Type of threat detected
`confidence`	number	Confidence score (0-1)
`location`	string	File and line where threat was found
`snippet`	string	Code snippet containing the threat

Threat Types:

prompt_injection - Hidden instructions targeting AI agents
instruction_override - Attempts to override agent instructions
data_exfiltration - Code that exfiltrates data
social_engineering - Deceptive content targeting agents
install_script_injection - Malicious install scripts
malicious_code - Other malicious code patterns

Capabilities Object

Field	Type	Description
`network`	object	Network access analysis
`filesystem`	object	File system access analysis
`process`	object	Process spawning analysis
`environment`	object	Environment variable access
`native`	object	Native module analysis

Error Responses

All errors return JSON with an error field:

JSON

{
  "error": "Package not found"
}

Status Codes:

Code	Description
`200`	Success
`400`	Bad request (invalid parameters)
`404`	Package not found
`500`	Internal server error

On this page

Share feedback