Skip to content

docs: add binary integrity verification section (P0-4) #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
beonde merged 2 commits into from
May 2, 2026
Merged

docs: add binary integrity verification section (P0-4) #19

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
548f1cd
docs: add binary integrity verification section (P0-4)
beonde May 2, 2026
26d82cd
docs: clarify checksum bypass vs mismatch failure modes
beonde May 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,18 @@ The Python wrapper includes specific commands to manage the binary:
- **Linux**: AMD64, ARM64
- **Windows**: AMD64

## Binary Integrity Verification

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
```
Comment on lines +64 to +80
Copy link
Copy Markdown
Member Author

@beonde beonde May 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)


## Troubleshooting

**"Permission denied" errors:**
Expand All @@ -70,6 +82,10 @@ capiscio --wrapper-clean
**"Binary not found" or download errors:**
If you are behind a corporate firewall, ensure you can access `github.com`.

**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.
Copy link
Copy Markdown
Member Author

@beonde beonde May 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


## License

Apache-2.0
Loading