Project Plan: CODITECT Agent Security Layer

Document ID: PLAN-CODITECT-SEC-001 Version: 1.0.0 Created: 2026-02-18 Status: CONDITIONAL GO — Pending Sprint 1 kickoff approval Track: D (Security) Category: R&D (Development)

---

Table of Contents

1. Executive Summary
2. Vision and Strategic Context
3. Scope and Boundaries
4. Architecture Overview
5. Implementation Roadmap
6. Success Metrics
7. Risk Assessment
8. Team Requirements
9. Dependencies
10. Compliance Alignment
11. Research Pipeline Reference
12. Appendix: Pattern Library Summary

---

1. Executive Summary

1.1 Decision

CONDITIONAL GO — Build CODITECT-native AI Agent Security Layer using patterns and architecture from the ClawGuard open-source ecosystem.

Do not pull any ClawGuard repository as a runtime dependency. Build from validated design inputs.

1.2 The Problem

CODITECT orchestrates 776 AI agents executing hundreds of tool calls per session across multi-tenant environments. None of CODITECT's 118 hooks currently perform security evaluation. This is not a theoretical risk — during the research evaluation phase that produced this plan, one of five repositories examined was a live, trojanized fork (lauty1505/clawguard) containing an injected binary payload designed to social-engineer downloads. The attack vector this layer is designed to prevent is actively being used against the security tooling ecosystem itself.

Current exposure surface per agent session:

• Prompt injection via document content, tool results, or API responses overriding agent behavior
• Secret exfiltration — API keys, JWT tokens, cloud credentials — persisting in session logs unredacted
• Destructive command execution (rm -rf, DROP TABLE, git reset --hard) requiring no special privileges
• PII flowing unredacted through tool pipelines to external endpoints or log storage
• Lateral movement across tenant boundaries through shared session state

1.3 The Solution

A hook-based, inline security subsystem integrated into CODITECT's existing 118-hook framework. The system intercepts every tool call before execution, evaluates it against a unified pattern library derived from three validated open-source sources, and enforces one of five actions: BLOCK, REDACT, CONFIRM, WARN, or LOG.

Six components form the complete system:

Component	Role
SecurityGateHook	Intercepts all tool calls at the CODITECT dispatch boundary
PatternEngine	Evaluates 80+ threat patterns from three research sources
RiskAnalyzer	Aggregates pattern matches into a 0-100 numeric risk score
ActionRouter	Maps risk score + tenant policy to concrete enforcement decisions
MonitorDashboard	Real-time session security visibility with WebSocket streaming
AuditLogger	Compliance-grade event persistence to org.db

1.4 Technology Stack

Layer	Technology
Hook runtime	Python 3.11+ (CODITECT hook system is Python-native)
Pattern storage	YAML rule files + SQLite (org.db)
Dashboard backend	FastAPI + WebSocket
Dashboard frontend	React + TypeScript
Rule validation	Pydantic v2 models

1.5 Timeline at a Glance

Phase	Sprints	Scope	Milestone
Phase 1	Sprint 1-2	SecurityGateHook + PatternEngine core	PreToolUse gate operational
Phase 2	Sprint 3-4	Full pattern library + PostToolUse hook + REDACT	Output scanning live
Phase 3	Sprint 5-6	MonitorDashboard + AlertDispatcher	Live monitoring dashboard
Phase 4	Sprint 7-8	Multi-tenant + CODITECT platform integration	Production-ready

Total estimated engineering effort: 16 weeks (8 two-week sprints) Core LOC estimate: ~3,200 Python + ~2,000 TypeScript (dashboard)

---

2. Vision and Strategic Context

2.1 Vision Statement

Every tool call executed by a CODITECT AI agent passes through a security gate that detects, evaluates, and enforces against the full range of AI agent threat vectors — before any side effect occurs — with complete audit traceability and zero impact on legitimate operations.

2.2 Strategic Drivers

March 11, 2026 Public Launch CODITECT launches publicly with 776 agents and multi-tenant infrastructure. Operating a 776-agent platform without any security interception layer is not an acceptable posture for an enterprise product.

Multi-Tenant Enterprise Sales Enterprise customers require documented security controls as a prerequisite for procurement. SOC 2 Type II preparation depends on having a demonstrable monitoring and audit trail capability.

Ralph Wiggum Autonomous Loops CODITECT's autonomous agent loops (ADR-108/110/111) run for extended periods without human checkpoints. These loops represent the highest-risk surface in the platform — an autonomous agent executing hundreds of tool calls without security gates is a material operational risk.

