Alexander Kazantsev 7ab93a673b deploy openssh

2026-05-12 18:38:21 +03:00

14 KiB

Raw Blame History

Contributing to ansible-role-openssh_server

Want to help secure SSH servers across the internet? Awesome! 🚀

This OpenSSH server hardening role protects systems running critical infrastructure, compliance-regulated workloads, and sensitive data worldwide. Your contributions help administrators deploy secure SSH configurations with confidence.

Whether you're fixing a typo, adding support for a new distribution, tracking a CVE, or implementing a compliance framework—all contributions matter.

Ways to Contribute
Communication Channels
Code of Conduct
Getting Started
Development Workflow
Coding Standards
Documentation Standards
Testing Requirements
Pull Request Process
Security Contributions
Recognition

Ways to Contribute

You don't have to be a security expert to contribute! Here are ways to help:

🐛 Report Bugs

Found an issue? Let us know! See Reporting Bugs.

💡 Suggest Features

Have an idea? We'd love to hear it! Open an issue to discuss.

📝 Improve Documentation

Fix typos, clarify instructions, add examples—documentation contributions are invaluable.

🔐 Track Security Issues

Research CVE status, verify patch levels, update compliance mappings.

🧪 Add Distribution Support

Test on new Debian/Ubuntu releases and contribute compatibility updates.

🎯 Implement Compliance Frameworks

Map additional regulatory frameworks (ISO, NIST, etc.) to role configuration.

💬 Help Others

Answer questions in issues, review PRs, share your experience.

Communication Channels

GitHub Issues: Bug reports, feature requests, discussions
Pull Requests: Code contributions and reviews
Security Issues: Email maintainer directly (see repository contacts) or use GitHub Security Advisories

Note: This is a volunteer-run hobby project. We'll respond as time permits and appreciate your patience.

Code of Conduct

This project follows a straightforward code of conduct based on mutual respect:

Our Standards

Be respectful: Treat all contributors with professionalism and courtesy
Be constructive: Provide helpful, actionable feedback
Be accurate: Back security claims with authoritative sources (links required)
Be collaborative: Work together to improve security for everyone
Be inclusive: Welcome contributors of all skill levels and backgrounds

Not Acceptable

Harassment, discriminatory language, or personal attacks
False or unverified security claims
Intentionally submitting vulnerable configurations
Spam or off-topic discussions

Enforcement

First offense: Warning and request to correct behavior
Second offense: Temporary ban from project participation (7-30 days)
Third offense: Permanent ban from project participation

Maintainers will enforce standards fairly and transparently.

Reporting Bugs

If you find a bug, please open an issue with:

Clear description: What you expected vs. what happened
Environment details: Distribution, OpenSSH version, Ansible version
Reproduction steps: How to reproduce the issue
Configuration: Relevant role variables (sanitize sensitive data)

Suggesting Enhancements

We welcome suggestions for:

New compliance framework support
Additional security features
Distribution support expansion
Documentation improvements
Performance optimizations

Please open an issue to discuss major changes before implementing them.

Security Vulnerabilities

DO NOT open public issues for security vulnerabilities. Instead:

Email the maintainer directly (see repository contacts)
Use GitHub Security Advisories (if enabled)
Provide CVE numbers, affected versions, and proof of concept if available

Getting Started

Prerequisites

Ansible 2.15+
Python 3.8+
Git
yamllint
ansible-lint

Fork and Clone

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/ansible-role-openssh_server.git
cd ansible-role-openssh_server

# Add upstream remote
git remote add upstream https://github.com/welshwandering/ansible-role-openssh_server.git

Install Development Tools

# Install Python dependencies
pip install yamllint ansible-lint ansible

# Install Ansible collections
ansible-galaxy collection install ansible.posix community.general

Development Workflow

1. Create a Feature Branch

# Update your main branch
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/your-feature-name

2. Make Your Changes

Follow the Coding Standards and Documentation Standards below.

3. Test Your Changes

# Run YAML linting
yamllint .

# Run Ansible linting (production profile is strict)
ansible-lint --profile=production

# Both must pass with 0 failures, 0 warnings

4. Update Documentation

