# Reference Documentation Index

## The Iron Vault - Aperion FSAL

This directory contains reference documentation, security research, and
integration guidance for the Iron Vault filesystem sandbox service.

---

## Documents

### [GAP_ANALYSIS.md](./GAP_ANALYSIS.md)
Comprehensive analysis of security gaps and improvement opportunities.

**Sections:**
- 🔴 Critical Gaps (5 items) - Security vulnerabilities requiring immediate attention
- 🟠 High Priority Gaps (5 items) - Production hardening requirements
- 🟡 Medium Priority Gaps (5 items) - Robustness improvements
- 🟢 Nice-to-have (5 items) - Future enhancements

**Key Finding:** Missing directory fsync after atomic rename could cause data loss.

---

### [SECURITY_BEST_PRACTICES.md](./SECURITY_BEST_PRACTICES.md)
Curated security guidance from authoritative sources.

**Topics Covered:**
- Path traversal prevention (OWASP, PortSwigger)
- Atomic file operations (python-atomicwrites)
- TOCTOU race conditions (CWE-367)
- FastAPI security patterns
- Production deployment hardening
- Token security

---

### [INTEGRATION_GUIDE.md](./INTEGRATION_GUIDE.md)
Guide for integrating Iron Vault with the Aperion Legendary AI system.

**Topics Covered:**
- API compatibility verification
- Deployment topology options (sidecar vs. separate service)
- Authentication integration patterns
- EventBus integration for audit
- CLI/TUI integration
- Migration checklist

---

### [IMPLEMENTATION_ROADMAP.md](./IMPLEMENTATION_ROADMAP.md)
Phased implementation plan with code samples.

**Phases:**
1. Critical Security Fixes (1-2 days)
2. Production Hardening (2-3 days)
3. Observability (1-2 days)
4. Robustness (2-3 days)
5. Enhancements (Future)

---

### [KNOWN_ISSUES.md](./KNOWN_ISSUES.md)
Tracked bugs, edge cases, and limitations.

**Categories:**
- 🔴 Confirmed Bugs
- 🟠 Edge Cases
- 🟡 Limitations
- 🟢 Fixed Issues

---

## Quick Links by Topic

### Security
- [Critical security gaps](./GAP_ANALYSIS.md#-critical-gaps-security)
- [TOCTOU race conditions](./SECURITY_BEST_PRACTICES.md#3-toctou-race-conditions)
- [Path traversal attacks tested](../tests/security/test_traversal.py)

### Production Deployment
- [Docker hardening](./GAP_ANALYSIS.md#8-dockerfile-should-use-gunicorn)
- [FastAPI security](./SECURITY_BEST_PRACTICES.md#4-fastapi-security)
- [Deployment topology](./INTEGRATION_GUIDE.md#2-deployment-topology-options)

### Integration with Aperion
- [API compatibility](./INTEGRATION_GUIDE.md#1-api-compatibility)
- [EventBus integration](./INTEGRATION_GUIDE.md#4-event-bus-integration)
- [CLI integration](./INTEGRATION_GUIDE.md#5-cli-integration)

---

## External References

| Resource | URL |
|----------|-----|
| OWASP Path Traversal | https://owasp.org/www-community/attacks/Path_Traversal |
| FastAPI Security | https://fastapi.tiangolo.com/tutorial/security/ |
| python-atomicwrites | https://python-atomicwrites.readthedocs.io/ |
| CWE-367 TOCTOU | https://cwe.mitre.org/data/definitions/367.html |
| Docker Security | https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html |

---

*Last updated: 2026-02-08*
