Skip to main content

Track D: Development & Engineering

Progress: 0/62 tasks complete (0%)

This track covers all implementation work for the CODITECT AI Agent Security Layer, derived directly from SDD-CODITECT-SEC-001 and TDD v1.0.0. Tasks follow the five-phase development plan defined in SDD Section 12.1.

Phase structure:

  • D.1–D.3: Phase 1 — Core Enforcement (6 weeks)
  • D.4: Phase 2 — Output Scanning and Redaction (3 weeks)
  • D.5: Phase 3 — Human Confirmation Flow (2 weeks)
  • D.6: Phase 4 — Dashboard and Alerting (4 weeks)
  • D.7: Phase 5 — Tenant Configuration and Operations (3 weeks)

Status Summary​

SectionDoneTotalStatus
D.1 SecurityGateHook011Pending
D.2 PatternEngine013Pending
D.3 RiskAnalyzer, ActionRouter & AuditLogger011Pending
D.4 Output Scanner (PostToolUse)08Pending
D.5 Human Confirmation Flow05Pending
D.6 Monitor Dashboard09Pending
D.7 Tenant Configuration & Operations05Pending

D.1 SecurityGateHook​

SDD Reference: Section 3.1 | Phase: 1 | Estimated Effort: Medium (~500 LOC Python)

The entry point for all security inspection. Receives hook events from CODITECT's hook dispatch system, assembles inspection payloads, coordinates the scan pipeline, and returns enforcement decisions. Registers as three CODITECT hooks: PreAgentStart, PreToolUse, PostToolUse.

  • D.1.1 Create hooks/security-gate/ directory structure with __init__.py, module skeleton files (security_gate_hook.py, models.py, config.py)
  • D.1.2 Implement SecurityGateConfig Pydantic v2 model — tenant_id, fail_mode (closed/open), scan_timeout_ms (500), max_input_bytes (1MB), enabled_checks list
  • D.1.3 Implement SecurityGateHook.__init__() with dependency injection for PatternEngine, RiskAnalyzer, ActionRouter, AuditLogger
  • D.1.4 Implement SecurityGateHook.on_before_tool_call() — synchronous PreToolUse handler; assembles ScanPayload, starts 500ms timeout timer, coordinates scan pipeline, returns ToolCallDecision
  • D.1.5 Implement SecurityGateHook.on_tool_result() — PostToolUse handler; assembles output scan payload, returns ToolResultDecision with optional redacted output
  • D.1.6 Implement SecurityGateHook.on_agent_start() — PreAgentStart handler; scans system prompt for injection attempts before session initialization
  • D.1.7 Implement fail-closed exception handler — catches all PatternEngine and RiskAnalyzer exceptions; returns BLOCK decision with SCAN_FAILED audit event regardless of exception type
  • D.1.8 Implement scan timeout enforcement — if scan_timeout_ms (500ms) exceeded, apply fail-closed behavior identical to exception path; log SCAN_FAILED with timeout=true
  • D.1.9 Implement circuit breaker (circuit_breaker.py) — CLOSED/OPEN/HALF-OPEN states; 5 consecutive failures within 60s opens circuit; 30s cooldown before HALF-OPEN probe; SDD Section 8.3
  • D.1.10 Write hook manifest (security-gate.manifest.json) — registers all three hook events with priority: 100, timeout_ms: 500, blocking: true; follows existing CODITECT hook manifest format
  • D.1.11 Validate hook registration against CODITECT hook dispatch system — verify SecurityGateHook appears first in PreToolUse chain before task-tracking-enforcer.py

D.2 PatternEngine​

SDD Reference: Sections 3.2, 6.2, Appendix A | Phase: 1 | Estimated Effort: High (~800 LOC Python + ~2,000 lines YAML)

