docs: add binary integrity verification section (P0-4)#19
Conversation
Document the checksum verification behavior, CAPISCIO_SKIP_CHECKSUM env var, and add troubleshooting entry for checksum failures. Ref: DOCS_REMEDIATION_PLAN P0-4 Part B
|
✅ All checks passed! Ready for review. |
There was a problem hiding this comment.
Pull request overview
This PR updates the project README to document how the Python wrapper verifies the integrity of the downloaded capiscio-core binary, including the CAPISCIO_SKIP_CHECKSUM escape hatch and related troubleshooting guidance.
Changes:
- Added a “Binary Integrity Verification” section describing SHA-256 verification against the release
checksums.txt. - Added a troubleshooting entry for checksum verification failures and a pointer to the new section.
| On first run, the wrapper downloads the capiscio-core binary and verifies its SHA-256 checksum | ||
| against the published `checksums.txt` from the GitHub release. | ||
|
|
||
| If verification fails or the checksums file is unavailable: | ||
|
|
||
| ```bash | ||
| # Temporary bypass (not recommended for production) | ||
| export CAPISCIO_SKIP_CHECKSUM=true | ||
| ``` |
There was a problem hiding this comment.
Fixed in 26d82cd — rewrote the section to clearly distinguish the two failure modes:\n1. Checksum mismatch (hard failure, cannot be bypassed)\n2. Checksums unavailable (can bypass with CAPISCIO_SKIP_CHECKSUM=true)
| **Checksum verification failures:** | ||
| If you see "Checksum verification failed", the binary integrity could not be confirmed. | ||
| This can happen with pre-release versions or network issues. See the [Binary Integrity Verification](#binary-integrity-verification) section above. |
There was a problem hiding this comment.
Fixed in 26d82cd — now documents both cases separately with their distinct error messages:\n- "Binary integrity check failed" → corruption/tampering, cannot be bypassed\n- "Checksum verification failed: checksums.txt could not be fetched" → network issue, can bypass
Address review comment: CAPISCIO_SKIP_CHECKSUM only bypasses when checksums.txt is unavailable/missing entry. Actual checksum mismatches are hard failures that cannot be bypassed.
|
✅ All checks passed! Ready for review. |
Summary
Document the checksum verification behavior for the capiscio-core binary download.
Documentation Audit Reference
Phase: P0-4
Severity: Critical
Changes
README.md: Added "Binary Integrity Verification" section documentingCAPISCIO_SKIP_CHECKSUMenv varREADME.md: Added troubleshooting entry for checksum verification failuresVerification
src/capiscio/manager.py