Skip to content

feedback.md

Latest commit

 

History

History
110 lines (84 loc) · 4.17 KB

feedback.md

File metadata and controls

110 lines (84 loc) · 4.17 KB
Raw

Feedback

Help improve PkgSafe with clear, safe reports.

  • GA ecosystems: npm, PyPI
  • Preview: Go, Cargo (label gaps as ecosystem_preview_gap)

Never paste secrets, tokens, private registry credentials, .npmrc auth, proprietary source, or unreleased package contents. Redact hostnames and scopes when needed. Do keep rule IDs, decisions, risk scores, and sanitized command output.

Docs index: README.md · Troubleshooting: troubleshooting.md

Taxonomy

Use these labels or issue title prefixes when reporting:

Type Use for
false_positive PkgSafe returned warn or block for a package you believe should be allowed.
false_block PkgSafe blocked an install or CI workflow that should not have been blocked.
false_negative PkgSafe returned allow or only warn for a package you believe should be blocked.
scanner_crash Panic, non-deterministic failure, malformed output, or unexpected command exit.
performance_issue Slow scan, timeout, excessive network use, or large lockfile regression.
docs_issue Incorrect, stale, or unclear documentation.
ecosystem_preview_gap Go or Cargo behavior that is missing compared with npm/PyPI public-beta coverage.
private_registry_issue Private registry routing, redaction, fallback, or authentication problems.
osv_update_issue OSV reachability, cache, update-db, or advisory database problems.
github_action_issue GitHub Action configuration, SARIF upload, summary, or fail-on behavior problems.

What To Include

For false positives and false blocks, include:

  • Package name, ecosystem, and version.
  • Exact command or GitHub Action workflow snippet used.
  • PkgSafe decision, risk score, and rule IDs.
  • Finding fingerprint when generated by pkgsafe feedback create.
  • Sanitized --json output if possible.
  • Whether lifecycle scripts are present.
  • Whether a private registry or registry config was involved.
  • Why you believe the decision should change.

Local Feedback Artifacts

Use pkgsafe feedback create to generate a sanitized false-positive report from existing PkgSafe JSON output:

pkgsafe scan-npm-package example-package --version 1.2.3 --json > scan.json
pkgsafe feedback create \
  --input scan.json \
  --reason "Maintainer and source reviewed; lifecycle script is expected." \
  --command "pkgsafe scan-npm-package example-package --version 1.2.3 --json"

By default the command writes JSON and Markdown under .pkgsafe/feedback/. The JSON includes package, ecosystem, version, rule IDs, decision, risk score, sanitized finding output, lifecycle-script involvement, private-registry involvement, and a stable fingerprint. Review generated Markdown before filing an issue and keep any organization-specific details sanitized.

For scanner crashes, include:

  • pkgsafe version.
  • OS and architecture.
  • Exact command.
  • Sanitized terminal output or stack trace.
  • Whether the scan was online or --offline.

For private registry issues, include:

  • Ecosystem and registry type.
  • Whether scope/prefix routing was used.
  • Sanitized registry config shape without tokens or credentials.
  • Whether public fallback was expected or disabled.

For OSV or update-db issues, include:

  • Command output from pkgsafe update-db or pkgsafe doctor.
  • Ecosystem.
  • Whether the problem happens online, offline, or both.
  • Any rate-limit or reachability errors with tokens and internal URLs removed.

For GitHub Action issues, include:

  • Workflow YAML with secrets removed.
  • Action inputs used.
  • Whether SARIF upload, PR comment, changed-only, or offline mode was enabled.
  • The generated Markdown summary or JSON report if safe to share.

Recommended Labels

If repository labels are configured, use:

  • false_positive
  • false_block
  • false_negative
  • scanner_crash
  • performance_issue
  • docs_issue
  • ecosystem_preview_gap
  • private_registry_issue
  • osv_update_issue
  • github_action_issue

Use the false-positive template for tuning over-strict rules and the scanner bug template for crashes or broken command behavior. Security vulnerabilities in PkgSafe itself should follow SECURITY.md, not public issues.