Evaluates tool call payloads against the unified pattern library. The rule authoring effort (YAML files) is the largest single effort in the entire project.

  • D.2.1 Implement PatternEngine class with RuleLoader dependency — loads YAML rule files from hooks/security-gate/rules/ at startup; compiles regex patterns using @lru_cache per pattern string
  • D.2.2 Implement ScanPayload and PatternMatch Pydantic v2 models — all fields per SDD Section 3.2 interface definition
  • D.2.3 Implement PatternEngine.scan() — executes all applicable rules against ScanPayload.raw_text; respects enabled_checks from SecurityGateConfig; returns list[PatternMatch]; raises PatternEngineException on failure
  • D.2.4 Implement PatternEngine.redact() — replaces matched text in payload with [REDACTED:<rule_id>] tokens; handles nested JSON field traversal
  • D.2.5 Implement PatternEngine.reload_rules() — hot-reload rule YAML files without service restart; must complete within 200ms with zero dropped requests during reload
  • D.2.6 Implement tenant rule overlay — Layer 0 (non-overridable platform rules) + Layer 1 (tenant-overridable) + Layer 2 (tenant custom rules from tenant_security_configs); 30-60 second TTL caches per tenant_id
  • D.2.7 Author rules/prompt-injection.yaml — 10 rules PI-001 through PI-010: ignore_instructions (CRITICAL), delimiter_injection (HIGH), new_instructions (HIGH), system_prompt_override (CRITICAL), tool_call_injection (HIGH), exfiltration_attempt (CRITICAL), secret_request (HIGH), jailbreak_attempt (HIGH), encoding_evasion (MEDIUM), hidden_instruction (HIGH); ported from maxxie114 patterns
  • D.2.8 Author rules/secret-detection.yaml — 13 rules SD-001 through SD-013: AWS access key (CRITICAL), AWS secret key (CRITICAL), private key PEM (CRITICAL), GCP service account (CRITICAL), GitHub token (HIGH), JWT token (HIGH), Stripe key (HIGH), Twilio auth token (HIGH), Slack token (HIGH), Azure connection string (HIGH), database URL with credentials (HIGH), bearer token (MEDIUM), generic API key (HIGH); apply to both tool_input and tool_output phases
  • D.2.9 Author rules/pii-detection.yaml — 5 rules PII-001 through PII-005: phone number (via phonenumbers library), email address, US SSN, credit card number, passport number; ported from ClawGuardian patterns/pii.ts
  • D.2.10 Author rules/destructive-commands.yaml — 55+ rules DC-001 through DC-055+: 11 CRITICAL rules (sudo shell, rm_rf_system, curl_pipe_sh, keychain_extract, credential_store_access, dd, mkfs, disk_format), 30+ HIGH rules (cloud CLI destructive, email_exfil, camera_mic_access, persistence_mechanism, network_listener, privileged_docker), 20+ MEDIUM rules (file_deletion, database_drop, git_reset_hard, sudo_nopass); ported from JaydenBeard 55+ patterns
  • D.2.11 Author rules/path-traversal.yaml — 30+ rules PT-001 through PT-030+: sensitive path reads (.ssh, .aws, .kube, .env, ~/.gnupg, ~/Library/Keychains, password manager database paths, cloud configuration stores), path traversal escape patterns (../../ variants); ported from JaydenBeard sensitive path library
  • D.2.12 Create test fixtures in tests/fixtures/payloads/ — one positive test payload per rule (should match); negative test payloads (clean CODITECT operations that must NOT trigger CRITICAL/HIGH matches)
  • D.2.13 Validate pattern performance benchmark — single PatternEngine.scan() on 64 KB payload must complete in under 50ms; all 80+ patterns compiled once at startup via LRU cache

D.3 RiskAnalyzer, ActionRouter & AuditLogger​

SDD Reference: Sections 3.3, 3.4, 3.6, 6.1 | Phase: 1 | Estimated Effort: Low-Medium (~600 LOC Python)

The scoring, decision, and persistence components. These are designed to be straightforward implementations of well-specified algorithms.

  • D.3.1 Implement RiskAnalyzer.score() — deterministic scoring algorithm: CRITICAL=80, HIGH=40, MEDIUM=20, LOW=5, INFO=1; min(100, sum(scores)); single CRITICAL match sets minimum score to 80; PI + SD co-occurrence adds 15 bonus points; destructive_tool_allowlist reduces score by 20
  • D.3.2 Implement RiskScore Pydantic v2 model — numeric_score, severity_category, primary_threat, contributing_matches, reasoning string (required on every score), recommended_action
  • D.3.3 Implement ScanContext Pydantic v2 model — tool_name, session_id, tenant_id, agent_id, user_confirmed_tools, tenant_allowlist
  • D.3.4 Implement ActionRouter.decide() — severity-to-action lookup table (CRITICAL=BLOCK hard-coded, HIGH=BLOCK, MEDIUM=CONFIRM, LOW=WARN, INFO=LOG); applies tenant action_overrides for non-CRITICAL severities; builds EnforcementDecision
  • D.3.5 Implement ActionRouter CONFIRM timeout — register confirmation request with 30-second countdown; escalate to BLOCK on timeout; emit TOOL_CONFIRM_TIMEOUT audit event
  • D.3.6 Implement ActionRouter REDACT action — call PatternEngine.redact(payload, matches) to build sanitized input; populate EnforcementDecision.redacted_input
  • D.3.7 Implement AuditLogger with org.db integration — use scripts.core.paths.get_org_db_path() to locate database; write to security_audit_events table; synchronous write for BLOCK/REDACT/SCAN_FAILED; async write for WARN/LOG/ALLOW
  • D.3.8 Implement AuditLogger.log() and AuditLogger.log_batch() — write AuditEvent to security_audit_events table in finally block (never dropped even on exception)
  • D.3.9 Implement AuditLogger.query() — parameterized queries by tenant_id, session_id, event_types, date range, limit; must return 1000 events in under 500ms
  • D.3.10 Run migrate_security_schema.py — create four new tables in org.db: security_audit_events, tenant_security_configs, pattern_effectiveness, kill_switch_events; all indexes per SDD Section 6.1
  • D.3.11 Implement write-through audit queue — dedicated writer thread for async audit events; prevents I/O from blocking scan path; page on-call if queue depth exceeds 1000