Research Validation The ClawGuard ecosystem analysis (research pipeline artifacts in docs/original-research/) confirmed that the architectural patterns needed already exist in open-source form, are MIT-licensed, and map directly onto CODITECT's existing hook infrastructure. Build cost is validation-reduced compared to a greenfield design.

2.3 Why Now

The PreToolUse hook point is the correct interception position and it already exists in CODITECT's infrastructure. The governance hooks (task_id_validator.py, task-tracking-enforcer.py) demonstrate that hooks can conditionally block tool execution — the security gap is not architectural, it is the absence of security-specific pattern evaluation within those hooks. The foundation is present; the security layer is the next layer to build on it.

---

3. Scope and Boundaries

3.1 In Scope

• Pre-execution interception of all PreToolUse events (every tool call)
• Post-execution interception of PostToolUse events for output secret/PII redaction
• Agent session startup security via PreAgentStart hook (system prompt injection detection)
• Per-tenant rule configuration with layered override model (platform base → tenant custom)
• Real-time monitoring dashboard with WebSocket event streaming
• Webhook alerting to Discord, Slack, and PagerDuty
• Emergency kill switch (admin + MFA gated) for tenant session termination
• Compliance-grade audit log in org.db with configurable retention policies
• Pattern library covering: prompt injection, secret detection, PII filtering, destructive commands, sensitive path access

3.2 Out of Scope

• Authentication and authorization (handled by existing CODITECT RBAC layer)
• Network egress filtering (handled at infrastructure layer)
• LLM model prompt safety (handled by Anthropic/LLM providers)
• Email pipeline sanitization (maxxie114 ClawGuard scope — not applicable to CODITECT)
• Agent-to-agent message integrity validation (requires separate architecture decision)
• Context database tamper detection (requires separate security design)
• LLM-based prompt injection detection using a classification model (future iteration)

3.3 Architecture Decision Record References

This project is informed by and will produce ADRs for:

• Hook registration priority ordering (SecurityGateHook must execute first in PreToolUse chain)
• security.db vs org.db audit log placement (SDD recommends org.db extension — irreplaceable)
• Fail-closed vs fail-open default behavior (SDD mandates fail-closed)
• Per-tenant rule layering model (platform non-overridable → tenant overridable)

---

4. Architecture Overview

4.1 System Position (C1 Context)

The security layer sits between the CODITECT Agent Dispatch Layer and the Tool Execution Layer. Every AI agent tool call passes through it synchronously before any side effect occurs.

4.2 Component Interaction (C2 Container)

4.3 Security Enforcement Flow

The critical enforcement path for a PreToolUse event:

4.4 Risk Scoring Model

The scoring algorithm combines maxxie114's additive aggregation with JaydenBeard's severity tier model:

Base score per match:
  CRITICAL  = 80 points
  HIGH      = 40 points
  MEDIUM    = 20 points
  LOW       =  5 points
  INFO      =  1 point

Aggregation:
  raw_score = sum(base_score for each match)
  final_score = min(100, raw_score)

Severity category thresholds:
  90-100  CRITICAL  → BLOCK (non-overridable)
  70-89   HIGH      → BLOCK or REDACT (tenant-overridable)
  40-69   MEDIUM    → CONFIRM or WARN (tenant-overridable)
  10-39   LOW       → WARN or LOG (tenant-overridable)
  0-9     INFO      → LOG (tenant-overridable)

Special rules:
  Any single CRITICAL match → minimum score 80
  Prompt injection + secret detection co-occurrence → +15 bonus points
  Tool in tenant allowlist → -20 discount

4.5 File Structure

hooks/
└── security-gate/
    ├── security_gate_hook.py       # SecurityGateHook — hook entry point
    ├── pattern_engine.py           # PatternEngine — rule loading + regex evaluation
    ├── risk_analyzer.py            # RiskAnalyzer — scoring algorithm
    ├── action_router.py            # ActionRouter — severity-to-action mapping
    ├── audit_logger.py             # AuditLogger — org.db writer
    ├── models.py                   # Pydantic models (all shared types)
    ├── config.py                   # SecurityGateConfig + TenantSecurityConfig
    ├── redactor.py                 # Text redaction utilities
    ├── circuit_breaker.py          # CircuitBreaker (5 failures → OPEN state)
    ├── rules/
    │   ├── prompt-injection.yaml   # 10 rules (PI-001 to PI-010)
    │   ├── secret-detection.yaml   # 13 rules (SD-001 to SD-013)
    │   ├── pii-detection.yaml      # 5 rules (PII-001 to PII-005)
    │   ├── destructive-commands.yaml # 55+ rules (DC-001+)
    │   └── path-traversal.yaml     # 30+ rules (PT-001+)
    ├── security-gate.manifest.json
    └── tests/
        ├── test_pattern_engine.py
        ├── test_risk_analyzer.py
        ├── test_action_router.py
        ├── test_audit_logger.py
        ├── test_security_gate_hook.py
        ├── test_integration.py
        └── fixtures/

