Magebean API Reference

Summary

Most checks execute locally. Rules that require Magebean advisory, package-status, or Adobe patch data call the corresponding API endpoint with the documented request body.

Endpoint index

The CLI calls a POST endpoint when a selected rule requires that endpoint's dataset or evaluation.

Common conventions

Clients should send Accept: application/json. Requests containing JSON should also send Content-Type: application/json.

Base URL: https://api.magebean.com
Accept: application/json
Content-Type: application/json

The read-only routes are publicly addressable. Integrations must not assume ingestion routes are anonymous; their deployed authorization policy still applies.

Like any HTTPS service, the server or infrastructure can observe ordinary connection metadata: public source IP, request time and path, TLS/HTTP metadata, and a User-Agent header when supplied. This is not Magento scan content.

Read-only endpoints

GET /health

Checks service availability. Request body: none.

curl --fail-with-body https://api.magebean.com/health

GET /latest-cves

Legacy route for the latest CVE definitions. Request body: none.

curl --fail-with-body \
  --header 'Accept: application/json' \
  https://api.magebean.com/latest-cves

GET /v1/latest-cves

Versioned route for the latest CVE definitions. The definitions are downloaded for local matching; the request does not need a package list, composer.lock, configuration, or scan results.

curl --fail-with-body \
  --header 'Accept: application/json' \
  https://api.magebean.com/v1/latest-cves

GET /v1/stats

Returns aggregate statistics about the Magebean vulnerability dataset. Request body: none.

curl --fail-with-body \
  --header 'Accept: application/json' \
  https://api.magebean.com/v1/stats

GET /v1/packages/{vendor}/{package}

Returns vulnerability information for a Composer package. The package identifier in the URL is visible to the API; local package files, installed version, and scan results are not implied by this lookup.

curl --fail-with-body \
  --header 'Accept: application/json' \
  https://api.magebean.com/v1/packages/magento/product-community-edition

Clients must URL-encode path segments.

GET /v1/cves/{cve}

Returns information for a public CVE identifier.

curl --fail-with-body \
  --header 'Accept: application/json' \
  https://api.magebean.com/v1/cves/CVE-2024-34102

GET /v1/vulns/{id}

Returns a vulnerability using its Magebean dataset identifier.

curl --fail-with-body \
  --header 'Accept: application/json' \
  https://api.magebean.com/v1/vulns/ID

GET /v1/bundles/latest

Returns the latest generated vulnerability bundle. Request body: none. Clients should honor the response Content-Type rather than assuming a media type.

curl --fail-with-body \
  https://api.magebean.com/v1/bundles/latest

GET /v1/uncovered-packages

Returns package entries recorded as not covered by the vulnerability dataset. Calling this route does not upload the caller's package inventory.

curl --fail-with-body \
  --header 'Accept: application/json' \
  https://api.magebean.com/v1/uncovered-packages

POST endpoints used by Magebean CLI

The payloads in this section are generated by ComposerCheck in the current Magebean CLI source.

POST /v1/osv/advisories

Requests advisories for installed Composer packages. Packages are read from composer.lock and sent in batches.

{
  "schema_version": "magebean-osv-request-v1",
  "ecosystem": "Packagist",
  "packages": [
    {"name": "vendor/package", "version": "1.2.3"}
  ],
  "client": {"name": "magebean-cli", "version": "1.0.0"}
}

POST /v1/packages/status

Requests package status, classification, lifecycle, release, or withdrawal metadata used by the selected rule.

{
  "schema_version": "magebean-package-status-request-v1",
  "packages": [
    {"name": "vendor/package", "version": "1.2.3"}
  ]
}

The package set varies by rule and can contain all locked packages or a subset such as direct dependencies, Adobe core packages, or Magento modules.

POST /v1/adobe/security-patches

Evaluates the installed Magento product and version against Adobe security-patch data.

{
  "schema_version": "magebean-adobe-patch-request-v1",
  "product": "magento-open-source",
  "installed_version": "2.4.8-p1",
  "evidence": {
    "packages": {},
    "patch_artifacts": []
  },
  "client": {"name": "magebean-cli", "version": "1.0.0"}
}

The v1 schema retains empty evidence containers for compatibility. Installed package constraints, patch identifiers, applied status, local paths, and file fingerprints are evaluated by the CLI after the API returns alternative_rules.

Error handling

Clients should primarily handle HTTP statuses until a formal error response schema is published.

Magebean CLI data disclosure

Request data is determined by the endpoint and selected rule. The CLI sends JSON fields, not the composer.lock file itself.

Adobe patch alternatives are matched locally against installed packages, applied patch identifiers, and file fingerprints. Standard HTTPS connection metadata and configured authorization headers are visible to the receiving service.

Remote scans invoked with --url additionally connect to the selected storefront for externally observable checks.