D.4 Output Scanner (PostToolUse)​

SDD Reference: Sections 2.2, 4.2, 3.1 (on_tool_result) | Phase: 2 | Estimated Effort: Medium (~400 LOC Python)

PostToolUse scanning for secrets and PII in tool outputs before they are passed back to the agent context window. Builds on the PatternEngine and ActionRouter from Phase 1.

  • D.4.1 Implement OutputScanner class — wraps SecurityGateHook.on_tool_result() with output-phase scan logic; serializes tool_output dict to scannable raw text
  • D.4.2 Configure secret detection rules to apply to tool_output phase — verify apply_to: ["tool_input", "tool_output"] is set on all 13 SD-* rules and all PII-* rules
  • D.4.3 Implement output redaction in ActionRouter — for REDACT decisions on output scan, replace matched secrets with [REDACTED:<rule_id>] tokens; return sanitized output as ToolResultDecision.redacted_output
  • D.4.4 Implement PatternEngine.scan(phase="output") path — output scans apply only categories with apply_to containing "tool_output"; destructive-commands.yaml rules do not apply to output phase
  • D.4.5 Implement PostToolUse hook registration — PostToolUse hook with priority: 10, timeout_ms: 300; lower priority than PreToolUse because output scan is non-blocking for most cases
  • D.4.6 Implement correlation between PreToolUse and PostToolUse events — AuditEvent for output scan includes pre_event_id foreign key linking to the corresponding PreToolUse audit event
  • D.4.7 Implement TOOL_REDACTED audit event — emitted when output scanner redacts secrets; redacted_fields list contains field names only (never values); synchronous write to org.db
  • D.4.8 Validate redaction does not mutate agent context — confirm redacted output returned to CODITECT dispatch layer replaces original output entirely; no partial redaction that leaves discoverable fragments

D.5 Human Confirmation Flow​

SDD Reference: Section 3.4 (CONFIRM action), 4.1 (control flow) | Phase: 3 | Estimated Effort: Medium (~400 LOC Python + UI integration)

The CONFIRM action pauses MEDIUM-severity tool calls pending human approval via the CODITECT UI. Timeout escalates to BLOCK.

  • D.5.1 Implement CONFIRM suspension mechanism in CODITECT dispatch layer — register pending confirmation request; return CONFIRM decision to dispatch layer; dispatch suspends tool call execution
  • D.5.2 Implement CONFIRM response handler — listen for human approval or rejection via CODITECT UI confirmation dialog; resume or block tool call based on response
  • D.5.3 Implement CONFIRM timeout escalation — if no human response within confirm_timeout_seconds (default: 30), emit TOOL_CONFIRM_TIMEOUT audit event and escalate decision to BLOCK
  • D.5.4 Implement CONFIRM rate limiter — maximum 3 CONFIRM requests per session per minute; excess CONFIRM decisions automatically escalate to BLOCK to prevent false-positive DoS
  • D.5.5 Integrate CONFIRM dialog with CODITECT UI — surface confirmation dialog showing tool name, risk score, primary threat category, and reasoning string; provide Approve / Block buttons with 30-second countdown timer display

D.6 Monitor Dashboard​

SDD Reference: Section 3.5, 5.2, 9.4 | Phase: 4 | Estimated Effort: High (~1,200 LOC Python + TypeScript)