submodules/dev/coditect-dev-agent-security/
└── dashboard/
    ├── server.py                   # FastAPI dashboard server
    ├── routes/
    │   ├── sessions.py
    │   ├── events.py
    │   ├── gateway.py              # Kill switch endpoint
    │   ├── streaming.py            # WebSocket handler
    │   └── export.py               # Compliance export
    ├── event_bus.py
    ├── alert_dispatcher.py
    └── frontend/                   # React TypeScript UI
        └── src/
            ├── components/
            │   ├── LiveFeed.tsx
            │   ├── SessionMap.tsx
            │   ├── AlertCenter.tsx
            │   └── SystemHealth.tsx
            └── hooks/
                └── useSecurityStream.ts

---

5. Implementation Roadmap

Phase 1 — SecurityGateHook + Core Pattern Engine (Sprints 1-2)

Duration: 4 weeks (2 sprints) Goal: Inline PreToolUse security gate operational. All critical and high severity patterns blocking. Audit log writing.

Sprint 1 — Foundation (Weeks 1-2)

Task	Description	Assignee	Effort
1.1	Create hooks/security-gate/ directory structure and Pydantic models	security-specialist	1 day
1.2	Implement PatternEngine with YAML rule loader and compiled regex cache	security-specialist	3 days
1.3	Author prompt injection rules (PI-001 to PI-010) — port from maxxie114 and ClawGuardian	security-specialist	2 days
1.4	Author secret detection rules (SD-001 to SD-013) — port from ClawGuardian patterns/api-keys.ts, cloud-credentials.ts, tokens.ts	security-specialist	2 days
1.5	Implement RiskAnalyzer scoring algorithm with co-occurrence bonuses	security-specialist	1 day
1.6	Implement ActionRouter with BLOCK, WARN, LOG actions and tenant config overrides	security-specialist	1 day

Sprint 1 Deliverable: PatternEngine scans payloads and produces correct matches; RiskAnalyzer scores deterministically; ActionRouter dispatches correctly.

Sprint 2 — Hook Integration + Audit (Weeks 3-4)

Task	Description	Assignee	Effort
2.1	Implement SecurityGateHook — PreToolUse handler with 500ms timeout and fail-closed behavior	security-specialist	2 days
2.2	Implement AuditLogger with org.db schema migration (4 new tables)	database-architect	2 days
2.3	Register hook in security-gate.manifest.json and verify CODITECT hook dispatch integration	devops-engineer	1 day
2.4	Author destructive command rules (DC-001 to DC-012 critical/high) — port from ClawGuardian destructive/detector.ts	security-specialist	2 days
2.5	Implement CircuitBreaker (5 consecutive failures → OPEN, 30s cooldown)	senior-architect	1 day
2.6	Unit tests for all Phase 1 components — target 90% coverage	testing-specialist	2 days

Phase 1 Acceptance Criteria:

• All PreToolUse tool calls scanned before execution
• BLOCK decisions enforced; error returned to Agent Orchestrator
• SCAN_FAILED and TOOL_BLOCKED events written to org.db within 100ms
• Scan latency p50 < 20ms, p99 < 80ms on 64KB payload
• Fail-closed: scan exception produces BLOCK, not ALLOW
• CRITICAL severity cannot be downgraded by tenant config

---

Phase 2 — Full Pattern Library + PostToolUse Hook (Sprints 3-4)

Duration: 4 weeks (2 sprints) Goal: Complete 80+ pattern library active. Output scanning with REDACT action. PII filtering. Human CONFIRM flow.

Sprint 3 — Pattern Completion + Output Scanning (Weeks 5-6)

Task	Description	Assignee	Effort
3.1	Author remaining destructive command rules (DC-013 to DC-055+) — port all 55+ patterns from JaydenBeard lib/risk-analyzer.js	security-specialist	3 days
3.2	Author sensitive path traversal rules (PT-001 to PT-030+) — port from JaydenBeard's 30+ path patterns (.ssh, .aws, .kube, .env, password managers)	security-specialist	2 days
3.3	Author PII detection rules (PII-001 to PII-005) — port from ClawGuardian patterns/pii.ts (phone via phonenumbers Python library)	security-specialist	2 days
3.4	Implement PostToolUse hook handler in SecurityGateHook — output redaction flow	security-specialist	2 days
3.5	Implement REDACT action in ActionRouter with field-level redaction via [REDACTED:<rule_id>] substitution	security-specialist	1 day