Update relevant files in docs/ directory
Update README.md if adding features
REQUIRED: Update docs/CHANGELOG.md (see below)

5. Commit Your Changes

# Stage your changes
git add .

# Commit with clear message
git commit -m "Add support for XYZ feature

- Detailed description of what changed
- Why the change was needed
- Any breaking changes or considerations"

6. Push and Create Pull Request

# Push to your fork
git push origin feature/your-feature-name

# Create pull request on GitHub

Coding Standards

Ansible Best Practices

Use Fully Qualified Collection Names (FQCN):

# Good
- ansible.builtin.apt:
    name: openssh-server

# Bad
- apt:
    name: openssh-server

Boolean values as true/false:

# defaults/main.yml
openssh_password_authentication: false  # boolean

# templates/sshd_config.j2
PasswordAuthentication {{ 'yes' if openssh_password_authentication else 'no' }}

Task naming:
- Use descriptive names
- Start with verb (e.g., "Install", "Configure", "Verify")
- Be specific about what the task does
Line length: Keep lines under 160 characters (yamllint rule)
YAML document start: All YAML files must start with ---

Version-Aware Development

This role supports 15 distributions with OpenSSH versions 7.2p2 through 10.0p1. Never break older distributions.

When adding features that require specific OpenSSH versions:

Check version requirement in OpenSSH release notes

Add capability flag in tasks/main.yml:

openssh_has_new_feature: "{{ openssh_version is defined and openssh_version >= 9.5 }}"

Use conditional logic in templates/sshd_config.j2:

{% if openssh_has_new_feature | default(false) and openssh_enable_new_feature %}
NewFeature yes
{% endif %}

Test on both old and new versions conceptually

Security Contributions

CRITICAL: Never make security claims without verification.

Verify CVE patch status using official trackers:
- Debian: https://security-tracker.debian.org/tracker/CVE-XXXX-XXXXX
- Ubuntu: https://ubuntu.com/security/CVE-XXXX-XXXXX
Understand vendor backports: Distribution package version ≠ vulnerability status
Research compliance frameworks thoroughly: Fetch official documentation
Cite sources: Reference official advisories, CVE databases, government standards

Example:

