mirror of
https://github.com/Anon-Planet/thgtoa.git
synced 2026-05-06 11:34:18 +02:00
Moving some things around
Signed-off-by: nopeitsnothing <no@anonymousplanet.org>
This commit is contained in:
nopeitsnothing
@@ -0,0 +1,132 @@
|
||||
# PDF Build, Scan & Release Scripts
|
||||
|
||||
This directory contains scripts for building PDFs from MkDocs documentation, scanning them with VirusTotal, generating hashes, and uploading artifacts to GitHub releases.
|
||||
|
||||
## Scripts
|
||||
|
||||
### `pdf_release.sh` (v2 - Recommended)
|
||||
The main script that handles:
|
||||
- SHA256 hash generation for PDF files
|
||||
- VirusTotal scanning of PDFs
|
||||
- Release creation/update on GitHub
|
||||
- GPG signature verification support
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
./scripts/pdf_release.sh --build <light|dark|both> --release <tag|latest> [--vt-api-key VT_KEY] [--github-token TOKEN]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `--build`: PDF build mode (`light`, `dark`, or `both`) - Required
|
||||
- `--release`: Release update mode (`tag` for tagged releases, `latest` to always update) - Default: `tag`
|
||||
- `--vt-api-key`: VirusTotal API key (optional)
|
||||
- `--github-token`: GitHub token for release operations (optional)
|
||||
|
||||
### `build_guide_pdf.py`
|
||||
Python script that builds MkDocs documentation and converts it to PDF using Chromium/Chrome.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
python scripts/build_guide_pdf.py --both # Build both light and dark mode
|
||||
python scripts/build_guide_pdf.py --dark-mode # Dark mode only
|
||||
python scripts/build_guide_pdf.py --skip-mkdocs # Skip MkDocs build, use existing site
|
||||
```
|
||||
|
||||
## GitHub Actions Workflow
|
||||
|
||||
The workflow `.github/workflows/build-pdf-combined.yml` combines all operations:
|
||||
|
||||
1. **Build PDFs** - Generates light/dark mode PDFs with GPG signatures
|
||||
2. **Scan & Release** - Scans with VirusTotal and updates/releases artifacts
|
||||
|
||||
### Required Secrets
|
||||
|
||||
Add these to your repository settings under **Settings > Secrets and variables > Actions**:
|
||||
|
||||
- `GPG_PRIVATE_KEY`: Your GPG private key for signing
|
||||
- `GPG_PASSPHRASE`: Passphrase for the GPG key (if any)
|
||||
- `VT_API_KEY`: VirusTotal API key for malware scanning
|
||||
- `GITHUB_TOKEN`: Automatically available, but can be manually added
|
||||
|
||||
### Workflow Triggers
|
||||
|
||||
The workflow runs on:
|
||||
- Manual dispatch (`workflow_dispatch`) with customizable options
|
||||
- Push to main branch when docs, mkdocs.yml, or scripts change
|
||||
|
||||
## Output Files
|
||||
|
||||
After running the build and release process, you'll get:
|
||||
|
||||
```
|
||||
export/
|
||||
├── thgtoa.pdf # Light mode PDF
|
||||
├── thgtoa-dark.pdf # Dark mode PDF
|
||||
├── thgtoa.pdf.sig # GPG signature for light PDF
|
||||
├── thgtoa-dark.pdf.sig # GPG signature for dark PDF
|
||||
├── thgtoa.pdf.sha256 # SHA256 hash for light PDF
|
||||
├── thgtoa-dark.pdf.sha256 # SHA256 hash for dark PDF
|
||||
├── sha256sum-combined.txt # Combined hash file
|
||||
├── sha256sum-combined.txt.sig # GPG signature for combined hashes
|
||||
└── virus-total-results.md # VirusTotal scan results
|
||||
```
|
||||
|
||||
## Hash Verification
|
||||
|
||||
To verify the integrity of downloaded PDFs:
|
||||
|
||||
```bash
|
||||
# Verify against individual hash file
|
||||
sha256sum -c thgtoa.pdf.sha256
|
||||
|
||||
# Or verify against combined hash file
|
||||
sha256sum -c sha256sum-combined.txt
|
||||
```
|
||||
|
||||
## VirusTotal Integration
|
||||
|
||||
When a `VT_API_KEY` is provided, the script will:
|
||||
1. Upload each PDF to VirusTotal's API
|
||||
2. Generate individual scan reports
|
||||
3. Include VT report links in release notes and artifacts
|
||||
|
||||
The VT results file (`virus-total-results.md`) contains:
|
||||
- Scan timestamp
|
||||
- SHA256 hashes for each PDF
|
||||
- Direct links to VirusTotal GUI reports
|
||||
|
||||
## Release Management
|
||||
|
||||
The script supports two release modes:
|
||||
|
||||
1. **Tag mode** (`--release tag`): Updates the release matching the current git tag
|
||||
2. **Latest mode** (`--release latest`): Always updates the most recent release (useful for continuous deployment)
|
||||
|
||||
When running in a GitHub Actions workflow with a tag push, it will automatically create or update the corresponding release.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### PDF Build Fails
|
||||
- Ensure Chrome/Chromium is installed: `sudo apt install chromium-browser`
|
||||
- Check MkDocs configuration is valid: `mkdocs build --strict`
|
||||
- Verify all documentation files are present and properly formatted
|
||||
|
||||
### VirusTotal Scan Fails
|
||||
- Check VT_API_KEY secret is correctly set in repository settings
|
||||
- Verify the API key has sufficient quota (free tier allows 4 requests/minute)
|
||||
- Check network connectivity to VirusTotal API
|
||||
|
||||
### Release Upload Fails
|
||||
- Ensure GITHUB_TOKEN has appropriate permissions (repo scope)
|
||||
- For existing releases, use `--release latest` instead of `tag`
|
||||
- Check that the release tag format matches GitHub's requirements (e.g., `v1.0.0`)
|
||||
|
||||
## Security Notes
|
||||
|
||||
- **GPG Keys**: Never commit private keys to version control. Use GitHub Secrets.
|
||||
- **VT API Key**: Keep your VirusTotal API key secret and rotate periodically.
|
||||
- **Release Artifacts**: All uploaded artifacts are publicly visible on your releases page.
|
||||
|
||||
## License
|
||||
|
||||
These scripts are part of the "The How-To Guide To Anonymity" project and follow the same licensing as the main repository.
|
||||
Reference in New Issue
Block a user