M1: Complete all specification documents (kiro standards)
Completed comprehensive spec-driven documentation: - SPEC.md (222 lines): Project scope, objectives, constraints - ARCHITECTURE.md (290 lines): System design, components, data flow - REQUIREMENTS.md (168 lines): Functional & non-functional requirements - API_SPEC.md (556 lines): 15 API endpoints with schemas - SECURITY.md (188 lines): STRIDE threat model, security controls - ROADMAP.md (203 lines): 5 phases, 8 milestones, risk register Total: 1,627 lines of specification documentation Milestone M1 complete - Ready for Phase 0 (Rust scaffolding)
This commit is contained in:
579
API_SPEC.md
579
API_SPEC.md
@ -1,55 +1,556 @@
|
|||||||
# Linux_Patch_API - API Specification Document
|
# Linux_Patch_API - API Specification Document
|
||||||
|
|
||||||
## API Overview
|
## API Overview
|
||||||
[Describe API purpose and design philosophy]
|
|
||||||
|
**Purpose:** Secure REST API for remote package and patch management on Linux systems
|
||||||
|
|
||||||
|
**Design Philosophy:**
|
||||||
|
- Pure REST architecture (resources as nouns, HTTP verbs for actions)
|
||||||
|
- mTLS certificate-based authentication (no sessions)
|
||||||
|
- Hybrid execution model (sync for quick ops, async for long ops)
|
||||||
|
- Real-time status via WebSocket streaming
|
||||||
|
- JSON request/response with standard envelope
|
||||||
|
|
||||||
|
**Base Path:** `/api/v1/`
|
||||||
|
**Protocol:** HTTPS (TLS 1.3 only)
|
||||||
|
**Port:** 12443
|
||||||
|
**Trailing Slashes:** Not required
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Authentication
|
## Authentication
|
||||||
|
|
||||||
### Authentication Method
|
### Authentication Method
|
||||||
- Type: [TBD - JWT/OAuth2/API Key]
|
- **Type:** mTLS Certificate-Based Authentication
|
||||||
- Token Endpoint: [TBD]
|
- **CA:** Internal self-hosted Certificate Authority
|
||||||
- Token Expiry: [TBD]
|
- **Certificate Validity:** 1 year maximum
|
||||||
|
- **Client Identity:** Unique certificate per client
|
||||||
|
- **Session Management:** None (stateless)
|
||||||
|
|
||||||
|
### Authorization
|
||||||
|
- **Method:** IP Whitelist Enforcement
|
||||||
|
- **Default:** Deny all (block unless explicitly allowed)
|
||||||
|
- **Permissions:** Binary (whitelisted IP + valid cert = full access)
|
||||||
|
- **No Granular Permissions:** All authenticated clients have full API access
|
||||||
|
|
||||||
|
### Connection Requirements
|
||||||
|
- Valid client certificate signed by internal CA
|
||||||
|
- Client IP must be in whitelist configuration
|
||||||
|
- TLS 1.3 only
|
||||||
|
- Silent drop for non-compliant connections (no response)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Standard Response Envelope
|
||||||
|
|
||||||
|
All API responses use this standard structure:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"request_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||||
|
"timestamp": "2026-04-09T13:04:02Z",
|
||||||
|
"data": {},
|
||||||
|
"error": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Fields:
|
||||||
|
| Field | Type | Description |
|
||||||
|
|-------|------|-------------|
|
||||||
|
| `success` | boolean | true for successful requests, false for errors |
|
||||||
|
| `request_id` | UUID | Unique identifier for request tracking/auditing |
|
||||||
|
| `timestamp` | ISO 8601 | Server timestamp of response |
|
||||||
|
| `data` | object | Response payload (null on error) |
|
||||||
|
| `error` | object | Error details (null on success) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Response Format
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": false,
|
||||||
|
"request_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||||
|
"timestamp": "2026-04-09T13:04:02Z",
|
||||||
|
"data": null,
|
||||||
|
"error": {
|
||||||
|
"code": "ERROR_CODE",
|
||||||
|
"message": "Human-readable description",
|
||||||
|
"details": {},
|
||||||
|
"retryable": false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Error Codes:
|
||||||
|
| Code | HTTP Status | Description |
|
||||||
|
|------|-------------|-------------|
|
||||||
|
| `AUTH_INVALID_CERT` | 401 | Certificate validation failed |
|
||||||
|
| `AUTH_CERT_EXPIRED` | 401 | Certificate has expired |
|
||||||
|
| `AUTHZ_IP_DENIED` | 403 | IP not in whitelist |
|
||||||
|
| `PKG_NOT_FOUND` | 404 | Package not found |
|
||||||
|
| `PKG_MANAGER_ERROR` | 500 | Package manager operation failed |
|
||||||
|
| `JOB_NOT_FOUND` | 404 | Job ID not found |
|
||||||
|
| `JOB_TIMEOUT` | 408 | Job exceeded 30-minute timeout |
|
||||||
|
| `CONFIG_INVALID` | 400 | Configuration validation failed |
|
||||||
|
| `SERVICE_UNHEALTHY` | 503 | Service not ready |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Endpoints
|
## Endpoints
|
||||||
|
|
||||||
### PATCH Management Endpoints
|
### Package Management Endpoints
|
||||||
#### GET /api/v1/patches
|
|
||||||
[Describe endpoint]
|
|
||||||
|
|
||||||
#### POST /api/v1/patches/apply
|
#### POST /api/v1/packages
|
||||||
[Describe endpoint]
|
|
||||||
|
|
||||||
#### GET /api/v1/patches/status/{id}
|
**Description:** Install one or more packages (async operation)
|
||||||
[Describe endpoint]
|
|
||||||
|
|
||||||
### Software Management Endpoints
|
**Request Body:**
|
||||||
#### GET /api/v1/software
|
```json
|
||||||
[Describe endpoint]
|
{
|
||||||
|
"packages": [
|
||||||
|
{
|
||||||
|
"name": "nginx",
|
||||||
|
"version": "1.24.0-1"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"options": {
|
||||||
|
"force": false,
|
||||||
|
"no_recommends": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
#### POST /api/v1/software/install
|
**Response (202 Accepted):**
|
||||||
[Describe endpoint]
|
```json
|
||||||
|
{
|
||||||
#### POST /api/v1/software/remove
|
"success": true,
|
||||||
[Describe endpoint]
|
"request_id": "uuid",
|
||||||
|
"timestamp": "2026-04-09T13:04:02Z",
|
||||||
### System Endpoints
|
"data": {
|
||||||
#### GET /api/v1/system/status
|
"job_id": "uuid",
|
||||||
[Describe endpoint]
|
"status": "pending",
|
||||||
|
"operation": "install",
|
||||||
#### GET /api/v1/system/logs
|
"packages": ["nginx"]
|
||||||
[Describe endpoint]
|
},
|
||||||
|
"error": null
|
||||||
## Request/Response Formats
|
}
|
||||||
### Standard Response Structure
|
```
|
||||||
[Define response schema]
|
|
||||||
|
|
||||||
### Error Response Format
|
|
||||||
[Define error response schema]
|
|
||||||
|
|
||||||
## Rate Limiting
|
|
||||||
[Define rate limits]
|
|
||||||
|
|
||||||
## Versioning Strategy
|
|
||||||
[API versioning approach]
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
#### GET /api/v1/packages
|
||||||
|
|
||||||
|
**Description:** List installed packages with filtering and sorting
|
||||||
|
|
||||||
|
**Query Parameters:**
|
||||||
|
| Parameter | Type | Description |
|
||||||
|
|-----------|------|-------------|
|
||||||
|
| `name` | string | Filter by package name (supports wildcard `*`) |
|
||||||
|
| `status` | string | Filter: `installed`, `upgradable`, `available` |
|
||||||
|
| `upgradable` | boolean | `true` to show only upgradable packages |
|
||||||
|
| `sort` | string | Sort field: `name`, `version`, `status` (default: `name`) |
|
||||||
|
| `order` | string | Sort order: `asc`, `desc` (default: `asc`) |
|
||||||
|
|
||||||
|
**Response (200 OK):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"request_id": "uuid",
|
||||||
|
"timestamp": "2026-04-09T13:04:02Z",
|
||||||
|
"data": {
|
||||||
|
"packages": [
|
||||||
|
{
|
||||||
|
"name": "nginx",
|
||||||
|
"version": "1.24.0-1",
|
||||||
|
"status": "installed",
|
||||||
|
"upgradable": true,
|
||||||
|
"latest_version": "1.25.0-1",
|
||||||
|
"description": "High performance web server",
|
||||||
|
"dependencies": ["libc6", "libssl3"],
|
||||||
|
"reverse_dependencies": ["nginx-core"]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"total": 1
|
||||||
|
},
|
||||||
|
"error": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### GET /api/v1/packages/{name}
|
||||||
|
|
||||||
|
**Description:** Get details of a specific package
|
||||||
|
|
||||||
|
**Response (200 OK):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"request_id": "uuid",
|
||||||
|
"timestamp": "2026-04-09T13:04:02Z",
|
||||||
|
"data": {
|
||||||
|
"name": "nginx",
|
||||||
|
"version": "1.24.0-1",
|
||||||
|
"status": "installed",
|
||||||
|
"upgradable": true,
|
||||||
|
"latest_version": "1.25.0-1",
|
||||||
|
"description": "High performance web server",
|
||||||
|
"dependencies": ["libc6", "libssl3"],
|
||||||
|
"reverse_dependencies": ["nginx-core"],
|
||||||
|
"install_date": "2026-01-15T10:30:00Z",
|
||||||
|
"size_installed": "2.5 MB"
|
||||||
|
},
|
||||||
|
"error": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### PUT /api/v1/packages/{name}
|
||||||
|
|
||||||
|
**Description:** Update a specific package (async operation)
|
||||||
|
|
||||||
|
**Response (202 Accepted):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"request_id": "uuid",
|
||||||
|
"timestamp": "2026-04-09T13:04:02Z",
|
||||||
|
"data": {
|
||||||
|
"job_id": "uuid",
|
||||||
|
"status": "pending",
|
||||||
|
"operation": "update",
|
||||||
|
"package": "nginx"
|
||||||
|
},
|
||||||
|
"error": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### DELETE /api/v1/packages/{name}
|
||||||
|
|
||||||
|
**Description:** Remove a package (async operation)
|
||||||
|
|
||||||
|
**Response (202 Accepted):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"request_id": "uuid",
|
||||||
|
"timestamp": "2026-04-09T13:04:02Z",
|
||||||
|
"data": {
|
||||||
|
"job_id": "uuid",
|
||||||
|
"status": "pending",
|
||||||
|
"operation": "remove",
|
||||||
|
"package": "nginx"
|
||||||
|
},
|
||||||
|
"error": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Patch Management Endpoints
|
||||||
|
|
||||||
|
#### GET /api/v1/patches
|
||||||
|
|
||||||
|
**Description:** List available updates/patches
|
||||||
|
|
||||||
|
**Response (200 OK):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"request_id": "uuid",
|
||||||
|
"timestamp": "2026-04-09T13:04:02Z",
|
||||||
|
"data": {
|
||||||
|
"patches": [
|
||||||
|
{
|
||||||
|
"name": "linux-kernel",
|
||||||
|
"current_version": "5.15.0-91",
|
||||||
|
"available_version": "5.15.0-92",
|
||||||
|
"severity": "critical",
|
||||||
|
"description": "Security update for kernel vulnerabilities",
|
||||||
|
"cve_ids": ["CVE-2024-1234"],
|
||||||
|
"requires_reboot": true
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"total": 1,
|
||||||
|
"security_updates": 1,
|
||||||
|
"requires_reboot": true
|
||||||
|
},
|
||||||
|
"error": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### POST /api/v1/patches/apply
|
||||||
|
|
||||||
|
**Description:** Apply all or specific patches (async operation)
|
||||||
|
|
||||||
|
**Request Body:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"packages": ["linux-kernel", "libc6"], // optional, all if omitted
|
||||||
|
"reboot": true, // optional, auto-reboot after patching
|
||||||
|
"reboot_delay_seconds": 60 // optional, delay before reboot
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response (202 Accepted):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"request_id": "uuid",
|
||||||
|
"timestamp": "2026-04-09T13:04:02Z",
|
||||||
|
"data": {
|
||||||
|
"job_id": "uuid",
|
||||||
|
"status": "pending",
|
||||||
|
"operation": "patch_apply",
|
||||||
|
"packages_count": 2,
|
||||||
|
"reboot_scheduled": true
|
||||||
|
},
|
||||||
|
"error": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### System Endpoints
|
||||||
|
|
||||||
|
#### GET /api/v1/system/info
|
||||||
|
|
||||||
|
**Description:** Get system information
|
||||||
|
|
||||||
|
**Response (200 OK):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"request_id": "uuid",
|
||||||
|
"timestamp": "2026-04-09T13:04:02Z",
|
||||||
|
"data": {
|
||||||
|
"hostname": "server01",
|
||||||
|
"os": "Ubuntu",
|
||||||
|
"os_version": "22.04 LTS",
|
||||||
|
"kernel": "5.15.0-91-generic",
|
||||||
|
"architecture": "x86_64",
|
||||||
|
"last_update_check": "2026-04-09T12:00:00Z",
|
||||||
|
"last_update_apply": "2026-04-01T03:00:00Z",
|
||||||
|
"pending_reboot": false
|
||||||
|
},
|
||||||
|
"error": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### GET /api/v1/health
|
||||||
|
|
||||||
|
**Description:** Health check endpoint
|
||||||
|
|
||||||
|
**Response (200 OK - Healthy):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"request_id": "uuid",
|
||||||
|
"timestamp": "2026-04-09T13:04:02Z",
|
||||||
|
"data": {
|
||||||
|
"status": "healthy",
|
||||||
|
"uptime_seconds": 12345,
|
||||||
|
"version": "0.0.1"
|
||||||
|
},
|
||||||
|
"error": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response (503 - Unhealthy):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": false,
|
||||||
|
"request_id": "uuid",
|
||||||
|
"timestamp": "2026-04-09T13:04:02Z",
|
||||||
|
"data": null,
|
||||||
|
"error": {
|
||||||
|
"code": "SERVICE_UNHEALTHY",
|
||||||
|
"message": "Service not ready",
|
||||||
|
"details": {},
|
||||||
|
"retryable": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### POST /api/v1/system/reboot
|
||||||
|
|
||||||
|
**Description:** Reboot the system (async operation)
|
||||||
|
|
||||||
|
**Request Body:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"delay_seconds": 0, // optional, immediate if omitted
|
||||||
|
"force": false // optional, skip pending job checks
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response (202 Accepted):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"request_id": "uuid",
|
||||||
|
"timestamp": "2026-04-09T13:04:02Z",
|
||||||
|
"data": {
|
||||||
|
"job_id": "uuid",
|
||||||
|
"status": "pending",
|
||||||
|
"operation": "reboot",
|
||||||
|
"scheduled_at": "2026-04-09T13:04:02Z"
|
||||||
|
},
|
||||||
|
"error": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Job Management Endpoints
|
||||||
|
|
||||||
|
#### GET /api/v1/jobs
|
||||||
|
|
||||||
|
**Description:** List all jobs with optional filtering
|
||||||
|
|
||||||
|
**Query Parameters:**
|
||||||
|
| Parameter | Type | Description |
|
||||||
|
|-----------|------|-------------|
|
||||||
|
| `status` | string | Filter: `pending`, `running`, `completed`, `failed`, `cancelled` |
|
||||||
|
| `limit` | integer | Max results (default: 50, no pagination beyond limit) |
|
||||||
|
|
||||||
|
**Response (200 OK):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"request_id": "uuid",
|
||||||
|
"timestamp": "2026-04-09T13:04:02Z",
|
||||||
|
"data": {
|
||||||
|
"jobs": [
|
||||||
|
{
|
||||||
|
"job_id": "uuid",
|
||||||
|
"operation": "install",
|
||||||
|
"status": "completed",
|
||||||
|
"created_at": "2026-04-09T13:00:00Z",
|
||||||
|
"completed_at": "2026-04-09T13:02:00Z",
|
||||||
|
"packages": ["nginx"]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"total": 1
|
||||||
|
},
|
||||||
|
"error": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### GET /api/v1/jobs/{id}
|
||||||
|
|
||||||
|
**Description:** Get specific job status
|
||||||
|
|
||||||
|
**Response (200 OK):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"request_id": "uuid",
|
||||||
|
"timestamp": "2026-04-09T13:04:02Z",
|
||||||
|
"data": {
|
||||||
|
"job_id": "uuid",
|
||||||
|
"operation": "install",
|
||||||
|
"status": "running",
|
||||||
|
"progress": 45,
|
||||||
|
"message": "Downloading package...",
|
||||||
|
"created_at": "2026-04-09T13:00:00Z",
|
||||||
|
"completed_at": null,
|
||||||
|
"packages": ["nginx"],
|
||||||
|
"logs": ["Starting installation...", "Resolving dependencies..."]
|
||||||
|
},
|
||||||
|
"error": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### POST /api/v1/jobs/{id}/rollback
|
||||||
|
|
||||||
|
**Description:** Rollback a completed/failed job (async, exclusive mode)
|
||||||
|
|
||||||
|
**Response (202 Accepted):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"request_id": "uuid",
|
||||||
|
"timestamp": "2026-04-09T13:04:02Z",
|
||||||
|
"data": {
|
||||||
|
"job_id": "uuid-rollback",
|
||||||
|
"status": "pending",
|
||||||
|
"operation": "rollback",
|
||||||
|
"original_job_id": "uuid",
|
||||||
|
"exclusive_mode": true
|
||||||
|
},
|
||||||
|
"error": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### WebSocket: /api/v1/ws/jobs
|
||||||
|
|
||||||
|
**Description:** Real-time job status streaming
|
||||||
|
|
||||||
|
**Connection:** Upgrade HTTP connection with mTLS
|
||||||
|
|
||||||
|
**Client → Server (subscribe):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"action": "subscribe",
|
||||||
|
"job_id": "uuid" // optional, omit for all jobs
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Server → Client (status update):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"event": "job_status",
|
||||||
|
"job_id": "uuid",
|
||||||
|
"status": "running",
|
||||||
|
"progress": 45,
|
||||||
|
"message": "Installing package...",
|
||||||
|
"timestamp": "2026-04-09T13:04:02Z"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Server → Client (job complete):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"event": "job_complete",
|
||||||
|
"job_id": "uuid",
|
||||||
|
"status": "completed",
|
||||||
|
"progress": 100,
|
||||||
|
"message": "Installation complete",
|
||||||
|
"timestamp": "2026-04-09T13:04:02Z"
|
||||||
|
}
|
||||||
|
---
|
||||||
|
|
||||||
|
## Rate Limiting
|
||||||
|
|
||||||
|
**Not Required:** Internal network only with strict IP whitelist
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Versioning Strategy
|
||||||
|
|
||||||
|
- **Method:** URL Path Versioning (`/api/v1/`)
|
||||||
|
- **Backward Compatibility:** Breaking changes require new major version
|
||||||
|
- **Deprecation:** Old versions supported for 6 months after new version release
|
||||||
|
- **Current Version:** v1
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
*Following kiro spec-driven development standards*
|
*Following kiro spec-driven development standards*
|
||||||
|
|||||||
310
ARCHITECTURE.md
310
ARCHITECTURE.md
@ -1,36 +1,290 @@
|
|||||||
# Linux_Patch_API - Architecture Document
|
# Linux_Patch_API - Architecture Document
|
||||||
|
|
||||||
## System Overview
|
## System Overview
|
||||||
[High-level system architecture description]
|
|
||||||
|
|
||||||
## Component Architecture
|
The Linux_Patch_API is a secure, single-host API service that enables remote package and patch management on Linux systems. Each instance runs as a systemd service on the managed host, providing a REST API over mTLS with strict IP whitelist enforcement.
|
||||||
### Core Components
|
|
||||||
[List and describe core components]
|
|
||||||
|
|
||||||
### External Integrations
|
**Architecture Type:** Agent Per Host (Option B)
|
||||||
[Describe external system integrations]
|
**Deployment:** One instance per managed Linux host
|
||||||
|
**Network:** Internal network only (no internet exposure)
|
||||||
## Technology Stack
|
|
||||||
### Backend
|
|
||||||
- Language: [TBD]
|
|
||||||
- Framework: [TBD]
|
|
||||||
- Database: [TBD]
|
|
||||||
|
|
||||||
### Frontend (if applicable)
|
|
||||||
- Framework: [TBD]
|
|
||||||
|
|
||||||
### Infrastructure
|
|
||||||
- Container: [TBD]
|
|
||||||
- Orchestration: [TBD]
|
|
||||||
|
|
||||||
## Security Architecture
|
|
||||||
[Security layers and controls]
|
|
||||||
|
|
||||||
## Data Flow
|
|
||||||
[Describe data flow through the system]
|
|
||||||
|
|
||||||
## API Design Principles
|
|
||||||
[REST/gRPC/GraphQL design decisions]
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Component Architecture
|
||||||
|
|
||||||
|
### Core Components
|
||||||
|
|
||||||
|
1. **API Layer (Actix-web/Axum)**
|
||||||
|
- HTTP/HTTPS endpoint handling
|
||||||
|
- mTLS termination
|
||||||
|
- IP whitelist enforcement
|
||||||
|
- Request routing
|
||||||
|
- WebSocket support for real-time job status
|
||||||
|
|
||||||
|
2. **Authentication Layer**
|
||||||
|
- Certificate validation (mTLS)
|
||||||
|
- Client identity extraction from certificate
|
||||||
|
- No session management (stateless, cert-based auth only)
|
||||||
|
|
||||||
|
3. **Authorization Layer**
|
||||||
|
- IP whitelist checking (deny by default)
|
||||||
|
- No permission validation (whitelisted IP + valid cert = full access)
|
||||||
|
|
||||||
|
4. **Job Manager**
|
||||||
|
- Async job queue for long-running operations
|
||||||
|
- Job status tracking with persistent storage
|
||||||
|
- WebSocket broadcast for real-time status updates
|
||||||
|
- 30-minute timeout enforcement
|
||||||
|
- Job cleanup and expiration
|
||||||
|
|
||||||
|
5. **Package Manager Backend (Pluggable)**
|
||||||
|
- apt/dpkg adapter (Debian/Ubuntu - primary)
|
||||||
|
- dnf/yum adapter (RHEL/CentOS/Fedora)
|
||||||
|
- apk adapter (Alpine)
|
||||||
|
- pacman adapter (Arch)
|
||||||
|
- Distribution detection and adapter selection
|
||||||
|
|
||||||
|
6. **Audit Logger**
|
||||||
|
- systemd journal integration (primary)
|
||||||
|
- Optional remote syslog server
|
||||||
|
- Local file fallback (`/var/log/linux_patch_api/`)
|
||||||
|
- 30-day retention with daily rotation and gzip compression
|
||||||
|
|
||||||
|
7. **Configuration Manager**
|
||||||
|
- YAML config file watcher (`/etc/linux_patch_api/config.yaml`)
|
||||||
|
- Auto-reload on file change
|
||||||
|
- Config validation before reload (prevents service downtime)
|
||||||
|
- Runtime settings access for all components
|
||||||
|
|
||||||
|
### External Integrations
|
||||||
|
|
||||||
|
- **Package Managers:** apt, dnf, yum, apk, pacman (via system commands)
|
||||||
|
- **systemd:** Service management and journal logging
|
||||||
|
- **Internal CA:** Certificate validation against self-hosted CA
|
||||||
|
- **Remote Syslog:** Optional external log aggregation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Technology Stack
|
||||||
|
|
||||||
|
### Backend
|
||||||
|
- **Language:** Rust
|
||||||
|
- **Framework:** Actix-web or Axum
|
||||||
|
- **Database:** None (file-based job storage)
|
||||||
|
- **mTLS:** Rust TLS library (rustls or native-tls)
|
||||||
|
|
||||||
|
### Infrastructure
|
||||||
|
- **Service Manager:** systemd
|
||||||
|
- **Configuration:** YAML
|
||||||
|
- **Logging:** systemd journal + optional syslog
|
||||||
|
|
||||||
|
### Deployment
|
||||||
|
- **Package Format:** Native Linux packages (deb, rpm, apk, pkg.tar.zst)
|
||||||
|
- **Distribution:** Via target system package manager (apt, dnf, apk, pacman)
|
||||||
|
- **Installation:** Package installs binary, systemd service, and default config structure
|
||||||
|
- **Updates:** Handled through system package manager
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Security Architecture
|
||||||
|
|
||||||
|
### Authentication
|
||||||
|
- mTLS certificate-based authentication (required)
|
||||||
|
- Internal self-hosted CA
|
||||||
|
- Unique client certificates (1-year validity)
|
||||||
|
- Silent drop for non-mTLS connections
|
||||||
|
|
||||||
|
### Authorization
|
||||||
|
- IP whitelist enforcement (block all by default)
|
||||||
|
- No granular permissions (binary access: allowed or denied)
|
||||||
|
- Whitelisted IP + valid cert = full API access
|
||||||
|
|
||||||
|
### Process Security (systemd Hardening)
|
||||||
|
- **User:** root (required for package management)
|
||||||
|
- **NoNewPrivileges:** true (prevent privilege escalation)
|
||||||
|
- **ProtectSystem:** strict (read-only filesystem except allowed paths)
|
||||||
|
- **ProtectHome:** true (no access to /home, /root, /run/user)
|
||||||
|
- **PrivateTmp:** true (isolated /tmp)
|
||||||
|
- **SystemCallFilter:** Restrict to required syscalls only (application whitelist)
|
||||||
|
- **RestrictAddressFamilies:** AF_INET, AF_INET6, AF_UNIX (network restrictions)
|
||||||
|
- **CapabilityBoundingSet:** CAP_NET_BIND_SERVICE, CAP_SYS_ADMIN (minimal capabilities)
|
||||||
|
|
||||||
|
### Data Security
|
||||||
|
- All communications encrypted via TLS
|
||||||
|
- Certificates stored securely with restricted permissions
|
||||||
|
- Audit logging of all operations
|
||||||
|
|
||||||
|
### Certificate Storage (Option A: Separate Files)
|
||||||
|
|
||||||
|
```
|
||||||
|
/etc/linux_patch_api/certs/
|
||||||
|
├── ca.pem (644) - CA certificate
|
||||||
|
├── server.pem (644) - Server certificate
|
||||||
|
└── server.key (600) - Server private key (restricted)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Rationale:**
|
||||||
|
- Tighter permissions on private key only (600)
|
||||||
|
- Easier certificate rotation (replace cert without touching key)
|
||||||
|
- Standard practice for TLS deployments
|
||||||
|
- No extraction overhead
|
||||||
|
---
|
||||||
|
|
||||||
|
## File System Layout
|
||||||
|
|
||||||
|
```
|
||||||
|
/etc/linux_patch_api/
|
||||||
|
├── config.yaml # Main configuration
|
||||||
|
├── whitelist.yaml # IP whitelist
|
||||||
|
└── certs/
|
||||||
|
├── ca.pem # CA certificate (or server.p12)
|
||||||
|
├── server.pem # Server certificate
|
||||||
|
└── server.key # Server private key
|
||||||
|
|
||||||
|
/var/lib/linux_patch_api/
|
||||||
|
├── jobs/ # Job storage (cleared on restart)
|
||||||
|
└── state/ # Runtime state
|
||||||
|
|
||||||
|
/var/log/linux_patch_api/
|
||||||
|
└── audit.log # Local audit log fallback
|
||||||
|
|
||||||
|
/usr/bin/linux-patch-api # Binary location
|
||||||
|
/etc/systemd/system/linux-patch-api.service # Systemd service
|
||||||
|
```
|
||||||
|
---
|
||||||
|
|
||||||
|
## Data Flow
|
||||||
|
|
||||||
|
### Synchronous Request Flow (Quick Operations):
|
||||||
|
|
||||||
|
```
|
||||||
|
Client → [mTLS Handshake] → [IP Whitelist Check] → [API Layer]
|
||||||
|
↓
|
||||||
|
[Auth: Cert Valid?] → No → Silent Drop
|
||||||
|
↓ Yes
|
||||||
|
[Authz: IP Allowed?] → No → Silent Drop
|
||||||
|
↓ Yes
|
||||||
|
[Route to Handler] → [Execute Package Op] → [Log to Audit]
|
||||||
|
↓
|
||||||
|
[Return JSON Response] ← Client
|
||||||
|
```
|
||||||
|
|
||||||
|
### Asynchronous Request Flow (Long Operations):
|
||||||
|
|
||||||
|
```
|
||||||
|
Client → [mTLS + IP Check] → [API Layer] → [Create Job] → [Return Job ID]
|
||||||
|
↓
|
||||||
|
[Job Manager Queue]
|
||||||
|
↓
|
||||||
|
[Package Manager Backend]
|
||||||
|
↓
|
||||||
|
[Update Job Status] → [WebSocket Broadcast]
|
||||||
|
↓
|
||||||
|
[Job Complete/Timeout]
|
||||||
|
↓
|
||||||
|
[Log to Audit]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Job Status Endpoint Flow:
|
||||||
|
|
||||||
|
```
|
||||||
|
Client → [mTLS + IP Check] → [API Layer] → [GET /jobs/{id}]
|
||||||
|
↓
|
||||||
|
[Query Job Storage]
|
||||||
|
↓
|
||||||
|
[Return Job Status JSON]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Configuration Reload Flow:
|
||||||
|
|
||||||
|
```
|
||||||
|
[Config File Changed] → [File Watcher Detects]
|
||||||
|
↓
|
||||||
|
[Validate New Config] → Invalid → [Log Error, Keep Old Config]
|
||||||
|
↓ Valid
|
||||||
|
[Swap Config in Memory] → [Notify Components] → [Log Reload Event]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Certificate Renewal Flow:
|
||||||
|
|
||||||
|
```
|
||||||
|
[Cert File Updated] → [File Watcher Detects]
|
||||||
|
↓
|
||||||
|
[Validate Certificate Chain] → Invalid → [Log Error, Keep Old Certs]
|
||||||
|
↓ Valid
|
||||||
|
[Reload TLS Context] → [New Connections Use New Certs] → [Log Reload Event]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Rollback Execution Flow (Exclusive):
|
||||||
|
|
||||||
|
```
|
||||||
|
[Rollback Triggered] → [Set Exclusive Mode] → [Reject New Requests]
|
||||||
|
↓
|
||||||
|
[Execute Rollback Operations] → [Log Each Step]
|
||||||
|
↓
|
||||||
|
[Rollback Complete] → [Clear Exclusive Mode] → [Accept New Requests]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Behaviors:
|
||||||
|
|
||||||
|
- Failed jobs are cleared on service restart (no persistence)
|
||||||
|
- Rollback execution is exclusive - no new requests accepted until complete
|
||||||
|
- Certificate renewal follows same validation pattern as config reload
|
||||||
|
- Status endpoint available (GET /jobs/{id}) in addition to WebSocket for job monitoring
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## API Design Principles
|
||||||
|
|
||||||
|
- Pure REST (resources as nouns, HTTP verbs for actions)
|
||||||
|
- JSON request/response with standard envelope
|
||||||
|
- Hybrid execution model (sync for quick ops, async for long ops)
|
||||||
|
- WebSocket for real-time job status streaming
|
||||||
|
- GET /jobs/{id} endpoint for job status polling
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Network Configuration
|
||||||
|
|
||||||
|
- **Bind Address:** 0.0.0.0 (all interfaces)
|
||||||
|
- **Port:** 12443 (HTTPS/mTLS)
|
||||||
|
- **Protocol:** TLS 1.3 only
|
||||||
|
- **Firewall:** Host-level firewall should restrict inbound to whitelisted IPs only
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Health Checks
|
||||||
|
|
||||||
|
### Endpoint: GET /health
|
||||||
|
|
||||||
|
**Purpose:** General service status check
|
||||||
|
|
||||||
|
**Response (200 OK - Healthy):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"request_id": "uuid",
|
||||||
|
"timestamp": "2026-04-09T13:04:02Z",
|
||||||
|
"data": {
|
||||||
|
"status": "healthy",
|
||||||
|
"uptime_seconds": 12345,
|
||||||
|
"version": "0.0.1"
|
||||||
|
},
|
||||||
|
"error": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Health Check Criteria:**
|
||||||
|
- Service is listening on port 12443
|
||||||
|
- mTLS is configured and valid
|
||||||
|
- Config file is loaded and valid
|
||||||
|
- Package manager backend is accessible
|
||||||
|
|
||||||
|
**NOT Required:**
|
||||||
|
- Metrics collection
|
||||||
|
- Alerting integration
|
||||||
|
- Prometheus/Grafana endpoints
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
*Following kiro spec-driven development standards*
|
*Following kiro spec-driven development standards*
|
||||||
|
|||||||
179
REQUIREMENTS.md
179
REQUIREMENTS.md
@ -1,43 +1,168 @@
|
|||||||
# Linux_Patch_API - Requirements Document
|
# Linux_Patch_API - Requirements Document
|
||||||
|
|
||||||
## Functional Requirements
|
## Functional Requirements
|
||||||
### FR-001: Remote Patch Management
|
|
||||||
[Define patch management requirements]
|
|
||||||
|
|
||||||
### FR-002: Software Installation/Removal
|
### FR-001: Package Management Endpoints
|
||||||
[Define software package management requirements]
|
|
||||||
|
|
||||||
### FR-003: Authentication & Authorization
|
| ID | Endpoint | Method | Description | Sync/Async |
|
||||||
[Define auth requirements]
|
|----|----------|--------|-------------|------------|
|
||||||
|
| FR-001.1 | `/packages` | GET | List installed packages with filtering (name, version, status, upgradable) | Sync |
|
||||||
|
| FR-001.2 | `/packages/{name}` | GET | Get specific package details | Sync |
|
||||||
|
| FR-001.3 | `/packages` | POST | Install package(s) with optional version pinning | Async |
|
||||||
|
| FR-001.4 | `/packages/{name}` | PUT | Update specific package | Async |
|
||||||
|
| FR-001.5 | `/packages/{name}` | DELETE | Remove package | Async |
|
||||||
|
|
||||||
### FR-004: Audit Logging
|
### FR-002: Patch Management Endpoints
|
||||||
[Define logging requirements]
|
|
||||||
|
|
||||||
## Non-Functional Requirements
|
| ID | Endpoint | Method | Description | Sync/Async |
|
||||||
### NFR-001: Security
|
|----|----------|--------|-------------|------------|
|
||||||
[Security requirements]
|
| FR-002.1 | `/patches` | GET | List available updates/patches | Sync |
|
||||||
|
| FR-002.2 | `/patches/apply` | POST | Apply all or specific patches | Async |
|
||||||
|
|
||||||
### NFR-002: Performance
|
### FR-003: System Endpoints
|
||||||
[Performance requirements]
|
|
||||||
|
|
||||||
### NFR-003: Availability
|
| ID | Endpoint | Method | Description | Sync/Async |
|
||||||
[Availability requirements]
|
|----|----------|--------|-------------|------------|
|
||||||
|
| FR-003.1 | `/system/info` | GET | Get system information (OS version, kernel, last update time) | Sync |
|
||||||
|
| FR-003.2 | `/health` | GET | Health check endpoint | Sync |
|
||||||
|
| FR-003.3 | `/jobs/{id}` | GET | Get specific job status | Sync |
|
||||||
|
| FR-003.4 | `/jobs` | GET | List all jobs (with optional status filter) | Sync |
|
||||||
|
|
||||||
### NFR-004: Scalability
|
### FR-004: Job Management Endpoints
|
||||||
[Scalability requirements]
|
|
||||||
|
|
||||||
## User Stories
|
| ID | Endpoint | Method | Description | Sync/Async |
|
||||||
[List user stories with acceptance criteria]
|
|----|----------|--------|-------------|------------|
|
||||||
|
| FR-004.1 | `/jobs/{id}/rollback` | POST | Rollback a completed/failed job | Async (Exclusive) |
|
||||||
|
|
||||||
## Technical Requirements
|
### FR-005: Authentication & Authorization
|
||||||
### System Requirements
|
|
||||||
- OS: [TBD]
|
|
||||||
- Memory: [TBD]
|
|
||||||
- Storage: [TBD]
|
|
||||||
|
|
||||||
### Network Requirements
|
- mTLS certificate validation (required for all endpoints)
|
||||||
- Ports: [TBD]
|
- IP whitelist enforcement (deny by default, allow listed only)
|
||||||
- Protocols: [TBD]
|
- No session management (stateless, cert-based auth)
|
||||||
|
- No granular permissions (whitelisted IP + valid cert = full access)
|
||||||
|
|
||||||
|
### FR-006: Audit Logging
|
||||||
|
|
||||||
|
- Log all API requests with client cert ID, endpoint, method, timestamp
|
||||||
|
- Log all package operations (package name, version, action)
|
||||||
|
- Log authentication events (success/failure, cert validation)
|
||||||
|
- Log IP whitelist denials (blocked connection attempts)
|
||||||
|
- Log configuration changes (whitelist updates, cert renewals)
|
||||||
|
- Log system changes made by the API
|
||||||
|
|
||||||
---
|
---
|
||||||
|
## Non-Functional Requirements
|
||||||
|
|
||||||
|
### NFR-001: Security
|
||||||
|
|
||||||
|
- **Authentication:** mTLS certificate-based (TLS 1.3 only)
|
||||||
|
- **Authorization:** IP whitelist enforcement (block all by default)
|
||||||
|
- **Certificate Validity:** 1-year maximum, unique per client
|
||||||
|
- **Subprocess Restriction:** SystemCallFilter to limit allowed syscalls
|
||||||
|
- **Error Handling:** Silent drop for non-mTLS connections, detailed errors for authenticated clients
|
||||||
|
- **Data Encryption:** All communications encrypted via TLS
|
||||||
|
|
||||||
|
### NFR-002: Performance
|
||||||
|
|
||||||
|
- **Quick Operations:** < 5 seconds response time (GET endpoints)
|
||||||
|
- **Long Operations:** Async with job tracking, max 30-minute timeout
|
||||||
|
- **Concurrent Jobs:** Configurable limit (default: 5)
|
||||||
|
- **WebSocket:** Real-time status updates for async jobs
|
||||||
|
|
||||||
|
### NFR-003: Availability
|
||||||
|
|
||||||
|
- **Service Type:** systemd service with automatic restart on failure
|
||||||
|
- **Config Reload:** Auto-reload on config file change (validated before apply)
|
||||||
|
- **Certificate Reload:** Auto-reload on cert file change (validated before apply)
|
||||||
|
- **Health Check:** GET /health endpoint for monitoring
|
||||||
|
|
||||||
|
### NFR-004: Scalability
|
||||||
|
|
||||||
|
- **Architecture:** Single instance per host (Agent Per Host model)
|
||||||
|
- **No Central Coordination:** Each host operates independently
|
||||||
|
- **Package Manager:** Pluggable backend for multi-distribution support
|
||||||
|
|
||||||
|
### NFR-005: Reliability
|
||||||
|
|
||||||
|
- **Job Persistence:** Jobs stored in memory/file, cleared on restart
|
||||||
|
- **Rollback:** Exclusive mode during rollback (no new requests accepted)
|
||||||
|
- **Batch Operations:** Best-effort (not atomic)
|
||||||
|
- **Idempotency:** Operations should be idempotent where possible
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## User Stories
|
||||||
|
|
||||||
|
### US-001: System Administrator - Install Package
|
||||||
|
**As a** system administrator
|
||||||
|
**I want to** install a package remotely via API
|
||||||
|
**So that** I can manage software without SSH access
|
||||||
|
|
||||||
|
**Acceptance Criteria:**
|
||||||
|
- POST /packages with package name returns job ID
|
||||||
|
- Job status available via GET /jobs/{id} and WebSocket
|
||||||
|
- Audit log records the installation
|
||||||
|
- Rollback available if installation fails
|
||||||
|
|
||||||
|
### US-002: System Administrator - Apply Security Patches
|
||||||
|
**As a** system administrator
|
||||||
|
**I want to** apply all available security patches
|
||||||
|
**So that** the system stays secure
|
||||||
|
|
||||||
|
**Acceptance Criteria:**
|
||||||
|
- GET /patches shows available updates
|
||||||
|
- POST /patches/apply initiates patching
|
||||||
|
- Real-time status via WebSocket
|
||||||
|
- All operations logged to audit
|
||||||
|
|
||||||
|
### US-003: System Administrator - Check System Status
|
||||||
|
**As a** system administrator
|
||||||
|
**I want to** check system health and package status
|
||||||
|
**So that** I can monitor the system
|
||||||
|
|
||||||
|
**Acceptance Criteria:**
|
||||||
|
- GET /health returns service status
|
||||||
|
- GET /system/info returns OS details
|
||||||
|
- GET /packages returns installed packages
|
||||||
|
- All queries require valid mTLS cert
|
||||||
|
|
||||||
|
### US-004: System Administrator - Remove Package
|
||||||
|
**As a** system administrator
|
||||||
|
**I want to** remove an unwanted package
|
||||||
|
**So that** I can clean up the system
|
||||||
|
|
||||||
|
**Acceptance Criteria:**
|
||||||
|
- DELETE /packages/{name} returns job ID
|
||||||
|
- Job tracks removal progress
|
||||||
|
- Audit log records the removal
|
||||||
|
- Rollback available if needed
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Technical Requirements
|
||||||
|
|
||||||
|
### System Requirements
|
||||||
|
|
||||||
|
- **OS:** Linux (Debian/Ubuntu primary, RHEL/CentOS/Fedora, Alpine, Arch supported)
|
||||||
|
- **Memory:** Minimum 256MB RAM, recommended 512MB
|
||||||
|
- **Storage:** Minimum 100MB for binary and config, plus job storage
|
||||||
|
- **CPU:** Any modern x86_64 or ARM64 processor
|
||||||
|
- **Privileges:** Root access required (for package management)
|
||||||
|
|
||||||
|
### Network Requirements
|
||||||
|
|
||||||
|
- **Port:** 12443 (TCP)
|
||||||
|
- **Protocol:** TLS 1.3 only
|
||||||
|
- **Bind Address:** 0.0.0.0 (all interfaces)
|
||||||
|
- **Firewall:** Host-level firewall to restrict inbound to whitelisted IPs
|
||||||
|
|
||||||
|
### Dependencies
|
||||||
|
|
||||||
|
- **Runtime:** None (compiled Rust binary)
|
||||||
|
- **Package Managers:** apt/dpkg, dnf/yum, apk, or pacman (at least one required)
|
||||||
|
- **systemd:** For service management
|
||||||
|
- **Certificates:** Valid mTLS certificates from internal CA
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
*Following kiro spec-driven development standards*
|
*Following kiro spec-driven development standards*
|
||||||
|
|||||||
244
ROADMAP.md
244
ROADMAP.md
@ -1,57 +1,203 @@
|
|||||||
# Linux_Patch_API - Development Roadmap
|
# Linux_Patch_API - Development Roadmap
|
||||||
|
|
||||||
|
## Project Timeline Overview
|
||||||
|
|
||||||
|
**Start Date:** 2026-04-09
|
||||||
|
**Target Production:** 2026-07-17
|
||||||
|
**Total Duration:** 14 weeks (Aggressive timeline)
|
||||||
|
**Phase Strategy:** Sequential (no overlap)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Project Phases
|
## Project Phases
|
||||||
|
|
||||||
### Phase 1: Foundation
|
### Phase 0: Rust Project Scaffolding
|
||||||
**Target Date:** [TBD]
|
**Duration:** 3 days
|
||||||
**Status:** Not Started
|
**Target Date:** 2026-04-09 to 2026-04-12
|
||||||
|
**Status:** Ready to Start
|
||||||
|
|
||||||
- [ ] Complete all specification documents
|
- [ ] Initialize Rust project with Cargo
|
||||||
- [ ] Set up development environment
|
- [ ] Set up project structure (src/, tests/, configs/)
|
||||||
- [ ] Initialize git repository
|
- [ ] Configure Cargo.toml with dependencies (actix-web, tokio, openssl, serde, etc.)
|
||||||
- [ ] Configure CI/CD pipeline
|
- [ ] Set up Clippy and rustfmt for code quality
|
||||||
- [ ] Establish security baseline
|
- [ ] Create initial module structure (api, auth, jobs, packages, config, logging)
|
||||||
|
- [ ] Configure .gitignore for Rust projects
|
||||||
### Phase 2: Core API Development
|
- [ ] Set up initial logging framework
|
||||||
**Target Date:** [TBD]
|
|
||||||
**Status:** Not Started
|
|
||||||
|
|
||||||
- [ ] Implement authentication system
|
|
||||||
- [ ] Build patch management endpoints
|
|
||||||
- [ ] Build software management endpoints
|
|
||||||
- [ ] Implement audit logging
|
|
||||||
- [ ] Unit test coverage >80%
|
|
||||||
|
|
||||||
### Phase 3: Security Hardening
|
|
||||||
**Target Date:** [TBD]
|
|
||||||
**Status:** Not Started
|
|
||||||
|
|
||||||
- [ ] Penetration testing
|
|
||||||
- [ ] Security audit
|
|
||||||
- [ ] Implement rate limiting
|
|
||||||
- [ ] Complete threat model validation
|
|
||||||
- [ ] Compliance review
|
|
||||||
|
|
||||||
### Phase 4: Production Readiness
|
|
||||||
**Target Date:** [TBD]
|
|
||||||
**Status:** Not Started
|
|
||||||
|
|
||||||
- [ ] Performance optimization
|
|
||||||
- [ ] Documentation completion
|
|
||||||
- [ ] Deployment automation
|
|
||||||
- [ ] Monitoring and alerting
|
|
||||||
- [ ] User acceptance testing
|
|
||||||
|
|
||||||
## Milestones
|
|
||||||
| Milestone | Description | Target Date |
|
|
||||||
|-----------|-------------|-------------|
|
|
||||||
| M1 | Spec completion | [TBD] |
|
|
||||||
| M2 | Alpha release | [TBD] |
|
|
||||||
| M3 | Beta release | [TBD] |
|
|
||||||
| M4 | Production release | [TBD] |
|
|
||||||
|
|
||||||
## Risk Register
|
|
||||||
[List identified risks and mitigation strategies]
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
### Phase 1: Foundation
|
||||||
|
**Duration:** 2 weeks
|
||||||
|
**Target Date:** 2026-04-12 to 2026-04-26
|
||||||
|
**Status:** Not Started
|
||||||
|
|
||||||
|
- [ ] Complete all specification documents ✅ (in progress)
|
||||||
|
- [ ] Set up development environment (Rust toolchain, IDE config)
|
||||||
|
- [ ] Initialize git repository ✅ (complete)
|
||||||
|
- [ ] Configure CI/CD pipeline (GitHub Actions or GitLab CI)
|
||||||
|
- [ ] Establish security baseline (dependency scanning, cargo-audit)
|
||||||
|
- [ ] Set up test framework (cargo test, integration test structure)
|
||||||
|
- [ ] Create systemd service file template
|
||||||
|
- [ ] Set up internal CA infrastructure for mTLS certs
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 2: Core API Development
|
||||||
|
**Duration:** 6 weeks
|
||||||
|
**Target Date:** 2026-04-26 to 2026-06-07
|
||||||
|
**Status:** Not Started
|
||||||
|
|
||||||
|
- [ ] Implement mTLS authentication layer
|
||||||
|
- [ ] Implement IP whitelist enforcement
|
||||||
|
- [ ] Build configuration management (YAML loading, validation, auto-reload)
|
||||||
|
- [ ] Build job manager (queue, status tracking, WebSocket broadcast)
|
||||||
|
- [ ] Implement Package Management endpoints:
|
||||||
|
- GET /api/v1/packages (list/filter/sort)
|
||||||
|
- GET /api/v1/packages/{name} (details)
|
||||||
|
- POST /api/v1/packages (install)
|
||||||
|
- PUT /api/v1/packages/{name} (update)
|
||||||
|
- DELETE /api/v1/packages/{name} (remove)
|
||||||
|
- [ ] Implement Patch Management endpoints:
|
||||||
|
- GET /api/v1/patches (list available)
|
||||||
|
- POST /api/v1/patches/apply (apply patches)
|
||||||
|
- [ ] Implement System endpoints:
|
||||||
|
- GET /api/v1/system/info
|
||||||
|
- GET /api/v1/health
|
||||||
|
- POST /api/v1/system/reboot
|
||||||
|
- [ ] Implement Job Management endpoints:
|
||||||
|
- GET /api/v1/jobs (list)
|
||||||
|
- GET /api/v1/jobs/{id} (status)
|
||||||
|
- POST /api/v1/jobs/{id}/rollback
|
||||||
|
- [ ] Implement WebSocket streaming (/api/v1/ws/jobs)
|
||||||
|
- [ ] Implement audit logging (systemd journal + file fallback)
|
||||||
|
- [ ] Unit test coverage >95%
|
||||||
|
- [ ] Integration tests for all endpoints
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 3: Security Hardening
|
||||||
|
**Duration:** 3 weeks
|
||||||
|
**Target Date:** 2026-06-07 to 2026-06-28
|
||||||
|
**Status:** Not Started
|
||||||
|
|
||||||
|
- [ ] Penetration testing (internal/external)
|
||||||
|
- [ ] Threat model validation (verify all STRIDE mitigations)
|
||||||
|
- [ ] Security control implementation review
|
||||||
|
- [ ] Fuzz testing on API endpoints
|
||||||
|
- [ ] Certificate validation testing
|
||||||
|
- [ ] Config file tampering resistance testing
|
||||||
|
- [ ] Privilege escalation testing
|
||||||
|
- [ ] Fix all security findings
|
||||||
|
- [ ] Security documentation completion
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 4: Production Readiness
|
||||||
|
**Duration:** 3 weeks
|
||||||
|
**Target Date:** 2026-06-28 to 2026-07-17
|
||||||
|
**Status:** Not Started
|
||||||
|
|
||||||
|
- [ ] Performance optimization (benchmarking, profiling)
|
||||||
|
- [ ] Documentation completion (README, deployment guide, API docs)
|
||||||
|
- [ ] Deployment automation (package creation: .deb, .rpm)
|
||||||
|
- [ ] Installation script development
|
||||||
|
- [ ] User acceptance testing
|
||||||
|
- [ ] Final security review
|
||||||
|
- [ ] Production deployment checklist
|
||||||
|
- [ ] Release v1.0.0
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Milestones
|
||||||
|
|
||||||
|
| Milestone | Description | Target Date | Status |
|
||||||
|
|-----------|-------------|-------------|--------|
|
||||||
|
| M0 | Phase 0 complete (scaffolding) | 2026-04-12 | ⏳ Pending |
|
||||||
|
| M1 | All spec documents complete | 2026-04-09 | ✅ Complete |
|
||||||
|
| M2 | Development environment ready | 2026-04-15 | ⏳ Pending |
|
||||||
|
| M3 | CI/CD pipeline operational | 2026-04-22 | ⏳ Pending |
|
||||||
|
| M4 | mTLS + IP whitelist working | 2026-05-03 | ⏳ Pending |
|
||||||
|
| M5 | Core API functional (Alpha) | 2026-06-07 | ⏳ Pending |
|
||||||
|
| M6 | Security testing complete (Beta) | 2026-06-28 | ⏳ Pending |
|
||||||
|
| M7 | Production release (v1.0.0) | 2026-07-17 | ⏳ Pending |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Risk Register
|
||||||
|
|
||||||
|
| ID | Risk | Likelihood | Impact | Mitigation Strategy | Owner |
|
||||||
|
|----|------|------------|--------|---------------------|-------|
|
||||||
|
| R001 | Rust learning curve delays development | Medium | Medium | Pair programming, Rust documentation, community support | Dev Team |
|
||||||
|
| R002 | mTLS certificate management complexity | Medium | High | Early CA setup, detailed documentation, testing certs | Security |
|
||||||
|
| R003 | Package manager API differences across distros | High | Medium | Pluggable backend architecture, extensive testing per distro | Dev Team |
|
||||||
|
| R004 | Security vulnerabilities in dependencies | Low | High | cargo-audit in CI, regular dependency updates, minimal deps | Security |
|
||||||
|
| R005 | Performance issues with concurrent jobs | Medium | Medium | Load testing in Phase 3, configurable concurrency limits | Dev Team |
|
||||||
|
| R006 | Scope creep during development | Medium | High | Strict spec adherence, change control process | PM |
|
||||||
|
| R007 | Internal CA infrastructure delays | Low | High | Start CA setup in Phase 0, use test certs for development | Security |
|
||||||
|
| R008 | systemd integration issues | Low | Medium | Early systemd testing, reference existing Rust systemd services | Dev Team |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Resource Requirements
|
||||||
|
|
||||||
|
### Development Team
|
||||||
|
| Role | Count | Commitment |
|
||||||
|
|------|-------|------------|
|
||||||
|
| Rust Developer | 1-2 | Full-time |
|
||||||
|
| Security Engineer | 1 | Part-time (Phases 1, 3, 4) |
|
||||||
|
| QA/Test Engineer | 1 | Part-time (Phases 2, 3, 4) |
|
||||||
|
|
||||||
|
### Infrastructure
|
||||||
|
| Resource | Purpose | Notes |
|
||||||
|
|----------|---------|-------|
|
||||||
|
| Development Server | Code development | Ubuntu 22.04 LTS |
|
||||||
|
| Test Servers | Multi-distro testing | Ubuntu, Debian, RHEL, Alpine, Arch |
|
||||||
|
| CI/CD Runner | Automated testing | GitHub Actions or self-hosted |
|
||||||
|
| Internal CA | Certificate issuance | Separate secure host |
|
||||||
|
|
||||||
|
### Tools & Services
|
||||||
|
| Tool | Purpose | Cost |
|
||||||
|
|------|---------|------|
|
||||||
|
| Rust Toolchain | Development | Free |
|
||||||
|
| cargo-audit | Security scanning | Free |
|
||||||
|
| Git/Gitea | Version control | Self-hosted |
|
||||||
|
| Wireshark | Network analysis | Free |
|
||||||
|
| Burp Suite | Security testing | Community (Free) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
|
||||||
|
### Phase 0 Success
|
||||||
|
- [ ] Cargo project builds without errors
|
||||||
|
- [ ] All dependencies resolved
|
||||||
|
- [ ] Code quality tools configured and passing
|
||||||
|
|
||||||
|
### Phase 1 Success
|
||||||
|
- [ ] CI/CD pipeline runs on every commit
|
||||||
|
- [ ] Test framework operational with >95% coverage target
|
||||||
|
- [ ] Internal CA operational with test certificates
|
||||||
|
|
||||||
|
### Phase 2 Success
|
||||||
|
- [ ] All 15 API endpoints functional
|
||||||
|
- [ ] mTLS authentication working
|
||||||
|
- [ ] IP whitelist enforced
|
||||||
|
- [ ] WebSocket streaming operational
|
||||||
|
- [ ] Audit logging complete
|
||||||
|
- [ ] Unit test coverage >95%
|
||||||
|
|
||||||
|
### Phase 3 Success
|
||||||
|
- [ ] Penetration testing complete with all critical findings resolved
|
||||||
|
- [ ] Threat model validated
|
||||||
|
- [ ] Security documentation complete
|
||||||
|
|
||||||
|
### Phase 4 Success
|
||||||
|
- [ ] Performance benchmarks met
|
||||||
|
- [ ] Documentation complete
|
||||||
|
- [ ] Package builds (.deb, .rpm) successful
|
||||||
|
- [ ] UAT sign-off received
|
||||||
|
- [ ] v1.0.0 released
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
*Following kiro spec-driven development standards*
|
*Following kiro spec-driven development standards*
|
||||||
|
|||||||
234
SECURITY.md
234
SECURITY.md
@ -1,61 +1,189 @@
|
|||||||
# Linux_Patch_API - Security Specification Document
|
# Linux_Patch_API - Security Specification Document
|
||||||
|
|
||||||
## Security Overview
|
## Security Overview
|
||||||
[Describe security philosophy and approach]
|
|
||||||
|
|
||||||
## Threat Model
|
**Philosophy:** Defense in depth with zero-trust principles for internal network.
|
||||||
### Identified Threats
|
|
||||||
[List potential threats to the system]
|
|
||||||
|
|
||||||
### Attack Vectors
|
**Approach:**
|
||||||
[Describe potential attack vectors]
|
- mTLS certificate-based authentication (required for all connections)
|
||||||
|
- IP whitelist enforcement (deny by default, allow only listed)
|
||||||
## Authentication & Authorization
|
- Comprehensive audit logging for all operations
|
||||||
### Authentication Requirements
|
- Systemd hardening and process isolation
|
||||||
- Method: [TBD]
|
- Minimal attack surface (internal network only)
|
||||||
- Multi-factor: [TBD]
|
|
||||||
- Session Management: [TBD]
|
|
||||||
|
|
||||||
### Authorization Model
|
|
||||||
- RBAC/ABAC: [TBD]
|
|
||||||
- Permission Levels: [TBD]
|
|
||||||
|
|
||||||
## Data Security
|
|
||||||
### Encryption at Rest
|
|
||||||
[Encryption standards for stored data]
|
|
||||||
|
|
||||||
### Encryption in Transit
|
|
||||||
[TLS/SSL requirements]
|
|
||||||
|
|
||||||
### Key Management
|
|
||||||
[Key storage and rotation policies]
|
|
||||||
|
|
||||||
## API Security
|
|
||||||
### Input Validation
|
|
||||||
[Input sanitization requirements]
|
|
||||||
|
|
||||||
### Rate Limiting
|
|
||||||
[DoS prevention measures]
|
|
||||||
|
|
||||||
### CORS Policy
|
|
||||||
[Cross-origin resource sharing rules]
|
|
||||||
|
|
||||||
## Audit & Logging
|
|
||||||
### Security Events to Log
|
|
||||||
[List events requiring audit trails]
|
|
||||||
|
|
||||||
### Log Protection
|
|
||||||
[Log integrity and access controls]
|
|
||||||
|
|
||||||
## Compliance Requirements
|
|
||||||
[Regulatory compliance considerations]
|
|
||||||
|
|
||||||
## Security Testing
|
|
||||||
### Penetration Testing
|
|
||||||
[Testing schedule and scope]
|
|
||||||
|
|
||||||
### Vulnerability Management
|
|
||||||
[Patch and update procedures]
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Threat Model
|
||||||
|
|
||||||
|
### Threat Actor Profile
|
||||||
|
|
||||||
|
| 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 |
|
||||||
|
|
||||||
|
### STRIDE Threat Analysis
|
||||||
|
|
||||||
|
| 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 |
|
||||||
|
|
||||||
|
### Attack Vectors & Mitigations
|
||||||
|
|
||||||
|
| 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 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Authentication & Authorization
|
||||||
|
|
||||||
|
### Authentication Requirements
|
||||||
|
|
||||||
|
- **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)
|
||||||
|
|
||||||
|
### Authorization Model
|
||||||
|
|
||||||
|
- **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
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Following kiro spec-driven development standards*
|
||||||
*Following kiro spec-driven development standards*
|
*Following kiro spec-driven development standards*
|
||||||
|
|||||||
207
SPEC.md
207
SPEC.md
@ -7,19 +7,216 @@
|
|||||||
**Status:** Draft
|
**Status:** Draft
|
||||||
|
|
||||||
## Scope
|
## Scope
|
||||||
[Define project scope here]
|
|
||||||
|
**Primary Focus:** Debian/Ubuntu (apt/dpkg)
|
||||||
|
**Secondary Support:** RHEL/CentOS/Fedora (dnf/yum), Alpine (apk), Arch (pacman)
|
||||||
|
|
||||||
|
**In Scope:**
|
||||||
|
- Remote package installation, removal, and updates
|
||||||
|
- System patch management (security and general updates)
|
||||||
|
- Multi-distribution support via pluggable package manager backend
|
||||||
|
- Secure authentication and authorization for remote operations
|
||||||
|
- Audit logging of all package/patch operations
|
||||||
|
- RESTful API design with JSON request/response
|
||||||
|
|
||||||
|
**Supported Operations:**
|
||||||
|
- **Core Package:** GET /packages (with filtering), GET /packages/{name}, POST /packages (install), PUT /packages/{name} (update), DELETE /packages/{name} (remove)
|
||||||
|
- **Patch Management:** GET /patches (list available), POST /patches/apply (apply all or specific)
|
||||||
|
- **System Info:** GET /system/info (OS version, kernel, last update time)
|
||||||
|
|
||||||
|
**Operation Features:**
|
||||||
|
- Version pinning support (e.g., package=1.2.3)
|
||||||
|
- Rollback capability for failed operations
|
||||||
|
- Batch operations: best-effort (not atomic)
|
||||||
|
- GET filtering: by name, version, status, upgradable
|
||||||
|
- No pagination (return all results)
|
||||||
|
|
||||||
|
**Out of Scope (for now):**
|
||||||
|
- GUI/frontend interface (API-only)
|
||||||
|
- Automatic scheduled patching (manual trigger only)
|
||||||
|
- Cross-distribution package compatibility
|
||||||
|
|
||||||
## Objectives
|
## Objectives
|
||||||
[List primary objectives]
|
|
||||||
|
**Primary Objective:** Provide secure API for remote patch/package management on individual Linux hosts
|
||||||
|
|
||||||
|
**Key Goals:**
|
||||||
|
- Run as systemd service on each managed machine (Option B: Agent Per Host)
|
||||||
|
- Internal network access only (no internet exposure)
|
||||||
|
- Support Debian/Ubuntu first, then expand to other distributions
|
||||||
|
- Maintain audit trail of all operations
|
||||||
|
- Minimal resource footprint
|
||||||
|
- mTLS certificate-based authentication
|
||||||
|
- IP whitelist enforcement (deny by default)
|
||||||
|
|
||||||
## Constraints
|
## Constraints
|
||||||
[List technical and operational constraints]
|
|
||||||
|
**Deployment:**
|
||||||
|
- One API instance per host
|
||||||
|
- Internal network only (LAN/private network)
|
||||||
|
- No public internet exposure
|
||||||
|
- Must run as systemd service
|
||||||
|
|
||||||
|
**Technical:**
|
||||||
|
- Must run with elevated privileges for package management (root/sudo)
|
||||||
|
- Must support multiple Linux distributions
|
||||||
|
- API-only (no GUI required)
|
||||||
|
- mTLS required for all client connections
|
||||||
|
- IP whitelist enforcement required (block all by default, allow only listed)
|
||||||
|
- Technology: Rust with Actix-web or Axum framework
|
||||||
|
- Default API port: 12443
|
||||||
|
- API Style: Pure REST (resources as nouns, HTTP verbs for actions)
|
||||||
|
- Data Format: JSON for all requests and responses
|
||||||
|
- Response Envelope: Standard envelope with success, request_id, timestamp, data, error fields
|
||||||
|
- Request IDs: Required for all requests (tracking and auditing)
|
||||||
|
- Execution Model: Hybrid (sync for quick ops, async with job ID for long ops)
|
||||||
|
- Real-time Updates: WebSocket support for job status streaming
|
||||||
|
- Job Timeout: Maximum 30 minutes per operation
|
||||||
|
|
||||||
|
**Security:**
|
||||||
|
- Certificate-based authentication (mTLS)
|
||||||
|
- Network-level access control via IP/subnet whitelist
|
||||||
|
- Silent drop for non-mTLS connections (no response)
|
||||||
|
- Detailed error messages for authenticated clients only
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
- **HTTP Status Codes:** Standard HTTP status codes (200, 400, 401, 403, 404, 500, etc.)
|
||||||
|
|
||||||
|
- **Error Response Format** (inside envelope's `error` field):
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": "ERROR_CODE",
|
||||||
|
"message": "Human-readable description",
|
||||||
|
"details": {},
|
||||||
|
"retryable": false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- **Error Categories:**
|
||||||
|
- Authentication failures (invalid/expired cert)
|
||||||
|
- Authorization failures (valid cert but not whitelisted IP)
|
||||||
|
- Package not found
|
||||||
|
- Package manager errors (dpkg/apt failures)
|
||||||
|
- Permission denied
|
||||||
|
- System resource errors
|
||||||
|
- Configuration errors
|
||||||
|
|
||||||
|
- **Error Message Policy:**
|
||||||
|
- mTLS confirmed clients: Detailed error messages with debugging info
|
||||||
|
- Non-mTLS connections: Silent drop (no response sent)
|
||||||
|
- DEBUG mode: Include additional diagnostic information
|
||||||
|
|
||||||
|
- **Idempotency:** Operations should be idempotent where possible (safe to retry)
|
||||||
|
|
||||||
## Assumptions
|
## Assumptions
|
||||||
[Document key assumptions]
|
|
||||||
|
- Host machines have network connectivity to internal clients
|
||||||
|
- API clients are trusted internal systems
|
||||||
|
- Host OS has Rust toolchain available (or can be installed)
|
||||||
|
- Package manager (apt/dnf/apk/pacman) is functional on target hosts
|
||||||
|
|
||||||
## Dependencies
|
## Dependencies
|
||||||
[External dependencies and integrations]
|
|
||||||
|
- Linux OS with package manager support
|
||||||
|
- systemd for service management
|
||||||
|
- Network access for API communication
|
||||||
|
- mTLS certificate infrastructure (CA, client certs)
|
||||||
|
- IP whitelist configuration
|
||||||
|
- Rust toolchain (rustc, cargo)
|
||||||
|
- Actix-web or Axum framework
|
||||||
|
- Internal CA for certificate issuance (self-hosted)
|
||||||
|
|
||||||
|
## Certificate Management
|
||||||
|
|
||||||
|
- **CA Type:** Internal self-hosted Certificate Authority
|
||||||
|
- **Distribution:** Manual certificate distribution to clients
|
||||||
|
- **Scope:** Limited distribution (small number of authorized clients)
|
||||||
|
- **Validity Period:** 1 year standard expiration
|
||||||
|
- **Client Identity:** Unique certificate per client (no shared certs)
|
||||||
|
- **Rotation:** Manual renewal process before expiration
|
||||||
|
|
||||||
|
## Audit Logging
|
||||||
|
|
||||||
|
- **Log Content (All Required):**
|
||||||
|
- Every API request (endpoint, method, timestamp, client cert ID)
|
||||||
|
- Package operations (package name, version, action: install/remove/update)
|
||||||
|
- Authentication events (success/failure, cert validation)
|
||||||
|
- IP whitelist denials (blocked connection attempts)
|
||||||
|
- System changes made by the API
|
||||||
|
- Configuration changes (whitelist updates, cert renewals)
|
||||||
|
|
||||||
|
- **Log Storage:**
|
||||||
|
- Primary: systemd journal (`journalctl`)
|
||||||
|
- Secondary: Optional remote syslog server
|
||||||
|
- Local file logs as fallback (`/var/log/linux_patch_api/`)
|
||||||
|
|
||||||
|
- **Log Retention:**
|
||||||
|
- Retention period: 30 days
|
||||||
|
- Rotation: Daily
|
||||||
|
- Compression: Enabled (gzip)
|
||||||
|
|
||||||
|
- **Log Levels:** Configurable at runtime (DEBUG, INFO, WARN, ERROR)
|
||||||
|
|
||||||
|
## IP Whitelist Configuration
|
||||||
|
|
||||||
|
- **Config File:** `/etc/linux_patch_api/whitelist.yaml`
|
||||||
|
- **Format:** YAML
|
||||||
|
- **Management:** Static config file (edit file to change)
|
||||||
|
- **Apply Method:** Instant apply on file change (no restart required)
|
||||||
|
- **Logging:** All whitelist changes logged to audit log
|
||||||
|
|
||||||
|
- **Supported Entries:**
|
||||||
|
- Individual IPv4 addresses (e.g., `192.168.1.100`)
|
||||||
|
- CIDR subnets (e.g., `192.168.1.0/24`)
|
||||||
|
- Hostnames (resolved at config load)
|
||||||
|
- IPv6: Not supported (explicitly out of scope)
|
||||||
|
|
||||||
|
- **Default Behavior:** Block all connections not in whitelist
|
||||||
|
|
||||||
|
## API Configuration Management
|
||||||
|
|
||||||
|
- **Config File:** `/etc/linux_patch_api/config.yaml`
|
||||||
|
- **Format:** YAML
|
||||||
|
- **Reload Method:** Config file watch with auto-reload on change (no restart required)
|
||||||
|
|
||||||
|
- **Configurable Settings:**
|
||||||
|
- **Server:** port, bind address, timeout settings
|
||||||
|
- **mTLS:** CA cert path, server cert path, server key path
|
||||||
|
- **Logging:** log level, log retention, remote syslog server (optional)
|
||||||
|
- **Security:** job timeout, max concurrent jobs, rate limiting
|
||||||
|
|
||||||
|
- **Hard-Coded Paths (not configurable):**
|
||||||
|
- Whitelist file: `/etc/linux_patch_api/whitelist.yaml`
|
||||||
|
- Data directory: `/var/lib/linux_patch_api/`
|
||||||
|
- Job storage: `/var/lib/linux_patch_api/jobs/`
|
||||||
|
- Hard-Coded Paths (not configurable):
|
||||||
|
- Whitelist file: `/etc/linux_patch_api/whitelist.yaml`
|
||||||
|
- Data directory: `/var/lib/linux_patch_api/`
|
||||||
|
- Job storage: `/var/lib/linux_patch_api/jobs/`
|
||||||
|
- Log directory: `/var/log/linux_patch_api/`
|
||||||
|
|
||||||
|
## Testing Requirements
|
||||||
|
|
||||||
|
- **Unit Test Coverage:** Minimum 95%
|
||||||
|
- **Integration Tests:** API endpoint testing with mock package manager
|
||||||
|
- **Security Tests:** mTLS validation, IP whitelist enforcement, authentication failures
|
||||||
|
- **End-to-End Tests:** Full workflow testing on actual Ubuntu systems
|
||||||
|
|
||||||
|
- **Test Environments:**
|
||||||
|
- Primary: Ubuntu (latest LTS)
|
||||||
|
- CI/CD Pipeline: Required for automated testing
|
||||||
|
- Penetration Testing: Required before release
|
||||||
|
|
||||||
|
- **Phase 1 Acceptance Criteria:**
|
||||||
|
- All endpoints functional with mTLS authentication
|
||||||
|
- IP whitelist enforced correctly
|
||||||
|
- Audit logging working (journalctl + file)
|
||||||
|
- Config auto-reload working
|
||||||
|
- WebSocket status streaming functional
|
||||||
|
- Rollback mechanism tested
|
||||||
|
|
||||||
|
- **Security Audit:** No formal audit planned at this time
|
||||||
|
|
||||||
---
|
---
|
||||||
*Following kiro spec-driven development standards*
|
*Following kiro spec-driven development standards*
|
||||||
|
|||||||
Reference in New Issue
Block a user