Skip to content

faq

Jump to bottom
Purplemet CI edited this page Jun 2, 2026 · 5 revisions

FAQ & Troubleshooting

Authentication

"Access is not authorized without a valid session"

Your API token is invalid or expired.

"api http 401"

Same as above. The token is not recognized by the API.

"api http 403: ..."

The API rejected the request for the current token. The CLI surfaces the raw API response after the api http 403: prefix. The most common case is an admin-only command (users, sessions, tokens) run with an OPERATOR or READER token, which returns:

api http 403: {"code":"API_METHOD_NOT_ALLOWED","error":"Access to this method is not allowed to entity"}

Use an ADMIN token for those commands, or check the token's permissions in the Purplemet dashboard.

"API token is required: set PURPLEMET_API_TOKEN or use --token"

No token was configured. Set it via one of:

# Environment variable (recommended)
export PURPLEMET_API_TOKEN=your-token

# CLI flag
purplemet-cli analyze https://app.com --token your-token

# .env file in current directory
echo "PURPLEMET_API_TOKEN=your-token" > .env

Network

"network: connection refused" / "network: no such host"

  • Check your internet connection
  • Verify PURPLEMET_BASE_URL is correct
  • If behind a proxy, set HTTP_PROXY / HTTPS_PROXY

"api http 429: Too Many Requests"

Rate limit reached. The CLI automatically retries with Retry-After. If persistent:

  • Reduce analysis frequency
  • Contact Purplemet support for limit increase

"timeout: polling timeout exceeded (--wait-timeout)"

  • Increase --wait-timeout (default: unlimited)
  • Increase --timeout for slow networks (default: 30s)
  • Check that the target URL is publicly reachable

"x509: certificate signed by unknown authority"

The CLI could not verify the TLS certificate of the Purplemet API endpoint it connects to (--base-url / PURPLEMET_BASE_URL) — e.g. a self-signed certificate, an internal API gateway, or a missing CA in the local trust store. This concerns the CLI-to-API connection only: the scanned target URL is fetched server-side by the Purplemet platform, so --insecure has no effect on any target-site certificate.

  • For development against such an endpoint: add --insecure (skips TLS verification of the API connection only — vulnerable to MITM, dev only)
  • For production: ensure the proper CA certificates are installed in the system trust store

Analysis

"analysis ended with status ERROR"

The analysis failed on the Purplemet platform. Check the detailed error in the Purplemet dashboard for the specific cause (typically the target URL was unreachable, returned an unexpected response, or was blocked).

[purplemet] FAILED severity: severity gate: ... (threshold: ...)

Expected behavior when --fail-on-severity (or any other --fail-on-* flag) is set and the analysis violates the gate. The CLI prints one FAILED line per failing gate to stderr, then a N/M gate(s) failed summary, and exits with code 1.

Common gate messages emitted by the CLI:

  • severity gate: 1 critical, 2 high (threshold: high)
  • rating gate: D (threshold: C)
  • CVSS gate: 9.8 >= 9.0 (CVE-2024-...)
  • EOL gate: 2 end-of-life component(s) (jQuery 2.1.4, PHP 7.4)
  • KEV gate: 3 CISA Known Exploited Vulnerability(ies) detected
  • EPSS gate: 0.85 >= 0.75 (CVE-2024-...)
  • WAF gate: no WAF detected
  • cert expiry gate: 1 certificate(s) expiring within 30 days (...)

Options to react:

  • Fix the vulnerabilities
  • Adjust the threshold (e.g. --fail-on-severity critical is less strict)
  • Remove the flag to disable the gate
  • Acknowledge the risk with purplemet-cli issues ignore (ignored issues are always excluded from gate evaluation)

"no site found for URL and creation disabled"

You used --no-create but the URL doesn't match any existing site. Either:

  • Remove --no-create to auto-create
  • Use the site UUID instead of URL: purplemet-cli sites list to find it

"argument is neither a UUID nor a valid URL"

