362 lines
12 KiB
Markdown
362 lines
12 KiB
Markdown
# Project Sentinel: Comprehensive Implementation Plan
|
|
|
|
**Version:** 3.0.0-Enterprise
|
|
**Status:** Ready for Development
|
|
**Total Estimated Effort:** 370k tokens (~$20-30 in API costs)
|
|
**Target Release:** Q2 2026
|
|
|
|
---
|
|
|
|
## Executive Summary
|
|
|
|
Project Sentinel is an active governance layer for Autonomous AI Agents. Unlike passive templates, Sentinel uses a compiled MCP server to physically enforce safety, security, and financial guardrails.
|
|
|
|
**Core Value Proposition:**
|
|
- **Active Enforcement**: Transforms "soft laws" into "hard physics"
|
|
- **Financial Governance**: Token budgeting prevents runaway API costs
|
|
- **Security**: VFS Jail prevents access to .env, ~/.ssh, and other restricted paths
|
|
- **Polyglot Support**: Native toolchains for 12+ programming languages
|
|
|
|
---
|
|
|
|
## Architecture Overview
|
|
|
|
### The Four Pillars
|
|
|
|
1. **Cortex (State Machine)**
|
|
- Finite State Machine: IDLE → PLANNING → ACTIVE → REVIEW → RELEASE
|
|
- One-task-at-a-time enforcement
|
|
- State-based tool availability (deploy only available in RELEASE)
|
|
|
|
2. **Jailor (VFS Security)**
|
|
- Path traversal protection (../../../etc/passwd blocked)
|
|
- Immutable core files (services/sentinel/*, .git/*, .sentinel/*)
|
|
- Read-only file enforcement
|
|
|
|
3. **Interceptor (Audit & PII)**
|
|
- Automatic secret redaction (sk-*, AKIA*, etc.)
|
|
- SQLite audit vault
|
|
- Real-time event streaming via gRPC
|
|
|
|
4. **Polyglot Engine**
|
|
- Auto-detection: go.mod, package.json, Cargo.toml, pom.xml
|
|
- Abstracted commands: run_tests(), build(), lint()
|
|
- Cross-platform execution (Linux/Mac/Windows)
|
|
|
|
---
|
|
|
|
## Implementation Phases
|
|
|
|
### PHASE 1: Kernel Foundation (120k tokens)
|
|
**Duration:** 2-3 weeks
|
|
**Output:** Basic `bin/sentinel` binary with SQLite + VFS Jail
|
|
|
|
#### Sprint 1.1: Boilerplate & Database
|
|
- [ ] **T-101: Project Structure**
|
|
- Initialize Go module: `github.com/TheArchitectit/agent-guardrails-template/services/sentinel`
|
|
- Create directory structure: cmd/, internal/kernel, internal/state, internal/audit
|
|
- Add dependencies: modernc.org/sqlite, mark3labs/mcp-go
|
|
- Create Makefile (build, test, clean)
|
|
- **Acceptance**: `go build` produces binary, runs without panic
|
|
|
|
- [ ] **T-102: SQLite Store & Migrator**
|
|
- Implement `internal/state/store.go`
|
|
- Create tables: schema_version, system_config, sprints, tasks, audit_log
|
|
- Enable WAL mode: `PRAGMA journal_mode=WAL`
|
|
- **Acceptance**: Migrations are idempotent, temp DB test passes
|
|
|
|
- [ ] **T-103: Audit Logger**
|
|
- Implement `internal/audit/logger.go`
|
|
- Add PII scrubbing regex (sk-*, AKIA*, high-entropy tokens)
|
|
- Dual output: Stderr + SQLite
|
|
- **Acceptance**: "sk-1234567890abcdef" → "[REDACTED]" in DB
|
|
|
|
#### Sprint 1.2: VFS Jail (Security Kernel)
|
|
- [ ] **T-104: Path Sanitization**
|
|
- Implement `kernel.ValidatePath(requested, operation)`
|
|
- filepath.Abs + filepath.Clean
|
|
- Prefix check (must start with Root)
|
|
- DenyList regex: .git, .env, id_rsa, services/sentinel
|
|
- **Acceptance**: "../../../etc/passwd" → Error, ".env" → Error
|
|
|
|
- [ ] **T-105: Safe IO Wrappers**
|
|
- Implement `kernel.ReadFile(path) []byte`
|
|
- Implement `kernel.WriteFile(path, data) error`
|
|
- Auto-create directories with MkdirAll
|
|
- Check sentinel.toml for read-only files
|
|
- **Acceptance**: Writing to "foo/bar/baz.txt" creates intermediate dirs
|
|
|
|
#### Sprint 1.3: Basic MCP Server
|
|
- [ ] **T-106: MCP Server Skeleton**
|
|
- Implement `kernel.StartMCP()`
|
|
- Register get_sentinel_status tool
|
|
- Stdio listener for Claude Desktop/Cursor compatibility
|
|
- **Acceptance**: Agent can call `get_sentinel_status` and receive JSON
|
|
|
|
---
|
|
|
|
### PHASE 2: Logic & Tooling (150k tokens)
|
|
**Duration:** 3-4 weeks
|
|
**Prerequisites:** Phase 1 complete
|
|
**Output:** Full-featured MCP server with polyglot support
|
|
|
|
#### Sprint 2.1: Polyglot Toolchain Engine
|
|
- [ ] **T-201: Language Detection**
|
|
- Implement `toolchain.DetectLanguage(root)`
|
|
- Check for: go.mod, package.json (+ lockfiles), Cargo.toml, pom.xml, flake.nix
|
|
- Return Profile struct with TestCmd, BuildCmd, LintCmd
|
|
- **Acceptance**: Running on this repo returns Go profile
|
|
|
|
- [ ] **T-202: Command Abstraction Layer**
|
|
- Implement `toolchain.ExecuteCommand(ctx, cmd)`
|
|
- Windows support via cmd.exe wrapping
|
|
- SanitizeEnv() to strip AWS_SECRET_KEY, GH_TOKEN
|
|
- **Acceptance**: `go version` executes successfully, env vars scrubbed
|
|
|
|
- [ ] **T-203: run_tests Tool**
|
|
- Register run_tests MCP tool
|
|
- Auto-detect language → Get TestCmd → Execute
|
|
- Parse output for "FAIL" patterns
|
|
- **Acceptance**: Broken project returns compiler error in tool output
|
|
|
|
#### Sprint 2.2: Workflow & State Enforcement
|
|
- [ ] **T-204: Sprint & Task CRUD**
|
|
- Implement `kernel.StartSprint(name, goals)`
|
|
- Implement `kernel.AddTask(title, complexity)`
|
|
- DB operations for sprints/tasks tables
|
|
- **Acceptance**: Can create sprint, add 3 tasks, query them back
|
|
|
|
- [ ] **T-205: State Machine Logic**
|
|
- Implement state transitions: IDLE → PLANNING → ACTIVE → REVIEW → RELEASE
|
|
- Block operations based on state (no coding in PLANNING)
|
|
- Enforce "One Task at a Time" rule
|
|
- **Acceptance**: Cannot start second task while first is active
|
|
|
|
- [ ] **T-206: Git Integration**
|
|
- Register git_commit tool with Conventional Commits enforcement
|
|
- Register git_push tool with main-branch protection
|
|
- Pre-commit verification (check recent test results)
|
|
- **Acceptance**: "wip: update" rejected, must use "feat: ..."
|
|
|
|
#### Sprint 2.3: Cost Governance
|
|
- [ ] **T-207: Token Estimator**
|
|
- Implement `cost.EstimateFileRead(path)`
|
|
- Heuristic: 3.5 chars/token for code, 4.0 for text
|
|
- Cost calculation based on OpenAI/Anthropic rates
|
|
- **Acceptance**: Reading 50KB file shows estimated cost
|
|
|
|
- [ ] **T-208: Budget Ledger**
|
|
- Implement `ledger.CheckBudget(cost, sprintID)`
|
|
- Track token usage per sprint
|
|
- Block operations when budget exceeded
|
|
- **Acceptance**: $0.50 budget blocks after $0.50 spent
|
|
|
|
---
|
|
|
|
### PHASE 3: Integration & Release (100k tokens)
|
|
**Duration:** 2-3 weeks
|
|
**Prerequisites:** Phase 2 complete
|
|
**Output:** Enterprise release v3.0.0
|
|
|
|
#### Sprint 3.1: REST API Gateway
|
|
- [ ] **T-301: HTTP Server**
|
|
- Implement `api/gateway.go` using chi router
|
|
- Endpoints: /health, /v1/sprint, /v1/tasks, /v1/audit
|
|
- Auth middleware (Bearer token for non-localhost)
|
|
- **Acceptance**: `curl localhost:8080/v1/status` returns JSON
|
|
|
|
- [ ] **T-302: Policy Check Endpoint**
|
|
- POST /v1/policy/check for CI/CD integration
|
|
- Returns ALLOWED/BLOCKED without writing files
|
|
- VFS check + PII scan
|
|
- **Acceptance**: CI pipeline can validate files before commit
|
|
|
|
#### Sprint 3.2: gRPC Service & Events
|
|
- [ ] **T-303: Event Bus**
|
|
- Implement `api/event_bus.go`
|
|
- Pub/sub for: SECURITY_VIOLATION, TASK_UPDATE, FILE_CHANGE
|
|
- Channel-based subscriptions
|
|
- **Acceptance**: Security event publishes to all subscribers
|
|
|
|
- [ ] **T-304: gRPC Server**
|
|
- Define proto/sentinel.proto (LogStream, ExecuteTool)
|
|
- Implement streaming logs for IDEs
|
|
- mTLS authentication
|
|
- **Acceptance**: JetBrains plugin receives real-time alerts
|
|
|
|
#### Sprint 3.3: Containerization & Deployment
|
|
- [ ] **T-305: Docker Image**
|
|
- Multi-stage Dockerfile (Alpine-based)
|
|
- Entry point: `sentinel serve --mode=remote`
|
|
- **Acceptance**: `docker run sentinel` starts successfully
|
|
|
|
- [ ] **T-306: Remote Mode**
|
|
- CLI flag --host (default 127.0.0.1, remote uses 0.0.0.0)
|
|
- Require SENTINEL_TOKEN in remote mode
|
|
- **Acceptance**: Container fails without token env var
|
|
|
|
#### Sprint 3.4: IDE Integration
|
|
- [ ] **T-307: LSP Diagnostics**
|
|
- Lint errors as IDE diagnostics
|
|
- "Guardrail Violation" severity level
|
|
- **Acceptance**: VS Code shows red underline on blocked file
|
|
|
|
- [ ] **T-308: Installation Scripts**
|
|
- `curl https://releases.project-sentinel.io/install.sh | sh`
|
|
- `sentinel init --root .`
|
|
- **Acceptance**: Single-command install for developers
|
|
|
|
---
|
|
|
|
## Testing Strategy
|
|
|
|
### Unit Tests
|
|
- **Kernel**: State transitions, path validation
|
|
- **Jailor**: Path traversal attacks, PII scrubbing
|
|
- **Toolchain**: Language detection, command execution
|
|
- **Cost**: Token estimation accuracy
|
|
|
|
### Integration Tests
|
|
- **MCP Server**: Tool registration and execution
|
|
- **Database**: Migration idempotency
|
|
- **Git**: Commit/push workflows
|
|
|
|
### Security Tests
|
|
- **Path Traversal**: ../../../etc/passwd, ..\..\..\windows\system32
|
|
- **Secret Leakage**: sk-*, AKIA*, passwords in logs
|
|
- **State Bypass**: Try to deploy in PLANNING state
|
|
|
|
### E2E Tests
|
|
- **Full Sprint**: Create sprint → Add tasks → Complete → Archive
|
|
- **Budget Enforce**: Exceed budget → Verify operations blocked
|
|
- **CI/CD**: Pipeline calls /v1/policy/check
|
|
|
|
---
|
|
|
|
## Success Criteria
|
|
|
|
### Phase 1 Gates
|
|
- [ ] Binary compiles on Linux, Mac, Windows
|
|
- [ ] SQLite migrations are idempotent
|
|
- [ ] Path traversal attacks are blocked
|
|
- [ ] PII is scrubbed from audit logs
|
|
|
|
### Phase 2 Gates
|
|
- [ ] Detects Go, Python, TypeScript, Rust, Java
|
|
- [ ] State machine enforces SDLC phases
|
|
- [ ] Token estimation within 10% margin
|
|
- [ ] Git commits enforce Conventional Commits
|
|
|
|
### Phase 3 Gates
|
|
- [ ] REST API serves all endpoints
|
|
- [ ] gRPC streams events in real-time
|
|
- [ ] Docker image runs in container
|
|
- [ ] IDE receives diagnostics
|
|
|
|
---
|
|
|
|
## Risk Mitigation
|
|
|
|
### Technical Risks
|
|
1. **SQLite Concurrency**
|
|
- Mitigation: WAL mode enabled by default
|
|
- Timeout: 5000ms for busy handler
|
|
|
|
2. **Path Detection Complexity**
|
|
- Mitigation: Start with 5 core languages (Go, Python, TS, Rust, Java)
|
|
- Fallback: Manual sentinel.toml configuration
|
|
|
|
3. **Token Estimation Accuracy**
|
|
- Mitigation: 10% error margin acceptable for guardrails
|
|
- Refinement: Track actual vs. estimated for model improvement
|
|
|
|
### Operational Risks
|
|
1. **Agent Resistance**
|
|
- Mitigation: Transparent error messages explain why blocked
|
|
- Documentation: Clear guides for each guardrail
|
|
|
|
2. **Performance Overhead**
|
|
- Mitigation: Asynchronous logging
|
|
- Measurement: Benchmark <50ms for path validation
|
|
|
|
3. **Language Drift**
|
|
- Mitigation: Modular language profiles (easy to add new ones)
|
|
- Community: Contributions for new languages
|
|
|
|
---
|
|
|
|
## Resource Requirements
|
|
|
|
### Development
|
|
- **Go Expert**: Full-time (40 hrs/week)
|
|
- **DevOps Engineer**: Part-time (10 hrs/week) for Phase 3
|
|
- **Security Reviewer**: On-call for audit
|
|
|
|
### Infrastructure
|
|
- **CI/CD**: GitHub Actions (already configured)
|
|
- **Releases**: GitHub Releases for binaries
|
|
- **Registry**: Docker Hub for container image
|
|
|
|
### Budget
|
|
- **Development API Costs**: ~$30 (370k tokens)
|
|
- **Testing Costs**: ~$20 (E2E test runs)
|
|
- **Total Estimated**: ~$50
|
|
|
|
---
|
|
|
|
## Timeline
|
|
|
|
```
|
|
Phase 1: Week 1-3 (Kernel Foundation)
|
|
├─ Sprint 1.1: Week 1
|
|
├─ Sprint 1.2: Week 2
|
|
└─ Sprint 1.3: Week 3
|
|
|
|
Phase 2: Week 4-7 (Logic & Tooling)
|
|
├─ Sprint 2.1: Week 4-5
|
|
├─ Sprint 2.2: Week 6
|
|
└─ Sprint 2.3: Week 7
|
|
|
|
Phase 3: Week 8-10 (Integration & Release)
|
|
├─ Sprint 3.1: Week 8
|
|
├─ Sprint 3.2: Week 9
|
|
└─ Sprint 3.3-3.4: Week 10
|
|
|
|
Release: Week 11 (v3.0.0-Enterprise)
|
|
```
|
|
|
|
---
|
|
|
|
## Post-Launch Roadmap
|
|
|
|
### v3.1 (Enhanced Languages)
|
|
- PHP, Ruby, Scala, Swift, Kotlin profiles
|
|
- NixOS/flake support enhancement
|
|
- WASM sandboxing option
|
|
|
|
### v3.2 (Cloud Native)
|
|
- Kubernetes operator
|
|
- Multi-agent coordination (swarm mode)
|
|
- Distributed audit log (PostgreSQL)
|
|
|
|
### v4.0 (AI Integration)
|
|
- LLM-hosted mode (Sentinel as an agent)
|
|
- Self-healing capabilities
|
|
- Predictive budgeting
|
|
|
|
---
|
|
|
|
## Compliance & Licensing
|
|
|
|
- **License**: BSD-3-Clause
|
|
- **Compliance**: SOC 2 Type II (target Q3 2026)
|
|
- **Data**: No telemetry sent externally (local-only audit)
|
|
|
|
---
|
|
|
|
## Conclusion
|
|
|
|
Project Sentinel transforms passive guardrails into active enforcement. This 3-phase plan delivers a production-ready system that protects agents from themselves while maintaining developer autonomy.
|
|
|
|
**Next Step:** Execute Sprint 1.1 (T-101: Project Structure)
|