Sprint 3 Deliverable: 80+ patterns active across all 5 categories; secrets and PII in tool outputs redacted before return to agent context window.

Sprint 4 — CONFIRM Flow + Pattern Validation (Weeks 7-8)

Task	Description	Assignee	Effort
4.1	Implement CONFIRM action — suspension mechanism, 30-second timeout escalation to BLOCK	senior-architect	2 days
4.2	Wire CONFIRM into CODITECT dispatch layer — surface confirmation dialog to operator	senior-architect	2 days
4.3	Author PreAgentStart hook handler — system prompt injection detection	security-specialist	1 day
4.4	Pattern validation dry run against real CODITECT session log samples — measure FP/FN rates before block mode activation	testing-specialist	2 days
4.5	Tune pattern sensitivity based on validation results — adjust severity levels to keep FP rate < 1%	security-specialist	2 days
4.6	Integration tests — end-to-end flow from hook event to audit record	testing-specialist	1 day

Phase 2 Acceptance Criteria:

• Output scan redacts secrets from tool results before returning to agent
• CONFIRM pauses tool execution; 30s timeout escalates to BLOCK
• 80+ patterns validated against CODITECT session samples — FP rate < 1% on CRITICAL/HIGH
• TOOL_REDACTED events include redacted_fields list (not values) in audit record
• System prompt injection detection blocks agent initialization on CRITICAL match

---

Phase 3 — MonitorDashboard + Alerting (Sprints 5-6)

Duration: 4 weeks (2 sprints) Goal: Real-time security visibility operational. Webhook alerting to Slack/PagerDuty. Kill switch functional.

Sprint 5 — Dashboard Backend + Event Bus (Weeks 9-10)

Task	Description	Assignee	Effort
5.1	Implement EventStreamBus — in-memory pub/sub connecting AuditLogger to dashboard consumers	senior-architect	2 days
5.2	Implement DashboardServer — FastAPI application with 6 REST routes + WebSocket endpoint	backend-developer	3 days
5.3	Implement AlertDispatcher — webhook delivery to Slack, Discord, PagerDuty with 3-retry exponential backoff	devops-engineer	2 days
5.4	Implement kill switch endpoint — POST /api/v1/security/gateway/{tenant_id}/kill with MFA gate	security-specialist	2 days
5.5	Implement compliance export endpoint — NDJSON/CSV for 30-day audit data ranges	backend-developer	1 day

Sprint 5 Deliverable: Dashboard API serving live security events via WebSocket; alerts dispatching to configured webhook endpoints within 30 seconds of event.

Sprint 6 — Dashboard Frontend + Operations (Weeks 11-12)

Task	Description	Assignee	Effort
6.1	Build React TypeScript dashboard — LiveFeed, SessionMap, AlertCenter, SystemHealth widgets	frontend-react-typescript-expert	4 days
6.2	Implement useSecurityStream hook — WebSocket connection with auto-reconnect	frontend-react-typescript-expert	1 day
6.3	Implement nightly pattern effectiveness aggregation job (pattern_effectiveness table)	backend-developer	1 day
6.4	LaunchAgent / systemd service registration for dashboard process	devops-engineer	1 day
6.5	Load test — 50 concurrent scans, 100 WebSocket connections, kill switch SLA	testing-specialist	2 days
6.6	Alert deduplication and rate limiting (max 10 webhooks per minute per tenant)	senior-architect	1 day

Phase 3 Acceptance Criteria:

• WebSocket events delivered to connected dashboard clients within 200ms of security event
• Dashboard handles 100 concurrent WebSocket connections without degradation
• Webhook delivery retried up to 3 times with exponential backoff
• Kill switch terminates all tenant sessions within 5 seconds of invocation
• Load test: scan latency p99 < 50ms under 50 concurrent sessions

---

Phase 4 — Multi-Tenant + CODITECT Platform Integration (Sprints 7-8)

Duration: 4 weeks (2 sprints) Goal: Production-ready multi-tenant security layer. Full CODITECT platform integration. Compliance documentation.

Sprint 7 — Multi-Tenant Policy + Admin UI (Weeks 13-14)

Task	Description	Assignee	Effort
7.1	Implement layered rule configuration — Layer 0 (non-overridable), Layer 1 (tenant-overridable), Layer 2 (tenant-custom)	senior-architect	3 days
7.2	Implement per-tenant rule cache with 60-second TTL and hot-reload	senior-architect	2 days
7.3	Build tenant admin UI for security config — action overrides, allowlists, webhook configuration	frontend-react-typescript-expert	3 days
7.4	Implement tenant_security_configs table operations — CRUD API with audit trail	backend-developer	2 days

