From 5b013ced573220fbd42c5376095e824c7a70aca3 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:20:44 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- ARCHITECTURE.adoc | 48 +++++ ARCHITECTURE.md | 47 ---- CHANGELOG.adoc | 65 ++++++ CHANGELOG.md | 60 ------ CODE_OF_CONDUCT.adoc | 24 +++ CODE_OF_CONDUCT.md | 27 --- CONTRIBUTING.adoc | 115 ++++++++-- CONTRIBUTING.md | 116 ---------- GOVERNANCE.adoc | 60 ++++++ GOVERNANCE.md | 60 ------ README.adoc | 157 ++++++++++++++ README.md | 156 -------------- SECURITY.adoc | 378 +++++++++++++++++++++++++++++++++ SECURITY.md | 328 ---------------------------- docs/tech-debt-2026-05-26.adoc | 71 +++++++ docs/tech-debt-2026-05-26.md | 57 ----- 16 files changed, 905 insertions(+), 864 deletions(-) create mode 100644 ARCHITECTURE.adoc delete mode 100644 ARCHITECTURE.md create mode 100644 CHANGELOG.adoc delete mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md create mode 100644 GOVERNANCE.adoc delete mode 100644 GOVERNANCE.md create mode 100644 README.adoc delete mode 100644 README.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 docs/tech-debt-2026-05-26.adoc delete mode 100644 docs/tech-debt-2026-05-26.md diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..82b6dd6 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,65 @@ +== Changelog + +All notable changes to `+ipv6-site-enforcer+` will be documented in this +file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat: add RSR scaffolding and update manifest dependencies +* feat: add FlatRacoon manifest, K8s deployment for NAT64/DNS64 +* feat: add AI Gatekeeper Protocol manifest +* feat(ci): enable Hypatia scanning +* feat: initial scaffolding for IPv6-only enforcement + +==== Fixed + +* fix(licence): clear scaffold-placeholder leak (Tranche 2) (#35) +* fix(ci): sync hypatia-scan.yml to canonical (413: +env.HOME+Phase-2+SARIF) (#33) +* fix(ci): adopt canonical hypatia-scan.yml (env.HOME/scanner-layout + +Comment-step gate) (#31) +* fix(ci): Phase-2 fleet submission must not fail the security gate +(#30) +* fix(codeql): switch language matrix to '`actions`' (no JS/TS in repo) +(#29) +* fix: remove duplicate SCM files from root +* fix(security): update editorconfig SHA and CodeQL language + +==== Documentation + +* docs: record tech-debt audit findings (2026-05-26) (#41) +* docs(readme): add SPDX header and/or standard badges +* docs: add CONTRIBUTING.md +* docs: add checkpoint files for state tracking +* docs: update license from AGPL to PMPL + +==== CI + +* ci: bump actions/upload-artifact SHA to current v4 (#27) +* ci(secret-scanner): drop duplicate –fail from trufflehog extra_args +(#26) +* ci: fix workflow-linter YAML parse error + self-flag bug +* ci: fix workflow-linter self-flag bug + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 9c87532..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Changelog - -All notable changes to `ipv6-site-enforcer` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat: add RSR scaffolding and update manifest dependencies -- feat: add FlatRacoon manifest, K8s deployment for NAT64/DNS64 -- feat: add AI Gatekeeper Protocol manifest -- feat(ci): enable Hypatia scanning -- feat: initial scaffolding for IPv6-only enforcement - -### Fixed - -- fix(licence): clear scaffold-placeholder leak (Tranche 2) (#35) -- fix(ci): sync hypatia-scan.yml to canonical (413: env.HOME+Phase-2+SARIF) (#33) -- fix(ci): adopt canonical hypatia-scan.yml (env.HOME/scanner-layout + Comment-step gate) (#31) -- fix(ci): Phase-2 fleet submission must not fail the security gate (#30) -- fix(codeql): switch language matrix to 'actions' (no JS/TS in repo) (#29) -- fix: remove duplicate SCM files from root -- fix(security): update editorconfig SHA and CodeQL language - -### Documentation - -- docs: record tech-debt audit findings (2026-05-26) (#41) -- docs(readme): add SPDX header and/or standard badges -- docs: add CONTRIBUTING.md -- docs: add checkpoint files for state tracking -- docs: update license from AGPL to PMPL - -### CI - -- ci: bump actions/upload-artifact SHA to current v4 (#27) -- ci(secret-scanner): drop duplicate --fail from trufflehog extra_args (#26) -- ci: fix workflow-linter YAML parse error + self-flag bug -- ci: fix workflow-linter self-flag bug - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index eb045d6..8559a5b 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -1,20 +1,109 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Contributing Guide +== Clone the repository -== Getting Started +git clone https://github.com/hyperpolymath/ipv6-site-enforcer.git cd +ipv6-site-enforcer -1. Fork the repository -2. Create a feature branch from `main` -3. Sign off commits (`git commit -s`) -4. Submit a pull request +== Using Nix (recommended for reproducibility) -== Commit Guidelines +nix develop -* Conventional commits: `type(scope): description` -* Sign all commits (DCO required) -* Atomic, focused commits +== Or using toolbox/distrobox -== License +toolbox create ipv6-site-enforcer-dev toolbox enter +ipv6-site-enforcer-dev # Install dependencies manually -Contributions licensed under project license. +== Verify setup +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +ipv6-site-enforcer/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # +Library code (Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) +├── plugins/ # Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter 2) +├── docs/ # Documentation (Perimeter 3) │ ├── architecture/ # ADRs, +specs (Perimeter 2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ +# Examples (Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ +# Test suite (Perimeter 2-3) ├── .well-known/ # Protocol files +(Perimeter 1-3) ├── .github/ # GitHub config (Perimeter 1) │ ├── +ISSUE_TEMPLATE/ │ └── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── LICENSE ├── +MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.nix # Nix flake +(Perimeter 1) └── Justfile # Task runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `{{MAIN_BRANCH}}` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/ipv6-site-enforcer/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/ipv6-site-enforcer/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/ipv6-site-enforcer/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/ipv6-site-enforcer/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 801caff..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/ipv6-site-enforcer.git -cd ipv6-site-enforcer - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create ipv6-site-enforcer-dev -toolbox enter ipv6-site-enforcer-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -ipv6-site-enforcer/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `{{MAIN_BRANCH}}` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/ipv6-site-enforcer/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/ipv6-site-enforcer/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/ipv6-site-enforcer/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/ipv6-site-enforcer/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..77ef1f6 --- /dev/null +++ b/README.adoc @@ -0,0 +1,157 @@ +https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/ipv6-site-enforcer[image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF +Best Practices]] +https://github.com/hyperpolymath/palimpsest-license[image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: +PMPL-1.0]] + +== Purpose + +Tools and configurations to enforce IPv6-only ingress and service +routing across the FlatRacoon Network Stack. + +Part of the +https://github.com/hyperpolymath/flatracoon-netstack[FlatRacoon Network +Stack]. + +== Architecture + +.... + Internet (Dual-Stack) + │ + ┌──────────▼──────────┐ + │ IPv6 Ingress │ + │ (This Module) │ + │ ──────────────── │ + │ • NAT64/DNS64 │ + │ • IPv4 rejection │ + │ • Happy Eyeballs │ + └──────────┬──────────┘ + │ IPv6 only + ┌─────────────────┼─────────────────┐ + │ │ │ +┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ +│ Services │ │ ZeroTier │ │ IPFS │ +│ (K8s) │ │ Overlay │ │ Nodes │ +└─────────────┘ └─────────────┘ └─────────────┘ +.... + +== Components + +* *NAT64/DNS64 gateway* - Jool-based translation for legacy clients +* *IPv6 ingress controller* - Nginx/Envoy configured for v6-only +* *Policy enforcement* - NetworkPolicy manifests rejecting IPv4 +* *Monitoring hooks* - Prometheus metrics for v4 rejection counts +* *Happy Eyeballs support* - RFC 8305 compliant client handling + +== Directory Structure + +.... +ipv6-site-enforcer/ +├── manifests/ +│ ├── nat64-deployment.yaml +│ ├── dns64-configmap.yaml +│ ├── ingress-controller.yaml +│ └── networkpolicy-v6only.yaml +├── configs/ +│ ├── jool.ncl # NAT64 configuration +│ ├── dns64.ncl # DNS64 resolver config +│ ├── ingress.ncl # Ingress controller settings +│ └── policy.ncl # Network policy rules +├── scripts/ +│ ├── enforce-v6.sh # Runtime enforcement +│ ├── audit-v4.sh # Detect IPv4 leakage +│ └── metrics.sh # Collect rejection metrics +├── Justfile +├── README.adoc +├── STATE.scm +├── META.scm +└── ECOSYSTEM.scm +.... + +== Inputs + +[width="100%",cols="22%,47%,31%",options="header",] +|=== +|Input |Description |Source +|IPv6 prefix |Allocated /48 or /64 for services |Network administrator +|NAT64 prefix |64:ff9b::/96 or custom |Configuration +|DNS64 upstream |Resolver for synthesis |Network configuration +|Ingress rules |Service exposure policies |configs/ingress.ncl +|=== + +== Outputs + +[cols=",",options="header",] +|=== +|Output |Description +|IPv6-only ingress |All inbound traffic forced to IPv6 +|NAT64 gateway |Legacy IPv4 client compatibility +|Rejection metrics |IPv4 attempt counts and sources +|Audit logs |Compliance reporting +|=== + +== Integration Points + +=== With FlatRacoon Stack + +* *zerotier-k8s-link* - Overlay uses IPv6 addressing +* *ipfs-overlay* - IPFS nodes bind to IPv6 only +* *network-dashboard* - v4 rejection metrics displayed +* *bgp-backbone-lab* - IPv6 route announcements + +=== Machine-Readable Manifest + +[source,json] +---- +{ + "module": "ipv6-site-enforcer", + "version": "0.1.0", + "layer": "network", + "requires": ["kubernetes", "jool", "dns64"], + "provides": ["ipv6-only-ingress", "nat64", "dns64"], + "config_schema": "configs/schema.ncl", + "health_endpoint": "/ipv6/health", + "metrics_endpoint": "/ipv6/metrics" +} +---- + +== Quick Start + +[source,bash] +---- +# 1. Deploy NAT64/DNS64 gateway +just deploy-gateway + +# 2. Configure ingress controller +just configure-ingress + +# 3. Apply network policies +just enforce-policies + +# 4. Verify enforcement +just audit +---- + +== IPv6 Addressing Scheme + +.... +2001:db8:face::/48 # Example allocation +├── 2001:db8:face:0::/64 # Kubernetes services +├── 2001:db8:face:1::/64 # ZeroTier overlay +├── 2001:db8:face:2::/64 # IPFS cluster +└── 2001:db8:face:ff::/64 # NAT64 pool +.... + +== Status + +Phase + +Scaffolding + +Completion + +5% + +Next + +NAT64/DNS64 deployment manifests + +== License + +MPL-2.0 diff --git a/README.md b/README.md deleted file mode 100644 index c477a12..0000000 --- a/README.md +++ /dev/null @@ -1,156 +0,0 @@ - - -[![OpenSSF Best Practices](https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity)](https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/ipv6-site-enforcer) -[![License: PMPL-1.0](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](https://github.com/hyperpolymath/palimpsest-license) - -# Purpose - -Tools and configurations to enforce IPv6-only ingress and service -routing across the FlatRacoon Network Stack. - -Part of the [FlatRacoon Network -Stack](https://github.com/hyperpolymath/flatracoon-netstack). - -# Architecture - - Internet (Dual-Stack) - │ - ┌──────────▼──────────┐ - │ IPv6 Ingress │ - │ (This Module) │ - │ ──────────────── │ - │ • NAT64/DNS64 │ - │ • IPv4 rejection │ - │ • Happy Eyeballs │ - └──────────┬──────────┘ - │ IPv6 only - ┌─────────────────┼─────────────────┐ - │ │ │ - ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ - │ Services │ │ ZeroTier │ │ IPFS │ - │ (K8s) │ │ Overlay │ │ Nodes │ - └─────────────┘ └─────────────┘ └─────────────┘ - -# Components - -- **NAT64/DNS64 gateway** - Jool-based translation for legacy clients - -- **IPv6 ingress controller** - Nginx/Envoy configured for v6-only - -- **Policy enforcement** - NetworkPolicy manifests rejecting IPv4 - -- **Monitoring hooks** - Prometheus metrics for v4 rejection counts - -- **Happy Eyeballs support** - RFC 8305 compliant client handling - -# Directory Structure - - ipv6-site-enforcer/ - ├── manifests/ - │ ├── nat64-deployment.yaml - │ ├── dns64-configmap.yaml - │ ├── ingress-controller.yaml - │ └── networkpolicy-v6only.yaml - ├── configs/ - │ ├── jool.ncl # NAT64 configuration - │ ├── dns64.ncl # DNS64 resolver config - │ ├── ingress.ncl # Ingress controller settings - │ └── policy.ncl # Network policy rules - ├── scripts/ - │ ├── enforce-v6.sh # Runtime enforcement - │ ├── audit-v4.sh # Detect IPv4 leakage - │ └── metrics.sh # Collect rejection metrics - ├── Justfile - ├── README.adoc - ├── STATE.scm - ├── META.scm - └── ECOSYSTEM.scm - -# Inputs - -| Input | Description | Source | -|----------------|-----------------------------------|-----------------------| -| IPv6 prefix | Allocated /48 or /64 for services | Network administrator | -| NAT64 prefix | 64:ff9b::/96 or custom | Configuration | -| DNS64 upstream | Resolver for synthesis | Network configuration | -| Ingress rules | Service exposure policies | configs/ingress.ncl | - -# Outputs - -| Output | Description | -|-------------------|------------------------------------| -| IPv6-only ingress | All inbound traffic forced to IPv6 | -| NAT64 gateway | Legacy IPv4 client compatibility | -| Rejection metrics | IPv4 attempt counts and sources | -| Audit logs | Compliance reporting | - -# Integration Points - -## With FlatRacoon Stack - -- **zerotier-k8s-link** - Overlay uses IPv6 addressing - -- **ipfs-overlay** - IPFS nodes bind to IPv6 only - -- **network-dashboard** - v4 rejection metrics displayed - -- **bgp-backbone-lab** - IPv6 route announcements - -## Machine-Readable Manifest - -```json -{ - "module": "ipv6-site-enforcer", - "version": "0.1.0", - "layer": "network", - "requires": ["kubernetes", "jool", "dns64"], - "provides": ["ipv6-only-ingress", "nat64", "dns64"], - "config_schema": "configs/schema.ncl", - "health_endpoint": "/ipv6/health", - "metrics_endpoint": "/ipv6/metrics" -} -``` - -# Quick Start - -```bash -# 1. Deploy NAT64/DNS64 gateway -just deploy-gateway - -# 2. Configure ingress controller -just configure-ingress - -# 3. Apply network policies -just enforce-policies - -# 4. Verify enforcement -just audit -``` - -# IPv6 Addressing Scheme - - 2001:db8:face::/48 # Example allocation - ├── 2001:db8:face:0::/64 # Kubernetes services - ├── 2001:db8:face:1::/64 # ZeroTier overlay - ├── 2001:db8:face:2::/64 # IPFS cluster - └── 2001:db8:face:ff::/64 # NAT64 pool - -# Status - -Phase -Scaffolding - -Completion -5% - -Next -NAT64/DNS64 deployment manifests - -# License - -MPL-2.0 diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..6833c54 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,378 @@ +Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. Table of Contents + +.... +Reporting a Vulnerability +What to Include +Response Timeline +Disclosure Policy +Scope +Safe Harbour +Recognition +Security Updates +Security Best Practices +.... + +Reporting a Vulnerability Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +.... +Navigate to Report a Vulnerability +Click "Report a vulnerability" +Complete the form with as much detail as possible +Submit — we'll receive a private notification +.... + +This method ensures: + +.... +End-to-end encryption of your report +Private discussion space for collaboration +Coordinated disclosure tooling +Automatic credit when the advisory is published +.... + +Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +Email security@hyperpolymath.org PGP Key Download Public Key Fingerprint +See GPG key + +== Import our PGP key + +curl -sSL https://hyperpolymath.org/gpg/security.asc | gpg –import + +== Verify fingerprint + +gpg –fingerprint security@hyperpolymath.org + +== Encrypt your report + +gpg –armor –encrypt –recipient security@hyperpolymath.org report.txt + +.... +⚠️ Important: Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. +.... + +What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. Required Information + +.... +Description: Clear explanation of the vulnerability +Impact: What an attacker could achieve (confidentiality, integrity, availability) +Affected versions: Which versions/commits are affected +Reproduction steps: Detailed steps to reproduce the issue +.... + +Helpful Additional Information + +.... +Proof of concept: Code, scripts, or screenshots demonstrating the vulnerability +Attack scenario: Realistic attack scenario showing exploitability +CVSS score: Your assessment of severity (use CVSS 3.1 Calculator) +CWE ID: Common Weakness Enumeration identifier if known +Suggested fix: If you have ideas for remediation +References: Links to related vulnerabilities, research, or advisories +.... + +Example Report Structure + +=== Summary + +{empty}[One-sentence description of the vulnerability] + +=== Vulnerability Type + +{empty}[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +=== Affected Component + +{empty}[File path, function name, API endpoint, etc.] + +=== Affected Versions + +{empty}[Version range or specific commits] + +=== Severity Assessment + +* CVSS 3.1 Score: [X.X] +* CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +=== Description + +{empty}[Detailed technical description] + +=== Steps to Reproduce + +[arabic] +. [First step] +. [Second step] +. […] + +=== Proof of Concept + +{empty}[Code, curl commands, screenshots, etc.] + +=== Impact + +{empty}[What can an attacker achieve?] + +=== Suggested Remediation + +{empty}[Optional: your ideas for fixing] + +=== References + +{empty}[Links to related issues, CVEs, research] + +Response Timeline + +We commit to the following response times: Stage Timeframe Description +Initial Response 48 hours We acknowledge receipt and confirm we’re +investigating Triage 7 days We assess severity, confirm the +vulnerability, and estimate timeline Status Update Every 7 days Regular +updates on remediation progress Resolution 90 days Target for fix +development and release (complex issues may take longer) Disclosure 90 +days Public disclosure after fix is available (coordinated with you) + +.... +Note: These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. +.... + +Disclosure Policy + +We follow coordinated disclosure (also known as responsible disclosure): + +.... +You report the vulnerability privately +We acknowledge and begin investigation +We develop a fix and prepare a release +We coordinate disclosure timing with you +We publish security advisory and fix simultaneously +You may publish your research after disclosure +.... + +Our Commitments + +.... +We will not take legal action against researchers who follow this policy +We will work with you to understand and resolve the issue +We will credit you in the security advisory (unless you prefer anonymity) +We will notify you before public disclosure +We will publish advisories with sufficient detail for users to assess risk +.... + +Your Commitments + +.... +Report vulnerabilities promptly after discovery +Give us reasonable time to address the issue before disclosure +Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability +Do not degrade service availability (no DoS testing on production) +Do not share vulnerability details with others until coordinated disclosure +.... + +Disclosure Timeline + +Day 0 You report vulnerability Day 1-2 We acknowledge receipt Day 7 We +confirm vulnerability and share initial assessment Day 7-90 We develop +and test fix Day 90 Coordinated public disclosure (earlier if fix is +ready; later by mutual agreement) + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. Scope In Scope ✅ + +The following are within scope for security research: + +.... +This repository (hyperpolymath/terrapin-ssg) and all its code +Official releases and packages published from this repository +Documentation that could lead to security issues +Build and deployment configurations in this repository +Dependencies (report here, we'll coordinate with upstream) +.... + +Out of Scope ❌ + +The following are not in scope: + +.... +Third-party services we integrate with (report directly to them) +Social engineering attacks against maintainers +Physical security +Denial of service attacks against production infrastructure +Spam, phishing, or other non-technical attacks +Issues already reported or publicly known +Theoretical vulnerabilities without proof of concept +.... + +Qualifying Vulnerabilities + +We’re particularly interested in: + +.... +Remote code execution +SQL injection, command injection, code injection +Authentication/authorisation bypass +Cross-site scripting (XSS) and cross-site request forgery (CSRF) +Server-side request forgery (SSRF) +Path traversal / local file inclusion +Information disclosure (credentials, PII, secrets) +Cryptographic weaknesses +Deserialisation vulnerabilities +Memory safety issues (buffer overflows, use-after-free, etc.) +Supply chain vulnerabilities (dependency confusion, etc.) +Significant logic flaws +.... + +Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +.... +Missing security headers on non-sensitive pages +Clickjacking on pages without sensitive actions +Self-XSS (requires victim to paste code) +Missing rate limiting (unless it enables a specific attack) +Username/email enumeration (unless high-risk context) +Missing cookie flags on non-sensitive cookies +Software version disclosure +Verbose error messages (unless exposing secrets) +Best practice deviations without demonstrable impact +.... + +Safe Harbour + +We support security research conducted in good faith. Our Promise + +If you conduct security research in accordance with this policy: + +.... +✅ We will not initiate legal action against you +✅ We will not report your activity to law enforcement +✅ We will work with you in good faith to resolve issues +✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +✅ We waive any potential claim against you for circumvention of security controls +.... + +Good Faith Requirements + +To qualify for safe harbour, you must: + +.... +Comply with this security policy +Report vulnerabilities promptly +Avoid privacy violations (do not access others' data) +Avoid service degradation (no destructive testing) +Not exploit vulnerabilities beyond proof-of-concept +Not use vulnerabilities for profit (beyond bug bounties where offered) + +⚠️ Important: This safe harbour does not extend to third-party systems. Always check their policies before testing. +.... + +Recognition + +We believe in recognising security researchers who help us improve. Hall +of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +Security Acknowledgments (unless they prefer anonymity). + +Recognition includes: + +.... +Your name (or chosen alias) +Link to your website/profile (optional) +Brief description of the vulnerability class +Date of report +.... + +What We Offer + +.... +✅ Public credit in security advisories +✅ Acknowledgment in release notes +✅ Entry in our Hall of Fame +✅ Reference/recommendation letter upon request (for significant findings) +.... + +What We Don’t Currently Offer + +.... +❌ Monetary bug bounties +❌ Hardware or swag +❌ Paid security research contracts + +Note: We're a community project with limited resources. Your contributions help everyone who uses this software. +.... + +Security Updates Receiving Updates + +To stay informed about security updates: + +.... +Watch this repository: Click "Watch" → "Custom" → Select "Security alerts" +GitHub Security Advisories: Published at Security Advisories +Release notes: Security fixes noted in CHANGELOG +.... + +Update Policy Severity Response Critical/High Patch release as soon as +fix is ready Medium Included in next scheduled release (or earlier) Low +Included in next scheduled release Supported Versions Version Supported +Notes main branch ✅ Yes Latest development Latest release ✅ Yes +Current stable Previous minor release ✅ Yes Security fixes backported +Older versions ❌ No Please upgrade Security Best Practices + +When using terrapin-ssg, we recommend: General + +.... +Keep dependencies up to date +Use the latest stable release +Subscribe to security notifications +Review configuration against security documentation +Follow principle of least privilege +.... + +For Contributors + +.... +Never commit secrets, credentials, or API keys +Use signed commits (git config commit.gpgsign true) +Review dependencies before adding them +Run security linters locally before pushing +Report any concerns about existing code +.... + +Additional Resources + +.... +Our PGP Public Key +Security Advisories +Changelog +Contributing Guidelines +CVE Database +CVSS Calculator +.... + +Contact Purpose Contact Security issues Report via GitHub or +security@hyperpolymath.org General questions GitHub Discussions Other +enquiries See README for contact information Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +.... +Committed to this repository with a clear commit message +Noted in the changelog +Announced via GitHub Discussions (for major changes) +.... + +Thank you for helping keep terrapin-ssg and its users safe. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 5eb5e20..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,328 +0,0 @@ -Security Policy - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. -Table of Contents - - Reporting a Vulnerability - What to Include - Response Timeline - Disclosure Policy - Scope - Safe Harbour - Recognition - Security Updates - Security Best Practices - -Reporting a Vulnerability -Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - - Navigate to Report a Vulnerability - Click "Report a vulnerability" - Complete the form with as much detail as possible - Submit — we'll receive a private notification - -This method ensures: - - End-to-end encryption of your report - Private discussion space for collaboration - Coordinated disclosure tooling - Automatic credit when the advisory is published - -Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -Email security@hyperpolymath.org -PGP Key Download Public Key -Fingerprint See GPG key - -# Import our PGP key -curl -sSL https://hyperpolymath.org/gpg/security.asc | gpg --import - -# Verify fingerprint -gpg --fingerprint security@hyperpolymath.org - -# Encrypt your report -gpg --armor --encrypt --recipient security@hyperpolymath.org report.txt - - ⚠️ Important: Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - -What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. -Required Information - - Description: Clear explanation of the vulnerability - Impact: What an attacker could achieve (confidentiality, integrity, availability) - Affected versions: Which versions/commits are affected - Reproduction steps: Detailed steps to reproduce the issue - -Helpful Additional Information - - Proof of concept: Code, scripts, or screenshots demonstrating the vulnerability - Attack scenario: Realistic attack scenario showing exploitability - CVSS score: Your assessment of severity (use CVSS 3.1 Calculator) - CWE ID: Common Weakness Enumeration identifier if known - Suggested fix: If you have ideas for remediation - References: Links to related vulnerabilities, research, or advisories - -Example Report Structure - -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] - -Response Timeline - -We commit to the following response times: -Stage Timeframe Description -Initial Response 48 hours We acknowledge receipt and confirm we're investigating -Triage 7 days We assess severity, confirm the vulnerability, and estimate timeline -Status Update Every 7 days Regular updates on remediation progress -Resolution 90 days Target for fix development and release (complex issues may take longer) -Disclosure 90 days Public disclosure after fix is available (coordinated with you) - - Note: These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - -Disclosure Policy - -We follow coordinated disclosure (also known as responsible disclosure): - - You report the vulnerability privately - We acknowledge and begin investigation - We develop a fix and prepare a release - We coordinate disclosure timing with you - We publish security advisory and fix simultaneously - You may publish your research after disclosure - -Our Commitments - - We will not take legal action against researchers who follow this policy - We will work with you to understand and resolve the issue - We will credit you in the security advisory (unless you prefer anonymity) - We will notify you before public disclosure - We will publish advisories with sufficient detail for users to assess risk - -Your Commitments - - Report vulnerabilities promptly after discovery - Give us reasonable time to address the issue before disclosure - Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability - Do not degrade service availability (no DoS testing on production) - Do not share vulnerability details with others until coordinated disclosure - -Disclosure Timeline - -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. -Scope -In Scope ✅ - -The following are within scope for security research: - - This repository (hyperpolymath/terrapin-ssg) and all its code - Official releases and packages published from this repository - Documentation that could lead to security issues - Build and deployment configurations in this repository - Dependencies (report here, we'll coordinate with upstream) - -Out of Scope ❌ - -The following are not in scope: - - Third-party services we integrate with (report directly to them) - Social engineering attacks against maintainers - Physical security - Denial of service attacks against production infrastructure - Spam, phishing, or other non-technical attacks - Issues already reported or publicly known - Theoretical vulnerabilities without proof of concept - -Qualifying Vulnerabilities - -We're particularly interested in: - - Remote code execution - SQL injection, command injection, code injection - Authentication/authorisation bypass - Cross-site scripting (XSS) and cross-site request forgery (CSRF) - Server-side request forgery (SSRF) - Path traversal / local file inclusion - Information disclosure (credentials, PII, secrets) - Cryptographic weaknesses - Deserialisation vulnerabilities - Memory safety issues (buffer overflows, use-after-free, etc.) - Supply chain vulnerabilities (dependency confusion, etc.) - Significant logic flaws - -Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - - Missing security headers on non-sensitive pages - Clickjacking on pages without sensitive actions - Self-XSS (requires victim to paste code) - Missing rate limiting (unless it enables a specific attack) - Username/email enumeration (unless high-risk context) - Missing cookie flags on non-sensitive cookies - Software version disclosure - Verbose error messages (unless exposing secrets) - Best practice deviations without demonstrable impact - -Safe Harbour - -We support security research conducted in good faith. -Our Promise - -If you conduct security research in accordance with this policy: - - ✅ We will not initiate legal action against you - ✅ We will not report your activity to law enforcement - ✅ We will work with you in good faith to resolve issues - ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws - ✅ We waive any potential claim against you for circumvention of security controls - -Good Faith Requirements - -To qualify for safe harbour, you must: - - Comply with this security policy - Report vulnerabilities promptly - Avoid privacy violations (do not access others' data) - Avoid service degradation (no destructive testing) - Not exploit vulnerabilities beyond proof-of-concept - Not use vulnerabilities for profit (beyond bug bounties where offered) - - ⚠️ Important: This safe harbour does not extend to third-party systems. Always check their policies before testing. - -Recognition - -We believe in recognising security researchers who help us improve. -Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our Security Acknowledgments (unless they prefer anonymity). - -Recognition includes: - - Your name (or chosen alias) - Link to your website/profile (optional) - Brief description of the vulnerability class - Date of report - -What We Offer - - ✅ Public credit in security advisories - ✅ Acknowledgment in release notes - ✅ Entry in our Hall of Fame - ✅ Reference/recommendation letter upon request (for significant findings) - -What We Don't Currently Offer - - ❌ Monetary bug bounties - ❌ Hardware or swag - ❌ Paid security research contracts - - Note: We're a community project with limited resources. Your contributions help everyone who uses this software. - -Security Updates -Receiving Updates - -To stay informed about security updates: - - Watch this repository: Click "Watch" → "Custom" → Select "Security alerts" - GitHub Security Advisories: Published at Security Advisories - Release notes: Security fixes noted in CHANGELOG - -Update Policy -Severity Response -Critical/High Patch release as soon as fix is ready -Medium Included in next scheduled release (or earlier) -Low Included in next scheduled release -Supported Versions -Version Supported Notes -main branch ✅ Yes Latest development -Latest release ✅ Yes Current stable -Previous minor release ✅ Yes Security fixes backported -Older versions ❌ No Please upgrade -Security Best Practices - -When using terrapin-ssg, we recommend: -General - - Keep dependencies up to date - Use the latest stable release - Subscribe to security notifications - Review configuration against security documentation - Follow principle of least privilege - -For Contributors - - Never commit secrets, credentials, or API keys - Use signed commits (git config commit.gpgsign true) - Review dependencies before adding them - Run security linters locally before pushing - Report any concerns about existing code - -Additional Resources - - Our PGP Public Key - Security Advisories - Changelog - Contributing Guidelines - CVE Database - CVSS Calculator - -Contact -Purpose Contact -Security issues Report via GitHub or security@hyperpolymath.org -General questions GitHub Discussions -Other enquiries See README for contact information -Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - - Committed to this repository with a clear commit message - Noted in the changelog - Announced via GitHub Discussions (for major changes) - -Thank you for helping keep terrapin-ssg and its users safe. diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..2d57af3 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — ipv6-site-enforcer — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+MEDIUM+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+NONE+` +|Body classifier |`+MPL-some+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |181 +|`+docs/+` files |0 +|`+docs/+` LoC |0 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +181 lines has likely grown to do the work of `+docs/+` — split it into a +thin README + `+docs/architecture.md+`, `+docs/usage.md+`, etc. +Heavy-wiki exemplars to copy from: `+affinescript+`, `+boj-server+`, +`+echidna+`, `+hypatia+`. + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 5ad7f60..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Tech-Debt Audit — ipv6-site-enforcer — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `MEDIUM`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `NONE` | -| Body classifier | `MPL-some` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 181 | -| `docs/` files | 0 | -| `docs/` LoC | 0 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 181 lines has likely grown to do the work of `docs/` — split it into a thin README + `docs/architecture.md`, `docs/usage.md`, etc. Heavy-wiki exemplars to copy from: `affinescript`, `boj-server`, `echidna`, `hypatia`. - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer.