thgtoa/scripts

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:

./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:

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:

# 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.