Sprint 7 Deliverable: Each tenant has isolated security configuration; platform CRITICAL rules cannot be overridden; tenant-specific allowlists reduce false positives for legitimate tool use patterns.

Sprint 8 — Platform Integration + Compliance Documentation (Weeks 15-16)

Task	Description	Assignee	Effort
8.1	Integrate security.db / audit events into CODITECT session log pipeline	senior-architect	2 days
8.2	Extend ~/.coditect/scripts/backup-context-db.sh to include security audit data	devops-engineer	1 day
8.3	Wire security events into sessions.db cross-reference table for trajectory dashboard	backend-developer	2 days
8.4	Write ADRs: SecurityGateHook registration, audit log placement, fail-closed default, tenant rule layering	codi-documentation-writer	2 days
8.5	Write operational runbook — circuit breaker response, audit DB recovery, high block rate triage	codi-documentation-writer	1 day
8.6	Final security review — penetration test of security layer itself (bypass attempt)	security-specialist	2 days

Phase 4 Acceptance Criteria:

• Multi-tenant: zero cross-tenant rule bleed in integration tests
• All CODITECT databases backed up including security audit data
• ADRs approved by architecture team
• Operational runbook reviewed by DevOps
• Security layer itself survives bypass attempt testing (encoding evasion, timing, exception injection)

---

6. Success Metrics

6.1 Functional Metrics (Must achieve before production)

Metric	Target	Measurement Method
Security gate coverage	100% of PreToolUse events intercepted	Integration test verifying zero unscanned tool calls
CRITICAL block enforcement	100% — no tenant override possible	Automated test: attempt CRITICAL override, verify BLOCK
Audit completeness	100% of PreToolUse events produce AuditEvent	DB record count vs hook invocation count
Output redaction coverage	100% of secrets matched in PostToolUse scan are redacted	Pattern fixture test with known secret payloads
System prompt injection detection	CRITICAL matches block agent init	Integration test: inject PI-001 in system prompt

6.2 Performance Metrics

Metric	Target	Acceptable Maximum
Scan latency p50	< 20ms	100ms
Scan latency p99	< 50ms	500ms (hook timeout)
Audit write latency (BLOCK/REDACT)	< 50ms p99	100ms
WebSocket event delivery	< 200ms	500ms
Kill switch session termination	< 5 seconds	10 seconds
Dashboard connection capacity	100 concurrent WebSocket clients	—

6.3 Quality Metrics

Metric	Target	Method
False positive rate (CRITICAL/HIGH)	< 1%	Pattern validation against CODITECT session log sample
False positive rate (overall)	< 5%	Same validation dataset
Test coverage (all components)	> 90%	pytest coverage report
Pattern match correctness	100% of fixtures match expected rules	Parameterized test suite against rule fixtures
No sensitive data in log streams	0 violations	Log scrub audit — verify only rule_ids in logs, not matched text

6.4 Compliance Metrics

Metric	Target
TOOL_BLOCKED retention	1 year minimum in org.db
KILL_SWITCH_ACTIVATED retention	5 years in org.db
Audit export availability	30 days of data in NDJSON format
SOC 2 CC7.2 evidence	MonitorDashboard + AuditLogger produce complete event trail
Zero sensitive data in application logs	Verified by automated log scan

---

7. Risk Assessment

7.1 Risk Matrix

Risk	Probability	Impact	Severity	Mitigation
Pattern false positives blocking legitimate operations	HIGH	HIGH	CRITICAL	Phase 2 pattern validation against real session logs before block mode activation; start in WARN-only then promote to BLOCK
Scan latency degrading agent performance	MEDIUM	HIGH	HIGH	500ms timeout with fail-closed behavior; compiled regex cache; daemon process with Unix socket IPC to avoid cold start
org.db write failures halting agent operations	LOW	CRITICAL	HIGH	Write-through queue with dedicated writer thread; fail-closed when audit unavailable (no tool calls permitted)
Pattern library staleness	HIGH	MEDIUM	HIGH	Defined quarterly review process; versioned YAML files in git with PR-gated updates; pattern effectiveness nightly job surfaces stale patterns
Supply chain risk from research repo code	MEDIUM	HIGH	HIGH	All three repos are MIT; patterns/algorithms ported to Python (not imported); code review gate before any pattern enters production
Multi-tenant rule bleed	LOW	CRITICAL	HIGH	Integration tests verify tenant isolation on every PR; rule cache keyed by tenant_id; all queries enforce tenant_id
Kill switch abuse (unauthorized termination)	LOW	HIGH	MEDIUM	MFA gate + admin role required; every invocation logged in kill_switch_events (5-year retention); cannot affect other tenants
Circuit breaker cascading to complete agent blockout	LOW	HIGH	MEDIUM	30-second cooldown; HALF-OPEN probe before full recovery; on-call alert within 60 seconds of OPEN state
Regex-only detection bypassable via encoding evasion	MEDIUM	MEDIUM	MEDIUM	PI-009 encoding evasion pattern; document limitation; LLM-based classification as Phase 5 follow-on
Dashboard process crash creating visibility gap	LOW	LOW	LOW	Process supervisor auto-restart; enforcement continues independent of dashboard health

