Build pipeline WIP

Signed-off-by: nopeitsnothing <no@anonymousplanet.org>
2026-05-06 11:34:18 +02:00 · 2026-04-16 06:32:57 -04:00
parent 41ac52de0a
commit 5636291c8a
12 changed files with 771 additions and 40 deletions
@@ -0,0 +1,193 @@
+# Development
+
+## Overview
+
+This repository now includes an automated workflow that handles PDF generation, verification, and distribution with the following features:
+
+??? Note "How the pipeline works"
+
+    1. **Automatic PDF Generation** - Builds both light and dark mode PDFs from MkDocs source
+    2. **SHA256 Hash Generation** - Creates hash files for integrity verification
+    3. **GPG Signature Signing** - Signs all PDFs and hash files with repository GPG key
+    4. **VirusTotal Scanning** - Automatically scans PDFs and updates release notes
+    5. **Release Automation** - Packages everything into GitHub releases
+
+## Workflow Architecture
+
+### 1. Build PDF Workflow (`build-pdf.yml`)
+
+**Trigger:** Push to main, pull requests, or manual dispatch
+
+??? Note "Steps"
+
+    - Checkout repository
+    - Set up Python 3.13 and MkDocs Material
+    - Install Chromium browser
+    - Generate both light and dark mode PDFs
+    - Create SHA256 hash files
+    - Sign all files with GPG
+    - Upload artifacts to GitHub Actions
+    - Publish release
+
+### 2. VirusTotal Scan Workflow (`vt-scan.yml`)
+
+**Trigger:** Push to main, tags, or manual dispatch (runs after build-pdf)
+
+??? Note "Steps"
+
+    - Download PDF artifacts from build workflow
+    - Scan both PDFs with VirusTotal API
+    - Extract scan results and generate report links
+    - Update release notes with VT scan status and URLs
+
+## File Structure
+
+After a successful build, the repository will contain:
+
+```
+.../
+├── export/
+│   ├── thgtoa.pdf              # Light mode PDF
+│   ├── thgtoa-dark.pdf         # Dark mode PDF
+│   ├── thgtoa.pdf.sig          # GPG signature (light)
+│   └── thgtoa-dark.pdf.sig     # GPG signature (dark)
+├── thgtoa.pdf.sha256           # Hash file (light)
+├── thgtoa-dark.pdf.sha256      # Hash file (dark)
+├── sha256sum-light.txt         # Combined hash file
+└── scripts/
+    ├── build_guide_pdf.py      # PDF generation script
+    └── verify_pdf.py           # Verification utility
+```
+
+## Security Features
+
+### 1. SHA256 Hash Verification
+
+**Purpose:** Ensure file integrity during download/transit
+
+**How it works:**
+- Each PDF gets a unique SHA256 hash calculated at build time
+- Hash stored in `.sha256` files alongside the PDFs
+- Combined `sha256sum-light.txt` for batch verification
+
+**Verification command:**
+```bash
+sha256sum -c sha256sum-light.txt
+```
+
+### 2. GPG Signature Verification
+
+**Purpose:** Verify authenticity and prevent tampering
+
+??? Note "How it works"
+
+    - Detached signatures created for each PDF and hash file
+    - Public keys available in `/pgp/` directory
+
+**Verification command:**
+```bash
+gpg --import pgp/anonymousplanet-master.asc
+gpg --verify export/thgtoa.pdf.sig export/thgtoa.pdf
+```
+
+### 3. VirusTotal Integration
+
+**Purpose:** Malware detection and security scanning
+
+??? Note "How it works"
+
+    - Automatic scan of all generated PDFs
+    - Results published in release notes with direct links
+    - Provides third-party validation of file safety
+
+## Usage Examples
+
+### Local Development
+
+```bash
+# Build PDFs locally
+python scripts/build_guide_pdf.py --both
+
+# Verify hashes
+python scripts/verify_pdf.py --hashes
+
+# Verify signatures (requires GPG installed)
+python scripts/verify_pdf.py --signatures
+
+# Full verification with VirusTotal check
+export VT_API_KEY=your_api_key
+python scripts/verify_pdf.py --all
+```
+
+### CI/CD Verification
+
+The workflows automatically verify everything during the build process. To manually trigger:
+
+1. Go to Actions tab
+2. Select "Build guide PDF" or "VirusTotal Scan"
+3. Click "Run workflow"
+4. Download artifacts from successful run
+
+## Release Process
+
+When you create a tag (e.g., `v1.0.0`):
+
+1. Push the tag: `git push origin v1.0.0`
+2. Build PDF workflow triggers automatically
+3. VirusTotal scan workflow runs after build completes
+4. Both workflows update/create GitHub release with:
+   - Light and dark mode PDFs
+   - GPG signatures for all files
+   - Hash files for verification
+   - Release notes with VT scan results
+
+## Troubleshooting
+
+### Common Issues
+
+**GPG signing fails:**
+- Check that `GPG_PRIVATE_KEY` is in ASCII armor format
+- Verify passphrase is correct
+- Ensure key has signing capability
+
+**Hash mismatch after download:**
+- Re-download the file (corruption during transfer)
+- Verify you're using the correct hash file
+- Check disk integrity
+
+**VirusTotal scan fails:**
+- Verify `VT_API_KEY` is set correctly
+- Check API quota limits (free tier: 4 requests/minute)
+- Ensure PDF files exist before scanning
+
+### Debug Mode
+
+Enable verbose output by adding to workflow:
+```yaml
+- name: Debug
+  run: |
+    echo "Current directory:" && pwd
+    echo "Files in export:" && ls -la export/
+    echo "Hash file contents:" && cat sha256sum-light.txt
+```
+
+## Best Practices
+
+1. **Always verify signatures** before opening PDFs from untrusted sources
+2. **Check VirusTotal results** for any suspicious detections
+3. **Keep GPG keys secure** - never commit private keys to repository
+4. **Monitor API usage** for VirusTotal to avoid rate limiting
+5. **Test locally** before pushing tags to production
+
+## Future Enhancements
+
+Potential improvements:
+- Multi-signature support (multiple maintainers)
+- Automated changelog generation with hashes
+- Cross-platform signature verification scripts
+- Integration with additional malware scanners
+- Automatic mirror updates with verified files
+
+---
+
+*This workflow is designed for security-conscious users who need to verify the authenticity and integrity of downloaded documents.*