diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..91dcb87 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,79 @@ +# Contributing to Linux-Patch-Api + +Thank you for your interest in contributing to Linux-Patch-Api! We appreciate every contribution — from bug reports and documentation improvements to new features and security fixes. + +## Code of Conduct + +This project follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) code of conduct. By participating, you are expected to uphold this standard. Please report unacceptable behavior to the maintainers. + +## How to Contribute + +1. **Fork** the repository +2. Create a **feature branch** from `main`: + ```bash + git checkout -b feat/my-feature + ``` +3. Make your changes +4. Ensure all CI checks pass: + ```bash + cargo fmt --check + cargo clippy -- -D warnings + cargo test + ``` +5. **Commit** using conventional commit format (see below) +6. Open a **Pull Request** against `main` + +## Development Setup + +### Prerequisites + +- **Rust toolchain** (stable) — [rustup](https://rustup.rs/) +- **System dependencies**: + ```bash + sudo apt-get install build-essential libsystemd-dev pkg-config libssl-dev + ``` + +### Build & Run + +```bash +cargo build +cargo test +``` + +## Commit Messages + +We use [Conventional Commits](https://www.conventionalcommits.org/): + +| Prefix | Usage | +|----------|------------------------| +| `feat:` | New feature | +| `fix:` | Bug fix | +| `docs:` | Documentation changes | +| `chore:` | Maintenance tasks | +| `refactor:` | Code refactoring | +| `test:` | Adding or updating tests | +| `ci:` | CI configuration changes | + +Example: +``` +feat: add endpoint for patch rollback +``` + +## Pull Request Requirements + +- All CI checks must pass (fmt, clippy, test, audit, build) +- One feature or fix per PR — keep changes focused +- Include a clear description of what changed and why +- Update documentation if your change affects behavior + +## Reporting Issues + +Use [GitHub Issues](https://github.com/Draco-Lunaris/Linux-Patch-Api/issues) to report bugs, request features, or ask questions. Please include: + +- Steps to reproduce (for bugs) +- Expected vs. actual behavior +- Relevant logs or error messages + +## License + +By contributing, you agree that your contributions are licensed under the [Apache License 2.0](LICENSE), the same license as this project. diff --git a/SECURITY.md b/SECURITY.md index 4f701ef..677aaa0 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,346 +1,46 @@ -# Linux_Patch_API - Security Specification Document +# Security Policy -## Security Overview +## Supported Versions -**Philosophy:** Defense in depth with zero-trust principles for internal network. +Only the **latest release** is currently supported with security updates. -**Approach:** -- mTLS certificate-based authentication (required for all connections) -- IP whitelist enforcement (deny by default, allow only listed) -- Comprehensive audit logging for all operations -- Systemd hardening and process isolation -- Minimal attack surface (internal network only) +| Version | Supported | +|---------|----------| +| Latest | ✅ | +| Older | ❌ | ---- +## Reporting a Vulnerability -## Threat Model +**Do not report security vulnerabilities through public GitHub Issues.** -### Threat Actor Profile +Instead, use GitHub's private vulnerability reporting: -| Attribute | Description | -|-----------|-------------| -| **Origin** | Internal network only | -| **Skill Level** | Moderate to High | -| **Resources** | Limited (not nation-state) | -| **Motivation** | Unauthorized system access, privilege escalation | -| **Access** | Must bypass mTLS + IP whitelist | +👉 [Report a vulnerability for Linux-Patch-Api](https://github.com/Draco-Lunaris/Linux-Patch-Api/security/advisories/new) -### STRIDE Threat Analysis +This allows us to coordinate a fix before public disclosure. -| Threat Category | Potential Threat | Mitigation | Status | -|-----------------|------------------|------------|--------| -| **Spoofing** | Attacker impersonates valid client | mTLS certificate validation, unique certs per client | ✅ Mitigated | -| **Spoofing** | Attacker uses expired/revoked cert | Certificate expiry validation (1-year max) | ✅ Mitigated | -| **Tampering** | API requests modified in transit | TLS 1.3 encryption | ✅ Mitigated | -| **Tampering** | Config files modified unauthorized | File permissions (600/644), config validation before reload | ✅ Mitigated | -| **Repudiation** | Client denies making request | Audit logging with request_id, client cert ID | ✅ Mitigated | -| **Repudiation** | Server denies response | Comprehensive audit trail (systemd journal) | ✅ Mitigated | -| **Information Disclosure** | Package/data info leaked to unauthorized | Silent drop for non-mTLS, IP whitelist | ✅ Mitigated | -| **Information Disclosure** | Error messages leak system info | Detailed errors only for authenticated clients | ✅ Mitigated | -| **Denial of Service** | Resource exhaustion via many requests | Internal network only, IP whitelist limits exposure | ⚠️ Partial | -| **Denial of Service** | Job queue flooding | Configurable concurrent job limit (default: 5) | ✅ Mitigated | -| **Denial of Service** | Long-running job starvation | 30-minute job timeout enforcement | ✅ Mitigated | -| **Elevation of Privilege** | Unauthorized package installation | Root required, but mTLS + IP whitelist required | ✅ Mitigated | -| **Elevation of Privilege** | Subprocess escape | SystemCallFilter, ProtectSystem=strict | ✅ Mitigated | +### Response Timeline -### Attack Vectors & Mitigations +- **Acknowledgment** within 48 hours +- **Initial assessment** within 7 days +- **Ongoing updates** on remediation progress -| Attack Vector | Likelihood | Impact | Mitigation | -|---------------|------------|--------|------------| -| Network interception | Low | Critical | TLS 1.3 only, mTLS required | -| Certificate theft | Medium | Critical | Cert permissions (600), internal CA only | -| IP spoofing | Low | High | IP whitelist + mTLS (both required) | -| Config file tampering | Medium | High | File permissions, validation before reload | -| Package manager injection | Low | Critical | Pluggable backend with input validation | -| Job manipulation | Low | High | Job storage isolation, exclusive rollback mode | -| Log tampering | Medium | High | systemd journal (immutable), optional remote syslog | +## Disclosure Policy ---- +We follow **coordinated disclosure**: -## Authentication & Authorization +- We ask for **90 days** before public disclosure of a vulnerability +- Security advisories are published via [GitHub Security Advisories](https://github.com/Draco-Lunaris/Linux-Patch-Api/security/advisories) +- We will work with you to determine an appropriate disclosure timeline when a fix requires more time -### Authentication Requirements +## Security Best Practices -- **Method:** mTLS certificate-based authentication -- **Certificate Type:** Unique client certificate per client (1-year validity) -- **CA:** Internal self-hosted Certificate Authority -- **TLS Version:** TLS 1.3 only -- **Multi-factor:** Certificate + IP whitelist (dual requirement) -- **Session Management:** Stateless (no sessions) +This project is a security tool — we hold ourselves to a high standard: -### Authorization Model +- **Signed commits**: All commits must be signed (SSH signing) +- **CI enforcement**: All PRs require passing CI checks (fmt, clippy, test, audit, build) +- **Dependency auditing**: `cargo audit` runs in CI to catch known vulnerabilities -- **Model:** Binary authorization (all-or-nothing) -- **Permission Levels:** Single level (full access if authenticated) -- **Requirements:** - - Valid mTLS certificate (not expired, signed by internal CA) - - Source IP in whitelist (YAML config, instant apply) -- **No RBAC:** All authenticated clients have full API access +## Credit ---- - -## Data Security - -### Encryption at Rest - -- **Certificates:** File permissions 600 for private keys -- **Job Storage:** `/var/lib/linux_patch_api/jobs/` (cleared on restart) -- **Config Files:** `/etc/linux_patch_api/` (644 for config, 600 for keys) -- **Audit Logs:** systemd journal (immutable by default) - -### Encryption in Transit - -- **Protocol:** TLS 1.3 only -- **Port:** 12443 -- **Cipher Suites:** TLS 1.3 default (no legacy cipher support) -- **Certificate Validation:** Mutual TLS (server + client cert required) - -### Key Management - -- **CA Private Key:** Stored securely on CA host only -- **Server Certificates:** `/etc/linux_patch_api/certs/server.key` (600) -- **Client Certificates:** Distributed manually to authorized clients -- **Rotation:** 1-year certificate expiry, manual renewal process -- **Revocation:** Not implemented (rely on expiry + physical cert retrieval) - ---- - -## API Security - -### Input Validation - -- **Package Names:** Alphanumeric + standard package chars only -- **Versions:** Semantic versioning validation -- **IP Addresses:** IPv4 + CIDR validation for whitelist -- **JSON Schema:** Strict schema validation for all request bodies -- **Path Traversal:** Blocked (no `..` in paths) - -### Rate Limiting - -- **Not Required:** Internal network only with strict IP whitelist -- **Job Concurrency:** Configurable limit (default: 5 concurrent jobs) -- **Job Timeout:** 30-minute maximum per job - -### CORS Policy - -- **Not Applicable:** API is not browser-accessible -- **Origin:** mTLS clients only (no browser CORS concerns) - ---- - -## Audit & Logging - -### Security Events to Log - -- All API requests (endpoint, method, timestamp, client cert ID, source IP) -- Authentication events (success/failure, cert validation result) -- Authorization events (IP whitelist match/failure) -- Package operations (package name, version, action, result) -- Configuration changes (config reload, whitelist updates) -- Job lifecycle events (create, start, complete, fail, timeout, rollback) -- Service events (start, stop, restart, config validation failures) - -### Log Protection - -- **Primary Storage:** systemd journal (immutable, access-controlled) -- **Secondary Storage:** Optional remote syslog -- **Fallback:** Local file `/var/log/linux_patch_api/audit.log` (640) -- **Retention:** 30 days with daily rotation and compression -- **Access:** Root only, audit group read access -- **Integrity:** systemd journal provides tamper evidence - ---- - -## Compliance Requirements - -- **Internal Standards:** Follows organizational security policies -- **No External Compliance:** Not designed for PCI-DSS, HIPAA, SOC2 (can be extended) -- **Audit Trail:** Comprehensive logging supports internal audit requirements -- **Access Control:** mTLS + IP whitelist provides strong access control - ---- - -## Security Testing - -### Penetration Testing - -- **Schedule:** Required before production deployment -- **Scope:** - - mTLS authentication bypass attempts - - IP whitelist enforcement testing - - API endpoint fuzzing - - Certificate validation testing - - Config file tampering attempts - - Privilege escalation attempts -- **Tester:** Internal security team or external contractor -- **Frequency:** Annual or after major changes - -### Vulnerability Management - -- **Dependency Scanning:** Rust crate security advisories monitored -- **System Patches:** Host system patched via API itself (dogfooding) -- **Certificate Updates:** Annual renewal process -- **Config Audits:** Quarterly review of whitelist and security settings -- **Incident Response:** Log analysis for security event investigation - ---- - -## Phase 3 Security Testing Results - -**Test Date:** 2026-04-09 -**Tester:** Agent Zero Fuzz Testing Agent -**Status:** ✅ ALL CRITICAL ISSUES RESOLVED - Minor improvements recommended - -### Security Test Summary (16 Tests) - -| Category | Passed | Failed | Status | -|----------|--------|--------|--------| -| mTLS Enforcement | 3 | 0 | ✅ Complete | -| IP Whitelist | 1 | 0 | ✅ Complete | -| API Endpoints | 5 | 0 | ✅ Complete | -| Input Validation | 3 | 0 | ✅ Complete | -| Certificate Security | 2 | 0 | ✅ Complete | -| Configuration Security | 2 | 0 | ✅ Complete | -| **TOTAL** | **16** | **0** | **✅ 100%** | - ---- - -## Phase 3 Fuzz Testing Results - -**Test Date:** 2026-04-09 -**Tester:** Agent Zero Fuzz Testing Agent -**Test Type:** Comprehensive Fuzz Testing -**Overall Status:** ⚠️ GOOD - Minor improvements needed - -### Fuzz Test Summary (21 Tests) - -| Section | Tests | Passed | Failed | Pass Rate | -|---------|-------|--------|--------|-----------| -| API Input Fuzzing | 8 | 5 | 3 | 62.5% | -| Request Header Fuzzing | 5 | 2 | 3 | 40% | -| Certificate Fuzzing | 5 | 5 | 0 | 100% | -| Rate Limiting/DoS | 3 | 3 | 0 | 100% | -| **TOTAL** | **21** | **15** | **6** | **71.4%** | - -### Vulnerabilities Identified - -| ID | Severity | Category | Description | Status | -|----|----------|----------|-------------|--------| -| VULN-001 | MEDIUM | Input Validation | Missing input length validation | 📝 Recommended | -| VULN-002 | MEDIUM | Input Validation | Path traversal partial bypass | 📝 Recommended | -| VULN-003 | LOW | Input Validation | Empty string validation missing | 📝 Recommended | -| VULN-004 | MEDIUM | Header Security | Missing header size limits | 📝 Recommended | -| VULN-005 | LOW | HTTP Protocol | Invalid methods return 404 vs 405 | 📝 Recommended | -| VULN-006 | LOW | Header Security | Duplicate header handling | 📝 Recommended | - -### Security Strengths Confirmed - -✅ **mTLS Implementation: ROBUST** -- All invalid certificates properly rejected at TLS layer -- Silent drop behavior prevents information leakage -- Certificate chain validation working correctly - -✅ **Injection Protection: EFFECTIVE** -- SQL injection patterns: 4/4 blocked -- Command injection patterns: 5/5 handled safely - -✅ **DoS Protection: ADEQUATE** -- Large payloads (10MB) properly rejected with HTTP 413 -- Concurrent connections (20) handled gracefully -- Rapid flooding (100 req) completed without service degradation - -### Recommendations for Phase 4 - -**Medium Priority:** -1. Implement input length validation (package names: 256 chars max) -2. Enhance path traversal protection with strict normalization -3. Configure header size limits (8KB max) - -**Low Priority:** -4. Return 405 Method Not Allowed for unsupported methods -5. Reject empty strings for required fields -6. Handle duplicate headers with rejection - ---- - -## Overall Security Assessment - -| Category | Status | Notes | -|----------|--------|-------| -| Authentication (mTLS) | ✅ SECURE | All certificate attacks blocked | -| Authorization (IP Whitelist) | ✅ SECURE | Properly enforced | -| Input Validation | ⚠️ GOOD | Minor improvements recommended | -| Injection Protection | ✅ SECURE | SQL/Command/Path traversal blocked | -| DoS Protection | ✅ SECURE | Large payloads rejected | -| Certificate Security | ✅ SECURE | Robust mTLS implementation | - -**Overall Security Posture: GOOD** - -The API is suitable for internal network deployment. The 6 identified vulnerabilities are low-to-medium severity and represent hardening opportunities rather than critical security gaps. All critical and high severity issues from earlier testing have been resolved. - - ---- - -## Phase 3 Threat Model Validation - -**Validation Date:** 2026-04-09 -**Validator:** Threat Model Validation Agent (Agent Zero) -**Report:** THREAT_MODEL_VALIDATION.md - -### STRIDE Validation Summary - -| Category | Status | Confidence | -|----------|--------|------------| -| Spoofing | ✅ Fully Mitigated | High | -| Tampering | ⚠️ Partially Mitigated | Medium | -| Repudiation | ✅ Fully Mitigated | High | -| Information Disclosure | ✅ Fully Mitigated | High | -| Denial of Service | ⚠️ Partially Mitigated | Medium | -| Elevation of Privilege | ✅ Fully Mitigated | High | - -### Key Findings - -**Validated Strengths:** -- mTLS authentication robust (all certificate attacks blocked) -- TLS 1.3 enforcement verified (plain HTTP rejected) -- IP whitelist enforcement working correctly -- Audit logging provides strong non-repudiation -- Job-level DoS protection implemented -- Injection protection effective (SQL, command, path traversal) -- Systemd hardening in place - -**Identified Gaps (Medium Priority):** -- Rate limiting not implemented (relies on network security) -- Header size limits not configured -- Input length validation missing -- Config file integrity relies on permissions only -- No certificate revocation mechanism - -**Recommendation:** Proceed to Phase 4 with focus on medium-priority hardening items. API suitable for internal network deployment with current mitigations. - ---- - -## Test Artifacts - -- Fuzz test script: `/a0/usr/projects/linux_patch_api/fuzz_tests.sh` -- Security test script: `/a0/usr/projects/linux_patch_api/security_tests.sh` -- Fuzz test report: `/a0/usr/projects/linux_patch_api/FUZZ_TEST_REPORT.md` -- Security findings report: `/a0/usr/projects/linux_patch_api/SECURITY_FINDINGS_REPORT.md` -- Threat model validation: `/a0/usr/projects/linux_patch_api/THREAT_MODEL_VALIDATION.md` -- API specification: `/a0/usr/projects/linux_patch_api/API_SPEC.md` - ---- - -*Security documentation updated following Phase 3 Security Hardening and Threat Model Validation - Agent Zero* ---- - -## Test Artifacts - -- Fuzz test script: `/a0/usr/projects/linux_patch_api/fuzz_tests.sh` -- Security test script: `/a0/usr/projects/linux_patch_api/security_tests.sh` -- Fuzz test report: `/a0/usr/projects/linux_patch_api/FUZZ_TEST_REPORT.md` -- API specification: `/a0/usr/projects/linux_patch_api/API_SPEC.md` - ---- - -*Security documentation updated following Phase 3 Security Hardening - Agent Zero Fuzz Testing Agent* +Contributors who responsibly report vulnerabilities will be credited in the corresponding GitHub Security Advisory.