7.2 Critical Risk: False Positives

The highest operational risk is deploying block-mode patterns that generate false positives against legitimate CODITECT agent operations. This is addressed as an explicit Phase 2 gate:

1. All patterns start in WARN or LOG mode (non-blocking)
2. Pattern validation dry run against 30 days of real session logs before block activation
3. Decision gate: no pattern enters BLOCK mode with measured FP rate > 1% without explicit sign-off
4. Tenant allowlist mechanism available for legitimate use patterns that trigger rules (e.g., DevOps tenant using sudo legitimately)

7.3 Architecture Risk: Fail-Closed Default

The fail-closed default (fail_mode = "closed") means any unhandled scan exception blocks tool execution. This is the correct security posture but has operational consequences:

• org.db unavailability halts all tool calls (by design — no tool calls permitted without audit trail)
• Circuit breaker OPEN state blocks all tool calls during 30-second cooldown

Mitigations:

• PagerDuty alert on circuit breaker OPEN within 60 seconds
• org.db backup and recovery procedures in operational runbook
• fail_mode = "open" available as admin-only override for debugging (produces WARN not block, but logs SCAN_FAILED with circuit_open=true)

---

8. Team Requirements

8.1 Core Team

Role	Phase 1	Phase 2	Phase 3	Phase 4	Total Sprints
security-specialist (lead)	Full	Full	Partial	Partial	8
senior-architect	Partial	Full	Partial	Full	8
testing-specialist	Partial	Full	Partial	—	5
database-architect	Partial	—	—	Partial	2
devops-engineer	Partial	—	Partial	Partial	3
backend-developer	—	—	Full	Full	4
frontend-react-typescript-expert	—	—	Full	Partial	3
codi-documentation-writer	—	—	—	Full	2

8.2 External Dependencies on CODITECT Teams

Dependency	Owner Team	Required By
CODITECT hook dispatch review — confirm PreToolUse priority ordering	Platform Team	Sprint 1
org.db schema migration approval	Database Team	Sprint 2
CONFIRM flow integration into UI	Frontend Team	Sprint 4
Dashboard process service registration	DevOps Team	Sprint 6
ADR review and approval	Architecture Team	Sprint 8

---

9. Dependencies

9.1 CODITECT Infrastructure Dependencies

Asset	Version Required	Usage	Path
CODITECT hook system	core >= 3.3.0	SecurityGateHook registration via manifest	hooks/
org.db (SQLite)	ADR-118 schema	AuditLogger writes to 4 new tables	~/.coditect-data/context-storage/org.db
sessions.db (SQLite)	ADR-118 schema	SessionTracker reads session metadata	~/.coditect-data/context-storage/sessions.db
Python venv	3.11+	PatternEngine, RiskAnalyzer, AuditLogger	~/.coditect/.venv/
CODITECT RBAC layer	Existing	Dashboard API JWT validation	Existing auth layer
Backup script	Existing	Security audit data included in backups	~/.coditect/scripts/backup-context-db.sh
CODITECT metrics pipeline	Existing	Security metrics via existing collectors	Existing metrics infrastructure

9.2 Python Package Dependencies (New)

Package	Version	Purpose
pydantic	>= 2.0.0	Rule model validation, config models
phonenumbers	>= 8.13.0	PII phone number detection (ClawGuardian PII equivalent)
watchdog	>= 4.0.0	Session log file watching (chokidar Python equivalent)
fastapi	>= 0.115.0	MonitorDashboard API server
websockets	>= 12.0	WebSocket streaming for dashboard
uvicorn	>= 0.27.0	FastAPI ASGI server
httpx	>= 0.27.0	Webhook delivery with retry logic

9.3 Open-Source Research Dependencies (Pattern Extraction Only — Not Runtime)

Repository	License	Usage	Note
ClawGuardian (superglue-ai)	MIT	Hook architecture pattern + PII/cloud credential patterns	Port to Python YAML — not imported as npm
clawguard (JaydenBeard)	MIT	55+ destructive command patterns + severity model + dashboard architecture	Port to Python — not imported
ClawGuard (maxxie114)	MIT	Prompt injection patterns (10) + risk scoring algorithm	Port to Python — not imported

