mirror of
https://github.com/Anon-Planet/thgtoa.git
synced 2026-05-06 19:44:19 +02:00
Moving some things around
Signed-off-by: nopeitsnothing <no@anonymousplanet.org>
This commit is contained in:
nopeitsnothing
+17
-161
@@ -1,81 +1,35 @@
|
||||
# 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
|
||||
**Automatic PDF Generation:** - Builds both light and dark mode PDFs from MkDocs source
|
||||
**SHA256 Hash Generation:** - Creates hash files for integrity verification
|
||||
**GPG Signature Signing:** - Signs all PDFs and hash files with repository GPG key
|
||||
**VirusTotal Scanning:** - Automatically scans PDFs and updates release notes
|
||||
**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
|
||||
### Build PDF Workflow (`build-sign-release.yml`)
|
||||
|
||||
??? Note "Steps"
|
||||
|
||||
- Checkout repository
|
||||
- Set up Python 3.13 and MkDocs Material
|
||||
- Set up Python 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
|
||||
- Generate both light and dark mode PDFs with `scripts\build_guide_pdf.py`
|
||||
- Create SHA256 and blake2 hash files in `export/`
|
||||
- Sign all files with GPG in `export/`
|
||||
- Upload artifacts to GitHub Actions **manually**
|
||||
|
||||
### 2. VirusTotal Scan Workflow (`vt-scan.yml`)
|
||||
### SHA256 Hash Verification
|
||||
|
||||
**Trigger:** Push to main, tags, or manual dispatch (runs after build-pdf)
|
||||
!!! Note "**How it works**"
|
||||
|
||||
??? 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
|
||||
- Each PDF gets a unique SHA256 hash calculated at build time
|
||||
- Hash stored in `.sha256` files alongside the PDFs
|
||||
- Combined `sha256sum.txt` for batch verification
|
||||
### GPG Signature Verification
|
||||
|
||||
**Purpose:** Verify authenticity and prevent tampering
|
||||
|
||||
@@ -90,104 +44,6 @@ 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.*
|
||||
|
||||
Reference in New Issue
Block a user