prokop/thgtoa
1
0
Fork 0
mirror of https://github.com/Anon-Planet/thgtoa.git synced 2026-05-06 11:34:18 +02:00
Code Issues Packages Projects Releases Wiki Activity

Moving some things around

Browse Source 
Signed-off-by: nopeitsnothing <no@anonymousplanet.org>
This commit is contained in:
nopeitsnothing
2026-04-20 02:45:06 -04:00
parent 28556c016c
commit 904fa24478
17 changed files with 397 additions and 641 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/changelog/index.md
+68
View File
@@ -0,0 +1,68 @@
---
title: "TBA"
description: ""
schema:
"@context": https://schema.org
"@type": Organization
"@id": https://www.anonymousplanet.org/
name: Anonymous Planet
url: https://www.anonymousplanet.org/authors/
logo: ../media/favicon.png
sameAs:
- https://github.com/Anon-Planet
- https://opencollective.com/anonymousplanetorg
- https://mastodon.social/@anonymousplanet
---
# Changelog
All notable changes to this project will be documented in this file.
## [Unreleased]
### Added
- This changelog page
- Add ways to verify the files
### Changed
- Refactored GitHub Actions workflow **Build PDF** (`scripts\build_guide_pdf.py`): now builds both light and dark mode PDFs (`export/thgtoa.pdf` and `export/thgtoa-dark.pdf` respectively).
- Restored previous VT scans
## Fixed
- `docs/about/index.md`: replace broken reference-style internal links
- `docs/guide/index.md`: Appendix A6: comment out deprecated ODT information because we don't and probably won't use it in the future
### Feature
- Updated `scripts/build_guide_pdf.py` to use `--print-to-pdf` instead of `--save-as` for PDF generation, and added a new `--dark-mode` flag to generate dark mode PDFs. The script now supports generating both light and dark mode PDFs with a single command invocation by using the `--both` flag. This change improves the PDF generation process and provides better support for dark mode users. Save your eyes - you only get one pair.
## [1.2.1] - 2026-04-11
### Added
- GitHub Actions workflow **Build PDF** (`.github/workflows/build-pdf.yml`): installs Chromium on `ubuntu-latest`, runs `scripts/build_guide_pdf.py`, uploads `export/guide.pdf` as the `guide-pdf` artifact. Runs on `workflow_dispatch`, on pushes to `main` that touch docs or build inputs, and on matching pull requests.
- `scripts/build_guide_pdf.py` to build the MkDocs site and render the guide to a single PDF (`export/guide.pdf` by default) using a Chromium-based browser (Chrome or Edge) headless print-to-PDF.
- `docs/stylesheets/extra.css` and `extra_css` in `mkdocs.yml` for shared site styling.
- This `CHANGELOG.md`.
### Changed
- `README.md` “Ways to read or export the guide”: hosted link, local `mkdocs serve`, PDF build via the script, ODT note, raw Markdown link.
- Guide landing layout: wrap the opening block in `docs/guide/index.md` with a `guide-intro-lead` container so the logo and first sections share one layout context for web and print.
- `.gitignore` to exclude local build outputs `export/`, `site/`, and `_site_test/`.
- `scripts/build_guide_pdf.py`: when the `CI` environment variable is set, pass Chromium flags (`--no-sandbox`, `--disable-setuid-sandbox`, `--disable-dev-shm-usage`) so headless print works on typical CI images.
- `README.md`: note the **Build PDF** GitHub Actions workflow and the `guide-pdf` artifact.
### Fixed
- `docs/guide/index.md`: replace broken reference-style internal links (`[label][label:]`) with working same-page fragment links to the correct headings; correct the mismatched “Real-Name System” cross-reference; fix a broken footnote marker on the “free (unallocated) space of your hard drive” list item.
[Unreleased]: https://github.com/Anon-Planet/thgtoa/compare/v1.2.1...HEAD
[1.2.1]: https://github.com/Anon-Planet/thgtoa/releases/tag/v1.2.1
***The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),***
***and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).***
docs/guide/dev-workflow.md
+17 -161
View File
@@ -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.*
docs/index.md
+4 -5
View File
@@ -17,14 +17,13 @@ schema:
# **Hello, and welcome to the Hitchhiker's Guide.**
**9FA5 436D 0EE3 6098 5157 3825 17EC A05F 768D EDF6**
This is the master signing key fingerprint for Anonymous Planet.
You'll use it to [**verify the checksum** and **GPG signature** of all files for authenticity.](verify/index.md)
Please share this project if you enjoy it and you think it might be useful to others.
You'll use it to [**verify the checksum** and **GPG signature** of all files for authenticity.](verify/index.md)
Please share this project if you enjoy it and you think it might be useful to others.
![Anonymous Planet logo](media/profile.png){ align=right }
Anonymous Planet is a collective of volunteers and contributors. No one person is considered more valuable than another, and no one person should be viewed as having "more impact" on Anonymous Planet.
Anonymous Planet is a collective of volunteers.
??? person "Das Kolburn"
docs/verify/index.md
+9 -6
View File
@@ -62,9 +62,12 @@ gpg --verify export/thgtoa-dark.pdf.sig export/thgtoa-dark.pdf
Expected output for successful verification:
```
gpg: Signature made [date]
gpg: using RSA key [key-id]
gpg: Good signature from "[owner]"
gpg: Signature made Mon 20 Apr 2026 01:46:40 AM EDT
gpg: using EDDSA key 9FA5436D0EE360985157382517ECA05F768DEDF6
gpg: Good signature from "Anonymous Planet Master Signing Key" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: 9FA5 436D 0EE3 6098 5157 3825 17EC A05F 768D EDF6
```
#### 3. Check VirusTotal Status
@@ -114,9 +117,9 @@ The GitHub Actions workflows automatically:
## Key Information
**Signing Key:** Anonymous Planet Master Key
**Key ID:** See `pgp/anonymousplanet-master.asc` for details
**Fingerprint:** Verify from the repository's official documentation
**Signing Key:** Anonymous Planet Master Signing Key ("MSK")
**Key ID:** See `pgp/anonymousplanet-master.asc` for details
**Fingerprint:** Verify from the repository's official documentation
---