The argument to analyze must be either:

  • A valid URL starting with http:// or https://
  • A valid UUID (e.g. a1b2c3d4-e5f6-7890-abcd-ef1234567890)

Analysis exceeds the default timeout

If polling reaches --wait-timeout before the analysis completes, the CLI exits with code 3. Raise the timeout for large sites:

purplemet-cli analyze <url> --wait-timeout 600000   # 10 minutes

Refer to the Purplemet documentation for details on how analyses run.

Output

How do I get JSON output?

purplemet-cli analyze https://app.com --json
# or
purplemet-cli analyze https://app.com --format json

How do I save the report to a file?

# Any format
purplemet-cli analyze https://app.com --format json --output-file report.json
purplemet-cli analyze https://app.com --format html --output-file report.html
purplemet-cli analyze https://app.com --format sarif --output-file results.sarif

How do I generate a SARIF report?

purplemet-cli analyze https://app.com --format sarif --output-file results.sarif

SARIF 2.1.0 output is compatible with GitHub Code Scanning, Azure DevOps Advanced Security, and any SARIF-compatible viewer.

How do I interpret the security rating?

Ratings (A–F) are computed and defined by the Purplemet platform. See the official Purplemet documentation for authoritative definitions.

CI/CD

"PURPLEMET_API_TOKEN is not set"

Set the token as a secret/variable in your CI platform:

  • GitHub: Settings → Secrets and variables → Actions → New repository secret
  • GitLab: Settings → CI/CD → Variables (mark as masked)
  • Bitbucket: Repository Settings → Pipelines → Variables (mark as secured)
  • Jenkins: Manage Jenkins → Credentials → Add credentials
  • Azure DevOps: Pipelines → Library → Variable Groups (mark as secret)

Analysis takes too long in CI

  • Set --wait-timeout 300000 (5 min) to bound execution
  • Check that the target URL is reachable from the internet

Exit code 1 but I want the pipeline to continue

Use the appropriate mechanism for your CI platform:

Platform Mechanism
GitHub Actions continue-on-error: true
GitLab CI/CD allow_failure: true or allow_failure: exit_codes: [1]
Bitbucket after-script for post-processing
Jenkins Mark build UNSTABLE instead of FAILURE
Azure DevOps continueOnError: true

Example (any platform):

purplemet-cli analyze https://app.com --json --fail-on-severity high || true

How do I run analyses on multiple sites?

Use a matrix/parallel strategy in your CI platform, or loop in shell:

for URL in https://app1.com https://app2.com https://app3.com; do
  purplemet-cli analyze "$URL" --json --fail-on-severity high || true
done

How do I compare analyses over time?

Use the diff command to compare two analyses:

purplemet-cli diff <analysisId1> <analysisId2> --site-id <siteId>

Docker

"exec format error"

Wrong architecture. Use the correct image for your platform:

  • ppmsupport/purplemet-cli:latest supports linux/amd64 and linux/arm64
  • Specify platform: docker run --platform linux/amd64 ...

"certificate verify failed"

Add --insecure flag (dev only) or ensure CA certificates are available in the container.

How do I use a specific CLI version with Docker?

docker run --rm -e PURPLEMET_API_TOKEN=<token> ppmsupport/purplemet-cli:v1.2.0 analyze https://app.com

General

Where do I create an API token?

Go to cloud.purplemet.com/#/tokens/create.

Where can I see my analysis results online?

Log in to cloud.purplemet.com to view your sites, analyses, and detailed findings in the Purplemet dashboard.

How do I schedule recurring analyses?

# Daily at 2am
purplemet-cli sites schedule <siteId> --frequency DAILY --time 02:00

# Weekly on Monday at 2am
purplemet-cli sites schedule <siteId> --frequency WEEKLY --day monday --time 02:00

Or use your CI/CD platform's scheduling (e.g. GitHub Actions schedule, GitLab schedules).

How do I get support?

  • Documentation: docs/
  • Issues: Contact Purplemet support

Clone this wiki locally