docs: add CONTRIBUTING.md and SECURITY.md for open source

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.

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:** 
+| Version | Supported |
-- mTLS certificate-based authentication (required for all connections)
+|---------|----------|
-- IP whitelist enforcement (deny by default, allow only listed)
+| Latest  | ✅       |
-- Comprehensive audit logging for all operations
+| Older   | ❌       |
-- Systemd hardening and process isolation
-- Minimal attack surface (internal network only)
 
----
+## 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 |
+👉 [Report a vulnerability for Linux-Patch-Api](https://github.com/Draco-Lunaris/Linux-Patch-Api/security/advisories/new)
-|-----------|-------------|
-| **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 |
 
-### STRIDE Threat Analysis
+This allows us to coordinate a fix before public disclosure.
 
-| Threat Category | Potential Threat | Mitigation | Status |
+### Response Timeline
-|-----------------|------------------|------------|--------|
-| **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 |
 
-### Attack Vectors & Mitigations
+- **Acknowledgment** within 48 hours
+- **Initial assessment** within 7 days
+- **Ongoing updates** on remediation progress
 
-| Attack Vector | Likelihood | Impact | Mitigation |
+## Disclosure Policy
-|---------------|------------|--------|------------|
-| 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 |
 
----
+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
+This project is a security tool — we hold ourselves to a high standard:
-- **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)
 
-### 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)
+## Credit
-- **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
 
----
+Contributors who responsibly report vulnerabilities will be credited in the corresponding GitHub Security Advisory.
-
-## 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*