Security Note: lauty1505/clawguard is MALWARE (trojanized fork, Software-tannin.zip binary). Never clone, never reference. yourclaw/clawguard has no functional code. Neither is used in any capacity.

9.4 Infrastructure Prerequisites

Prerequisite	Status	Action Required
org.db schema extension (4 new tables)	Not started	Sprint 2 migration script
Hook priority ordering documentation	Gap	ADR required Sprint 1
Dashboard process supervision config	Not started	Sprint 6
Backup script extension	Not started	Sprint 8
PagerDuty integration (security alerts)	Existing	Configure alert routing Sprint 5

---

10. Compliance Alignment

10.1 OWASP LLM Top 10 Coverage

OWASP Control	Implementation	Component
LLM01: Prompt Injection	10 prompt injection patterns (PI-001 to PI-010)	PatternEngine
LLM02: Insecure Output Handling	PostToolUse output scan + REDACT action	SecurityGateHook + ActionRouter
LLM06: Sensitive Information Disclosure	SecretDetector (13 rules) + PIIFilter (5 rules)	PatternEngine
LLM08: Excessive Agency	DestructiveCommandBlocker (55+ patterns)	PatternEngine

10.2 SOC 2 Type II Alignment

SOC 2 Control	Implementation
CC6.1 Logical Access Controls	ActionRouter BLOCK disposition — CRITICAL threats cannot execute
CC6.6 Transmission Encryption	Local-first architecture — no data transmitted to third-party scanning
CC7.2 System Monitoring	MonitorDashboard + SecurityEventStore provide real-time activity monitoring
CC7.3 Security Incident Identification	AlertDispatcher triggers on HIGH/CRITICAL events; kill switch for emergency response
CC8.1 Change Management	All rule changes via git PR with review; audit table is append-only (no UPDATE/DELETE)

SOC 2 Evidence Package: AuditLogger NDJSON export provides complete event trail. Compliance export endpoint supports date-range queries for auditor evidence collection.

10.3 GDPR / CCPA Alignment

Regulation	Control	Implementation
GDPR Article 25 (Privacy by Design)	PII filtering before tool execution	PIIFilter — automatic redaction before side effects
GDPR Article 5 (Data Minimization)	Sensitive data not retained in logs	Matched text never logged; only rule_id and category in log streams
CCPA Data Minimization	Same as GDPR	Same implementation

10.4 Compliance Gaps (Acknowledged, Not in Scope)

• HIPAA PHI patterns (MRN, NPI, diagnosis codes) — Phase 5 follow-on
• IBAN and financial account patterns — Phase 5 follow-on
• Canadian SIN and regional government ID patterns — Phase 5 follow-on
• SIEM integration for centralized log aggregation — infrastructure team dependency
• Incident escalation workflow beyond webhook alerting — operations team dependency

---

11. Research Pipeline Reference

This project plan is derived from a five-artifact research pipeline completed 2026-02-18, evaluating the ClawGuard AI Agent Security Ecosystem across three retained repositories (two eliminated — one for malware, one for no code).

11.1 Artifact Index

Artifact	File	Description
Executive Summary	docs/original-research/executive-summary.md	CTO decision brief — repositories evaluated, recommendation, decision factors
CODITECT Impact Analysis	docs/original-research/coditect-impact.md	Integration architecture, multi-tenancy implications, compliance surface, gap analysis
Software Design Document	docs/original-research/sdd.md	Full SDD (IEEE 1016-2009) — all 6 components, API specs, DB schema, failure modes
Technical Design Document	docs/original-research/tdd.md	Implementation-level TDD — TypeScript interfaces, YAML pattern examples, hook contracts
C4 Architecture Model	docs/original-research/c4-architecture.md	C1/C2/C3/C4 Mermaid diagrams, pattern rule catalog, compliance mapping

11.2 Repository Evaluation Summary

Repository	Score	Status	Primary Value
ClawGuardian (superglue-ai)	85/100	Retained	Hook architecture, action model, PII/cloud credential patterns
clawguard (JaydenBeard)	78/100	Retained	55+ destructive command patterns, severity model, dashboard architecture
ClawGuard (maxxie114)	65/100	Retained	Prompt injection patterns (10), risk scoring 0-100, secret detection patterns
lauty1505/clawguard	REMOVED	MALWARE	Trojanized fork — never use
yourclaw/clawguard	REMOVED	No code	README only — not evaluatable

11.3 Key Architectural Decisions from Research

