git-echo/linux_patch_api
Private
Public Access
1
0
Fork 0
Code Releases 32 Wiki Activity

docs: add CONTRIBUTING.md and SECURITY.md for open source
All checks were successful
CI/CD Pipeline / Code Format (push) Successful in 4s
CI/CD Pipeline / Clippy Lints (push) Successful in 43s
CI/CD Pipeline / All Unit Tests (push) Successful in 1m12s
CI/CD Pipeline / Security Audit (push) Successful in 4s
CI/CD Pipeline / Enrollment Tests (push) Successful in 1m14s
CI/CD Pipeline / Verify Enrollment CLI Flag (push) Successful in 1m8s
CI/CD Pipeline / Build Debian Package (Ubuntu 22.04) (push) Successful in 2m26s
CI/CD Pipeline / Build RPM Package (push) Successful in 2m33s
CI/CD Pipeline / Build Arch Package (push) Successful in 2m37s
CI/CD Pipeline / Build Debian Package (push) Successful in 2m15s
CI/CD Pipeline / Build Alpine Package (push) Successful in 3m31s

Browse Source
This commit is contained in:
git-echo
2026-05-31 00:12:14 -05:00
parent e80437ad06
commit ae515ecb3a
2 changed files with 107 additions and 328 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
CONTRIBUTING.md Normal file
View File

@ -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.

356
SECURITY.md
View File

@ -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.