❌ WRONG: "Debian Bookworm is vulnerable to CVE-2024-6387"
✅ RIGHT: "Debian Bookworm PATCHED CVE-2024-6387 via 1:9.2p1-2+deb12u3
          (verified at https://security-tracker.debian.org/tracker/CVE-2024-6387)"

Documentation Standards

File Organization

README.md: Quick start, features, navigation (~150 lines)
docs/DISTRIBUTIONS.md: Distribution matrix and capability flags
docs/COMPLIANCE.md: Compliance framework mappings
docs/CVE-TRACKING.md: Vulnerability status by distribution
docs/CONFIGURATION.md: Complete variable reference
docs/EXAMPLES.md: Configuration examples
docs/TROUBLESHOOTING.md: Common issues

Quality Standards

Use tables for structured data: Distribution matrices, CVE status, compliance mappings
Provide specific versions: "Debian Bookworm 1:9.2p1-2+deb12u3" not "Debian Bookworm is patched"
Include verification commands: Show users how to check their status
Cross-reference documents: Link to related topics
Keep README concise: Link to detailed docs rather than embedding everything

docs/CHANGELOG.md (REQUIRED)

Every contribution MUST update docs/CHANGELOG.md following Keep a Changelog format.

Add to Unreleased section:

## [Unreleased]

### Added
- Your new feature

### Changed
- What you modified

### Fixed
- What you fixed

### Security
- Security improvements

Write clear entries:
- ✅ GOOD: "Added support for ML-KEM post-quantum key exchange on OpenSSH 9.9+"
- ✅ GOOD: "Fixed CVE-2025-26465 mitigation by disabling VerifyHostKeyDNS by default"
- ❌ BAD: "Updated docs"
- ❌ BAD: "Various fixes"
Reference specific files:
- "Updated docs/CVE-TRACKING.md with CVE-2024-6387 distribution patch status"

Testing Requirements

Linting (Required)

# YAML syntax validation
yamllint .

# Ansible best practices (production profile is strictest)
ansible-lint --profile=production

Both must pass with 0 failures, 0 warnings.

Manual Testing (Recommended)

If possible, test your changes on:

Legacy: Debian Bullseye (OpenSSH 8.4p1) or Ubuntu 20.04 (OpenSSH 8.2p1)
Modern: Debian Bookworm (OpenSSH 9.2p1) or Ubuntu 22.04 (OpenSSH 8.9p1)
Latest: Debian Trixie (OpenSSH 10.0p1) or Ubuntu 24.04 (OpenSSH 9.6p1)

Molecule Testing (Future)

We plan to implement comprehensive Molecule tests. Contributions to testing infrastructure are welcome!

Pull Request Process

Before Submitting

Code passes yamllint . with 0 failures
Code passes ansible-lint --profile=production with 0 failures
Documentation updated (relevant files in docs/)
docs/CHANGELOG.md updated with clear, specific entries
Examples updated if behavior changes
Backwards compatibility maintained
Security claims verified with authoritative sources

PR Description Template

## Description
Brief description of what this PR does.

## Motivation and Context
Why is this change needed? What problem does it solve?
If it fixes an open issue, link to it here.

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
- [ ] Documentation update
- [ ] Security fix

## Testing
How was this tested? Include:
- Distribution(s) tested on
- OpenSSH version(s) tested with
- Test procedure

## Checklist
- [ ] yamllint passes
- [ ] ansible-lint passes
- [ ] Documentation updated
- [ ] docs/CHANGELOG.md updated
- [ ] Examples updated (if applicable)
- [ ] Security claims verified with sources

Review Process

Automated checks: Linting must pass
Maintainer review: Code quality, security accuracy, documentation
Community feedback: Other contributors may provide feedback
Approval and merge: Once approved, maintainer will merge

After Your PR is Merged

Update your fork:

git checkout main
git pull upstream main
git push origin main

Delete your feature branch:

git branch -d feature/your-feature-name
git push origin --delete feature/your-feature-name

Common Contribution Types

Adding a New Compliance Framework

Research official framework documentation
Identify SSH-related requirements
Map requirements to role variables
Update docs/COMPLIANCE.md with new table entry
Create example playbook in examples/ if needed
Update README.md feature list
Update docs/CHANGELOG.md under [Unreleased] → ### Added

Adding a New Distribution

Check OpenSSH version shipped with distribution
Add to distribution tables in docs/DISTRIBUTIONS.md
Test capability flags work correctly
Check CVE patch status for that distribution
Update docs/CVE-TRACKING.md if needed
Add to meta/main.yml platforms list
Update README.md badges
Update docs/CHANGELOG.md under [Unreleased] → ### Added

Responding to a New CVE

Research CVE on openssh.com/security.html and NVD
Check all 15 distributions' patch status
Determine if role configuration provides mitigation
Update docs/CVE-TRACKING.md with comprehensive status
Update defaults/templates if mitigation needed
Update docs/CHANGELOG.md under [Unreleased] → ### Security

Updating Cryptographic Standards

Check OpenSSH release notes for new algorithms
Review Mozilla/NSA/BSI/ANSSI guidance updates
Test algorithm availability on Debian Stretch (oldest)
Update defaults/main.yml with new preferences
Add capability flags if version-specific
Update docs/COMPLIANCE.md if affects compliance
Update docs/CHANGELOG.md under [Unreleased] → ### Changed or ### Security

Language and Terminology

Preferred Language

Use clear, direct language: "comprehensive", "robust", "sophisticated attacks"
Avoid buzzwords: "enterprise-grade", "enterprise-level", "nation-state level", "APTs"
Prefer technical accuracy over impressive-sounding claims

Code Comments

Explain why, not just what
Reference compliance requirements where applicable
Use comments to make configuration self-documenting

Questions?

Check existing documentation
Review AGENTS.md for detailed development guidelines
Open an issue for discussion
Check git commit history for examples

Recognition

Contributors will be:

Listed in git commit history
Recognized in release notes
Credited in docs/CHANGELOG.md for significant contributions

Thank you for helping make this project better! 🚀

Last updated: 2025-10-05

14 KiB Raw Blame History