Decision	Rationale	Source
Fail-closed by default	Scan failure that permits execution creates exploitable bypass	Executive Summary §4.1
Port patterns to Python — do not import as npm	TypeScript/Node.js incompatible with CODITECT Python hook runtime	Impact Analysis §1.1
Pattern validation before block mode	JaydenBeard patterns have unknown FP/FN against CODITECT sessions	Impact Analysis §7.5
Audit to org.db not new security.db	Security events are as irreplaceable as architecture decisions	SDD §3.6
Five-level action taxonomy	Allows incremental deployment — warn before block	SDD §3.4
Per-tenant layered rule config	None of the source repos support multi-tenancy — must be built	Impact Analysis §2.1

---

12. Appendix: Pattern Library Summary

The complete pattern library targets 80+ rules across five categories, derived from all three research repositories.

12.1 Prompt Injection Rules (10 rules — PI-001 to PI-010)

Rule ID	Name	Severity	Pattern Target
PI-001	ignore_instructions	CRITICAL	"ignore all previous instructions" variants
PI-002	delimiter_injection	HIGH	Chat template delimiters (</system>, [SYSTEM], `<
PI-003	new_instructions	HIGH	"new instructions follow" / "updated system prompt"
PI-004	system_prompt_override	CRITICAL	Direct system prompt replacement attempts
PI-005	tool_call_injection	HIGH	Injected tool call syntax in user content
PI-006	exfiltration_attempt	CRITICAL	"send/upload" + sensitive keyword co-occurrence
PI-007	secret_request	HIGH	"tell me your API key/password/secret"
PI-008	jailbreak_attempt	HIGH	DAN, developer mode, "pretend you have no restrictions"
PI-009	encoding_evasion	MEDIUM	Base64/URL/ROT13 encoded injection patterns
PI-010	hidden_instruction	HIGH	Unicode homoglyphs, zero-width characters, ANSI sequences

12.2 Secret Detection Rules (13 rules — SD-001 to SD-013)

Rule ID	Name	Severity
SD-001	api_key_generic	HIGH
SD-002	aws_access_key	CRITICAL
SD-003	aws_secret_key	CRITICAL
SD-004	github_token	HIGH
SD-005	jwt_token	HIGH
SD-006	private_key_pem	CRITICAL
SD-007	gcp_service_account	CRITICAL
SD-008	azure_connection_string	HIGH
SD-009	stripe_key	HIGH
SD-010	twilio_auth_token	HIGH
SD-011	slack_token	HIGH
SD-012	database_url	HIGH
SD-013	bearer_token	MEDIUM

12.3 PII Detection Rules (5 rules — PII-001 to PII-005)

Rule ID	Name	Severity	Method
PII-001	phone_number	MEDIUM	phonenumbers Python library (international)
PII-002	email_address	MEDIUM	RFC 5322 regex
PII-003	ssn_us	HIGH	\d{3}-\d{2}-\d{4} with context validation
PII-004	credit_card	HIGH	Luhn-validated 13-19 digit sequences
PII-005	passport_number	HIGH	Country-specific format regex set

12.4 Destructive Command Rules (Critical/High selection — DC-001 to DC-055+)

Rule ID	Name	Severity
DC-001	sudo_shell	CRITICAL
DC-002	rm_rf_system	CRITICAL
DC-003	curl_pipe_sh	CRITICAL
DC-004	keychain_extract	CRITICAL
DC-005	credential_store_access	CRITICAL
DC-006	disk_format	CRITICAL
DC-007	cloud_destructive	HIGH
DC-008	email_exfil	HIGH
DC-009	camera_mic_access	HIGH
DC-010	persistence_mechanism	HIGH
DC-011	network_listener	HIGH
DC-012	privileged_docker	HIGH
DC-013+	(43+ additional patterns from JaydenBeard — ported in Phase 2)	MEDIUM/HIGH

12.5 Sensitive Path Traversal Rules (30+ rules — PT-001 to PT-030+)

Coverage includes: .ssh, .aws, .kube, .env, password manager directories (1Password, Bitwarden, Keychain), cloud configuration files, and ../../ path traversal escape patterns.

---

Document Control

Field	Value
Document ID	PLAN-CODITECT-SEC-001
Version	1.0.0 — Initial plan, 2026-02-18
Author	software-design-document-specialist (Claude Sonnet 4.6)
Review Required	Architecture team, Security track lead, DevOps lead
Next Review	Prior to Sprint 1 kickoff
Supersedes	None — first version

Source Research: All architectural decisions derive from the five research artifacts in docs/original-research/. Before modifying this plan, consult those artifacts for the evidence base behind each decision.

Author: Claude (Sonnet 4.6)