Real-time visibility into security events across active agent sessions. FastAPI backend with WebSocket streaming; React TypeScript frontend with four dashboard widgets.

  • D.6.1 Implement DashboardServer (FastAPI) — six REST routes: GET /api/v1/security/sessions, GET /api/v1/security/events, POST /api/v1/security/gateway/{tenant_id}/kill, GET /api/v1/security/export, GET /api/v1/security/stats, GET /api/v1/security/alerts; use existing CODITECT JWT authentication
  • D.6.2 Implement EventStreamBus — in-memory pub/sub for real-time event distribution from AuditLogger to WebSocket clients; overflow drops dashboard events without affecting enforcement; batch polling fallback at 30-second intervals when bus degrades
  • D.6.3 Implement WebSocket endpoint (/ws/v1/security/stream) — token auth via query parameter; broadcasts SecurityEvent messages to all connected clients within 200ms of security event; handles 100 concurrent connections without degradation
  • D.6.4 Implement kill switch endpoint (POST /api/v1/security/gateway/{tenant_id}/kill) — admin + MFA-gated (X-MFA-Token header required); terminates all active agent sessions for tenant within 5 seconds; writes KILL_SWITCH_ACTIVATED event to kill_switch_events table (5-year retention); emits KILL_SWITCH_ACTIVATED to MonitorDashboard
  • D.6.5 Implement AlertDispatcher — webhook delivery to Discord, Slack, PagerDuty targets; POST with retry up to 3 times with exponential backoff (base: 2s); per SDD alert payload schema including dashboard_url
  • D.6.6 Implement export endpoint (GET /api/v1/security/export) — NDJSON, CSV, JSON formats; date range filtering; generates up to 30 days of audit data; streams response to avoid memory pressure on large exports
  • D.6.7 Implement React dashboard frontend — four widgets: Live Feed (WebSocket real-time events), Session Map (active sessions with risk level), Pattern Hit Rates (last 1 hour by rule_id), System Health (PatternEngine/RiskAnalyzer/AuditLogger status + scan p99 vs 500ms limit)
  • D.6.8 Implement useSecurityStream React hook — manages WebSocket lifecycle, auto-reconnects with exponential backoff on disconnect, buffers events during reconnection, exposes typed SecurityEvent stream
  • D.6.9 Implement nightly_pattern_effectiveness_job.py — SQL aggregation of match_count, block_count, false_positive_count per rule_id per tenant_id per day; populates pattern_effectiveness table; runs via systemd timer or cron

D.7 Tenant Configuration & Operations​

SDD Reference: Sections 7.1, 10.1, 14.1-14.4 | Phase: 5 | Estimated Effort: Medium (~400 LOC Python + UI)

Multi-tenant rule layering, admin configuration UI, and operational hardening for production readiness.

  • D.7.1 Implement three-layer rule resolution at scan time — Layer 0 (platform base, always included, process-level cache), Layer 1 (platform recommended, tenant-overridable, 60s TTL per tenant_id), Layer 2 (tenant custom rules from tenant_security_configs.rule_overrides, 30s TTL per tenant_id); Layer 0 wins over all; Layer 1 wins over Layer 2 for CRITICAL severity
  • D.7.2 Implement tenant config management API — GET/PUT /api/v1/security/tenant/{tenant_id}/config; stores TenantSecurityConfig in tenant_security_configs table; validates that CRITICAL action overrides are rejected; logs all config changes as TENANT_OVERRIDE events
  • D.7.3 Implement admin UI for tenant security configuration — view and edit action_overrides, allowlisted_tools, rule_overrides, alert_webhooks, confirm_timeout; requires admin role; displays current config version and last-updated-by
  • D.7.4 Run load test — 50 concurrent scan requests; validate p99 scan latency under 500ms; validate kill switch terminates all sessions within 5 seconds under 100 concurrent sessions; validate 100 WebSocket connections without degradation
  • D.7.5 Write operational runbook — three sections: SecurityGateCircuitOpen response (check PatternEngine/RiskAnalyzer, inspect logs, verify rule YAML syntax, circuit auto-recovery); SecurityGateAuditDbDown response (check disk space, WAL lock, notify tenants, do not disable audit); SecurityGateHighBlockRate response (review recent blocks, differentiate false positives from genuine threats, open PR to adjust rules if false positive)

D.8 GitHub Actions CI Security Gate​

TaskDoneTotalStatus
D.8 GitHub Actions CI Security Gate06Pending

SDD Reference: ADR-001 (native architecture), ADR-002 (YAML patterns) | Phase: 1.5 | Estimated Effort: Small (~300 LOC Python + YAML)

GitHub Actions workflow that scans push/PR diffs against the YAML pattern library to prevent secrets, destructive commands, and prompt injection from entering the repository. Reuses PatternEngine and aggregate_score from the core security modules.

  • D.8.1 Implement PatternEngine.load_patterns() — YAML loading from config/security-patterns/ directory; compile regex patterns; return count loaded
  • D.8.2 Create scripts/ci-security-scan.py — standalone scanner that loads patterns, scans git diff, outputs GitHub Actions annotations, returns exit code 1 on critical/high findings
  • D.8.3 Create .github/workflows/security-scan.yml — GitHub Actions workflow triggered on push and pull_request; runs ci-security-scan.py against changed files
  • D.8.4 Write unit tests for PatternEngine.load_patterns() and CI scanner
  • D.8.5 Create scripts/ci-security-scan-README.md — usage documentation for the scanner and GitHub Action
  • D.8.6 Validate end-to-end: push test commit with known secret pattern, verify action blocks