# SECURITY MITIGATION ROADMAP

## Hermes Agent Security Remediation Plan
**Version:** 1.0  
**Date:** March 30, 2026  
**Status:** Draft for Implementation

---

## EXECUTIVE SUMMARY

This roadmap provides a structured approach to addressing the 32 security vulnerabilities identified in the comprehensive security audit. The plan is organized into four phases, prioritizing fixes by risk and impact.

---

## PHASE 1: CRITICAL FIXES (Week 1-2)
**Target:** Eliminate all CVSS 9.0+ vulnerabilities

### 1.1 Remove shell=True Subprocess Calls (V-001)
**Owner:** Security Team Lead  
**Estimated Effort:** 16 hours  
**Priority:** P0

#### Tasks:
- [ ] Audit all subprocess calls in codebase
- [ ] Replace shell=True with argument lists
- [ ] Implement shlex.quote for necessary string interpolation
- [ ] Add input validation wrappers

#### Files to Modify:
- `tools/terminal_tool.py`
- `tools/file_operations.py`
- `tools/environments/docker.py`
- `tools/environments/modal.py`
- `tools/environments/ssh.py`
- `tools/environments/singularity.py`

#### Testing:
- [ ] Unit tests for all command execution paths
- [ ] Fuzzing with malicious inputs
- [ ] Penetration testing

---

### 1.2 Implement Strict Path Sandboxing (V-002)
**Owner:** Security Team Lead  
**Estimated Effort:** 12 hours  
**Priority:** P0

#### Tasks:
- [ ] Create PathValidator class
- [ ] Implement canonical path resolution
- [ ] Add path traversal detection
- [ ] Enforce sandbox root boundaries

#### Implementation:
```python
class PathValidator:
    def __init__(self, sandbox_root: Path):
        self.sandbox_root = sandbox_root.resolve()
    
    def validate(self, user_path: str) -> Path:
        expanded = Path(user_path).expanduser().resolve()
        if not str(expanded).startswith(str(self.sandbox_root)):
            raise SecurityError("Path outside sandbox")
        return expanded
```

#### Files to Modify:
- `tools/file_operations.py`
- `tools/file_tools.py`
- All environment implementations

---

### 1.3 Fix Secret Leakage in Child Processes (V-003)
**Owner:** Security Engineer  
**Estimated Effort:** 8 hours  
**Priority:** P0

#### Tasks:
- [ ] Create environment variable whitelist
- [ ] Implement secret detection patterns
- [ ] Add env var scrubbing for child processes
- [ ] Audit credential file mounting

#### Whitelist Approach:
```python
_ALLOWED_ENV_VARS = frozenset([
    "PATH", "HOME", "USER", "LANG", "LC_ALL",
    "TERM", "SHELL", "PWD", "OLDPWD",
    "PYTHONPATH", "PYTHONHOME", "PYTHONNOUSERSITE",
    "DISPLAY", "XDG_SESSION_TYPE",  # GUI apps
])

def sanitize_environment():
    return {k: v for k, v in os.environ.items() 
            if k in _ALLOWED_ENV_VARS}
```

---

### 1.4 Add Connection-Level URL Validation (V-005)
**Owner:** Security Engineer  
**Estimated Effort:** 8 hours  
**Priority:** P0

#### Tasks:
- [ ] Implement egress proxy option
- [ ] Add connection-level IP validation
- [ ] Validate redirect targets
- [ ] Block private IP ranges at socket level

---

## PHASE 2: HIGH PRIORITY (Week 3-4)
**Target:** Address all CVSS 7.0-8.9 vulnerabilities

### 2.1 Implement Input Validation Framework (V-006, V-007)
**Owner:** Senior Developer  
**Estimated Effort:** 20 hours  
**Priority:** P1

#### Tasks:
- [ ] Create Pydantic models for all tool inputs
- [ ] Implement length validation
- [ ] Add character allowlisting
- [ ] Create validation decorators

---

### 2.2 Fix CORS Configuration (V-008)
**Owner:** Backend Developer  
**Estimated Effort:** 4 hours  
**Priority:** P1

#### Changes:
- Remove wildcard support when credentials enabled
- Implement strict origin validation
- Add origin allowlist configuration

---

### 2.3 Fix Authentication Bypass (V-009)
**Owner:** Backend Developer  
**Estimated Effort:** 4 hours  
**Priority:** P1

#### Changes:
```python
# Fail-closed default
if not self._api_key:
    logger.error("API server requires authentication")
    return web.json_response(
        {"error": "Authentication required"},
        status=401
    )
```

---

### 2.4 Fix OAuth State Validation (V-014)
**Owner:** Security Engineer  
**Estimated Effort:** 6 hours  
**Priority:** P1

#### Tasks:
- Store state parameter in session
- Cryptographically verify callback state
- Implement state expiration

---

### 2.5 Add Rate Limiting (V-016)
**Owner:** Backend Developer  
**Estimated Effort:** 10 hours  
**Priority:** P1

#### Implementation:
- Per-IP rate limiting: 100 requests/minute
- Per-user rate limiting: 1000 requests/hour
- Endpoint-specific limits
- Sliding window algorithm

