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 index 56ad213..927f2bd 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -1,135 +1,148 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Changelog +== Changelog All notable changes to Qubes SDP will be documented in this file. -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -== [1.0.0] - 2024-11-22 - -=== Added - -==== Core System -- Simple setup script (`qubes-setup.sh`) for basic topology -- Advanced setup script (`qubes-setup-advanced.sh`) with full configuration -- Comprehensive configuration file (`qubes-config.conf`) -- Makefile (`Makefile.qubes`) for automation -- Salt Stack configuration for declarative setup - -==== Qubes -- Work qube with restricted firewall (HTTP/HTTPS/DNS only) -- Vault qube (air-gapped, no network) -- Anon qube (Tor/Whonix integration) -- Untrusted qube (DisposableVM template) -- Optional VPN qube (ProxyVM) -- Optional USB qube (device management) - -==== Features -- Topology presets (journalist, developer, researcher, teacher, pentester) -- Interactive setup wizard -- Dry-run mode for testing -- Comprehensive logging -- Rollback mechanism -- Progress indicators -- Health checks -- Split-GPG automation -- Split-SSH automation -- Qrexec policy generation -- Firewall rule automation -- Automated backups with cron -- Template update automation - -==== Tools -- `qubes-status.sh` - Status dashboard -- `qubes-dashboard.sh` - Interactive real-time monitor -- `qubes-firewall-analyzer.sh` - Firewall analysis -- `qubes-template-manager.sh` - Template management -- `qubes-backup-validator.sh` - Backup verification -- `qubes-restore.sh` - Disaster recovery -- `qubes-policy-generator.sh` - Qrexec policy management +The format is based on https://keepachangelog.com/en/1.0.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [1.0.0] - 2024-11-22 + +==== Added + +===== Core System + +* Simple setup script (`+qubes-setup.sh+`) for basic topology +* Advanced setup script (`+qubes-setup-advanced.sh+`) with full +configuration +* Comprehensive configuration file (`+qubes-config.conf+`) +* Makefile (`+Makefile.qubes+`) for automation +* Salt Stack configuration for declarative setup + +===== Qubes + +* Work qube with restricted firewall (HTTP/HTTPS/DNS only) +* Vault qube (air-gapped, no network) +* Anon qube (Tor/Whonix integration) +* Untrusted qube (DisposableVM template) +* Optional VPN qube (ProxyVM) +* Optional USB qube (device management) + +===== Features + +* Topology presets (journalist, developer, researcher, teacher, +pentester) +* Interactive setup wizard +* Dry-run mode for testing +* Comprehensive logging +* Rollback mechanism +* Progress indicators +* Health checks +* Split-GPG automation +* Split-SSH automation +* Qrexec policy generation +* Firewall rule automation +* Automated backups with cron +* Template update automation + +===== Tools + +* `+qubes-status.sh+` - Status dashboard +* `+qubes-dashboard.sh+` - Interactive real-time monitor +* `+qubes-firewall-analyzer.sh+` - Firewall analysis +* `+qubes-template-manager.sh+` - Template management +* `+qubes-backup-validator.sh+` - Backup verification +* `+qubes-restore.sh+` - Disaster recovery +* `+qubes-policy-generator.sh+` - Qrexec policy management + +===== Documentation + +* Comprehensive README with architecture diagrams +* QUICKSTART guide for rapid deployment +* CONTRIBUTING guidelines +* Complete wiki system with 10+ pages: +** Getting Started +** Installation Guide +** Configuration Guide +** Security Guide +** Topology Presets +** Split-GPG Guide +** Split-SSH Guide +** Backup & Restore Guide +** Troubleshooting +** FAQ +* Example configurations (journalist, developer, minimal) +* API documentation +* Tool documentation + +===== Testing + +* Syntax tests for all scripts +* Unit tests for components +* Integration tests for system interactions +* Security tests for vulnerabilities +* Automated test runner + +===== Wiki System + +* Markdown to HTML builder +* Professional responsive design +* Interactive features (TOC, copy buttons) +* Search functionality +* Mobile-friendly layout + +==== Security + +* Air-gapped vault enforced +* Default-deny firewall policies +* Minimal template usage +* DisposableVM for risky content +* Split-GPG/SSH key isolation +* Comprehensive security testing +* Input validation throughout +* No hardcoded credentials ==== Documentation -- Comprehensive README with architecture diagrams -- QUICKSTART guide for rapid deployment -- CONTRIBUTING guidelines -- Complete wiki system with 10+ pages: - - Getting Started - - Installation Guide - - Configuration Guide - - Security Guide - - Topology Presets - - Split-GPG Guide - - Split-SSH Guide - - Backup & Restore Guide - - Troubleshooting - - FAQ -- Example configurations (journalist, developer, minimal) -- API documentation -- Tool documentation - -==== Testing -- Syntax tests for all scripts -- Unit tests for components -- Integration tests for system interactions -- Security tests for vulnerabilities -- Automated test runner - -==== Wiki System -- Markdown to HTML builder -- Professional responsive design -- Interactive features (TOC, copy buttons) -- Search functionality -- Mobile-friendly layout - -=== Security -- Air-gapped vault enforced -- Default-deny firewall policies -- Minimal template usage -- DisposableVM for risky content -- Split-GPG/SSH key isolation -- Comprehensive security testing -- Input validation throughout -- No hardcoded credentials - -=== Documentation -- 10+ wiki pages with 4000+ lines -- README with feature overview -- QUICKSTART for rapid onboarding -- Example configurations -- Troubleshooting guides -- FAQ with 50+ questions -- Tool documentation -- API reference - -== [Unreleased] - -=== Planned -- Web-based configuration UI -- Additional topology presets -- Automated security auditing -- Performance optimization tools -- Multi-language support -- Video tutorials -- Plugin system enhancements -- CI/CD pipeline integration -- Docker-based testing environment - -== Version History -=== [1.0.0] - 2024-11-22 -- Initial release -- Complete feature set -- Full documentation -- Production ready +* 10+ wiki pages with 4000+ lines +* README with feature overview +* QUICKSTART for rapid onboarding +* Example configurations +* Troubleshooting guides +* FAQ with 50+ questions +* Tool documentation +* API reference + +=== [Unreleased] + +==== Planned + +* Web-based configuration UI +* Additional topology presets +* Automated security auditing +* Performance optimization tools +* Multi-language support +* Video tutorials +* Plugin system enhancements +* CI/CD pipeline integration +* Docker-based testing environment + +=== Version History + +==== [1.0.0] - 2024-11-22 + +* Initial release +* Complete feature set +* Full documentation +* Production ready ---- +''''' -== Types of Changes +=== Types of Changes -- **Added** for new features -- **Changed** for changes in existing functionality -- **Deprecated** for soon-to-be removed features -- **Removed** for now removed features -- **Fixed** for any bug fixes -- **Security** for vulnerability fixes +* *Added* for new features +* *Changed* for changes in existing functionality +* *Deprecated* for soon-to-be removed features +* *Removed* for now removed features +* *Fixed* for any bug fixes +* *Security* for vulnerability fixes diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 6ea2b8a..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,134 +0,0 @@ -# Changelog - -All notable changes to Qubes SDP will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [1.0.0] - 2024-11-22 - -### Added - -#### Core System -- Simple setup script (`qubes-setup.sh`) for basic topology -- Advanced setup script (`qubes-setup-advanced.sh`) with full configuration -- Comprehensive configuration file (`qubes-config.conf`) -- Makefile (`Makefile.qubes`) for automation -- Salt Stack configuration for declarative setup - -#### Qubes -- Work qube with restricted firewall (HTTP/HTTPS/DNS only) -- Vault qube (air-gapped, no network) -- Anon qube (Tor/Whonix integration) -- Untrusted qube (DisposableVM template) -- Optional VPN qube (ProxyVM) -- Optional USB qube (device management) - -#### Features -- Topology presets (journalist, developer, researcher, teacher, pentester) -- Interactive setup wizard -- Dry-run mode for testing -- Comprehensive logging -- Rollback mechanism -- Progress indicators -- Health checks -- Split-GPG automation -- Split-SSH automation -- Qrexec policy generation -- Firewall rule automation -- Automated backups with cron -- Template update automation - -#### Tools -- `qubes-status.sh` - Status dashboard -- `qubes-dashboard.sh` - Interactive real-time monitor -- `qubes-firewall-analyzer.sh` - Firewall analysis -- `qubes-template-manager.sh` - Template management -- `qubes-backup-validator.sh` - Backup verification -- `qubes-restore.sh` - Disaster recovery -- `qubes-policy-generator.sh` - Qrexec policy management - -#### Documentation -- Comprehensive README with architecture diagrams -- QUICKSTART guide for rapid deployment -- CONTRIBUTING guidelines -- Complete wiki system with 10+ pages: - - Getting Started - - Installation Guide - - Configuration Guide - - Security Guide - - Topology Presets - - Split-GPG Guide - - Split-SSH Guide - - Backup & Restore Guide - - Troubleshooting - - FAQ -- Example configurations (journalist, developer, minimal) -- API documentation -- Tool documentation - -#### Testing -- Syntax tests for all scripts -- Unit tests for components -- Integration tests for system interactions -- Security tests for vulnerabilities -- Automated test runner - -#### Wiki System -- Markdown to HTML builder -- Professional responsive design -- Interactive features (TOC, copy buttons) -- Search functionality -- Mobile-friendly layout - -### Security -- Air-gapped vault enforced -- Default-deny firewall policies -- Minimal template usage -- DisposableVM for risky content -- Split-GPG/SSH key isolation -- Comprehensive security testing -- Input validation throughout -- No hardcoded credentials - -### Documentation -- 10+ wiki pages with 4000+ lines -- README with feature overview -- QUICKSTART for rapid onboarding -- Example configurations -- Troubleshooting guides -- FAQ with 50+ questions -- Tool documentation -- API reference - -## [Unreleased] - -### Planned -- Web-based configuration UI -- Additional topology presets -- Automated security auditing -- Performance optimization tools -- Multi-language support -- Video tutorials -- Plugin system enhancements -- CI/CD pipeline integration -- Docker-based testing environment - -## Version History - -### [1.0.0] - 2024-11-22 -- Initial release -- Complete feature set -- Full documentation -- Production ready - ---- - -## Types of Changes - -- **Added** for new features -- **Changed** for changes in existing functionality -- **Deprecated** for soon-to-be removed features -- **Removed** for now removed features -- **Fixed** for any bug fixes -- **Security** for vulnerability fixes diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..11abf46 --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,240 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +our community a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, color, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +=== Our Standards + +==== Examples of behavior that contributes to a positive environment: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our +mistakes, and learning from the experience +* Focusing on what is best not just for us as individuals, but for the +overall community +* Using welcoming and inclusive language +* *Recognizing and respecting emotional safety* as fundamental to +productive collaboration +* *Assuming good intent* and seeking clarification before making +accusations +* *Celebrating experimentation* and learning from failures without blame + +==== Examples of unacceptable behavior: + +* The use of sexualized language or imagery, and sexual attention or +advances of any kind +* Trolling, insulting or derogatory comments, and personal or political +attacks +* Public or private harassment +* Publishing others’ private information, such as a physical or email +address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a +professional setting +* *Weaponizing mistakes* against contributors +* *Gate-keeping* or dismissing newcomers’ contributions +* *Deliberate stress-inducing* communication patterns +* *Invalidating others’ experiences* or emotions + +=== Emotional Safety + +Beyond traditional conduct standards, we recognize *emotional safety* as +critical to community health: + +==== We Value + +* *Psychological safety* - Freedom to experiment without fear of +humiliation +* *Reversibility* - Ability to undo mistakes easily (git revert, +rollback, etc.) +* *Gentle feedback* - Constructive criticism without personal attacks +* *Learning culture* - Mistakes are learning opportunities, not failings +* *Inclusive language* - Avoiding jargon that excludes newcomers +* *Transparent processes* - Clear contribution pathways reduce anxiety + +==== We Avoid + +* *Perfectionism* - Demanding flawless contributions from the start +* *Time pressure* - Arbitrary deadlines that induce stress +* *Public shaming* - Calling out mistakes in humiliating ways +* *Imposter syndrome triggers* - "`This is obvious`", "`Everyone +knows`", etc. +* *Gatekeeping* - "`You should already know this`" +* *Scope creep* - Demanding endless revisions beyond original scope + +=== Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our +standards of acceptable behavior and will take appropriate and fair +corrective action in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other +contributions that are not aligned to this Code of Conduct, and will +communicate reasons for moderation decisions when appropriate. + +=== Scope + +This Code of Conduct applies within all community spaces, and also +applies when an individual is officially representing the community in +public spaces. Examples of representing our community include using an +official e-mail address, posting via an official social media account, +or acting as an appointed representative at an online or offline event. + +=== Tri-Perimeter Contribution Framework (TPCF) + +This project operates under TPCF *Perimeter 3 (Community Sandbox)*: + +==== What This Means + +* *Open Contribution* - All contributions welcome, regardless of +employer +* *Community Governance* - Decisions made through consensus or +maintainer discretion +* *No Corporate Control* - Project independence from any single +organization +* *Meritocracy* - Contributions judged on technical merit and community +value +* *Transparency* - Decisions explained publicly + +==== Contribution Expectations + +* *Be patient* - Maintainers are volunteers with limited time +* *Be thorough* - Include tests, documentation, and clear commit +messages +* *Be respectful* - Follow this Code of Conduct +* *Be collaborative* - Work with maintainers, don’t demand acceptance +* *Be understanding* - Not all contributions fit project scope + +=== Enforcement + +==== Reporting + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported to the community leaders responsible for enforcement at: + +*Email:* conduct@qubes-sdp.org + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security +of the reporter of any incident. + +==== Confidentiality + +Reports will be kept confidential. Details may be shared only with: + +* Other maintainers (to assess and respond) +* Legal authorities (if required by law) +* The accused (only facts necessary for their response) + +*We will never:* + +* Publicly disclose reporter identity without consent +* Retaliate against good-faith reporters +* Share reports with the reporter’s employer +* Use reports for purposes beyond community safety + +==== Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of +this Code of Conduct: + +===== 1. Correction + +*Community Impact:* Use of inappropriate language or other behavior +deemed unprofessional or unwelcome in the community. + +*Consequence:* A private, written warning from community leaders, +providing clarity around the nature of the violation and an explanation +of why the behavior was inappropriate. A public apology may be +requested. + +===== 2. Warning + +*Community Impact:* A violation through a single incident or series of +actions. + +*Consequence:* A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period of +time. This includes avoiding interactions in community spaces as well as +external channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +===== 3. Temporary Ban + +*Community Impact:* A serious violation of community standards, +including sustained inappropriate behavior. + +*Consequence:* A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No +public or private interaction with the people involved, including +unsolicited interaction with those enforcing the Code of Conduct, is +allowed during this period. Violating these terms may lead to a +permanent ban. + +===== 4. Permanent Ban + +*Community Impact:* Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence:* A permanent ban from any sort of public interaction +within the community. + +=== Appeal Process + +If you believe an enforcement action was unjust: + +[arabic] +. *Email:* appeals@qubes-sdp.org within 14 days +. *Include:* +* Original incident details +* Enforcement action taken +* Why you believe it was unjust +* Any new information +. *Review:* Different maintainer(s) will review +. *Response:* Within 30 days +. *Final Decision:* Maintainers’ decision is final + +=== Attribution + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org[Contributor Covenant], version +2.1 +* https://github.com/hyperpolymath/cccp-manifesto[CCCP Manifesto] - +Emotional safety principles +* TPCF Framework - Tri-perimeter contribution model + +For answers to common questions about this code of conduct, see the FAQ +at https://www.contributor-covenant.org/faq + +=== Updates + +This Code of Conduct may be updated to reflect community growth and +feedback. + +*Version:* 1.0.0 *Last Updated:* 2024-11-22 *Canonical URL:* +https://github.com/hyperpolymath/qubes-sdp/blob/main/CODE_OF_CONDUCT.md + +=== Contact + +* *General Questions:* conduct@qubes-sdp.org +* *Report Violation:* conduct@qubes-sdp.org (confidential) +* *Appeals:* appeals@qubes-sdp.org +* *Suggestions:* contribute@qubes-sdp.org diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index c8fd57a..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,180 +0,0 @@ -# Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -## Our Standards - -### Examples of behavior that contributes to a positive environment: - -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience -* Focusing on what is best not just for us as individuals, but for the overall community -* Using welcoming and inclusive language -* **Recognizing and respecting emotional safety** as fundamental to productive collaboration -* **Assuming good intent** and seeking clarification before making accusations -* **Celebrating experimentation** and learning from failures without blame - -### Examples of unacceptable behavior: - -* The use of sexualized language or imagery, and sexual attention or advances of any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email address, without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a professional setting -* **Weaponizing mistakes** against contributors -* **Gate-keeping** or dismissing newcomers' contributions -* **Deliberate stress-inducing** communication patterns -* **Invalidating others' experiences** or emotions - -## Emotional Safety - -Beyond traditional conduct standards, we recognize **emotional safety** as critical to community health: - -### We Value - -* **Psychological safety** - Freedom to experiment without fear of humiliation -* **Reversibility** - Ability to undo mistakes easily (git revert, rollback, etc.) -* **Gentle feedback** - Constructive criticism without personal attacks -* **Learning culture** - Mistakes are learning opportunities, not failings -* **Inclusive language** - Avoiding jargon that excludes newcomers -* **Transparent processes** - Clear contribution pathways reduce anxiety - -### We Avoid - -* **Perfectionism** - Demanding flawless contributions from the start -* **Time pressure** - Arbitrary deadlines that induce stress -* **Public shaming** - Calling out mistakes in humiliating ways -* **Imposter syndrome triggers** - "This is obvious", "Everyone knows", etc. -* **Gatekeeping** - "You should already know this" -* **Scope creep** - Demanding endless revisions beyond original scope - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. - -## Tri-Perimeter Contribution Framework (TPCF) - -This project operates under TPCF **Perimeter 3 (Community Sandbox)**: - -### What This Means - -* **Open Contribution** - All contributions welcome, regardless of employer -* **Community Governance** - Decisions made through consensus or maintainer discretion -* **No Corporate Control** - Project independence from any single organization -* **Meritocracy** - Contributions judged on technical merit and community value -* **Transparency** - Decisions explained publicly - -### Contribution Expectations - -* **Be patient** - Maintainers are volunteers with limited time -* **Be thorough** - Include tests, documentation, and clear commit messages -* **Be respectful** - Follow this Code of Conduct -* **Be collaborative** - Work with maintainers, don't demand acceptance -* **Be understanding** - Not all contributions fit project scope - -## Enforcement - -### Reporting - -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at: - -**Email:** conduct@qubes-sdp.org - -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the reporter of any incident. - -### Confidentiality - -Reports will be kept confidential. Details may be shared only with: - -* Other maintainers (to assess and respond) -* Legal authorities (if required by law) -* The accused (only facts necessary for their response) - -**We will never:** - -* Publicly disclose reporter identity without consent -* Retaliate against good-faith reporters -* Share reports with the reporter's employer -* Use reports for purposes beyond community safety - -### Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: - -#### 1. Correction - -**Community Impact:** Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. - -**Consequence:** A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. - -#### 2. Warning - -**Community Impact:** A violation through a single incident or series of actions. - -**Consequence:** A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -#### 3. Temporary Ban - -**Community Impact:** A serious violation of community standards, including sustained inappropriate behavior. - -**Consequence:** A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -#### 4. Permanent Ban - -**Community Impact:** Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence:** A permanent ban from any sort of public interaction within the community. - -## Appeal Process - -If you believe an enforcement action was unjust: - -1. **Email:** appeals@qubes-sdp.org within 14 days -2. **Include:** - - Original incident details - - Enforcement action taken - - Why you believe it was unjust - - Any new information - -3. **Review:** Different maintainer(s) will review -4. **Response:** Within 30 days -5. **Final Decision:** Maintainers' decision is final - -## Attribution - -This Code of Conduct is adapted from: - -* [Contributor Covenant](https://www.contributor-covenant.org), version 2.1 -* [CCCP Manifesto](https://github.com/hyperpolymath/cccp-manifesto) - Emotional safety principles -* TPCF Framework - Tri-perimeter contribution model - -For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq - -## Updates - -This Code of Conduct may be updated to reflect community growth and feedback. - -**Version:** 1.0.0 -**Last Updated:** 2024-11-22 -**Canonical URL:** https://github.com/hyperpolymath/qubes-sdp/blob/main/CODE_OF_CONDUCT.md - -## Contact - -* **General Questions:** conduct@qubes-sdp.org -* **Report Violation:** conduct@qubes-sdp.org (confidential) -* **Appeals:** appeals@qubes-sdp.org -* **Suggestions:** contribute@qubes-sdp.org diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index eb045d6..dab29bd 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -1,20 +1,3 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Contributing Guide - -== Getting Started - -1. Fork the repository -2. Create a feature branch from `main` -3. Sign off commits (`git commit -s`) -4. Submit a pull request - -== Commit Guidelines - -* Conventional commits: `type(scope): description` -* Sign all commits (DCO required) -* Atomic, focused commits - -== License - -Contributions licensed under project license. +== Contributing +See CONTRIBUTING.adoc for full contribution guidelines. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index bf6cd14..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,3 +0,0 @@ -# Contributing - -See [CONTRIBUTING.adoc](CONTRIBUTING.adoc) for full contribution guidelines. 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/MAINTAINERS.adoc b/MAINTAINERS.adoc index 48d9781..0606b98 100644 --- a/MAINTAINERS.adoc +++ b/MAINTAINERS.adoc @@ -1,47 +1,259 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This document lists the maintainers of the Qubes SDP project and +explains the governance model. -== Current Maintainers +=== Current Maintainers -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact +==== Lead Maintainer -| Jonathan D.A. Jewell -| Lead Maintainer -| https://github.com/hyperpolymath[@hyperpolymath] -|=== +* *Name:* [To be designated] +* *GitHub:* [@username] +* *Email:* lead@qubes-sdp.org +* *Responsibilities:* +** Final decision on contentious issues +** Release management +** Security coordination +** Community health -== Responsibilities +==== Core Maintainers -Maintainers are responsible for: +_(To be added as project grows)_ -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +* *Name:* [Contributor Name] +** *Focus Areas:* Setup scripts, automation +** *GitHub:* [@username] +** *Email:* [email] +* *Name:* [Contributor Name] +** *Focus Areas:* Documentation, wiki +** *GitHub:* [@username] +** *Email:* [email] +* *Name:* [Contributor Name] +** *Focus Areas:* Testing, CI/CD +** *GitHub:* [@username] +** *Email:* [email] -== Becoming a Maintainer +=== Governance Model -Contributors who demonstrate: +==== TPCF Perimeter 3 - Community Sandbox -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +This project operates in *TPCF Perimeter 3*, which means: -May be invited to become maintainers at the discretion of existing maintainers. +* *Open contribution* - Anyone can contribute +* *Meritocracy* - Contributions judged on technical merit +* *No corporate control* - Independent from any single organization +* *Community-driven* - Decisions made by consensus when possible +* *Maintainer discretion* - Final decisions when consensus fails -== Decision Making +==== Decision Making -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +===== Consensus-Driven -== Contact +For most decisions, we seek consensus among: 1. Active contributors (3+ +merged PRs in last 6 months) 2. Core maintainers 3. Community feedback +(issues, discussions) -For questions about project governance, open an issue or contact the maintainers listed above. +*Process:* 1. Proposal posted as GitHub Discussion or Issue 2. Minimum 7 +days for feedback 3. Address concerns and iterate 4. If consensus +reached, implement 5. If no consensus, maintainer makes final call + +===== Maintainer Decision + +For urgent or contentious issues: 1. Lead maintainer has final say 2. +Decision must be explained publicly 3. Appeals can be made (see +CODE_OF_CONDUCT.md) + +==== Areas Requiring Consensus + +* Breaking API changes +* License changes +* Security policy changes +* Code of Conduct changes +* Adding/removing maintainers +* Project direction (major features) + +==== Areas for Maintainer Decision + +* Bug fixes +* Documentation improvements +* Dependency updates +* Minor features (aligned with roadmap) +* Code style consistency +* Issue triage + +=== Becoming a Maintainer + +Maintainers are not appointed arbitrarily. The path is: + +==== 1. Consistent Contribution (6+ months) + +* Regular PRs (documentation, code, tests) +* Quality contributions (thorough, well-tested) +* Community engagement (helping others, reviews) +* Alignment with project values + +==== 2. Domain Expertise + +Demonstrate deep knowledge in at least one area: * Qubes OS architecture +* Security best practices * Bash scripting * Salt Stack * Documentation +* Community management + +==== 3. Trust Building + +* Respectful communication +* Collaborative approach +* Follows Code of Conduct +* Constructive code reviews +* Helps newcomers + +==== 4. Nomination + +Current maintainers discuss and nominate candidates: * Lead maintainer +initiates discussion * Consensus among current maintainers * Public +announcement and invitation * Nominee accepts or declines + +==== 5. Onboarding + +New maintainers receive: * Repository write access * Maintainer +documentation * Security disclosure access * Community contact +information * Mentorship from existing maintainer + +=== Maintainer Responsibilities + +==== Code Review + +* Respond to PRs within 7 days +* Provide constructive feedback +* Ensure code quality standards +* Verify tests pass +* Check security implications + +==== Issue Triage + +* Label issues appropriately +* Close duplicates/spam +* Ask for clarification +* Welcome newcomers +* Identify good-first-issues + +==== Community + +* Be welcoming and inclusive +* Model Code of Conduct +* Help onboard contributors +* Recognize contributions +* Manage conflict constructively + +==== Security + +* Monitor security reports +* Coordinate vulnerability disclosure +* Review security-sensitive changes +* Maintain SECURITY.md +* Update .well-known/security.txt + +==== Release Management + +* Follow semantic versioning +* Maintain CHANGELOG.md +* Tag releases appropriately +* Update documentation +* Announce releases + +==== Time Commitment + +Maintainers should expect: * *Minimum:* 4 hours/month (issue triage, PR +review) * *Typical:* 8-10 hours/month (above + features) * *Active +releases:* 15-20 hours/month (release prep, testing) + +*Note:* This is volunteer work. Life happens. Communicate +unavailability. + +=== Stepping Down + +Maintainers can step down anytime: + +[arabic] +. *Notify* other maintainers privately +. *Transition* ongoing work +. *Remove* yourself from MAINTAINERS.md +. *Announce* publicly (optional) + +*No explanation required.* We respect your time and privacy. + +==== Emeritus Status + +Former maintainers who contributed significantly: * Listed in +ACKNOWLEDGMENTS.md * Retain recognition in git history * Can return as +maintainer if desired * Invited to occasional discussions + +=== Inactive Maintainers + +If a maintainer is inactive (no activity for 6+ months): + +[arabic] +. *Outreach* - Check if they’re okay, need help +. *Transition* - Reassign their responsibilities +. *Move to emeritus* - Remove write access, list as emeritus +. *No penalty* - Can return anytime + +=== Conflict Resolution + +==== Among Maintainers + +[arabic] +. *Private discussion* - Try to resolve directly +. *Mediation* - Another maintainer mediates +. *Lead decision* - Lead maintainer decides +. *Last resort* - Vote (simple majority) + +==== With Community + +[arabic] +. *Public discussion* - In issue/PR/discussion +. *Code of Conduct* - Follow enforcement guidelines +. *Appeal process* - See CODE_OF_CONDUCT.md + +=== Contact + +==== Public + +* *GitHub Discussions:* For feature requests, Q&A +* *GitHub Issues:* For bugs, improvements +* *Email:* contribute@qubes-sdp.org + +==== Private + +* *Security:* security@qubes-sdp.org +* *Code of Conduct:* conduct@qubes-sdp.org +* *Maintainers:* maintainers@qubes-sdp.org + +=== Acknowledgments + +We’re grateful to all contributors, past and present: + +* Contributors (1+ merged PR): See git history +* Community helpers: Forum/chat moderators +* Testers: Those who test in production +* Documenters: Wiki and guide writers +* Security researchers: Responsible disclosure + +=== Updates + +This document is reviewed semi-annually and updated as needed. + +*Version:* 1.0.0 *Last Updated:* 2024-11-22 + +''''' + +=== For Prospective Maintainers + +Interested in becoming a maintainer? + +[arabic] +. *Start contributing* - Pick an issue, submit PRs +. *Be patient* - Build trust over months, not weeks +. *Ask questions* - We’re happy to mentor +. *Have fun* - This is volunteer work; enjoy it! + +Welcome to the community! 🎉 diff --git a/MAINTAINERS.md b/MAINTAINERS.md deleted file mode 100644 index f8409c7..0000000 --- a/MAINTAINERS.md +++ /dev/null @@ -1,272 +0,0 @@ -# Maintainers - -This document lists the maintainers of the Qubes SDP project and explains the governance model. - -## Current Maintainers - -### Lead Maintainer - -* **Name:** [To be designated] -* **GitHub:** [@username] -* **Email:** lead@qubes-sdp.org -* **Responsibilities:** - - Final decision on contentious issues - - Release management - - Security coordination - - Community health - -### Core Maintainers - -*(To be added as project grows)* - -* **Name:** [Contributor Name] - - **Focus Areas:** Setup scripts, automation - - **GitHub:** [@username] - - **Email:** [email] - -* **Name:** [Contributor Name] - - **Focus Areas:** Documentation, wiki - - **GitHub:** [@username] - - **Email:** [email] - -* **Name:** [Contributor Name] - - **Focus Areas:** Testing, CI/CD - - **GitHub:** [@username] - - **Email:** [email] - -## Governance Model - -### TPCF Perimeter 3 - Community Sandbox - -This project operates in **TPCF Perimeter 3**, which means: - -* **Open contribution** - Anyone can contribute -* **Meritocracy** - Contributions judged on technical merit -* **No corporate control** - Independent from any single organization -* **Community-driven** - Decisions made by consensus when possible -* **Maintainer discretion** - Final decisions when consensus fails - -### Decision Making - -#### Consensus-Driven - -For most decisions, we seek consensus among: -1. Active contributors (3+ merged PRs in last 6 months) -2. Core maintainers -3. Community feedback (issues, discussions) - -**Process:** -1. Proposal posted as GitHub Discussion or Issue -2. Minimum 7 days for feedback -3. Address concerns and iterate -4. If consensus reached, implement -5. If no consensus, maintainer makes final call - -#### Maintainer Decision - -For urgent or contentious issues: -1. Lead maintainer has final say -2. Decision must be explained publicly -3. Appeals can be made (see CODE_OF_CONDUCT.md) - -### Areas Requiring Consensus - -* Breaking API changes -* License changes -* Security policy changes -* Code of Conduct changes -* Adding/removing maintainers -* Project direction (major features) - -### Areas for Maintainer Decision - -* Bug fixes -* Documentation improvements -* Dependency updates -* Minor features (aligned with roadmap) -* Code style consistency -* Issue triage - -## Becoming a Maintainer - -Maintainers are not appointed arbitrarily. The path is: - -### 1. Consistent Contribution (6+ months) - -* Regular PRs (documentation, code, tests) -* Quality contributions (thorough, well-tested) -* Community engagement (helping others, reviews) -* Alignment with project values - -### 2. Domain Expertise - -Demonstrate deep knowledge in at least one area: -* Qubes OS architecture -* Security best practices -* Bash scripting -* Salt Stack -* Documentation -* Community management - -### 3. Trust Building - -* Respectful communication -* Collaborative approach -* Follows Code of Conduct -* Constructive code reviews -* Helps newcomers - -### 4. Nomination - -Current maintainers discuss and nominate candidates: -* Lead maintainer initiates discussion -* Consensus among current maintainers -* Public announcement and invitation -* Nominee accepts or declines - -### 5. Onboarding - -New maintainers receive: -* Repository write access -* Maintainer documentation -* Security disclosure access -* Community contact information -* Mentorship from existing maintainer - -## Maintainer Responsibilities - -### Code Review - -* Respond to PRs within 7 days -* Provide constructive feedback -* Ensure code quality standards -* Verify tests pass -* Check security implications - -### Issue Triage - -* Label issues appropriately -* Close duplicates/spam -* Ask for clarification -* Welcome newcomers -* Identify good-first-issues - -### Community - -* Be welcoming and inclusive -* Model Code of Conduct -* Help onboard contributors -* Recognize contributions -* Manage conflict constructively - -### Security - -* Monitor security reports -* Coordinate vulnerability disclosure -* Review security-sensitive changes -* Maintain SECURITY.md -* Update .well-known/security.txt - -### Release Management - -* Follow semantic versioning -* Maintain CHANGELOG.md -* Tag releases appropriately -* Update documentation -* Announce releases - -### Time Commitment - -Maintainers should expect: -* **Minimum:** 4 hours/month (issue triage, PR review) -* **Typical:** 8-10 hours/month (above + features) -* **Active releases:** 15-20 hours/month (release prep, testing) - -**Note:** This is volunteer work. Life happens. Communicate unavailability. - -## Stepping Down - -Maintainers can step down anytime: - -1. **Notify** other maintainers privately -2. **Transition** ongoing work -3. **Remove** yourself from MAINTAINERS.md -4. **Announce** publicly (optional) - -**No explanation required.** We respect your time and privacy. - -### Emeritus Status - -Former maintainers who contributed significantly: -* Listed in ACKNOWLEDGMENTS.md -* Retain recognition in git history -* Can return as maintainer if desired -* Invited to occasional discussions - -## Inactive Maintainers - -If a maintainer is inactive (no activity for 6+ months): - -1. **Outreach** - Check if they're okay, need help -2. **Transition** - Reassign their responsibilities -3. **Move to emeritus** - Remove write access, list as emeritus -4. **No penalty** - Can return anytime - -## Conflict Resolution - -### Among Maintainers - -1. **Private discussion** - Try to resolve directly -2. **Mediation** - Another maintainer mediates -3. **Lead decision** - Lead maintainer decides -4. **Last resort** - Vote (simple majority) - -### With Community - -1. **Public discussion** - In issue/PR/discussion -2. **Code of Conduct** - Follow enforcement guidelines -3. **Appeal process** - See CODE_OF_CONDUCT.md - -## Contact - -### Public - -* **GitHub Discussions:** For feature requests, Q&A -* **GitHub Issues:** For bugs, improvements -* **Email:** contribute@qubes-sdp.org - -### Private - -* **Security:** security@qubes-sdp.org -* **Code of Conduct:** conduct@qubes-sdp.org -* **Maintainers:** maintainers@qubes-sdp.org - -## Acknowledgments - -We're grateful to all contributors, past and present: - -* Contributors (1+ merged PR): See git history -* Community helpers: Forum/chat moderators -* Testers: Those who test in production -* Documenters: Wiki and guide writers -* Security researchers: Responsible disclosure - -## Updates - -This document is reviewed semi-annually and updated as needed. - -**Version:** 1.0.0 -**Last Updated:** 2024-11-22 - ---- - -## For Prospective Maintainers - -Interested in becoming a maintainer? - -1. **Start contributing** - Pick an issue, submit PRs -2. **Be patient** - Build trust over months, not weeks -3. **Ask questions** - We're happy to mentor -4. **Have fun** - This is volunteer work; enjoy it! - -Welcome to the community! 🎉 diff --git a/QUICKSTART.md b/QUICKSTART.adoc similarity index 52% rename from QUICKSTART.md rename to QUICKSTART.adoc index 54c6785..e6d463f 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.adoc @@ -1,49 +1,54 @@ -# Quick Start Guide +== Quick Start Guide Get Qubes SDP running in 5 minutes. -## Prerequisites Check +=== Prerequisites Check -✅ Running Qubes OS 4.1 or later -✅ At least 8GB RAM (16GB recommended) -✅ 50GB free disk space -✅ Internet connection (for template downloads) +✅ Running Qubes OS 4.1 or later ✅ At least 8GB RAM (16GB recommended) +✅ 50GB free disk space ✅ Internet connection (for template downloads) -## Installation in 3 Steps +=== Installation in 3 Steps -### Step 1: Download (in a qube, NOT dom0) +==== Step 1: Download (in a qube, NOT dom0) Choose one method: -**Option A: Git Clone** -```bash +*Option A: Git Clone* + +[source,bash] +---- # In a qube (e.g., work or personal): cd ~/Downloads git clone https://github.com/yourusername/qubes-sdp.git -``` +---- + +*Option B: Download ZIP* -**Option B: Download ZIP** -```bash +[source,bash] +---- # Download and extract cd ~/Downloads wget https://github.com/yourusername/qubes-sdp/archive/main.zip unzip main.zip mv qubes-sdp-main qubes-sdp -``` +---- -### Step 2: Transfer to dom0 +==== Step 2: Transfer to dom0 -```bash +[source,bash] +---- # In dom0 terminal: cd /tmp qvm-run --pass-io 'tar -C /home/user/Downloads/qubes-sdp -c .' | tar -x -``` +---- -Replace `` with the qube where you downloaded (e.g., `work`). +Replace `++` with the qube where you downloaded (e.g., +`+work+`). -### Step 3: Run Setup +==== Step 3: Run Setup -```bash +[source,bash] +---- # Still in dom0: cd /tmp/qubes-sdp @@ -54,19 +59,19 @@ cd /tmp/qubes-sdp ./qubes-setup.sh --dry-run # Then run for real: ./qubes-setup.sh -``` +---- -That's it! Setup creates 4 qubes: -- **work** - Your daily driver (2GB RAM, restricted network) -- **vault** - Air-gapped sensitive storage (1GB RAM, NO network) -- **anon** - Anonymous Tor qube (1GB RAM) -- **untrusted** - Disposable risky content handler (1GB RAM) +That’s it! Setup creates 4 qubes: - *work* - Your daily driver (2GB RAM, +restricted network) - *vault* - Air-gapped sensitive storage (1GB RAM, +NO network) - *anon* - Anonymous Tor qube (1GB RAM) - *untrusted* - +Disposable risky content handler (1GB RAM) -## Verification +=== Verification Check everything was created: -```bash +[source,bash] +---- # List SDP qubes qvm-ls | grep -E "(work|vault|anon|untrusted)" @@ -78,86 +83,104 @@ qvm-firewall work list # Run status check ./qubes-status.sh -``` +---- -## First Use +=== First Use -### Start a Qube +==== Start a Qube -```bash +[source,bash] +---- qvm-start work -``` +---- -Or click "work" in Qubes menu. +Or click "`work`" in Qubes menu. -### Transfer File to Vault +==== Transfer File to Vault -From work qube: -1. Right-click file -2. Select "Copy to other AppVM" -3. Choose "vault" +From work qube: 1. Right-click file 2. Select "`Copy to other AppVM`" 3. +Choose "`vault`" Or command line: -```bash + +[source,bash] +---- qvm-copy-to-vm vault /path/to/file -``` +---- -### Use Disposable VM +==== Use Disposable VM -```bash +[source,bash] +---- # Open file in disposable qvm-open-in-dvm suspicious-file.pdf # Run browser in disposable qvm-run --dispvm untrusted firefox -``` +---- + +=== Next Steps -## Next Steps +==== Customize Your Setup -### Customize Your Setup +[arabic] +. Copy example config: -1. Copy example config: -```bash +[source,bash] +---- cp examples/journalist-config.conf qubes-config.conf -``` +---- -2. Edit as needed: -```bash +[arabic, start=2] +. Edit as needed: + +[source,bash] +---- vi qubes-config.conf -``` +---- + +[arabic, start=3] +. Run advanced setup: -3. Run advanced setup: -```bash +[source,bash] +---- ./qubes-setup-advanced.sh -``` +---- + +==== Enable Advanced Features -### Enable Advanced Features +*Split-GPG (for encrypted email)*: -**Split-GPG (for encrypted email)**: -```bash +[source,bash] +---- # Edit config ENABLE_SPLIT_GPG="true" # Re-run setup ./qubes-setup-advanced.sh -``` +---- -**Split-SSH (for development)**: -```bash +*Split-SSH (for development)*: + +[source,bash] +---- ENABLE_SPLIT_SSH="true" ./qubes-setup-advanced.sh -``` +---- + +*Automated Backups*: -**Automated Backups**: -```bash +[source,bash] +---- AUTO_BACKUP="true" BACKUP_SCHEDULE="0 2 * * *" # Daily at 2 AM ./qubes-setup-advanced.sh -``` +---- -### Use Topology Presets +==== Use Topology Presets -```bash +[source,bash] +---- # Journalist workflow make -f Makefile.qubes setup-preset-journalist @@ -168,13 +191,14 @@ make -f Makefile.qubes setup-preset-developer TOPOLOGY_PRESET="custom" # Edit config for minimal resources ./qubes-setup-advanced.sh -``` +---- -## Common Tasks +=== Common Tasks -### Status and Monitoring +==== Status and Monitoring -```bash +[source,bash] +---- # Quick status ./tools/qubes-status.sh @@ -183,21 +207,23 @@ TOPOLOGY_PRESET="custom" # Firewall analysis ./tools/qubes-firewall-analyzer.sh -``` +---- -### Template Management +==== Template Management -```bash +[source,bash] +---- # Update all templates ./tools/qubes-template-manager.sh update # Clean package cache ./tools/qubes-template-manager.sh clean -``` +---- -### Backups +==== Backups -```bash +[source,bash] +---- # Create backup make -f Makefile.qubes backup @@ -206,42 +232,46 @@ make -f Makefile.qubes backup # Restore from backup ./tools/qubes-restore.sh /var/backups/qubes-sdp/backup-20240101 -``` +---- -## Troubleshooting +=== Troubleshooting -### "Template not found" +==== "`Template not found`" -```bash +[source,bash] +---- # Install missing template qubes-dom0-update --enablerepo=qubes-templates-itl fedora-40-minimal # Or enable auto-install # Edit qubes-config.conf: AUTO_INSTALL_TEMPLATES="true" -``` +---- -### "Insufficient memory" +==== "`Insufficient memory`" -```bash +[source,bash] +---- # Reduce memory allocations # Edit qubes-config.conf: WORK_MEMORY="1024" VAULT_MEMORY="512" ANON_MEMORY="512" -``` +---- -### "sys-whonix not found" +==== "`sys-whonix not found`" -```bash +[source,bash] +---- # Anon qube automatically falls back to sys-firewall # To install Whonix: qubes-dom0-update --enablerepo=qubes-templates-community whonix-gateway-17 whonix-workstation-17 -``` +---- -### Can't access work qube +==== Can’t access work qube -```bash +[source,bash] +---- # Start it qvm-start work @@ -250,50 +280,58 @@ qvm-ls work # Check logs journalctl -u qubes-vm@work -``` - -## Tips - -### Best Practices - -1. **Always test with dry-run first** - ```bash - ./qubes-setup-advanced.sh --dry-run - ``` - -2. **Backup vault regularly** - ```bash - make -f Makefile.qubes backup - ``` - -3. **Keep templates updated** - ```bash - make -f Makefile.qubes template-update - ``` - -4. **Never connect vault to network** - ```bash - # Verify it's air-gapped: - qvm-prefs vault netvm - # Should be empty - ``` - -5. **Use untrusted for risky files** - ```bash - qvm-open-in-dvm suspicious.pdf - ``` +---- + +=== Tips + +==== Best Practices + +[arabic] +. *Always test with dry-run first* ++ +[source,bash] +---- +./qubes-setup-advanced.sh --dry-run +---- +. *Backup vault regularly* ++ +[source,bash] +---- +make -f Makefile.qubes backup +---- +. *Keep templates updated* ++ +[source,bash] +---- +make -f Makefile.qubes template-update +---- +. *Never connect vault to network* ++ +[source,bash] +---- +# Verify it's air-gapped: +qvm-prefs vault netvm +# Should be empty +---- +. *Use untrusted for risky files* ++ +[source,bash] +---- +qvm-open-in-dvm suspicious.pdf +---- -### Keyboard Shortcuts +==== Keyboard Shortcuts -- `Alt+F3` - Qubes menu -- `Ctrl+Alt+Del` - Lock screen -- Drag window border to move between qubes +* `+Alt+F3+` - Qubes menu +* `+Ctrl+Alt+Del+` - Lock screen +* Drag window border to move between qubes -### Memory Optimization +==== Memory Optimization If you have limited RAM: -```bash +[source,bash] +---- # Close unused qubes qvm-shutdown work @@ -302,21 +340,22 @@ qvm-shutdown work # Disable auto-start WORK_AUTOSTART="false" -``` +---- -## Getting Help +=== Getting Help -### Documentation +==== Documentation -- **Full docs**: [README.md](README.md) -- **Wiki**: [wiki/](wiki/) -- **Configuration**: [wiki/pages/configuration.md](wiki/pages/configuration.md) -- **Troubleshooting**: [wiki/pages/troubleshooting.md](wiki/pages/troubleshooting.md) -- **FAQ**: [wiki/pages/faq.md](wiki/pages/faq.md) +* *Full docs*: README.md +* *Wiki*: wiki/ +* *Configuration*: wiki/pages/configuration.md +* *Troubleshooting*: wiki/pages/troubleshooting.md +* *FAQ*: wiki/pages/faq.md -### Commands Reference +==== Commands Reference -```bash +[source,bash] +---- # Setup ./qubes-setup.sh # Simple ./qubes-setup-advanced.sh # Advanced @@ -341,34 +380,32 @@ make -f Makefile.qubes backup # Create # Templates ./tools/qubes-template-manager.sh update # Update make -f Makefile.qubes template-update # Via make -``` - -## What's Next? - -1. **Read the documentation** - - [Security Guide](wiki/pages/security-guide.md) - - [Configuration Guide](wiki/pages/configuration.md) - -2. **Set up Split-GPG/SSH** - - [Split-GPG Guide](wiki/pages/split-gpg.md) - - [Split-SSH Guide](wiki/pages/split-ssh.md) - -3. **Configure backups** - - [Backup & Restore Guide](wiki/pages/backup-restore.md) - -4. **Explore tools** - - [Tools README](tools/README.md) - -5. **Join community** - - Report issues - - Share configurations - - Contribute improvements - -## Quick Command Reference Card +---- + +=== What’s Next? + +[arabic] +. *Read the documentation* +* link:wiki/pages/security-guide.md[Security Guide] +* link:wiki/pages/configuration.md[Configuration Guide] +. *Set up Split-GPG/SSH* +* link:wiki/pages/split-gpg.md[Split-GPG Guide] +* link:wiki/pages/split-ssh.md[Split-SSH Guide] +. *Configure backups* +* link:wiki/pages/backup-restore.md[Backup & Restore Guide] +. *Explore tools* +* link:tools/README.md[Tools README] +. *Join community* +* Report issues +* Share configurations +* Contribute improvements + +=== Quick Command Reference Card Save this for easy reference: -```bash +[source,bash] +---- # Status ./tools/qubes-status.sh @@ -392,12 +429,14 @@ qvm-firewall work list # Health check ./qubes-setup-advanced.sh --health-check -``` +---- ---- +''''' -**Welcome to Qubes SDP!** 🎉 +*Welcome to Qubes SDP!* 🎉 -You now have a secure, isolated work environment. Explore the documentation to learn more about advanced features. +You now have a secure, isolated work environment. Explore the +documentation to learn more about advanced features. -**Need help?** Check the [FAQ](wiki/pages/faq.md) or [Troubleshooting Guide](wiki/pages/troubleshooting.md). +*Need help?* Check the link:wiki/pages/faq.md[FAQ] or +link:wiki/pages/troubleshooting.md[Troubleshooting Guide]. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..17b64c0 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,330 @@ +== Security Policy + +=== Supported Versions + +Currently supported versions for security updates: + +[cols=",",options="header",] +|=== +|Version |Supported +|1.0.x |:white_check_mark: +|< 1.0 |:x: +|=== + +=== Security Model + +Qubes SDP operates within the Qubes OS security model and adds +additional protections: + +==== Trust Boundaries + +[arabic] +. *dom0* - Most trusted (runs setup scripts) +. *vault qube* - Air-gapped (NO network, stores secrets) +. *work qube* - Moderate trust (restricted firewall) +. *anon qube* - Low trust (Tor/Whonix) +. *untrusted qube* - Minimal trust (DisposableVMs) + +==== Security Features + +* ✅ Air-gapped vault (enforced no-network) +* ✅ Default-deny firewalls +* ✅ Split-GPG/SSH (keys isolated in vault) +* ✅ DisposableVMs for risky content +* ✅ Input validation on all user inputs +* ✅ No hardcoded credentials +* ✅ Minimal templates (reduced attack surface) +* ✅ Qrexec policy enforcement + +=== Threat Model + +==== In Scope + +* Vulnerabilities in setup scripts +* Privilege escalation within dom0 +* Policy bypass in qrexec configurations +* Firewall rule circumvention +* Vault network isolation bypass +* Input validation flaws +* Insecure defaults +* Information disclosure + +==== Out of Scope + +* Qubes OS core vulnerabilities (report to Qubes Security Team) +* Template package vulnerabilities (report to distro maintainers) +* Hardware vulnerabilities (CPU, speculative execution) +* Physical access attacks +* Social engineering + +=== Reporting a Vulnerability + +*DO NOT* create public GitHub issues for security vulnerabilities. + +==== Preferred Method: GitHub Security Advisories + +[arabic] +. Go to: https://github.com/hyperpolymath/qubes-sdp/security/advisories +. Click "`Report a vulnerability`" +. Fill in the details +. Submit privately + +==== Alternative: Email + +*Email:* security@qubes-sdp.org + +*PGP Key:* [Available in .well-known/security.txt] + +==== What to Include + +Please provide: + +[arabic] +. *Description* - Clear explanation of the vulnerability +. *Impact* - Potential security impact and affected components +. *Steps to Reproduce* - Detailed reproduction steps +. *Proof of Concept* - Code, screenshots, or logs (if applicable) +. *Suggested Fix* - Your recommendation (optional) +. *Environment* - Qubes version, RAM, setup configuration + +==== Example Report + +.... +Subject: [SECURITY] Vault network isolation bypass + +Description: +The vault qube can be created with network access if the user +modifies VAULT_NETVM before setup validation occurs. + +Impact: +High - Compromises air-gap security model + +Steps to Reproduce: +1. Edit qubes-config.conf +2. Set VAULT_NETVM="sys-firewall" (commented out) +3. Run setup without dry-run +4. Vault qube has network access + +Suggested Fix: +Add explicit check: if vault netvm is set, abort setup +and warn user. + +Environment: +Qubes OS 4.2, 16GB RAM, fedora-40-minimal templates +.... + +=== Response Process + +==== Timeline + +* *Acknowledgment:* Within 48 hours +* *Initial Assessment:* Within 7 days +* *Status Update:* Every 7 days until resolved +* *Fix Development:* Depends on severity (see below) +* *Public Disclosure:* After fix is released + 14 days + +==== Severity Levels + +*Critical* (CVSS 9.0-10.0) - Air-gap bypass - dom0 compromise - +Immediate fix (24-48 hours) + +*High* (CVSS 7.0-8.9) - Policy bypass - Privilege escalation - Fix +within 7 days + +*Medium* (CVSS 4.0-6.9) - Information disclosure - Weak defaults - Fix +within 30 days + +*Low* (CVSS 0.1-3.9) - Minor security improvements - Fix in next release + +==== Disclosure Policy + +We follow *coordinated disclosure*: + +[arabic] +. Reporter notifies us privately +. We acknowledge and assess +. We develop and test fix +. We release patched version +. We publish security advisory +. Reporter receives credit (if desired) + +*Embargo period:* Minimum 14 days after fix release + +=== Security Best Practices + +==== For Users + +[arabic] +. *Always review scripts before running in dom0* ++ +[source,bash] +---- +# Read the code first +less qubes-setup.sh + +# Test with dry-run +./qubes-setup.sh --dry-run +---- +. *Verify vault has no network* ++ +[source,bash] +---- +qvm-prefs vault netvm +# Should be empty +---- +. *Keep templates updated* ++ +[source,bash] +---- +make -f Makefile.qubes template-update +---- +. *Run security tests* ++ +[source,bash] +---- +bash tests/security-tests.sh +---- +. *Use minimal templates* ++ +[source,bash] +---- +DEFAULT_TEMPLATE="fedora-40-minimal" +---- + +==== For Developers + +[arabic] +. *Validate all inputs* ++ +[source,bash] +---- +# Bad +qvm-create "${user_input}" + +# Good +if [[ ! "${user_input}" =~ ^[a-z0-9-]+$ ]]; then + error "Invalid qube name" +fi +---- +. *Never hardcode secrets* ++ +[source,bash] +---- +# Bad +PASSWORD="secret123" + +# Good +read -s -p "Password: " PASSWORD +---- +. *Use set -e for error handling* ++ +[source,bash] +---- +#!/bin/bash +set -e # Exit on error +set -u # Error on undefined variables +set -o pipefail # Catch errors in pipes +---- +. *Avoid dangerous commands* ++ +[source,bash] +---- +# Never +rm -rf / +eval "${user_input}" +curl https://url | bash +---- +. *Check for dom0* ++ +[source,bash] +---- +if [ "$(hostname)" != "dom0" ]; then + error "Must run in dom0" + exit 1 +fi +---- + +=== Security Testing + +==== Automated Tests + +[source,bash] +---- +# Run security test suite +bash tests/security-tests.sh + +# Check for: +# - Hardcoded credentials +# - Unsafe eval usage +# - Missing input validation +# - World-writable files +# - Vault network access +---- + +==== Manual Testing + +[arabic] +. *Air-gap verification* ++ +[source,bash] +---- +qvm-prefs vault netvm +qvm-run vault 'ping -c 1 8.8.8.8' # Should fail +---- +. *Firewall verification* ++ +[source,bash] +---- +qvm-firewall work list +# Should have drop rule at end +---- +. *Policy verification* ++ +[source,bash] +---- +cat /etc/qubes-rpc/policy/qubes.Filecopy +# Should have explicit rules, no wildcards +---- + +=== Known Limitations + +[arabic] +. *dom0 Trust* - Scripts run in dom0 with full privileges +* *Mitigation:* Dry-run mode, code review, testing +. *Template Vulnerabilities* - Inherited from upstream +* *Mitigation:* Use minimal templates, keep updated +. *Qrexec Policies* - User can modify after setup +* *Mitigation:* Validation tools, documentation +. *Backup Encryption* - Depends on user-chosen passphrase +* *Mitigation:* Passphrase strength checks, documentation + +=== Security Acknowledgments + +We thank the following researchers for responsible disclosure: + +_(List will be added as vulnerabilities are reported and fixed)_ + +=== Security Contacts + +* *Primary:* security@qubes-sdp.org +* *PGP Key:* See .well-known/security.txt +* *GitHub:* https://github.com/hyperpolymath/qubes-sdp/security + +=== Additional Resources + +* https://www.qubes-os.org/doc/security-guidelines/[Qubes OS Security +Guidelines] +* https://www.qubes-os.org/security/[Qubes OS Security Advisories] +* https://owasp.org/www-project-top-ten/[OWASP Top 10] +* https://cwe.mitre.org/top25/[CWE Top 25] + +=== Updates + +This security policy is reviewed quarterly and updated as needed. + +Last updated: 2024-11-22 Version: 1.0.0 + +''''' + +*Note:* This policy applies to the Qubes SDP project itself. For Qubes +OS security issues, see https://www.qubes-os.org/security/ diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 08f037d..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,312 +0,0 @@ -# Security Policy - -## Supported Versions - -Currently supported versions for security updates: - -| Version | Supported | -| ------- | ------------------ | -| 1.0.x | :white_check_mark: | -| < 1.0 | :x: | - -## Security Model - -Qubes SDP operates within the Qubes OS security model and adds additional protections: - -### Trust Boundaries - -1. **dom0** - Most trusted (runs setup scripts) -2. **vault qube** - Air-gapped (NO network, stores secrets) -3. **work qube** - Moderate trust (restricted firewall) -4. **anon qube** - Low trust (Tor/Whonix) -5. **untrusted qube** - Minimal trust (DisposableVMs) - -### Security Features - -- ✅ Air-gapped vault (enforced no-network) -- ✅ Default-deny firewalls -- ✅ Split-GPG/SSH (keys isolated in vault) -- ✅ DisposableVMs for risky content -- ✅ Input validation on all user inputs -- ✅ No hardcoded credentials -- ✅ Minimal templates (reduced attack surface) -- ✅ Qrexec policy enforcement - -## Threat Model - -### In Scope - -- Vulnerabilities in setup scripts -- Privilege escalation within dom0 -- Policy bypass in qrexec configurations -- Firewall rule circumvention -- Vault network isolation bypass -- Input validation flaws -- Insecure defaults -- Information disclosure - -### Out of Scope - -- Qubes OS core vulnerabilities (report to Qubes Security Team) -- Template package vulnerabilities (report to distro maintainers) -- Hardware vulnerabilities (CPU, speculative execution) -- Physical access attacks -- Social engineering - -## Reporting a Vulnerability - -**DO NOT** create public GitHub issues for security vulnerabilities. - -### Preferred Method: GitHub Security Advisories - -1. Go to: https://github.com/hyperpolymath/qubes-sdp/security/advisories -2. Click "Report a vulnerability" -3. Fill in the details -4. Submit privately - -### Alternative: Email - -**Email:** security@qubes-sdp.org - -**PGP Key:** [Available in .well-known/security.txt] - -### What to Include - -Please provide: - -1. **Description** - Clear explanation of the vulnerability -2. **Impact** - Potential security impact and affected components -3. **Steps to Reproduce** - Detailed reproduction steps -4. **Proof of Concept** - Code, screenshots, or logs (if applicable) -5. **Suggested Fix** - Your recommendation (optional) -6. **Environment** - Qubes version, RAM, setup configuration - -### Example Report - -``` -Subject: [SECURITY] Vault network isolation bypass - -Description: -The vault qube can be created with network access if the user -modifies VAULT_NETVM before setup validation occurs. - -Impact: -High - Compromises air-gap security model - -Steps to Reproduce: -1. Edit qubes-config.conf -2. Set VAULT_NETVM="sys-firewall" (commented out) -3. Run setup without dry-run -4. Vault qube has network access - -Suggested Fix: -Add explicit check: if vault netvm is set, abort setup -and warn user. - -Environment: -Qubes OS 4.2, 16GB RAM, fedora-40-minimal templates -``` - -## Response Process - -### Timeline - -- **Acknowledgment:** Within 48 hours -- **Initial Assessment:** Within 7 days -- **Status Update:** Every 7 days until resolved -- **Fix Development:** Depends on severity (see below) -- **Public Disclosure:** After fix is released + 14 days - -### Severity Levels - -**Critical** (CVSS 9.0-10.0) -- Air-gap bypass -- dom0 compromise -- Immediate fix (24-48 hours) - -**High** (CVSS 7.0-8.9) -- Policy bypass -- Privilege escalation -- Fix within 7 days - -**Medium** (CVSS 4.0-6.9) -- Information disclosure -- Weak defaults -- Fix within 30 days - -**Low** (CVSS 0.1-3.9) -- Minor security improvements -- Fix in next release - -### Disclosure Policy - -We follow **coordinated disclosure**: - -1. Reporter notifies us privately -2. We acknowledge and assess -3. We develop and test fix -4. We release patched version -5. We publish security advisory -6. Reporter receives credit (if desired) - -**Embargo period:** Minimum 14 days after fix release - -## Security Best Practices - -### For Users - -1. **Always review scripts before running in dom0** - ```bash - # Read the code first - less qubes-setup.sh - - # Test with dry-run - ./qubes-setup.sh --dry-run - ``` - -2. **Verify vault has no network** - ```bash - qvm-prefs vault netvm - # Should be empty - ``` - -3. **Keep templates updated** - ```bash - make -f Makefile.qubes template-update - ``` - -4. **Run security tests** - ```bash - bash tests/security-tests.sh - ``` - -5. **Use minimal templates** - ```bash - DEFAULT_TEMPLATE="fedora-40-minimal" - ``` - -### For Developers - -1. **Validate all inputs** - ```bash - # Bad - qvm-create "${user_input}" - - # Good - if [[ ! "${user_input}" =~ ^[a-z0-9-]+$ ]]; then - error "Invalid qube name" - fi - ``` - -2. **Never hardcode secrets** - ```bash - # Bad - PASSWORD="secret123" - - # Good - read -s -p "Password: " PASSWORD - ``` - -3. **Use set -e for error handling** - ```bash - #!/bin/bash - set -e # Exit on error - set -u # Error on undefined variables - set -o pipefail # Catch errors in pipes - ``` - -4. **Avoid dangerous commands** - ```bash - # Never - rm -rf / - eval "${user_input}" - curl https://url | bash - ``` - -5. **Check for dom0** - ```bash - if [ "$(hostname)" != "dom0" ]; then - error "Must run in dom0" - exit 1 - fi - ``` - -## Security Testing - -### Automated Tests - -```bash -# Run security test suite -bash tests/security-tests.sh - -# Check for: -# - Hardcoded credentials -# - Unsafe eval usage -# - Missing input validation -# - World-writable files -# - Vault network access -``` - -### Manual Testing - -1. **Air-gap verification** - ```bash - qvm-prefs vault netvm - qvm-run vault 'ping -c 1 8.8.8.8' # Should fail - ``` - -2. **Firewall verification** - ```bash - qvm-firewall work list - # Should have drop rule at end - ``` - -3. **Policy verification** - ```bash - cat /etc/qubes-rpc/policy/qubes.Filecopy - # Should have explicit rules, no wildcards - ``` - -## Known Limitations - -1. **dom0 Trust** - Scripts run in dom0 with full privileges - - **Mitigation:** Dry-run mode, code review, testing - -2. **Template Vulnerabilities** - Inherited from upstream - - **Mitigation:** Use minimal templates, keep updated - -3. **Qrexec Policies** - User can modify after setup - - **Mitigation:** Validation tools, documentation - -4. **Backup Encryption** - Depends on user-chosen passphrase - - **Mitigation:** Passphrase strength checks, documentation - -## Security Acknowledgments - -We thank the following researchers for responsible disclosure: - -*(List will be added as vulnerabilities are reported and fixed)* - -## Security Contacts - -- **Primary:** security@qubes-sdp.org -- **PGP Key:** See .well-known/security.txt -- **GitHub:** https://github.com/hyperpolymath/qubes-sdp/security - -## Additional Resources - -- [Qubes OS Security Guidelines](https://www.qubes-os.org/doc/security-guidelines/) -- [Qubes OS Security Advisories](https://www.qubes-os.org/security/) -- [OWASP Top 10](https://owasp.org/www-project-top-ten/) -- [CWE Top 25](https://cwe.mitre.org/top25/) - -## Updates - -This security policy is reviewed quarterly and updated as needed. - -Last updated: 2024-11-22 -Version: 1.0.0 - ---- - -**Note:** This policy applies to the Qubes SDP project itself. For Qubes OS security issues, see https://www.qubes-os.org/security/ diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..5741417 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,67 @@ +== Tech-Debt Audit — qubes-sdp — 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 |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |376 +|`+docs/+` files |0 +|`+docs/+` LoC |0 +|CHANGELOG.md |Y +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +376 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+`. + +=== 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 5cfd8f0..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,55 +0,0 @@ - - -# Tech-Debt Audit — qubes-sdp — 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 | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 376 | -| `docs/` files | 0 | -| `docs/` LoC | 0 | -| CHANGELOG.md | Y | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 376 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`. - -## 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/examples/README.adoc b/examples/README.adoc new file mode 100644 index 0000000..dce9166 --- /dev/null +++ b/examples/README.adoc @@ -0,0 +1,155 @@ +== Example Configurations + +Pre-configured examples for common use cases. + +=== Available Examples + +==== journalist-config.conf + +Optimized for investigative journalism: - work + vault + anon + +untrusted qubes - Split-GPG for encrypted communications - Daily +automated backups - Strict firewall rules - Anonymous qube via Tor + +*Memory Required*: 8GB minimum + +*Usage*: + +[source,bash] +---- +cp examples/journalist-config.conf qubes-config.conf +./qubes-setup-advanced.sh +---- + +==== developer-config.conf + +Optimized for software development: - work (4GB RAM) + vault + untrusted +qubes - Split-SSH for secure key management - Development tools +pre-installed - Ports for SSH and Git - Weekly backups + +*Memory Required*: 12GB minimum + +*Usage*: + +[source,bash] +---- +cp examples/developer-config.conf qubes-config.conf +./qubes-setup-advanced.sh +---- + +==== minimal-config.conf + +For systems with limited RAM: - work (1GB) + vault (512MB) only - +Minimal packages - No optional qubes - Reduced features + +*Memory Required*: 4GB minimum + +*Usage*: + +[source,bash] +---- +cp examples/minimal-config.conf qubes-config.conf +./qubes-setup-advanced.sh +---- + +=== Customizing Examples + +[arabic] +. Copy example to main config: + +[source,bash] +---- +cp examples/journalist-config.conf qubes-config.conf +---- + +[arabic, start=2] +. Edit as needed: + +[source,bash] +---- +vi qubes-config.conf +---- + +[arabic, start=3] +. Test with dry-run: + +[source,bash] +---- +./qubes-setup-advanced.sh --dry-run +---- + +[arabic, start=4] +. Apply: + +[source,bash] +---- +./qubes-setup-advanced.sh +---- + +=== Creating Your Own + +Start with the closest example and modify: + +[arabic] +. Copy base example +. Adjust memory allocations +. Enable/disable qubes +. Configure packages +. Set firewall rules +. Configure backups + +See `+qubes-config.conf+` for all available options. + +=== Common Customizations + +==== Add More Memory + +[source,bash] +---- +WORK_MEMORY="4096" +VAULT_MEMORY="2048" +---- + +==== Enable VPN + +[source,bash] +---- +ENABLE_VPN="true" +VPN_NAME="vpn" +VPN_NETVM="sys-firewall" +---- + +==== Change Template + +[source,bash] +---- +DEFAULT_TEMPLATE="debian-12-minimal" +---- + +==== Add Packages + +[source,bash] +---- +WORK_PACKAGES="vim git curl wget python3 nodejs docker" +---- + +==== Custom Firewall + +[source,bash] +---- +WORK_ALLOWED_PORTS="tcp:80,tcp:443,udp:53,tcp:22,tcp:8080" +---- + +=== Testing Examples + +Before applying, always test: + +[source,bash] +---- +./qubes-setup-advanced.sh --dry-run --config examples/journalist-config.conf +---- + +=== Support + +For issues with examples: 1. Review configuration syntax 2. Check memory +requirements 3. Verify template availability 4. See troubleshooting +guide diff --git a/examples/README.md b/examples/README.md deleted file mode 100644 index d0fe070..0000000 --- a/examples/README.md +++ /dev/null @@ -1,141 +0,0 @@ -# Example Configurations - -Pre-configured examples for common use cases. - -## Available Examples - -### journalist-config.conf - -Optimized for investigative journalism: -- work + vault + anon + untrusted qubes -- Split-GPG for encrypted communications -- Daily automated backups -- Strict firewall rules -- Anonymous qube via Tor - -**Memory Required**: 8GB minimum - -**Usage**: -```bash -cp examples/journalist-config.conf qubes-config.conf -./qubes-setup-advanced.sh -``` - -### developer-config.conf - -Optimized for software development: -- work (4GB RAM) + vault + untrusted qubes -- Split-SSH for secure key management -- Development tools pre-installed -- Ports for SSH and Git -- Weekly backups - -**Memory Required**: 12GB minimum - -**Usage**: -```bash -cp examples/developer-config.conf qubes-config.conf -./qubes-setup-advanced.sh -``` - -### minimal-config.conf - -For systems with limited RAM: -- work (1GB) + vault (512MB) only -- Minimal packages -- No optional qubes -- Reduced features - -**Memory Required**: 4GB minimum - -**Usage**: -```bash -cp examples/minimal-config.conf qubes-config.conf -./qubes-setup-advanced.sh -``` - -## Customizing Examples - -1. Copy example to main config: -```bash -cp examples/journalist-config.conf qubes-config.conf -``` - -2. Edit as needed: -```bash -vi qubes-config.conf -``` - -3. Test with dry-run: -```bash -./qubes-setup-advanced.sh --dry-run -``` - -4. Apply: -```bash -./qubes-setup-advanced.sh -``` - -## Creating Your Own - -Start with the closest example and modify: - -1. Copy base example -2. Adjust memory allocations -3. Enable/disable qubes -4. Configure packages -5. Set firewall rules -6. Configure backups - -See `qubes-config.conf` for all available options. - -## Common Customizations - -### Add More Memory - -```bash -WORK_MEMORY="4096" -VAULT_MEMORY="2048" -``` - -### Enable VPN - -```bash -ENABLE_VPN="true" -VPN_NAME="vpn" -VPN_NETVM="sys-firewall" -``` - -### Change Template - -```bash -DEFAULT_TEMPLATE="debian-12-minimal" -``` - -### Add Packages - -```bash -WORK_PACKAGES="vim git curl wget python3 nodejs docker" -``` - -### Custom Firewall - -```bash -WORK_ALLOWED_PORTS="tcp:80,tcp:443,udp:53,tcp:22,tcp:8080" -``` - -## Testing Examples - -Before applying, always test: - -```bash -./qubes-setup-advanced.sh --dry-run --config examples/journalist-config.conf -``` - -## Support - -For issues with examples: -1. Review configuration syntax -2. Check memory requirements -3. Verify template availability -4. See troubleshooting guide diff --git a/qubes-salt/README.adoc b/qubes-salt/README.adoc new file mode 100644 index 0000000..f3840b1 --- /dev/null +++ b/qubes-salt/README.adoc @@ -0,0 +1,148 @@ +== Qubes SDP Salt Stack Configuration + +This directory contains Salt Stack state files for automated Qubes OS +setup. + +=== Files + +* *qubes-sdp.sls* - Main Salt state file defining the qube topology +* *top.sls* - Top file that maps states to systems +* *README.md* - This file + +=== Usage + +==== Method 1: Apply States Directly + +[source,bash] +---- +# In dom0, apply the SDP states +sudo qubesctl state.apply qubes-sdp +---- + +==== Method 2: Copy to Salt Directory + +[source,bash] +---- +# Copy state files to Qubes Salt directory +sudo cp qubes-salt/*.sls /srv/salt/ + +# Apply the states +sudo qubesctl state.apply qubes-sdp +---- + +==== Method 3: Use Salt File Server + +[source,bash] +---- +# Copy to user salt directory +mkdir -p /srv/salt/user +sudo cp qubes-salt/*.sls /srv/salt/user/ + +# Apply from user states +sudo qubesctl state.apply user.qubes-sdp +---- + +=== Verification + +After applying, verify the setup: + +[source,bash] +---- +# List all VMs +qvm-ls + +# Check specific qube properties +qvm-prefs work +qvm-prefs vault + +# Check firewall rules +qvm-firewall work list +---- + +=== Customization + +Edit `+qubes-sdp.sls+` to customize: + +* Memory allocations +* Network settings +* Firewall rules +* Package installations +* Labels and colors + +=== Advanced Usage + +==== Dry Run (Test Mode) + +[source,bash] +---- +# Test what would be applied without making changes +sudo qubesctl state.apply qubes-sdp test=True +---- + +==== Highstate + +To apply all configured states: + +[source,bash] +---- +sudo qubesctl state.highstate +---- + +==== Target Specific Qubes + +[source,bash] +---- +# Apply only work qube configuration +sudo qubesctl state.sls qubes-sdp.work +---- + +=== Troubleshooting + +==== Check Salt Syntax + +[source,bash] +---- +# Validate state file syntax +sudo qubesctl state.show_sls qubes-sdp +---- + +==== View State Tree + +[source,bash] +---- +# See all available states +sudo qubesctl state.show_top +---- + +==== Debug Mode + +[source,bash] +---- +# Run with debug output +sudo qubesctl state.apply qubes-sdp -l debug +---- + +=== Integration with Scripts + +Salt Stack provides declarative configuration, while the bash scripts +offer imperative control. Choose based on your needs: + +* *Salt Stack*: Best for maintaining consistent state across systems +* *Bash Scripts*: Best for one-time setup or interactive configuration + +Both methods can coexist and complement each other. + +=== Notes + +* Salt states are idempotent - safe to run multiple times +* Changes are only made if the desired state differs from current state +* Always test with `+test=True+` first in production environments +* Salt runs in dom0 and has full system access + +=== References + +* https://www.qubes-os.org/doc/salt/[Qubes Salt Documentation] +* https://docs.saltproject.io/en/latest/ref/states/all/[Salt States +Reference] +* https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines[Qubes +Salt Examples] diff --git a/qubes-salt/README.md b/qubes-salt/README.md deleted file mode 100644 index 91a5f67..0000000 --- a/qubes-salt/README.md +++ /dev/null @@ -1,135 +0,0 @@ -# Qubes SDP Salt Stack Configuration - -This directory contains Salt Stack state files for automated Qubes OS setup. - -## Files - -- **qubes-sdp.sls** - Main Salt state file defining the qube topology -- **top.sls** - Top file that maps states to systems -- **README.md** - This file - -## Usage - -### Method 1: Apply States Directly - -```bash -# In dom0, apply the SDP states -sudo qubesctl state.apply qubes-sdp -``` - -### Method 2: Copy to Salt Directory - -```bash -# Copy state files to Qubes Salt directory -sudo cp qubes-salt/*.sls /srv/salt/ - -# Apply the states -sudo qubesctl state.apply qubes-sdp -``` - -### Method 3: Use Salt File Server - -```bash -# Copy to user salt directory -mkdir -p /srv/salt/user -sudo cp qubes-salt/*.sls /srv/salt/user/ - -# Apply from user states -sudo qubesctl state.apply user.qubes-sdp -``` - -## Verification - -After applying, verify the setup: - -```bash -# List all VMs -qvm-ls - -# Check specific qube properties -qvm-prefs work -qvm-prefs vault - -# Check firewall rules -qvm-firewall work list -``` - -## Customization - -Edit `qubes-sdp.sls` to customize: - -- Memory allocations -- Network settings -- Firewall rules -- Package installations -- Labels and colors - -## Advanced Usage - -### Dry Run (Test Mode) - -```bash -# Test what would be applied without making changes -sudo qubesctl state.apply qubes-sdp test=True -``` - -### Highstate - -To apply all configured states: - -```bash -sudo qubesctl state.highstate -``` - -### Target Specific Qubes - -```bash -# Apply only work qube configuration -sudo qubesctl state.sls qubes-sdp.work -``` - -## Troubleshooting - -### Check Salt Syntax - -```bash -# Validate state file syntax -sudo qubesctl state.show_sls qubes-sdp -``` - -### View State Tree - -```bash -# See all available states -sudo qubesctl state.show_top -``` - -### Debug Mode - -```bash -# Run with debug output -sudo qubesctl state.apply qubes-sdp -l debug -``` - -## Integration with Scripts - -Salt Stack provides declarative configuration, while the bash scripts offer -imperative control. Choose based on your needs: - -- **Salt Stack**: Best for maintaining consistent state across systems -- **Bash Scripts**: Best for one-time setup or interactive configuration - -Both methods can coexist and complement each other. - -## Notes - -- Salt states are idempotent - safe to run multiple times -- Changes are only made if the desired state differs from current state -- Always test with `test=True` first in production environments -- Salt runs in dom0 and has full system access - -## References - -- [Qubes Salt Documentation](https://www.qubes-os.org/doc/salt/) -- [Salt States Reference](https://docs.saltproject.io/en/latest/ref/states/all/) -- [Qubes Salt Examples](https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines) diff --git a/tools/README.adoc b/tools/README.adoc new file mode 100644 index 0000000..e4cabb6 --- /dev/null +++ b/tools/README.adoc @@ -0,0 +1,304 @@ +== Qubes SDP Tools + +Comprehensive utility tools for managing and monitoring Qubes SDP. + +=== Available Tools + +==== Status and Monitoring + +===== qubes-status.sh + +Complete status overview of all SDP qubes. + +[source,bash] +---- +./qubes-status.sh +---- + +Shows: - Qube state (running/halted) - Memory allocation - Network +configuration - Disk usage - Security checks - System resources + +===== qubes-dashboard.sh + +Interactive real-time dashboard with auto-refresh. + +[source,bash] +---- +./qubes-dashboard.sh +---- + +Features: - Live system resource monitoring - Qube status with visual +indicators - Security status checks - Recent activity log - Interactive +commands + +==== Firewall Management + +===== qubes-firewall-analyzer.sh + +Analyzes firewall rules across all SDP qubes. + +[source,bash] +---- +./qubes-firewall-analyzer.sh +---- + +Provides: - Rule visualization - Security level assessment - +Recommendations - Rule management commands + +==== Template Management + +===== qubes-template-manager.sh + +Manages templates used by SDP qubes. + +[source,bash] +---- +# Show template status +./qubes-template-manager.sh status + +# Update all templates +./qubes-template-manager.sh update + +# Install missing templates +./qubes-template-manager.sh install + +# Clean package cache +./qubes-template-manager.sh clean + +# Detailed information +./qubes-template-manager.sh info +---- + +==== Backup and Recovery + +===== qubes-backup-validator.sh + +Validates and manages backups. + +[source,bash] +---- +# Default location +./qubes-backup-validator.sh + +# Specific directory +./qubes-backup-validator.sh /path/to/backups +---- + +Shows: - Backup inventory - Integrity verification - Age analysis - +Cleanup recommendations + +===== qubes-restore.sh + +Guided disaster recovery and restore. + +[source,bash] +---- +./qubes-restore.sh /path/to/backup +---- + +Features: - Backup verification - Conflict detection - +Rename/replace/skip options - Post-restore validation - Recovery +recommendations + +==== Policy Management + +===== qubes-policy-generator.sh + +Generates and manages qrexec policies. + +[source,bash] +---- +# Show current policies +./qubes-policy-generator.sh show + +# Generate recommended policies +./qubes-policy-generator.sh generate + +# Apply policies +./qubes-policy-generator.sh apply + +# Backup policies +./qubes-policy-generator.sh backup +---- + +=== Usage Examples + +==== Daily Monitoring + +[source,bash] +---- +# Quick status check +./qubes-status.sh + +# Start dashboard for continuous monitoring +./qubes-dashboard.sh +---- + +==== Weekly Maintenance + +[source,bash] +---- +# Update templates +./qubes-template-manager.sh update + +# Check firewall rules +./qubes-firewall-analyzer.sh + +# Verify backups +./qubes-backup-validator.sh + +# Clean template cache +./qubes-template-manager.sh clean +---- + +==== After Setup + +[source,bash] +---- +# Verify configuration +./qubes-status.sh + +# Analyze firewall rules +./qubes-firewall-analyzer.sh + +# Generate policies +./qubes-policy-generator.sh generate +./qubes-policy-generator.sh apply +---- + +==== Disaster Recovery + +[source,bash] +---- +# Verify backup exists +./qubes-backup-validator.sh + +# Restore from backup +./qubes-restore.sh /var/backups/qubes-sdp/backup-20240101 +---- + +=== Integration with Makefile + +All tools are integrated with Makefile.qubes: + +[source,bash] +---- +# Status +make -f Makefile.qubes status + +# Dashboard +make -f Makefile.qubes dashboard + +# Firewall check +make -f Makefile.qubes firewall-check + +# Template update +make -f Makefile.qubes template-update + +# Backup validation +# (included in backup command) +---- + +=== Tool Dependencies + +All tools require: - Running in dom0 - Qubes OS 4.1+ - Standard Qubes +commands (qvm-*, xl) + +Optional dependencies: - python3 (for dashboard) - specific qubes for +their respective checks + +=== Output Formats + +All tools use color-coded output: - *Green (✓)*: Success, secure, +optimal - *Yellow (!)*: Warning, attention needed - *Red (✗)*: Error, +insecure, critical - *Blue*: Informational - *Cyan*: Headers + +=== Automation + +==== Cron Integration + +[source,bash] +---- +# Daily status check (email on changes) +0 8 * * * /path/to/qubes-status.sh | mail -s "Qubes SDP Status" admin@example.com + +# Weekly backup validation +0 9 * * 0 /path/to/qubes-backup-validator.sh + +# Monthly template updates +0 2 1 * * /path/to/qubes-template-manager.sh update +---- + +==== Systemd Timers + +[source,ini] +---- +# /etc/systemd/system/qubes-status.timer +[Unit] +Description=Qubes SDP Status Check + +[Timer] +OnCalendar=daily +Persistent=true + +[Install] +WantedBy=timers.target +---- + +=== Troubleshooting + +==== Permission Denied + +Ensure scripts are executable: + +[source,bash] +---- +chmod +x tools/*.sh +---- + +==== Command Not Found + +Run from dom0, not an AppVM: + +[source,bash] +---- +hostname # Should output: dom0 +---- + +==== Missing Qubes + +Tools gracefully handle missing qubes, showing "`not created`" status. + +=== Development + +==== Adding New Tools + +[arabic] +. Create script in tools/ directory +. Make executable: `+chmod +x tools/new-tool.sh+` +. Add to Makefile.qubes if appropriate +. Update this README +. Add help text with `+-h+` flag + +==== Testing Tools + +All tools support dry-run or read-only modes by default. They won’t make +changes unless explicitly requested. + +=== Security Considerations + +* All tools run in dom0 (full system access) +* Review scripts before running +* Backup policies before applying changes +* Test in dry-run mode when available + +=== Contributing + +Improvements welcome: - Bug fixes - New features - Better visualizations +- Performance improvements - Documentation updates + +=== References + +* https://www.qubes-os.org/doc/[Qubes OS Documentation] +* https://www.qubes-os.org/doc/qrexec/[Qrexec Policy] +* https://www.qubes-os.org/doc/backup-restore/[Qubes Backup] diff --git a/tools/README.md b/tools/README.md deleted file mode 100644 index 1cf366f..0000000 --- a/tools/README.md +++ /dev/null @@ -1,304 +0,0 @@ -# Qubes SDP Tools - -Comprehensive utility tools for managing and monitoring Qubes SDP. - -## Available Tools - -### Status and Monitoring - -#### qubes-status.sh -Complete status overview of all SDP qubes. - -```bash -./qubes-status.sh -``` - -Shows: -- Qube state (running/halted) -- Memory allocation -- Network configuration -- Disk usage -- Security checks -- System resources - -#### qubes-dashboard.sh -Interactive real-time dashboard with auto-refresh. - -```bash -./qubes-dashboard.sh -``` - -Features: -- Live system resource monitoring -- Qube status with visual indicators -- Security status checks -- Recent activity log -- Interactive commands - -### Firewall Management - -#### qubes-firewall-analyzer.sh -Analyzes firewall rules across all SDP qubes. - -```bash -./qubes-firewall-analyzer.sh -``` - -Provides: -- Rule visualization -- Security level assessment -- Recommendations -- Rule management commands - -### Template Management - -#### qubes-template-manager.sh -Manages templates used by SDP qubes. - -```bash -# Show template status -./qubes-template-manager.sh status - -# Update all templates -./qubes-template-manager.sh update - -# Install missing templates -./qubes-template-manager.sh install - -# Clean package cache -./qubes-template-manager.sh clean - -# Detailed information -./qubes-template-manager.sh info -``` - -### Backup and Recovery - -#### qubes-backup-validator.sh -Validates and manages backups. - -```bash -# Default location -./qubes-backup-validator.sh - -# Specific directory -./qubes-backup-validator.sh /path/to/backups -``` - -Shows: -- Backup inventory -- Integrity verification -- Age analysis -- Cleanup recommendations - -#### qubes-restore.sh -Guided disaster recovery and restore. - -```bash -./qubes-restore.sh /path/to/backup -``` - -Features: -- Backup verification -- Conflict detection -- Rename/replace/skip options -- Post-restore validation -- Recovery recommendations - -### Policy Management - -#### qubes-policy-generator.sh -Generates and manages qrexec policies. - -```bash -# Show current policies -./qubes-policy-generator.sh show - -# Generate recommended policies -./qubes-policy-generator.sh generate - -# Apply policies -./qubes-policy-generator.sh apply - -# Backup policies -./qubes-policy-generator.sh backup -``` - -## Usage Examples - -### Daily Monitoring - -```bash -# Quick status check -./qubes-status.sh - -# Start dashboard for continuous monitoring -./qubes-dashboard.sh -``` - -### Weekly Maintenance - -```bash -# Update templates -./qubes-template-manager.sh update - -# Check firewall rules -./qubes-firewall-analyzer.sh - -# Verify backups -./qubes-backup-validator.sh - -# Clean template cache -./qubes-template-manager.sh clean -``` - -### After Setup - -```bash -# Verify configuration -./qubes-status.sh - -# Analyze firewall rules -./qubes-firewall-analyzer.sh - -# Generate policies -./qubes-policy-generator.sh generate -./qubes-policy-generator.sh apply -``` - -### Disaster Recovery - -```bash -# Verify backup exists -./qubes-backup-validator.sh - -# Restore from backup -./qubes-restore.sh /var/backups/qubes-sdp/backup-20240101 -``` - -## Integration with Makefile - -All tools are integrated with Makefile.qubes: - -```bash -# Status -make -f Makefile.qubes status - -# Dashboard -make -f Makefile.qubes dashboard - -# Firewall check -make -f Makefile.qubes firewall-check - -# Template update -make -f Makefile.qubes template-update - -# Backup validation -# (included in backup command) -``` - -## Tool Dependencies - -All tools require: -- Running in dom0 -- Qubes OS 4.1+ -- Standard Qubes commands (qvm-*, xl) - -Optional dependencies: -- python3 (for dashboard) -- specific qubes for their respective checks - -## Output Formats - -All tools use color-coded output: -- **Green (✓)**: Success, secure, optimal -- **Yellow (!)**: Warning, attention needed -- **Red (✗)**: Error, insecure, critical -- **Blue**: Informational -- **Cyan**: Headers - -## Automation - -### Cron Integration - -```bash -# Daily status check (email on changes) -0 8 * * * /path/to/qubes-status.sh | mail -s "Qubes SDP Status" admin@example.com - -# Weekly backup validation -0 9 * * 0 /path/to/qubes-backup-validator.sh - -# Monthly template updates -0 2 1 * * /path/to/qubes-template-manager.sh update -``` - -### Systemd Timers - -```ini -# /etc/systemd/system/qubes-status.timer -[Unit] -Description=Qubes SDP Status Check - -[Timer] -OnCalendar=daily -Persistent=true - -[Install] -WantedBy=timers.target -``` - -## Troubleshooting - -### Permission Denied - -Ensure scripts are executable: -```bash -chmod +x tools/*.sh -``` - -### Command Not Found - -Run from dom0, not an AppVM: -```bash -hostname # Should output: dom0 -``` - -### Missing Qubes - -Tools gracefully handle missing qubes, showing "not created" status. - -## Development - -### Adding New Tools - -1. Create script in tools/ directory -2. Make executable: `chmod +x tools/new-tool.sh` -3. Add to Makefile.qubes if appropriate -4. Update this README -5. Add help text with `-h` flag - -### Testing Tools - -All tools support dry-run or read-only modes by default. They won't make changes unless explicitly requested. - -## Security Considerations - -- All tools run in dom0 (full system access) -- Review scripts before running -- Backup policies before applying changes -- Test in dry-run mode when available - -## Contributing - -Improvements welcome: -- Bug fixes -- New features -- Better visualizations -- Performance improvements -- Documentation updates - -## References - -- [Qubes OS Documentation](https://www.qubes-os.org/doc/) -- [Qrexec Policy](https://www.qubes-os.org/doc/qrexec/) -- [Qubes Backup](https://www.qubes-os.org/doc/backup-restore/)