Av False Positive

Context

!gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null !gh release view --json tagName --jq '.tagName' 2>/dev/null !grep -m1 'license' pyproject.toml 2>/dev/null !grep -m1 'name' pyproject.toml 2>/dev/null !grep -A1 '\[project.urls\]' pyproject.toml 2>/dev/null | head -5

Instructions

Scan release binaries on VirusTotal and generate per-vendor false-positive submission files for any flagged artifacts.

Step 1: resolve version and artifacts

If $ARGUMENTS is empty, use the latest release tag from the context above. Otherwise treat $ARGUMENTS as the version (accept both 6.2.1 and v6.2.1; normalize to bare version for filenames, v-prefixed for tags).

Detect the repository from the context (nameWithOwner). Extract the project name, license, and homepage URL from pyproject.toml.

Start from the scan history when present: docs/assets/virustotal-scans.csv holds one at-release snapshot per binary (tag, filename, SHA-256, scan date, per-category verdict counts), written by the release pipeline's scan-virustotal job. It identifies the flagged binaries of the target release without any API call, and the catalog in docs/binaries.md shows the same data at a glance. That job publishes through one long-lived scan-virustotal pull request each release appends to, so the newest release's records reach the default branch only once someone merges it: read the branch copy (git show origin/scan-virustotal:docs/assets/virustotal-scans.csv) before concluding the history carries nothing for the version. Fall back to listing release assets when neither copy has records for it:

$ gh release view v{VERSION} --json assets --jq '.assets[].name'

Step 2: retrieve or refresh VirusTotal results

The release pipeline already uploaded every release binary at publication time, so a fresh upload is rarely needed. Per-engine detection details (which neither the CLI nor the scan history expose) always require querying the VT API directly via Python with the vt library. For a re-upload, use the scan-virustotal CLI command: it requires --tag and --binaries-dir, and --poll --records docs/assets/virustotal-scans.csv appends the fresh snapshot to the scan history (same-day re-scans replace their record; later dates accumulate, and the catalog keeps showing the earliest, at-release snapshot). Add --carry-from scan-virustotal, which restores the records still pending in that pull request before appending: without it the run writes a history missing every snapshot nobody has merged yet.

The VT API key comes from: $VIRUSTOTAL_API_KEY env var, or ask the user.

For each binary artifact (.bin, .exe):

1. Download via gh release download.
2. Compute SHA256 locally (must match the digest in the scan history, when present).
3. Check GET /api/v3/files/{sha256} to see if VT already has results.
4. If not found or results are stale (older than 7 days), upload via POST /api/v3/files.
5. Poll GET /api/v3/analyses/{id} until status == "completed".
6. Handle rate limits (HTTP 429) by waiting 60 seconds and retrying.

Step 3: collect results

For each artifact, record:

• Filename, file size in bytes
• SHA256
• VT report URL: https://www.virustotal.com/gui/file/{sha256}
• Total engines scanned
• Number of malicious detections
• For each engine that flagged it: engine name and detection name
• The at-release snapshot from the scan history, when present: current counts below it mean earlier false-positive submissions are being processed

Also record the VT report URLs for the clean .whl and .tar.gz source distributions (used as evidence in every submission).

Step 4: print summary table

Print a markdown table:

Step 5: generate per-vendor submission files

For each vendor in § Vendor definitions, check if any artifacts were flagged by that vendor's engine(s). If so, generate fp-submission-{vendor}.md at the project root.

Only generate a file for a vendor if at least one artifact was flagged by that vendor.

Output format: fully self-contained, zero cross-references

Each submission file must be optimized for copy-paste. The maintainer should be able to work through each submission without scrolling back or cross-referencing. Concretely:

• Never write "copy from above" or "see the file section above". Every field value must be spelled out inline at the point of use.
• For vendors requiring one submission per file: repeat the full form walkthrough for each binary as a separate ## Submission N section with --- separators.
• For vendors accepting a single submission covering multiple files: one section is fine, but list every binary with its full details (SHA256, VT link, detection name, download URL) inline in the text.
• Every pre-written text block must include the specific binary's VT scan link, the clean source distribution VT links, and the GitHub release link. No placeholders: use the actual URLs.

Dynamic project metadata

All submission text blocks must derive project details from pyproject.toml and git metadata:

• Project name: from [project] name.
• License: from [project] license.
• Homepage/PyPI URL: from [project.urls].
• Maintainer name: from git config user.name or [project] authors.
• Previous FP reference: search the repo's GitHub issues for "false positive" or "VirusTotal" to find a prior reference issue. If none exists, omit the reference.

Vendor definitions

User-facing documentation of vendor portals, submission priority, and common issues is in docs/security.md § AV false-positive submissions.

Microsoft (engines: Microsoft)

• Portal: https://www.microsoft.com/en-us/wdsi/filesubmission?persona=SoftwareDeveloper
• Requires Microsoft account login. Select "Software developer" on the persona page.
• One file per form submission. Generate a separate ## Submission N section per flagged binary.
• Only include binaries where Microsoft's own engine returned category == "malicious". Windows ARM64 binaries are typically not flagged by Microsoft (only by MaxSecure), so check before including.
• macOS binaries can be flagged by Microsoft too (with Wacatac variants): include them if detected.
• Form fields per binary:

• Additional information: 1900 character limit. Include: binary's VT scan link, clean .whl and .tar.gz VT links, GitHub release link, project URL, PyPI URL, license, previous FP reference if found.
• Known portal issues: the upload sometimes fails with CORS errors or stuck progress modals (auth session expiring mid-upload). Workaround: sign out, clear cookies for microsoft.com and wdsiprod.westus.cloudapp.azure.com, sign back in, submit immediately. Also check the URL doesn't have a duplicated ?persona=SoftwareDeveloper&persona=SoftwareDeveloper parameter.

BitDefender (engines: BitDefender, ALYac, Arcabit, Emsisoft, GData, MicroWorld-eScan, VIPRE)

• Portal: https://www.bitdefender.com/submit/
• BitDefender's engine powers ~6 downstream vendors. Fixing BitDefender removes the most detections per submission.
• Only list artifacts flagged by the BitDefender engine itself (not downstream).
• One file per submission. Max 25 MB per file upload.
• The "Sensitive files / Screenshot" field is mandatory: instruct the user to take a screenshot of the VT report page showing the BitDefender detection row.
• Form fields per binary:

• Generate one complete ## Submission N section per binary.
• Known portal issues: the form sometimes returns "Your request could not be registered!" with no details. This is a backend issue on BitDefender's side. Retry later.