---

### 2.6 Secure Credential Storage (V-019, V-031)
**Owner:** Security Engineer  
**Estimated Effort:** 12 hours  
**Priority:** P1

#### Tasks:
- Implement OS keychain integration
- Add file encryption at rest
- Implement secure key derivation
- Add access audit logging

---

## PHASE 3: MEDIUM PRIORITY (Month 2)
**Target:** Address CVSS 4.0-6.9 vulnerabilities

### 3.1 Expand Dangerous Command Patterns (V-018)
**Owner:** Security Engineer  
**Estimated Effort:** 6 hours  
**Priority:** P2

#### Add Patterns:
- More encoding variants (base64, hex, unicode)
- Alternative shell syntaxes
- Indirect command execution
- Environment variable abuse

---

### 3.2 Add AST-Based Skill Scanning (V-011)
**Owner:** Security Engineer  
**Estimated Effort:** 16 hours  
**Priority:** P2

#### Implementation:
- Parse Python code to AST
- Detect dangerous function calls
- Analyze import statements
- Check for obfuscation patterns

---

### 3.3 Implement Subagent Isolation (V-024)
**Owner:** Senior Developer  
**Estimated Effort:** 20 hours  
**Priority:** P2

#### Tasks:
- Create isolated filesystem per subagent
- Implement network namespace isolation
- Add resource limits
- Implement subagent-to-subagent communication restrictions

---

### 3.4 Add Comprehensive Audit Logging (V-013, V-020, V-027)
**Owner:** DevOps Engineer  
**Estimated Effort:** 12 hours  
**Priority:** P2

#### Requirements:
- Log all tool invocations
- Log all authentication events
- Log configuration changes
- Implement log integrity protection
- Add SIEM integration hooks

---

## PHASE 4: LONG-TERM IMPROVEMENTS (Month 3+)

### 4.1 Security Headers Hardening (V-028)
**Owner:** Backend Developer  
**Estimated Effort:** 4 hours

Add headers:
- Content-Security-Policy
- Strict-Transport-Security
- X-Frame-Options
- X-XSS-Protection

---

### 4.2 Code Signing Verification (V-026)
**Owner:** Security Engineer  
**Estimated Effort:** 8 hours

- Require GPG signatures for binaries
- Implement signature verification
- Pin trusted signing keys

---

### 4.3 Supply Chain Security
**Owner:** DevOps Engineer  
**Estimated Effort:** 12 hours

- Implement dependency scanning
- Add SLSA compliance
- Use private package registry
- Implement SBOM generation

---

### 4.4 Automated Security Testing
**Owner:** QA Lead  
**Estimated Effort:** 16 hours

- Integrate SAST tools (Semgrep, Bandit)
- Add DAST to CI/CD
- Implement fuzzing
- Add security regression tests

---

## IMPLEMENTATION TRACKING

| Week | Deliverables | Owner | Status |
|------|-------------|-------|--------|
| 1 | P0 Fixes: V-001, V-002 | Security Team | ⏳ Planned |
| 1 | P0 Fixes: V-003, V-005 | Security Team | ⏳ Planned |
| 2 | P0 Testing & Validation | QA Team | ⏳ Planned |
| 3 | P1 Fixes: V-006 through V-010 | Dev Team | ⏳ Planned |
| 3 | P1 Fixes: V-014, V-016 | Dev Team | ⏳ Planned |
| 4 | P1 Testing & Documentation | QA/Doc Team | ⏳ Planned |
| 5-8 | P2 Fixes Implementation | Dev Team | ⏳ Planned |
| 9-12 | P3/P4 Long-term Improvements | All Teams | ⏳ Planned |

---

## SUCCESS METRICS

### Security Metrics
- [ ] Zero CVSS 9.0+ vulnerabilities
- [ ] < 5 CVSS 7.0-8.9 vulnerabilities
- [ ] 100% of subprocess calls without shell=True
- [ ] 100% path validation coverage
- [ ] 100% input validation on tool entry points

### Compliance Metrics
- [ ] OWASP Top 10 compliance
- [ ] CWE coverage > 90%
- [ ] Security test coverage > 80%

---

## RISK ACCEPTANCE

| Vulnerability | Risk | Justification | Approver |
|--------------|------|---------------|----------|
| V-029 (Version Info) | Low | Required for debugging | TBD |
| V-030 (Dead Code) | Low | Cleanup in next refactor | TBD |

---

## APPENDIX: TOOLS AND RESOURCES

### Recommended Security Tools
1. **SAST:** Semgrep, Bandit, Pylint-security
2. **DAST:** OWASP ZAP, Burp Suite
3. **Dependency:** Safety, Snyk, Dependabot
4. **Secrets:** GitLeaks, TruffleHog
5. **Fuzzing:** Atheris, Hypothesis

### Training Resources
- OWASP Top 10 for Python
- Secure Coding in Python (SANS)
- AWS Security Best Practices

---

**Document Owner:** Security Team  
**Review Cycle:** Monthly during remediation, Quarterly post-completion